View Javadoc

1   /*
2    *  Copyright 2001-2009 Stephen Colebourne
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.joda.time;
17  
18  /**
19   * Defines an exact duration of time in milliseconds.
20   * <p>
21   * The implementation of this interface may be mutable or immutable. This
22   * interface only gives access to retrieve data, never to change it.
23   * <p>
24   * Methods that are passed a duration as a parameter will treat <code>null</code>
25   * as a zero length duration.
26   * <p>
27   * The {@code compareTo} method is no longer defined in this class in version 2.0.
28   * Instead, the definition is simply inherited from the {@code Comparable} interface.
29   * This approach is necessary to preserve binary compatibility.
30   * The definition of the comparison is ascending order by millisecond duration.
31   * Implementors are recommended to extend {@code AbstractInstant} instead of this interface.
32   *
33   * @see ReadableInterval
34   * @see ReadablePeriod
35   * @author Brian S O'Neill
36   * @author Stephen Colebourne
37   * @since 1.0
38   */
39  public interface ReadableDuration extends Comparable<ReadableDuration> {
40  
41      /**
42       * Gets the total length of this duration in milliseconds.
43       *
44       * @return the total length of the time duration in milliseconds.
45       */
46      long getMillis();
47  
48      //-----------------------------------------------------------------------
49      /**
50       * Get this duration as an immutable <code>Duration</code> object.
51       * <p>
52       * This will either typecast this instance, or create a new <code>Duration</code>.
53       * 
54       * @return a Duration created using the millisecond duration from this instance
55       */
56      Duration toDuration();
57  
58      //-----------------------------------------------------------------------
59      /**
60       * Converts this duration to a Period instance using the standard period type
61       * and the ISO chronology.
62       * <p>
63       * Only precise fields in the period type will be used. Thus, only the hour,
64       * minute, second and millisecond fields on the period will be used.
65       * The year, month, week and day fields will not be populated.
66       * <p>
67       * If the duration is small, less than one day, then this method will perform
68       * as you might expect and split the fields evenly.
69       * If the duration is larger than one day then all the remaining duration will
70       * be stored in the largest available field, hours in this case.
71       * <p>
72       * For example, a duration effectively equal to (365 + 60 + 5) days will be
73       * converted to ((365 + 60 + 5) * 24) hours by this constructor.
74       * <p>
75       * For more control over the conversion process, you must pair the duration with
76       * an instant, see {@link Period#Period(ReadableInstant,ReadableDuration)}.
77       * 
78       * @return a Period created using the millisecond duration from this instance
79       */
80      Period toPeriod();
81  
82      //-----------------------------------------------------------------------
83      // Method is no longer defined here as that would break generic backwards compatibility
84  //    /**
85  //     * Compares this duration with the specified duration based on length.
86  //     *
87  //     * @param obj  a duration to check against
88  //     * @return negative value if this is less, 0 if equal, or positive value if greater
89  //     * @throws NullPointerException if the object is null
90  //     * @throws ClassCastException if the given object is not supported
91  //     */
92  //    int compareTo(ReadableDuration obj);
93  
94      /**
95       * Is the length of this duration equal to the duration passed in.
96       *
97       * @param duration  another duration to compare to, null means zero milliseconds
98       * @return true if this duration is equal to than the duration passed in
99       */
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 }