org.joda.time

Class Instant

Implemented Interfaces:
Comparable, ReadableInstant, Serializable

public final class Instant
extends AbstractInstant
implements ReadableInstant, Serializable

Instant is the standard implementation of a fully immutable instant in time.

Instant is an implementation of 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

Constructor Summary

Instant()
Constructs an instance set to the current system millisecond time.
Instant(Object instant)
Constructs an instance from an Object that represents a datetime.
Instant(long instant)
Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z.

Method Summary

Chronology
getChronology()
Gets the chronology of the instant, which is ISO in the UTC zone.
long
getMillis()
Gets the milliseconds of the instant.
Instant
minus(long duration)
Gets a copy of this instant with the specified duration taken away.
Instant
minus(ReadableDuration duration)
Gets a copy of this instant with the specified duration taken away.
Instant
plus(long duration)
Gets a copy of this instant with the specified duration added.
Instant
plus(ReadableDuration duration)
Gets a copy of this instant with the specified duration added.
DateTime
toDateTime()
Get this object as a DateTime using ISOChronology in the default zone.
DateTime
toDateTimeISO()
Deprecated. Use toDateTime() as it is identical
Instant
toInstant()
Get this object as an Instant by returning this.
MutableDateTime
toMutableDateTime()
Get this object as a MutableDateTime using ISOChronology in the default zone.
MutableDateTime
toMutableDateTimeISO()
Deprecated. Use toMutableDateTime() as it is identical
Instant
withDurationAdded(long durationToAdd, int scalar)
Gets a copy of this instant with the specified duration added.
Instant
withDurationAdded(ReadableDuration durationToAdd, int scalar)
Gets a copy of this instant with the specified duration added.
Instant
withMillis(long newMillis)
Gets a copy of this instant with different millis.

Methods inherited from class org.joda.time.base.AbstractInstant

compareTo, equals, get, get, getZone, hashCode, isAfter, isAfter, isAfterNow, isBefore, isBefore, isBeforeNow, isEqual, isEqual, isEqualNow, isSupported, toDate, toDateTime, toDateTime, toDateTime, toDateTimeISO, toInstant, toMutableDateTime, toMutableDateTime, toMutableDateTime, toMutableDateTimeISO, toString, toString

Constructor Details

Instant

public Instant()
Constructs an instance set to the current system millisecond time.

Instant

public Instant(Object instant)
Parameters:
instant - the datetime object, null means now

Instant

public Instant(long instant)
Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z.
Parameters:
instant - the milliseconds from 1970-01-01T00:00:00Z

Method Details

getChronology

public Chronology getChronology()
Gets the chronology of the instant, which is ISO in the UTC zone.

This method returns ISOChronology.getInstanceUTC() which corresponds to the definition of the Java epoch 1970-01-01T00:00:00Z.

Specified by:
getChronology in interface ReadableInstant
Returns:
ISO in the UTC zone

getMillis

public long getMillis()
Gets the milliseconds of the instant.
Specified by:
getMillis in interface ReadableInstant
Returns:
the number of milliseconds since 1970-01-01T00:00:00Z

minus

public Instant minus(long duration)
Gets a copy of this instant with the specified duration taken away.

If the amount is zero or null, then this is returned.

Parameters:
duration - the duration to reduce this instant by
Returns:
a copy of this instant with the duration taken away

minus

public Instant minus(ReadableDuration duration)
Gets a copy of this instant with the specified duration taken away.

If the amount is zero or null, then this is returned.

Parameters:
duration - the duration to reduce this instant by
Returns:
a copy of this instant with the duration taken away

plus

public Instant plus(long duration)
Gets a copy of this instant with the specified duration added.

If the amount is zero or null, then this is returned.

Parameters:
duration - the duration to add to this one
Returns:
a copy of this instant with the duration added

plus

public Instant plus(ReadableDuration duration)
Gets a copy of this instant with the specified duration added.

If the amount is zero or null, then this is returned.

Parameters:
duration - the duration to add to this one, null means zero
Returns:
a copy of this instant with the duration added

toDateTime

public DateTime toDateTime()
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 compatability with earlier versions of Joda-Time.

Overrides:
toDateTime in interface AbstractInstant
Returns:
a DateTime using the same millis

toDateTimeISO

public DateTime toDateTimeISO()

Deprecated. Use toDateTime() as it is identical

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 definition preserves compatability with earlier versions of Joda-Time.

Overrides:
toDateTimeISO in interface AbstractInstant
Returns:
a DateTime using the same millis with ISOChronology

toInstant

public Instant toInstant()
Get this object as an Instant by returning this.
Specified by:
toInstant in interface ReadableInstant
Overrides:
toInstant in interface AbstractInstant
Returns:
this

toMutableDateTime

public MutableDateTime toMutableDateTime()
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 compatability with earlier versions of Joda-Time.

Overrides:
toMutableDateTime in interface AbstractInstant
Returns:
a MutableDateTime using the same millis

toMutableDateTimeISO

public MutableDateTime toMutableDateTimeISO()

Deprecated. Use toMutableDateTime() as it is identical

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 definition preserves compatability with earlier versions of Joda-Time.

Overrides:
toMutableDateTimeISO in interface AbstractInstant
Returns:
a MutableDateTime using the same millis with ISOChronology

withDurationAdded

public Instant withDurationAdded(long durationToAdd,
                                 int scalar)
Gets a copy of this instant with the specified duration added.

If the addition is zero, then this is returned.

Parameters:
durationToAdd - the duration to add to this one
scalar - the amount of times to add, such as -1 to subtract once
Returns:
a copy of this instant with the duration added

withDurationAdded

public Instant withDurationAdded(ReadableDuration durationToAdd,
                                 int scalar)
Gets a copy of this instant with the specified duration added.

If the addition is zero, then this is returned.

Parameters:
durationToAdd - the duration to add to this one, null means zero
scalar - the amount of times to add, such as -1 to subtract once
Returns:
a copy of this instant with the duration added

withMillis

public Instant withMillis(long newMillis)
Gets a copy of this instant with different millis.

The returned object will be either be a new Instant or this.

Parameters:
newMillis - the new millis, from 1970-01-01T00:00:00Z
Returns:
a copy of this instant with different millis

Copyright (c) 2001-2006 - Joda.org