001    /*
002     *  Copyright 2001-2009 Stephen Colebourne
003     *
004     *  Licensed under the Apache License, Version 2.0 (the "License");
005     *  you may not use this file except in compliance with the License.
006     *  You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     *  Unless required by applicable law or agreed to in writing, software
011     *  distributed under the License is distributed on an "AS IS" BASIS,
012     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     *  See the License for the specific language governing permissions and
014     *  limitations under the License.
015     */
016    package org.joda.time;
017    
018    /**
019     * Defines an exact duration of time in milliseconds.
020     * <p>
021     * The implementation of this interface may be mutable or immutable. This
022     * interface only gives access to retrieve data, never to change it.
023     * <p>
024     * Methods that are passed a duration as a parameter will treat <code>null</code>
025     * as a zero length duration.
026     * <p>
027     * The {@code compareTo} method is no longer defined in this class in version 2.0.
028     * Instead, the definition is simply inherited from the {@code Comparable} interface.
029     * This approach is necessary to preserve binary compatibility.
030     * The definition of the comparison is ascending order by millisecond duration.
031     * Implementors are recommended to extend {@code AbstractInstant} instead of this interface.
032     *
033     * @see ReadableInterval
034     * @see ReadablePeriod
035     * @author Brian S O'Neill
036     * @author Stephen Colebourne
037     * @since 1.0
038     */
039    public interface ReadableDuration extends Comparable<ReadableDuration> {
040    
041        /**
042         * Gets the total length of this duration in milliseconds.
043         *
044         * @return the total length of the time duration in milliseconds.
045         */
046        long getMillis();
047    
048        //-----------------------------------------------------------------------
049        /**
050         * Get this duration as an immutable <code>Duration</code> object.
051         * <p>
052         * This will either typecast this instance, or create a new <code>Duration</code>.
053         * 
054         * @return a Duration created using the millisecond duration from this instance
055         */
056        Duration toDuration();
057    
058        //-----------------------------------------------------------------------
059        /**
060         * Converts this duration to a Period instance using the standard period type
061         * and the ISO chronology.
062         * <p>
063         * Only precise fields in the period type will be used. Thus, only the hour,
064         * minute, second and millisecond fields on the period will be used.
065         * The year, month, week and day fields will not be populated.
066         * <p>
067         * If the duration is small, less than one day, then this method will perform
068         * as you might expect and split the fields evenly.
069         * If the duration is larger than one day then all the remaining duration will
070         * be stored in the largest available field, hours in this case.
071         * <p>
072         * For example, a duration effectively equal to (365 + 60 + 5) days will be
073         * converted to ((365 + 60 + 5) * 24) hours by this constructor.
074         * <p>
075         * For more control over the conversion process, you must pair the duration with
076         * an instant, see {@link Period#Period(ReadableInstant,ReadableDuration)}.
077         * 
078         * @return a Period created using the millisecond duration from this instance
079         */
080        Period toPeriod();
081    
082        //-----------------------------------------------------------------------
083        // Method is no longer defined here as that would break generic backwards compatibility
084    //    /**
085    //     * Compares this duration with the specified duration based on length.
086    //     *
087    //     * @param obj  a duration to check against
088    //     * @return negative value if this is less, 0 if equal, or positive value if greater
089    //     * @throws NullPointerException if the object is null
090    //     * @throws ClassCastException if the given object is not supported
091    //     */
092    //    int compareTo(ReadableDuration obj);
093    
094        /**
095         * Is the length of this duration equal to the duration passed in.
096         *
097         * @param duration  another duration to compare to, null means zero milliseconds
098         * @return true if this duration is equal to than the duration passed in
099         */
100        boolean isEqual(ReadableDuration duration);
101    
102        /**
103         * Is the length of this duration longer than the duration passed in.
104         *
105         * @param duration  another duration to compare to, null means zero milliseconds
106         * @return true if this duration is equal to than the duration passed in
107         */
108        boolean isLongerThan(ReadableDuration duration);
109    
110        /**
111         * Is the length of this duration shorter than the duration passed in.
112         *
113         * @param duration  another duration to compare to, null means zero milliseconds
114         * @return true if this duration is equal to than the duration passed in
115         */
116        boolean isShorterThan(ReadableDuration duration);
117    
118        //-----------------------------------------------------------------------
119        /**
120         * Compares this object with the specified object for equality based
121         * on the millisecond length. All ReadableDuration instances are accepted.
122         *
123         * @param readableDuration  a readable duration to check against
124         * @return true if the length of the duration is equal
125         */
126        boolean equals(Object readableDuration);
127    
128        /**
129         * Gets a hash code for the duration that is compatable with the 
130         * equals method.
131         * The following formula must be used:
132         * <pre>
133         *  long len = getMillis();
134         *  return (int) (len ^ (len >>> 32));
135         * </pre>
136         *
137         * @return a hash code
138         */
139        int hashCode();
140    
141        //-----------------------------------------------------------------------
142        /**
143         * Gets the value as a String in the ISO8601 duration format using hours,
144         * minutes and seconds (including fractional milliseconds).
145         * <p>
146         * For example, "PT6H3M7S" represents 6 hours, 3 minutes, 7 seconds.
147         *
148         * @return the value as an ISO8601 string
149         */
150        String toString();
151    
152    }