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 }