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  ;
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  , Serializable   {
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   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   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  ("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   clone() {
376         try {
377             return super.clone();
378         } catch (CloneNotSupportedException   ex) {
379             throw new InternalError  ("Clone error");
380         }
381     }
382 
383 }
384
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags