KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > joda > time > MutableInterval


1 /*
2  * Copyright 2001-2005 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 import java.io.Serializable JavaDoc;
19
20 import org.joda.time.base.BaseInterval;
21 import org.joda.time.field.FieldUtils;
22
23 /**
24  * MutableInterval is the standard implementation of a mutable time interval.
25  * <p>
26  * A time interval represents a period of time between two instants.
27  * Intervals are inclusive of the start instant and exclusive of the end.
28  * The end instant is always greater than or equal to the start instant.
29  * <p>
30  * Intervals have a fixed millisecond duration.
31  * This is the difference between the start and end instants.
32  * The duration is represented separately by {@link ReadableDuration}.
33  * As a result, intervals are not comparable.
34  * To compare the length of two intervals, you should compare their durations.
35  * <p>
36  * An interval can also be converted to a {@link ReadablePeriod}.
37  * This represents the difference between the start and end points in terms of fields
38  * such as years and days.
39  * <p>
40  * If performing significant calculations on an interval, it may be faster to
41  * convert an Interval object to a MutableInterval one.
42  * <p>
43  * MutableInterval is mutable and not thread-safe, unless concurrent threads
44  * are not invoking mutator methods.
45  *
46  * @author Stephen Colebourne
47  * @author Brian S O'Neill
48  * @since 1.0
49  */

50 public class MutableInterval
51         extends BaseInterval
52         implements ReadWritableInterval, Cloneable JavaDoc, Serializable JavaDoc {
53
54     /** Serialization version */
55     private static final long serialVersionUID = -5982824024992428470L;
56
57     //-----------------------------------------------------------------------
58
/**
59      * Constructs a zero length time interval from 1970-01-01 to 1970-01-01.
60      */

61     public MutableInterval() {
62         super(0L, 0L, null);
63     }
64
65     /**
66      * Constructs an interval from a start and end instant with the ISO default chronology.
67      *
68      * @param startInstant start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
69      * @param endInstant end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
70      * @throws IllegalArgumentException if the end is before the start
71      */

72     public MutableInterval(long startInstant, long endInstant) {
73         super(startInstant, endInstant, null);
74     }
75
76     /**
77      * Constructs an interval from a start and end instant with a chronology.
78      *
79      * @param chronology the chronology to use, null is ISO default
80      * @param startInstant start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
81      * @param endInstant end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
82      * @throws IllegalArgumentException if the end is before the start
83      */

84     public MutableInterval(long startInstant, long endInstant, Chronology chronology) {
85         super(startInstant, endInstant, chronology);
86     }
87
88     /**
89      * Constructs an interval from a start and end instant.
90      * <p>
91      * The chronology used is that of the start instant.
92      *
93      * @param start start of this interval, null means now
94      * @param end end of this interval, null means now
95      * @throws IllegalArgumentException if the end is before the start
96      */

97     public MutableInterval(ReadableInstant start, ReadableInstant end) {
98         super(start, end);
99     }
100
101     /**
102      * Constructs an interval from a start instant and a duration.
103      *
104      * @param start start of this interval, null means now
105      * @param duration the duration of this interval, null means zero length
106      * @throws IllegalArgumentException if the end is before the start
107      * @throws ArithmeticException if the end instant exceeds the capacity of a long
108      */

109     public MutableInterval(ReadableInstant start, ReadableDuration duration) {
110         super(start, duration);
111     }
112
113     /**
114      * Constructs an interval from a millisecond duration and an end instant.
115      *
116      * @param duration the duration of this interval, null means zero length
117      * @param end end of this interval, null means now
118      * @throws IllegalArgumentException if the end is before the start
119      * @throws ArithmeticException if the start instant exceeds the capacity of a long
120      */

121     public MutableInterval(ReadableDuration duration, ReadableInstant end) {
122         super(duration, end);
123     }
124
125     /**
126      * Constructs an interval from a start instant and a time period.
127      * <p>
128      * When forming the interval, the chronology from the instant is used
129      * if present, otherwise the chronology of the period is used.
130      *
131      * @param start start of this interval, null means now
132      * @param period the period of this interval, null means zero length
133      * @throws IllegalArgumentException if the end is before the start
134      * @throws ArithmeticException if the end instant exceeds the capacity of a long
135      */

136     public MutableInterval(ReadableInstant start, ReadablePeriod period) {
137         super(start, period);
138     }
139
140     /**
141      * Constructs an interval from a time period and an end instant.
142      * <p>
143      * When forming the interval, the chronology from the instant is used
144      * if present, otherwise the chronology of the period is used.
145      *
146      * @param period the period of this interval, null means zero length
147      * @param end end of this interval, null means now
148      * @throws IllegalArgumentException if the end is before the start
149      * @throws ArithmeticException if the start instant exceeds the capacity of a long
150      */

151     public MutableInterval(ReadablePeriod period, ReadableInstant end) {
152         super(period, end);
153     }
154
155     /**
156      * Constructs a time interval by converting or copying from another object.
157      *
158      * @param interval the time interval to copy
159      * @throws IllegalArgumentException if the interval is invalid
160      */

161     public MutableInterval(Object JavaDoc interval) {
162         super(interval, null);
163     }
164
165     /**
166      * Constructs a time interval by converting or copying from another object,
167      * overriding the chronology.
168      *
169      * @param interval the time interval to copy
170      * @param chronology the chronology to use, null means ISO default
171      * @throws IllegalArgumentException if the interval is invalid
172      */

173     public MutableInterval(Object JavaDoc interval, Chronology chronology) {
174         super(interval, chronology);
175     }
176
177     //-----------------------------------------------------------------------
178
/**
179      * Sets this interval from two millisecond instants retaining the chronology.
180      *
181      * @param startInstant the start of the time interval
182      * @param endInstant the start of the time interval
183      * @throws IllegalArgumentException if the end is before the start
184      */

185     public void setInterval(long startInstant, long endInstant) {
186         super.setInterval(startInstant, endInstant, getChronology());
187     }
188
189     /**
190      * Sets this interval to be the same as another.
191      *
192      * @param interval the interval to copy
193      * @throws IllegalArgumentException if the interval is null
194      */

195     public void setInterval(ReadableInterval interval) {
196         if (interval == null) {
197             throw new IllegalArgumentException JavaDoc("Interval must not be null");
198         }
199         long startMillis = interval.getStartMillis();
200         long endMillis = interval.getEndMillis();
201         Chronology chrono = interval.getChronology();
202         super.setInterval(startMillis, endMillis, chrono);
203     }
204
205     /**
206      * Sets this interval from two instants, replacing the chronology with
207      * that from the start instant.
208      *
209      * @param start the start of the time interval
210      * @param end the start of the time interval
211      * @throws IllegalArgumentException if the end is before the start
212      */

213     public void setInterval(ReadableInstant start, ReadableInstant end) {
214         if (start == null && end == null) {
215             long now = DateTimeUtils.currentTimeMillis();
216             setInterval(now, now);
217         } else {
218             long startMillis = DateTimeUtils.getInstantMillis(start);
219             long endMillis = DateTimeUtils.getInstantMillis(end);
220             Chronology chrono = DateTimeUtils.getInstantChronology(start);
221             super.setInterval(startMillis, endMillis, chrono);
222         }
223     }
224
225     //-----------------------------------------------------------------------
226
/**
227      * Sets the chronology of this time interval.
228      *
229      * @param chrono the chronology to use, null means ISO default
230      */

231     public void setChronology(Chronology chrono) {
232         super.setInterval(getStartMillis(), getEndMillis(), chrono);
233     }
234
235     /**
236      * Sets the start of this time interval.
237      *
238      * @param startInstant the start of the time interval,
239      * millisecond instant from 1970-01-01T00:00:00Z
240      * @throws IllegalArgumentException if the end is before the start
241      */

242     public void setStartMillis(long startInstant) {
243         super.setInterval(startInstant, getEndMillis(), getChronology());
244     }
245
246     /**
247      * Sets the start of this time interval as an Instant.
248      *
249      * @param start the start of the time interval, null means now
250      * @throws IllegalArgumentException if the end is before the start
251      */

252     public void setStart(ReadableInstant start) {
253         long startMillis = DateTimeUtils.getInstantMillis(start);
254         super.setInterval(startMillis, getEndMillis(), getChronology());
255     }
256
257     /**
258      * Sets the end of this time interval.
259      *
260      * @param endInstant the end of the time interval,
261      * millisecond instant from 1970-01-01T00:00:00Z
262      * @throws IllegalArgumentException if the end is before the start
263      */

264     public void setEndMillis(long endInstant) {
265         super.setInterval(getStartMillis(), endInstant, getChronology());
266     }
267
268     /**
269      * Sets the end of this time interval as an Instant.
270      *
271      * @param end the end of the time interval, null means now
272      * @throws IllegalArgumentException if the end is before the start
273      */

274     public void setEnd(ReadableInstant end) {
275         long endMillis = DateTimeUtils.getInstantMillis(end);
276         super.setInterval(getStartMillis(), endMillis, getChronology());
277     }
278
279     //-----------------------------------------------------------------------
280
/**
281      * Sets the duration of this time interval, preserving the start instant.
282      *
283      * @param duration new duration for interval
284      * @throws IllegalArgumentException if the end is before the start
285      * @throws ArithmeticException if the end instant exceeds the capacity of a long
286      */

287     public void setDurationAfterStart(long duration) {
288         setEndMillis(FieldUtils.safeAdd(getStartMillis(), duration));
289     }
290
291     /**
292      * Sets the duration of this time interval, preserving the end instant.
293      *
294      * @param duration new duration for interval
295      * @throws IllegalArgumentException if the end is before the start
296      * @throws ArithmeticException if the start instant exceeds the capacity of a long
297      */

298     public void setDurationBeforeEnd(long duration) {
299         setStartMillis(FieldUtils.safeAdd(getEndMillis(), -duration));
300     }
301
302     //-----------------------------------------------------------------------
303
/**
304      * Sets the duration of this time interval, preserving the start instant.
305      *
306      * @param duration new duration for interval, null means zero length
307      * @throws IllegalArgumentException if the end is before the start
308      * @throws ArithmeticException if the end instant exceeds the capacity of a long
309      */

310     public void setDurationAfterStart(ReadableDuration duration) {
311         long durationMillis = DateTimeUtils.getDurationMillis(duration);
312         setEndMillis(FieldUtils.safeAdd(getStartMillis(), durationMillis));
313     }
314
315     /**
316      * Sets the duration of this time interval, preserving the end instant.
317      *
318      * @param duration new duration for interval, null means zero length
319      * @throws IllegalArgumentException if the end is before the start
320      * @throws ArithmeticException if the start instant exceeds the capacity of a long
321      */

322     public void setDurationBeforeEnd(ReadableDuration duration) {
323         long durationMillis = DateTimeUtils.getDurationMillis(duration);
324         setStartMillis(FieldUtils.safeAdd(getEndMillis(), -durationMillis));
325     }
326
327     //-----------------------------------------------------------------------
328
/**
329      * Sets the period of this time interval, preserving the start instant
330      * and using the ISOChronology in the default zone for calculations.
331      *
332      * @param period new period for interval, null means zero length
333      * @throws IllegalArgumentException if the end is before the start
334      * @throws ArithmeticException if the end instant exceeds the capacity of a long
335      */

336     public void setPeriodAfterStart(ReadablePeriod period) {
337         if (period == null) {
338             setEndMillis(getStartMillis());
339         } else {
340             setEndMillis(getChronology().add(period, getStartMillis(), 1));
341         }
342     }
343
344     /**
345      * Sets the period of this time interval, preserving the end instant
346      * and using the ISOChronology in the default zone for calculations.
347      *
348      * @param period new period for interval, null means zero length
349      * @throws IllegalArgumentException if the end is before the start
350      * @throws ArithmeticException if the start instant exceeds the capacity of a long
351      */

352     public void setPeriodBeforeEnd(ReadablePeriod period) {
353         if (period == null) {
354             setStartMillis(getEndMillis());
355         } else {
356             setStartMillis(getChronology().add(period, getEndMillis(), -1));
357         }
358     }
359
360     //-----------------------------------------------------------------------
361
/**
362      * Clone this object without having to cast the returned object.
363      *
364      * @return a clone of the this object.
365      */

366     public MutableInterval copy() {
367         return (MutableInterval) clone();
368     }
369
370     /**
371      * Clone this object.
372      *
373      * @return a clone of this object.
374      */

375     public Object JavaDoc clone() {
376         try {
377             return super.clone();
378         } catch (CloneNotSupportedException JavaDoc ex) {
379             throw new InternalError JavaDoc("Clone error");
380         }
381     }
382
383 }
384
Popular Tags