Class Instant
- All Implemented Interfaces:
Serializable
,Comparable<ReadableInstant>
,ReadableInstant
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.
- Since:
- 1.0
- Author:
- Stephen Colebourne
- See Also:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionGets the chronology of the instant, which is ISO in the UTC zone.long
Gets the milliseconds of the instant.minus
(long duration) Gets a copy of this instant with the specified duration taken away.minus
(ReadableDuration duration) Gets a copy of this instant with the specified duration taken away.static Instant
now()
Obtains anInstant
set to the current system millisecond time.static Instant
ofEpochMilli
(long epochMilli) Obtains anInstant
set to the milliseconds from 1970-01-01T00:00:00Z.static Instant
ofEpochSecond
(long epochSecond) Obtains anInstant
set to the seconds from 1970-01-01T00:00:00Z.static Instant
Parses anInstant
from the specified string.static Instant
parse
(String str, DateTimeFormatter formatter) Parses anInstant
from the specified string using a formatter.plus
(long duration) Gets a copy of this instant with the specified duration added.plus
(ReadableDuration duration) Gets a copy of this instant with the specified duration added.Get this object as a DateTime using ISOChronology in the default zone.Deprecated.Use toDateTime() as it is identicalGet this object as an Instant by returningthis
.Get this object as a MutableDateTime using ISOChronology in the default zone.Deprecated.Use toMutableDateTime() as it is identicalwithDurationAdded
(long durationToAdd, int scalar) Gets a copy of this instant with the specified duration added.withDurationAdded
(ReadableDuration durationToAdd, int scalar) Gets a copy of this instant with the specified duration added.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, toMutableDateTime, toMutableDateTime, toString, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface org.joda.time.ReadableInstant
equals, get, getZone, hashCode, isAfter, isBefore, isEqual, isSupported, toString
-
Field Details
-
EPOCH
The Java epoch of 1970-01-01T00:00:00Z.- Since:
- 2.10
-
-
Constructor Details
-
Instant
public Instant()Constructs an instance set to the current system millisecond time.- See Also:
-
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
-
Instant
Constructs an instance from an Object that represents a datetime.The recognised object types are defined in
ConverterManager
and include String, Calendar and Date.- Parameters:
instant
- the datetime object, null means now- Throws:
IllegalArgumentException
- if the instant is invalid
-
-
Method Details
-
now
Obtains anInstant
set to the current system millisecond time.- Returns:
- the current instant, not null
- Since:
- 2.0
-
ofEpochMilli
Obtains anInstant
set to the milliseconds from 1970-01-01T00:00:00Z.- Parameters:
epochMilli
- the milliseconds from 1970-01-01T00:00:00Z- Returns:
- the instant, not null
- Since:
- 2.10
-
ofEpochSecond
Obtains anInstant
set to the seconds from 1970-01-01T00:00:00Z.- Parameters:
epochSecond
- the seconds from 1970-01-01T00:00:00Z- Returns:
- the instant, not null
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long- Since:
- 2.10
-
parse
Parses anInstant
from the specified string.This uses
ISODateTimeFormat.dateTimeParser()
.- Parameters:
str
- the string to parse, not null- Returns:
- the parsed instant, not null
- Since:
- 2.0
-
parse
Parses anInstant
from the specified string using a formatter.- Parameters:
str
- the string to parse, not nullformatter
- the formatter to use, not null- Returns:
- the parsed instant, not null
- Since:
- 2.0
-
toInstant
Get this object as an Instant by returningthis
.- Specified by:
toInstant
in interfaceReadableInstant
- Overrides:
toInstant
in classAbstractInstant
- Returns:
this
-
withMillis
Gets a copy of this instant with different millis.The returned object will be either be a new Instant or
this
.Note that this replaces the entire state of the
Instant
. To manage the sub-second part of the instant, usetoDateTime()
andDateTime.withMillisOfSecond(int)
.- Parameters:
newMillis
- the new millis, from 1970-01-01T00:00:00Z- Returns:
- a copy of this instant with different millis
-
withDurationAdded
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 onescalar
- the amount of times to add, such as -1 to subtract once- Returns:
- a copy of this instant with the duration added
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
withDurationAdded
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 zeroscalar
- the amount of times to add, such as -1 to subtract once- Returns:
- a copy of this instant with the duration added
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
plus
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
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
plus
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
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
minus
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
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
minus
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
- Throws:
ArithmeticException
- if the new instant exceeds the capacity of a long
-
getMillis
public long getMillis()Gets the milliseconds of the instant.- Specified by:
getMillis
in interfaceReadableInstant
- Returns:
- the number of milliseconds since 1970-01-01T00:00:00Z
-
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 interfaceReadableInstant
- Returns:
- ISO in the UTC zone
-
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 compatibility with earlier versions of Joda-Time.
- Overrides:
toDateTime
in classAbstractInstant
- Returns:
- a DateTime using the same millis
-
toDateTimeISO
Deprecated.Use toDateTime() as it is identicalGet this object as a DateTime using ISOChronology in the default zone. This method is identical totoDateTime()
.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
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.
- Overrides:
toDateTimeISO
in classAbstractInstant
- Returns:
- a DateTime using the same millis with ISOChronology
-
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 compatibility with earlier versions of Joda-Time.
- Overrides:
toMutableDateTime
in classAbstractInstant
- Returns:
- a MutableDateTime using the same millis
-
toMutableDateTimeISO
Deprecated.Use toMutableDateTime() as it is identicalGet this object as a MutableDateTime using ISOChronology in the default zone. This method is identical totoMutableDateTime()
.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
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.
- Overrides:
toMutableDateTimeISO
in classAbstractInstant
- Returns:
- a MutableDateTime using the same millis with ISOChronology
-