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    }