001: /*
002: * Copyright 2001-2006 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: * Readable interface for an interval of time between two instants.
020: * <p>
021: * A time interval represents a period of time between two instants.
022: * Intervals are inclusive of the start instant and exclusive of the end.
023: * The end instant is always greater than or equal to the start instant.
024: * <p>
025: * Intervals have a fixed millisecond duration.
026: * This is the difference between the start and end instants.
027: * The duration is represented separately by {@link ReadableDuration}.
028: * As a result, intervals are not comparable.
029: * To compare the length of two intervals, you should compare their durations.
030: * <p>
031: * An interval can also be converted to a {@link ReadablePeriod}.
032: * This represents the difference between the start and end points in terms of fields
033: * such as years and days.
034: * <p>
035: * Methods that are passed an interval as a parameter will treat <code>null</code>
036: * as a zero length interval at the current instant in time.
037: *
038: * @author Sean Geoghegan
039: * @author Brian S O'Neill
040: * @author Stephen Colebourne
041: * @since 1.0
042: */
043: public interface ReadableInterval {
044:
045: /**
046: * Gets the chronology of the interval, which is the chronology of the first datetime.
047: *
048: * @return the chronology of the interval
049: */
050: Chronology getChronology();
051:
052: /**
053: * Gets the start of this time interval which is inclusive.
054: *
055: * @return the start of the time interval,
056: * millisecond instant from 1970-01-01T00:00:00Z
057: */
058: long getStartMillis();
059:
060: /**
061: * Gets the start of this time interval, which is inclusive, as a DateTime.
062: *
063: * @return the start of the time interval
064: */
065: DateTime getStart();
066:
067: /**
068: * Gets the end of this time interval which is exclusive.
069: *
070: * @return the end of the time interval,
071: * millisecond instant from 1970-01-01T00:00:00Z
072: */
073: long getEndMillis();
074:
075: /**
076: * Gets the end of this time interval, which is exclusive, as a DateTime.
077: *
078: * @return the end of the time interval
079: */
080: DateTime getEnd();
081:
082: //-----------------------------------------------------------------------
083: /**
084: * Does this time interval contain the specified instant.
085: * <p>
086: * Non-zero duration intervals are inclusive of the start instant and
087: * exclusive of the end. A zero duration interval cannot contain anything.
088: * <p>
089: * For example:
090: * <pre>
091: * [09:00 to 10:00) contains 08:59 = false (before start)
092: * [09:00 to 10:00) contains 09:00 = true
093: * [09:00 to 10:00) contains 09:59 = true
094: * [09:00 to 10:00) contains 10:00 = false (equals end)
095: * [09:00 to 10:00) contains 10:01 = false (after end)
096: *
097: * [14:00 to 14:00) contains 14:00 = false (zero duration contains nothing)
098: * </pre>
099: *
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: }
|