Instant


1   /*
2    *  Copyright 2001-2006 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.AbstractInstant;
21  import org.joda.time.chrono.ISOChronology;
22  import org.joda.time.convert.ConverterManager;
23  import org.joda.time.convert.InstantConverter;
24  
25  /**
26   * Instant is the standard implementation of a fully immutable instant in time.
27   * It holds the instant as milliseconds from the Java Epoch of 1970-01-01T00:00:00Z.
28   * <p>
29   * The chronology used is always ISO in the UTC time zone.
30   * This corresponds to the definition of the Java Epoch.
31   * <p>
32   * An Instant can be used to compare two <code>DateTime</code> objects:
33   * <pre>
34   * boolean sameInstant = dt1.toInstant().equals(dt2.toInstant());
35   * </pre>
36   * This code will return true if the two <code>DateTime</code> objects represent
37   * the same instant regardless of chronology or time zone.
38   * <p>
39   * Note that the following code will also perform the same check:
40   * <pre>
41   * boolean sameInstant = dt1.isEqual(dt2);
42   * </pre>
43   * <p>
44   * Instant is thread-safe and immutable.
45   *
46   * @author Stephen Colebourne
47   * @since 1.0
48   */
49  public final class Instant
50          extends AbstractInstant
51          implements ReadableInstant, Serializable   {
52  
53      /** Serialization lock */
54      private static final long serialVersionUID = 3299096530934209741L;
55  
56      /** The millis from 1970-01-01T00:00:00Z */
57      private final long iMillis;
58  
59      //-----------------------------------------------------------------------
60      /**
61       * Constructs an instance set to the current system millisecond time.
62       */
63      public Instant() {
64          super();
65          iMillis = DateTimeUtils.currentTimeMillis();
66      }
67  
68      /**
69       * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z.
70       * 
71       * @param instant  the milliseconds from 1970-01-01T00:00:00Z
72       */
73      public Instant(long instant) {
74          super();
75          iMillis = instant;
76      }
77  
78      /**
79       * Constructs an instance from an Object that represents a datetime.
80       * <p>
81       * The recognised object types are defined in {@link ConverterManager} and
82       * include String, Calendar and Date.
83       *
84       * @param instant  the datetime object, null means now
85       * @throws IllegalArgumentException if the instant is invalid
86       */
87      public Instant(Object   instant) {
88          super();
89          InstantConverter converter = ConverterManager.getInstance().getInstantConverter(instant);
90          iMillis = converter.getInstantMillis(instant, ISOChronology.getInstanceUTC());
91      }
92  
93      //-----------------------------------------------------------------------
94      /**
95       * Get this object as an Instant by returning <code>this</code>.
96       * 
97       * @return <code>this</code>
98       */
99      public Instant toInstant() {
100         return this;
101     }
102 
103     //-----------------------------------------------------------------------
104     /**
105      * Gets a copy of this instant with different millis.
106      * <p>
107      * The returned object will be either be a new Instant or <code>this</code>.
108      *
109      * @param newMillis  the new millis, from 1970-01-01T00:00:00Z
110      * @return a copy of this instant with different millis
111      */
112     public Instant withMillis(long newMillis) {
113         return (newMillis == iMillis ? this : new Instant(newMillis));
114     }
115 
116     /**
117      * Gets a copy of this instant with the specified duration added.
118      * <p>
119      * If the addition is zero, then <code>this</code> is returned.
120      * 
121      * @param durationToAdd  the duration to add to this one
122      * @param scalar  the amount of times to add, such as -1 to subtract once
123      * @return a copy of this instant with the duration added
124      * @throws ArithmeticException if the new instant exceeds the capacity of a long
125      */
126     public Instant withDurationAdded(long durationToAdd, int scalar) {
127         if (durationToAdd == 0 || scalar == 0) {
128             return this;
129         }
130         long instant = getChronology().add(getMillis(), durationToAdd, scalar);
131         return withMillis(instant);
132     }
133 
134     /**
135      * Gets a copy of this instant with the specified duration added.
136      * <p>
137      * If the addition is zero, then <code>this</code> is returned.
138      * 
139      * @param durationToAdd  the duration to add to this one, null means zero
140      * @param scalar  the amount of times to add, such as -1 to subtract once
141      * @return a copy of this instant with the duration added
142      * @throws ArithmeticException if the new instant exceeds the capacity of a long
143      */
144     public Instant withDurationAdded(ReadableDuration durationToAdd, int scalar) {
145         if (durationToAdd == null || scalar == 0) {
146             return this;
147         }
148         return withDurationAdded(durationToAdd.getMillis(), scalar);
149     }
150 
151     //-----------------------------------------------------------------------
152     /**
153      * Gets a copy of this instant with the specified duration added.
154      * <p>
155      * If the amount is zero or null, then <code>this</code> is returned.
156      * 
157      * @param duration  the duration to add to this one
158      * @return a copy of this instant with the duration added
159      * @throws ArithmeticException if the new instant exceeds the capacity of a long
160      */
161     public Instant plus(long duration) {
162         return withDurationAdded(duration, 1);
163     }
164 
165     /**
166      * Gets a copy of this instant with the specified duration added.
167      * <p>
168      * If the amount is zero or null, then <code>this</code> is returned.
169      * 
170      * @param duration  the duration to add to this one, null means zero
171      * @return a copy of this instant with the duration added
172      * @throws ArithmeticException if the new instant exceeds the capacity of a long
173      */
174     public Instant plus(ReadableDuration duration) {
175         return withDurationAdded(duration, 1);
176     }
177 
178     //-----------------------------------------------------------------------
179     /**
180      * Gets a copy of this instant with the specified duration taken away.
181      * <p>
182      * If the amount is zero or null, then <code>this</code> is returned.
183      * 
184      * @param duration  the duration to reduce this instant by
185      * @return a copy of this instant with the duration taken away
186      * @throws ArithmeticException if the new instant exceeds the capacity of a long
187      */
188     public Instant minus(long duration) {
189         return withDurationAdded(duration, -1);
190     }
191 
192     /**
193      * Gets a copy of this instant with the specified duration taken away.
194      * <p>
195      * If the amount is zero or null, then <code>this</code> is returned.
196      * 
197      * @param duration  the duration to reduce this instant by
198      * @return a copy of this instant with the duration taken away
199      * @throws ArithmeticException if the new instant exceeds the capacity of a long
200      */
201     public Instant minus(ReadableDuration duration) {
202         return withDurationAdded(duration, -1);
203     }
204 
205     //-----------------------------------------------------------------------
206     /**
207      * Gets the milliseconds of the instant.
208      * 
209      * @return the number of milliseconds since 1970-01-01T00:00:00Z
210      */
211     public long getMillis() {
212         return iMillis;
213     }
214 
215     /**
216      * Gets the chronology of the instant, which is ISO in the UTC zone.
217      * 
218      * @return ISO in the UTC zone
219      */
220     public Chronology getChronology() {
221         return ISOChronology.getInstanceUTC();
222     }
223 
224     //-----------------------------------------------------------------------
225     /**
226      * Get this object as a DateTime using ISOChronology in the default zone.
227      * <p>
228      * This method returns a DateTime object in the default zone.
229      * This differs from the similarly named method on DateTime, DateMidnight
230      * or MutableDateTime which retains the time zone. The difference is
231      * because Instant really represents a time <i>without</i> a zone,
232      * thus calling this method we really have no zone to 'retain' and
233      * hence expect to switch to the default zone.
234      * <p>
235      * This method definition preserves compatability with earlier versions
236      * of Joda-Time.
237      *
238      * @return a DateTime using the same millis
239      */
240     public DateTime toDateTime() {
241         return new DateTime(getMillis(), ISOChronology.getInstance());
242     }
243 
244     /**
245      * Get this object as a DateTime using ISOChronology in the default zone.
246      * This method is identical to <code>toDateTime()</code>.
247      * <p>
248      * This method returns a DateTime object in the default zone.
249      * This differs from the similarly named method on DateTime, DateMidnight
250      * or MutableDateTime which retains the time zone. The difference is
251      * because Instant really represents a time <i>without</i> a zone,
252      * thus calling this method we really have no zone to 'retain' and
253      * hence expect to switch to the default zone.
254      * <p>
255      * This method definition preserves compatability with earlier versions
256      * of Joda-Time.
257      *
258      * @return a DateTime using the same millis with ISOChronology
259      * @deprecated Use toDateTime() as it is identical
260      */
261     public DateTime toDateTimeISO() {
262         return toDateTime();
263     }
264 
265     /**
266      * Get this object as a MutableDateTime using ISOChronology in the default zone.
267      * <p>
268      * This method returns a MutableDateTime object in the default zone.
269      * This differs from the similarly named method on DateTime, DateMidnight
270      * or MutableDateTime which retains the time zone. The difference is
271      * because Instant really represents a time <i>without</i> a zone,
272      * thus calling this method we really have no zone to 'retain' and
273      * hence expect to switch to the default zone.
274      * <p>
275      * This method definition preserves compatability with earlier versions
276      * of Joda-Time.
277      *
278      * @return a MutableDateTime using the same millis
279      */
280     public MutableDateTime toMutableDateTime() {
281         return new MutableDateTime(getMillis(), ISOChronology.getInstance());
282     }
283 
284     /**
285      * Get this object as a MutableDateTime using ISOChronology in the default zone.
286      * This method is identical to <code>toMutableDateTime()</code>.
287      * <p>
288      * This method returns a MutableDateTime object in the default zone.
289      * This differs from the similarly named method on DateTime, DateMidnight
290      * or MutableDateTime which retains the time zone. The difference is
291      * because Instant really represents a time <i>without</i> a zone,
292      * thus calling this method we really have no zone to 'retain' and
293      * hence expect to switch to the default zone.
294      * <p>
295      * This method definition preserves compatability with earlier versions
296      * of Joda-Time.
297      *
298      * @return a MutableDateTime using the same millis with ISOChronology
299      * @deprecated Use toMutableDateTime() as it is identical
300      */
301     public MutableDateTime toMutableDateTimeISO() {
302         return toMutableDateTime();
303     }
304 
305 }
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags