* Instant is an implementation of {@link ReadableInstant}.
* As with all instants, it represents an exact point on the time-line,
* but limited to the precision of milliseconds. An Instant
* should be used to represent a point in time irrespective of any other
* factor, such as chronology or time zone.
*
* Internally, the class holds one piece of data, the instant as milliseconds * from the Java epoch of 1970-01-01T00:00:00Z. *
* For example, an Instant can be used to compare two DateTime
* objects irrespective of chronology or time zone.
*
* boolean sameInstant = dt1.toInstant().equals(dt2.toInstant()); ** Note that the following code will also perform the same check: *
* boolean sameInstant = dt1.isEqual(dt2); **
* Instant is thread-safe and immutable. * * @author Stephen Colebourne * @since 1.0 */ public final class Instant extends AbstractInstant implements ReadableInstant, Serializable { /** Serialization lock */ private static final long serialVersionUID = 3299096530934209741L; /** The millis from 1970-01-01T00:00:00Z */ private final long iMillis; //----------------------------------------------------------------------- /** * Obtains an {@code Instant} set to the current system millisecond time. * * @return the current instant, not null * @since 2.0 */ public static Instant now() { return new Instant(); } //----------------------------------------------------------------------- /** * Parses a {@code Instant} from the specified string. *
* This uses {@link ISODateTimeFormat#dateTimeParser()}. * * @param str the string to parse, not null * @since 2.0 */ @FromString public static Instant parse(String str) { return parse(str, ISODateTimeFormat.dateTimeParser()); } /** * Parses a {@code Instant} from the specified string using a formatter. * * @param str the string to parse, not null * @param formatter the formatter to use, not null * @since 2.0 */ public static Instant parse(String str, DateTimeFormatter formatter) { return formatter.parseDateTime(str).toInstant(); } //----------------------------------------------------------------------- /** * Constructs an instance set to the current system millisecond time. * * @see #now() */ public Instant() { super(); iMillis = DateTimeUtils.currentTimeMillis(); } /** * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z. * * @param instant the milliseconds from 1970-01-01T00:00:00Z */ public Instant(long instant) { super(); iMillis = instant; } /** * Constructs an instance from an Object that represents a datetime. *
* The recognised object types are defined in {@link ConverterManager} and
* include String, Calendar and Date.
*
* @param instant the datetime object, null means now
* @throws IllegalArgumentException if the instant is invalid
*/
public Instant(Object instant) {
super();
InstantConverter converter = ConverterManager.getInstance().getInstantConverter(instant);
iMillis = converter.getInstantMillis(instant, ISOChronology.getInstanceUTC());
}
//-----------------------------------------------------------------------
/**
* Get this object as an Instant by returning this.
*
* @return this
*/
public Instant toInstant() {
return this;
}
//-----------------------------------------------------------------------
/**
* Gets a copy of this instant with different millis.
*
* The returned object will be either be a new Instant or this.
*
* @param newMillis the new millis, from 1970-01-01T00:00:00Z
* @return a copy of this instant with different millis
*/
public Instant withMillis(long newMillis) {
return (newMillis == iMillis ? this : new Instant(newMillis));
}
/**
* Gets a copy of this instant with the specified duration added.
*
* If the addition is zero, then this is returned.
*
* @param durationToAdd the duration to add to this one
* @param scalar the amount of times to add, such as -1 to subtract once
* @return a copy of this instant with the duration added
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant withDurationAdded(long durationToAdd, int scalar) {
if (durationToAdd == 0 || scalar == 0) {
return this;
}
long instant = getChronology().add(getMillis(), durationToAdd, scalar);
return withMillis(instant);
}
/**
* Gets a copy of this instant with the specified duration added.
*
* If the addition is zero, then this is returned.
*
* @param durationToAdd the duration to add to this one, null means zero
* @param scalar the amount of times to add, such as -1 to subtract once
* @return a copy of this instant with the duration added
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant withDurationAdded(ReadableDuration durationToAdd, int scalar) {
if (durationToAdd == null || scalar == 0) {
return this;
}
return withDurationAdded(durationToAdd.getMillis(), scalar);
}
//-----------------------------------------------------------------------
/**
* Gets a copy of this instant with the specified duration added.
*
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to add to this one
* @return a copy of this instant with the duration added
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant plus(long duration) {
return withDurationAdded(duration, 1);
}
/**
* Gets a copy of this instant with the specified duration added.
*
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to add to this one, null means zero
* @return a copy of this instant with the duration added
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant plus(ReadableDuration duration) {
return withDurationAdded(duration, 1);
}
//-----------------------------------------------------------------------
/**
* Gets a copy of this instant with the specified duration taken away.
*
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to reduce this instant by
* @return a copy of this instant with the duration taken away
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant minus(long duration) {
return withDurationAdded(duration, -1);
}
/**
* Gets a copy of this instant with the specified duration taken away.
*
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to reduce this instant by
* @return a copy of this instant with the duration taken away
* @throws ArithmeticException if the new instant exceeds the capacity of a long
*/
public Instant minus(ReadableDuration duration) {
return withDurationAdded(duration, -1);
}
//-----------------------------------------------------------------------
/**
* Gets the milliseconds of the instant.
*
* @return the number of milliseconds since 1970-01-01T00:00:00Z
*/
public long getMillis() {
return iMillis;
}
/**
* Gets the chronology of the instant, which is ISO in the UTC zone.
*
* This method returns {@link ISOChronology#getInstanceUTC()} which * corresponds to the definition of the Java epoch 1970-01-01T00:00:00Z. * * @return ISO in the UTC zone */ public Chronology getChronology() { return ISOChronology.getInstanceUTC(); } //----------------------------------------------------------------------- /** * Get this object as a DateTime using ISOChronology in the default zone. *
* This method returns a DateTime object in the default zone. * This differs from the similarly named method on DateTime, DateMidnight * or MutableDateTime which retains the time zone. The difference is * because Instant really represents a time without a zone, * thus calling this method we really have no zone to 'retain' and * hence expect to switch to the default zone. *
* This method definition preserves compatibility with earlier versions
* of Joda-Time.
*
* @return a DateTime using the same millis
*/
public DateTime toDateTime() {
return new DateTime(getMillis(), ISOChronology.getInstance());
}
/**
* Get this object as a DateTime using ISOChronology in the default zone.
* This method is identical to toDateTime().
*
* This method returns a DateTime object in the default zone. * This differs from the similarly named method on DateTime, DateMidnight * or MutableDateTime which retains the time zone. The difference is * because Instant really represents a time without a zone, * thus calling this method we really have no zone to 'retain' and * hence expect to switch to the default zone. *
* This method is deprecated because it is a duplicate of {@link #toDateTime()}. * However, removing it would cause the superclass implementation to be used, * which would create silent bugs in any caller depending on this implementation. * As such, the method itself is not currently planned to be removed. *
* This method definition preserves compatibility with earlier versions * of Joda-Time. * * @return a DateTime using the same millis with ISOChronology * @deprecated Use toDateTime() as it is identical */ @Deprecated public DateTime toDateTimeISO() { return toDateTime(); } /** * Get this object as a MutableDateTime using ISOChronology in the default zone. *
* This method returns a MutableDateTime object in the default zone. * This differs from the similarly named method on DateTime, DateMidnight * or MutableDateTime which retains the time zone. The difference is * because Instant really represents a time without a zone, * thus calling this method we really have no zone to 'retain' and * hence expect to switch to the default zone. *
* This method definition preserves compatibility with earlier versions
* of Joda-Time.
*
* @return a MutableDateTime using the same millis
*/
public MutableDateTime toMutableDateTime() {
return new MutableDateTime(getMillis(), ISOChronology.getInstance());
}
/**
* Get this object as a MutableDateTime using ISOChronology in the default zone.
* This method is identical to toMutableDateTime().
*
* This method returns a MutableDateTime object in the default zone. * This differs from the similarly named method on DateTime, DateMidnight * or MutableDateTime which retains the time zone. The difference is * because Instant really represents a time without a zone, * thus calling this method we really have no zone to 'retain' and * hence expect to switch to the default zone. *
* This method is deprecated because it is a duplicate of {@link #toMutableDateTime()}. * However, removing it would cause the superclass implementation to be used, * which would create silent bugs in any caller depending on this implementation. * As such, the method itself is not currently planned to be removed. *
* This method definition preserves compatibility with earlier versions * of Joda-Time. * * @return a MutableDateTime using the same millis with ISOChronology * @deprecated Use toMutableDateTime() as it is identical */ @Deprecated public MutableDateTime toMutableDateTimeISO() { return toMutableDateTime(); } }