ReadableInterval


1   /*
2    *  Copyright 2001-2006 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   * Readable interface for an interval of time between two instants.
20   * <p>
21   * A time interval represents a period of time between two instants.
22   * Intervals are inclusive of the start instant and exclusive of the end.
23   * The end instant is always greater than or equal to the start instant.
24   * <p>
25   * Intervals have a fixed millisecond duration.
26   * This is the difference between the start and end instants.
27   * The duration is represented separately by {@link ReadableDuration}.
28   * As a result, intervals are not comparable.
29   * To compare the length of two intervals, you should compare their durations.
30   * <p>
31   * An interval can also be converted to a {@link ReadablePeriod}.
32   * This represents the difference between the start and end points in terms of fields
33   * such as years and days.
34   * <p>
35   * Methods that are passed an interval as a parameter will treat <code>null</code>
36   * as a zero length interval at the current instant in time.
37   *
38   * @author Sean Geoghegan
39   * @author Brian S O'Neill
40   * @author Stephen Colebourne
41   * @since 1.0
42   */
43  public interface ReadableInterval {
44  
45      /**
46       * Gets the chronology of the interval, which is the chronology of the first datetime.
47       *
48       * @return the chronology of the interval
49       */
50      Chronology getChronology();
51  
52      /**
53       * Gets the start of this time interval which is inclusive.
54       *
55       * @return the start of the time interval,
56       *  millisecond instant from 1970-01-01T00:00:00Z
57       */
58      long getStartMillis();
59  
60      /**
61       * Gets the start of this time interval, which is inclusive, as a DateTime.
62       *
63       * @return the start of the time interval
64       */
65      DateTime getStart();
66  
67      /** 
68       * Gets the end of this time interval which is exclusive.
69       *
70       * @return the end of the time interval,
71       *  millisecond instant from 1970-01-01T00:00:00Z
72       */
73      long getEndMillis();
74  
75      /** 
76       * Gets the end of this time interval, which is exclusive, as a DateTime.
77       *
78       * @return the end of the time interval
79       */
80      DateTime getEnd();
81  
82      //-----------------------------------------------------------------------
83      /**
84       * Does this time interval contain the specified instant.
85       * <p>
86       * Non-zero duration intervals are inclusive of the start instant and
87       * exclusive of the end. A zero duration interval cannot contain anything.
88       * <p>
89       * For example:
90       * <pre>
91       * [09:00 to 10:00) contains 08:59  = false (before start)
92       * [09:00 to 10:00) contains 09:00  = true
93       * [09:00 to 10:00) contains 09:59  = true
94       * [09:00 to 10:00) contains 10:00  = false (equals end)
95       * [09:00 to 10:00) contains 10:01  = false (after end)
96       * 
97       * [14:00 to 14:00) contains 14:00  = false (zero duration contains nothing)
98       * </pre>
99       *
100      * @param instant  the instant, null means now
101      * @return true if this time interval contains the instant
102      */
103     boolean contains(ReadableInstant instant);
104     
105     /**
106      * Does this time interval contain the specified time interval.
107      * <p>
108      * Non-zero duration intervals are inclusive of the start instant and
109      * exclusive of the end. The other interval is contained if this interval
110      * wholly contains, starts, finishes or equals it.
111      * A zero duration interval cannot contain anything.
112      * <p>
113      * When two intervals are compared the result is one of three states:
114      * (a) they abut, (b) there is a gap between them, (c) they overlap.
115      * The <code>contains</code> method is not related to these states.
116      * In particular, a zero duration interval is contained at the start of
117      * a larger interval, but does not overlap (it abuts instead).
118      * <p>
119      * For example:
120      * <pre>
121      * [09:00 to 10:00) contains [09:00 to 10:00)  = true
122      * [09:00 to 10:00) contains [09:00 to 09:30)  = true
123      * [09:00 to 10:00) contains [09:30 to 10:00)  = true
124      * [09:00 to 10:00) contains [09:15 to 09:45)  = true
125      * [09:00 to 10:00) contains [09:00 to 09:00)  = true
126      * 
127      * [09:00 to 10:00) contains [08:59 to 10:00)  = false (otherStart before thisStart)
128      * [09:00 to 10:00) contains [09:00 to 10:01)  = false (otherEnd after thisEnd)
129      * [09:00 to 10:00) contains [10:00 to 10:00)  = false (otherStart equals thisEnd)
130      * 
131      * [14:00 to 14:00) contains [14:00 to 14:00)  = false (zero duration contains nothing)
132      * </pre>
133      *
134      * @param interval  the time interval to compare to, null means a zero duration interval now
135      * @return true if this time interval contains the time interval
136      */
137     boolean contains(ReadableInterval interval);
138     
139     /**
140      * Does this time interval overlap the specified time interval.
141      * <p>
142      * Intervals are inclusive of the start instant and exclusive of the end.
143      * An interval overlaps another if it shares some common part of the
144      * datetime continuum. 
145      * <p>
146      * When two intervals are compared the result is one of three states:
147      * (a) they abut, (b) there is a gap between them, (c) they overlap.
148      * The abuts state takes precedence over the other two, thus a zero duration
149      * interval at the start of a larger interval abuts and does not overlap.
150      * <p>
151      * For example:
152      * <pre>
153      * [09:00 to 10:00) overlaps [08:00 to 08:30)  = false (completely before)
154      * [09:00 to 10:00) overlaps [08:00 to 09:00)  = false (abuts before)
155      * [09:00 to 10:00) overlaps [08:00 to 09:30)  = true
156      * [09:00 to 10:00) overlaps [08:00 to 10:00)  = true
157      * [09:00 to 10:00) overlaps [08:00 to 11:00)  = true
158      * 
159      * [09:00 to 10:00) overlaps [09:00 to 09:00)  = false (abuts before)
160      * [09:00 to 10:00) overlaps [09:00 to 09:30)  = true
161      * [09:00 to 10:00) overlaps [09:00 to 10:00)  = true
162      * [09:00 to 10:00) overlaps [09:00 to 11:00)  = true
163      * 
164      * [09:00 to 10:00) overlaps [09:30 to 09:30)  = true
165      * [09:00 to 10:00) overlaps [09:30 to 10:00)  = true
166      * [09:00 to 10:00) overlaps [09:30 to 11:00)  = true
167      * 
168      * [09:00 to 10:00) overlaps [10:00 to 10:00)  = false (abuts after)
169      * [09:00 to 10:00) overlaps [10:00 to 11:00)  = false (abuts after)
170      * 
171      * [09:00 to 10:00) overlaps [10:30 to 11:00)  = false (completely after)
172      * 
173      * [14:00 to 14:00) overlaps [14:00 to 14:00)  = false (abuts before and after)
174      * [14:00 to 14:00) overlaps [13:00 to 15:00)  = true
175      * </pre>
176      *
177      * @param interval  the time interval to compare to, null means a zero length interval now
178      * @return true if the time intervals overlap
179      */
180     boolean overlaps(ReadableInterval interval);
181     
182     //-----------------------------------------------------------------------
183     /**
184      * Is this time interval after the specified instant.
185      * <p>
186      * Intervals are inclusive of the start instant and exclusive of the end.
187      * 
188      * @param instant  the instant to compare to, null means now
189      * @return true if this time interval is after the instant
190      */
191     boolean isAfter(ReadableInstant instant);
192     
193     /**
194      * Is this time interval entirely after the specified interval.
195      * <p>
196      * Intervals are inclusive of the start instant and exclusive of the end.
197      * 
198      * @param interval  the interval to compare to, null means now
199      * @return true if this time interval is after the interval specified
200      */
201     boolean isAfter(ReadableInterval interval);
202     
203     /**
204      * Is this time interval before the specified instant.
205      * <p>
206      * Intervals are inclusive of the start instant and exclusive of the end.
207      * 
208      * @param instant  the instant to compare to, null means now
209      * @return true if this time interval is before the instant
210      */
211     boolean isBefore(ReadableInstant instant);
212     
213     /**
214      * Is this time interval entirely before the specified interval.
215      * <p>
216      * Intervals are inclusive of the start instant and exclusive of the end.
217      * 
218      * @param interval  the interval to compare to, null means now
219      * @return true if this time interval is before the interval specified
220      */
221     boolean isBefore(ReadableInterval interval);
222     
223     //-----------------------------------------------------------------------
224     /**
225      * Get this interval as an immutable <code>Interval</code> object.
226      * <p>
227      * This will either typecast this instance, or create a new <code>Interval</code>.
228      *
229      * @return the interval as an Interval object
230      */
231     Interval toInterval();
232 
233     /**
234      * Get this time interval as a <code>MutableInterval</code>.
235      * <p>
236      * This will always return a new <code>MutableInterval</code> with the same interval.
237      *
238      * @return the time interval as a MutableInterval object
239      */
240     MutableInterval toMutableInterval();
241 
242     //-----------------------------------------------------------------------
243     /**
244      * Gets the millisecond duration of this time interval.
245      *
246      * @return the millisecond duration of the time interval
247      * @throws ArithmeticException if the duration exceeds the capacity of a long
248      */
249     Duration toDuration();
250 
251     /**
252      * Gets the millisecond duration of this time interval.
253      *
254      * @return the millisecond duration of the time interval
255      * @throws ArithmeticException if the duration exceeds the capacity of a long
256      */
257     long toDurationMillis();
258 
259     /**
260      * Converts the duration of the interval to a period using the
261      * standard period type.
262      * <p>
263      * This method should be used to exract the field values describing the
264      * difference between the start and end instants.
265      *
266      * @return a time period derived from the interval
267      */
268     Period toPeriod();
269 
270     /**
271      * Converts the duration of the interval to a period using the
272      * specified period type.
273      * <p>
274      * This method should be used to exract the field values describing the
275      * difference between the start and end instants.
276      *
277      * @param type  the requested type of the duration, null means standard
278      * @return a time period derived from the interval
279      */
280     Period toPeriod(PeriodType type);
281 
282     //-----------------------------------------------------------------------
283     /**
284      * Compares this object with the specified object for equality based
285      * on start and end millis plus the chronology.
286      * All ReadableInterval instances are accepted.
287      * <p>
288      * To compare the duration of two time intervals, use {@link #toDuration()}
289      * to get the durations and compare those.
290      *
291      * @param readableInterval  a readable interval to check against
292      * @return true if the start and end millis are equal
293      */
294     boolean equals(Object   readableInterval);
295 
296     /**
297      * Gets a hash code for the time interval that is compatable with the 
298      * equals method.
299      * <p>
300      * The formula used must be as follows:
301      * <pre>int result = 97;
302      * result = 31 * result + ((int) (getStartMillis() ^ (getStartMillis() >>> 32)));
303      * result = 31 * result + ((int) (getEndMillis() ^ (getEndMillis() >>> 32)));
304      * result = 31 * result + getChronology().hashCode();
305      * return result;</pre>
306      *
307      * @return a hash code
308      */
309     int hashCode();
310 
311     //-----------------------------------------------------------------------
312     /**
313      * Get the value as a String in the ISO8601 interval format.
314      * <p>
315      * For example, "2004-06-09T12:30:00.000/2004-07-10T13:30:00.000".
316      *
317      * @return the value as an ISO8601 string
318      */
319     String   toString();
320 
321 }
322
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags