BaseDuration


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.base;
17  
18  import java.io.Serializable  ;
19  
20  import org.joda.time.Chronology;
21  import org.joda.time.DateTimeUtils;
22  import org.joda.time.Interval;
23  import org.joda.time.Period;
24  import org.joda.time.PeriodType;
25  import org.joda.time.ReadableDuration;
26  import org.joda.time.ReadableInstant;
27  import org.joda.time.convert.ConverterManager;
28  import org.joda.time.convert.DurationConverter;
29  import org.joda.time.field.FieldUtils;
30  
31  /**
32   * BaseDuration is an abstract implementation of ReadableDuration that stores
33   * data in a <code>long</code> duration milliseconds field.
34   * <p>
35   * This class should generally not be used directly by API users.
36   * The {@link ReadableDuration} interface should be used when different 
37   * kinds of duration objects are to be referenced.
38   * <p>
39   * BaseDuration subclasses may be mutable and not thread-safe.
40   *
41   * @author Brian S O'Neill
42   * @author Stephen Colebourne
43   * @since 1.0
44   */
45  public abstract class BaseDuration
46          extends AbstractDuration
47          implements ReadableDuration, Serializable   {
48  
49      /** Serialization version */
50      private static final long serialVersionUID = 2581698638990L;
51  
52      /** The duration length */
53      private long iMillis;
54  
55      /**
56       * Creates a duration from the given millisecond duration.
57       *
58       * @param duration  the duration, in milliseconds
59       */
60      protected BaseDuration(long duration) {
61          super();
62          iMillis = duration;
63      }
64  
65      /**
66       * Creates a duration from the given interval endpoints.
67       *
68       * @param startInstant  interval start, in milliseconds
69       * @param endInstant  interval end, in milliseconds
70       * @throws ArithmeticException if the duration exceeds a 64 bit long
71       */
72      protected BaseDuration(long startInstant, long endInstant) {
73          super();
74          iMillis = FieldUtils.safeAdd(endInstant, -startInstant);
75      }
76  
77      /**
78       * Creates a duration from the given interval endpoints.
79       *
80       * @param start  interval start, null means now
81       * @param end  interval end, null means now
82       * @throws ArithmeticException if the duration exceeds a 64 bit long
83       */
84      protected BaseDuration(ReadableInstant start, ReadableInstant end) {
85          super();
86          if (start == end) {
87              iMillis = 0L;
88          } else {
89              long startMillis = DateTimeUtils.getInstantMillis(start);
90              long endMillis = DateTimeUtils.getInstantMillis(end);
91              iMillis = FieldUtils.safeAdd(endMillis, -startMillis);
92          }
93      }
94  
95      /**
96       * Creates a duration from the specified object using the
97       * {@link org.joda.time.convert.ConverterManager ConverterManager}.
98       *
99       * @param duration  duration to convert
100      * @throws IllegalArgumentException if duration is invalid
101      */
102     protected BaseDuration(Object   duration) {
103         super();
104         DurationConverter converter = ConverterManager.getInstance().getDurationConverter(duration);
105         iMillis = converter.getDurationMillis(duration);
106     }
107 
108     //-----------------------------------------------------------------------
109     /**
110      * Gets the length of this duration in milliseconds.
111      *
112      * @return the length of the duration in milliseconds.
113      */
114     public long getMillis() {
115         return iMillis;
116     }
117 
118     //-----------------------------------------------------------------------
119     /**
120      * Sets the length of this duration in milliseconds.
121      * 
122      * @param duration  the new length of the duration
123      */
124     protected void setMillis(long duration) {
125         iMillis = duration;
126     }
127 
128     //-----------------------------------------------------------------------
129     /**
130      * Converts this duration to a Period instance using the specified period type
131      * and the ISO chronology.
132      * <p>
133      * Only precise fields in the period type will be used.
134      * At most these are hours, minutes, seconds and millis - the period
135      * type may restrict the selection further.
136      * <p>
137      * For more control over the conversion process, you must pair the duration with
138      * an instant, see {@link #toPeriodFrom(ReadableInstant, PeriodType)}.
139      * 
140      * @param type  the period type to use, null means standard
141      * @return a Period created using the millisecond duration from this instance
142      */
143     public Period toPeriod(PeriodType type) {
144         return new Period(getMillis(), type);
145     }
146 
147     /**
148      * Converts this duration to a Period instance using the standard period type
149      * and the specified chronology.
150      * <p>
151      * Only precise fields in the period type will be used.
152      * Exactly which fields are precise depends on the chronology.
153      * Only the time fields are precise for ISO chronology with a time zone.
154      * However, ISO UTC also has precise days and weeks.
155      * <p>
156      * For more control over the conversion process, you must pair the duration with
157      * an instant, see {@link #toPeriodFrom(ReadableInstant)} and
158      * {@link #toPeriodTo(ReadableInstant)}
159      * 
160      * @param chrono  the chronology to use, null means ISO default
161      * @return a Period created using the millisecond duration from this instance
162      */
163     public Period toPeriod(Chronology chrono) {
164         return new Period(getMillis(), chrono);
165     }
166 
167     /**
168      * Converts this duration to a Period instance using the specified period type
169      * and chronology.
170      * <p>
171      * Only precise fields in the period type will be used.
172      * Exactly which fields are precise depends on the chronology.
173      * Only the time fields are precise for ISO chronology with a time zone.
174      * However, ISO UTC also has precise days and weeks.
175      * <p>
176      * For more control over the conversion process, you must pair the duration with
177      * an instant, see {@link #toPeriodFrom(ReadableInstant, PeriodType)} and
178      * {@link #toPeriodTo(ReadableInstant, PeriodType)}
179      * 
180      * @param type  the period type to use, null means standard
181      * @param chrono  the chronology to use, null means ISO default
182      * @return a Period created using the millisecond duration from this instance
183      */
184     public Period toPeriod(PeriodType type, Chronology chrono) {
185         return new Period(getMillis(), type, chrono);
186     }
187 
188     /**
189      * Converts this duration to a Period instance by adding the duration to a start
190      * instant to obtain an interval using the standard period type.
191      * <p>
192      * This conversion will determine the fields of a period accurately.
193      * The results are based on the instant millis, the chronology of the instant,
194      * the standard period type and the length of this duration.
195      * 
196      * @param startInstant  the instant to calculate the period from, null means now
197      * @return a Period created using the millisecond duration from this instance
198      */
199     public Period toPeriodFrom(ReadableInstant startInstant) {
200         return new Period(startInstant, this);
201     }
202 
203     /**
204      * Converts this duration to a Period instance by adding the duration to a start
205      * instant to obtain an interval.
206      * <p>
207      * This conversion will determine the fields of a period accurately.
208      * The results are based on the instant millis, the chronology of the instant,
209      * the period type and the length of this duration.
210      * 
211      * @param startInstant  the instant to calculate the period from, null means now
212      * @param type  the period type determining how to split the duration into fields, null means All type
213      * @return a Period created using the millisecond duration from this instance
214      */
215     public Period toPeriodFrom(ReadableInstant startInstant, PeriodType type) {
216         return new Period(startInstant, this, type);
217     }
218 
219     /**
220      * Converts this duration to a Period instance by subtracting the duration
221      * from an end instant to obtain an interval using the standard period
222      * type.
223      * <p>
224      * This conversion will determine the fields of a period accurately.
225      * The results are based on the instant millis, the chronology of the instant,
226      * the standard period type and the length of this duration.
227      * 
228      * @param endInstant  the instant to calculate the period to, null means now
229      * @return a Period created using the millisecond duration from this instance
230      */
231     public Period toPeriodTo(ReadableInstant endInstant) {
232         return new Period(this, endInstant);
233     }
234 
235     /**
236      * Converts this duration to a Period instance by subtracting the duration
237      * from an end instant to obtain an interval using the standard period
238      * type.
239      * <p>
240      * This conversion will determine the fields of a period accurately.
241      * The results are based on the instant millis, the chronology of the instant,
242      * the period type and the length of this duration.
243      * 
244      * @param endInstant  the instant to calculate the period to, null means now
245      * @param type  the period type determining how to split the duration into fields, null means All type
246      * @return a Period created using the millisecond duration from this instance
247      */
248     public Period toPeriodTo(ReadableInstant endInstant, PeriodType type) {
249         return new Period(this, endInstant, type);
250     }
251 
252     /**
253      * Converts this duration to an Interval starting at the specified instant.
254      * 
255      * @param startInstant  the instant to start the interval at, null means now
256      * @return an Interval starting at the specified instant
257      */
258     public Interval toIntervalFrom(ReadableInstant startInstant) {
259         return new Interval(startInstant, this);
260     }
261 
262     /**
263      * Converts this duration to an Interval ending at the specified instant.
264      * 
265      * @param endInstant  the instant to end the interval at, null means now
266      * @return an Interval ending at the specified instant
267      */
268     public Interval toIntervalTo(ReadableInstant endInstant) {
269         return new Interval(this, endInstant);
270     }
271 
272 }
273
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags