public final class Instant extends Object implements InstantProvider, Comparable<Instant>, Serializable
The Time Framework for Java models time as a series of instantaneous events, known as instants, along a single time-line. This class represents one of those instants.
An instant is in reality an instantaneous event on an infinite time-line.
However, for practicality this API uses a precision of nanoseconds.
In addition, this API limits the measurable time-line to the number of seconds
that can be held in a long
.
This is greater than the current estimated age of the universe.
In order to represent the data a 96 bit number is required. To achieve this the
data is stored as seconds, measured using a long
, and nanoseconds,
measured using an int
. The nanosecond part will always be between
0 and 999,999,999 representing the nanosecond part of the second.
The seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z
.
Instants on the time-line after the epoch are positive, earlier are negative.
Instant
uses the UTC-SLS
time-scale which always has 86400 seconds in a day.
Essentially, UTC-SLS is a consistent mechanism of converting an accurate UTC time
(potentially with leap seconds) to a 86400 second day.
Its main benefit is that in an accurate implementation, the UTC-SLS time never experiences
any gaps or overlaps.
UTC-SLS is defined as spreading any leap second evenly over the last 1000 seconds of the day. This corresponds to times after 23:43:21 on a day with an added leap second, or times after 23:43:19 on a day with a removed leap second.
The UTC-SLS conversion only matters to users of this class with high precision requirements.
To keep full track of an instant using an accurate time-scale use the UTCInstant
or
TAIInstant
class.
For most applications, the behavior where each day has exactly 86400 seconds is the desired one.
The UTC-SLS time-scale is also used for all human-scale date-time classes,
such as OffsetDateTime
and ZonedDateTime
.
The standard Java epoch of 1970 is prior to the introduction of whole leap seconds into UTC in 1972. As such, the Time Framework for Java needs to define what the 1970 epoch actually means. The chosen definition is that there are no leap seconds or rate changes in the Java version of UTC prior to 1972, thus it remains 10 seconds offset from TAI. This differs from an accurate UTC implementation, but is relatively easy to handle if accuracy is required.
Operations to add or subtract durations will ignore leap seconds.
Use UTCInstant
or TAIInstant
if accurate duration calculations are required.
Instant is immutable and thread-safe.
Modifier and Type | Field and Description |
---|---|
static Instant |
EPOCH
Constant for the 1970-01-01T00:00:00Z epoch instant.
|
Modifier and Type | Method and Description |
---|---|
int |
compareTo(Instant otherInstant)
Compares this instant to the specified instant.
|
boolean |
equals(Object otherInstant)
Checks if this instant is equal to the specified instant.
|
long |
getEpochSeconds()
Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.
|
int |
getNanoOfSecond()
Gets the number of nanoseconds, later along the time-line, from the start
of the second.
|
int |
hashCode()
Returns a hash code for this instant.
|
boolean |
isAfter(Instant otherInstant)
Checks if this instant is after the specified instant.
|
boolean |
isBefore(Instant otherInstant)
Checks if this instant is before the specified instant.
|
Instant |
minus(Duration duration)
Returns a copy of this instant with the specified duration subtracted.
|
Instant |
minus(long amount,
TimeUnit unit)
Returns a copy of this duration with the specified duration subtracted.
|
Instant |
minusMillis(long millisToSubtract)
Returns a copy of this instant with the specified duration in milliseconds subtracted.
|
Instant |
minusNanos(long nanosToSubtract)
Returns a copy of this instant with the specified duration in nanoseconds subtracted.
|
Instant |
minusSeconds(long secondsToSubtract)
Returns a copy of this instant with the specified duration in seconds subtracted.
|
static Instant |
now()
Obtains the current instant from the system time-source in the default time-zone.
|
static Instant |
now(TimeSource timeSource)
Obtains the current instant from the specified clock.
|
static Instant |
of(InstantProvider instantProvider)
Obtains an instance of
Instant from a provider of instants. |
static Instant |
ofEpochMillis(long epochMillis)
Obtains an instance of
Instant using milliseconds from the
epoch of 1970-01-01T00:00:00Z. |
static Instant |
ofEpochNanos(BigInteger epochNanos)
Obtains an instance of
Instant using nanoseconds from the
epoch of 1970-01-01T00:00:00Z. |
static Instant |
ofEpochNanos(long epochNanos)
Obtains an instance of
Instant using nanoseconds from the
epoch of 1970-01-01T00:00:00Z. |
static Instant |
ofEpochSeconds(BigDecimal epochSeconds)
Obtains an instance of
Instant using seconds from the
epoch of 1970-01-01T00:00:00Z. |
static Instant |
ofEpochSeconds(long epochSeconds)
Obtains an instance of
Instant using seconds from the
epoch of 1970-01-01T00:00:00Z. |
static Instant |
ofEpochSeconds(long epochSeconds,
long nanoAdjustment)
Obtains an instance of
Instant using seconds from the
epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second. |
static Instant |
parse(String text)
Obtains an instance of
Instant by parsing a string. |
Instant |
plus(Duration duration)
Returns a copy of this instant with the specified duration added.
|
Instant |
plus(long amount,
TimeUnit unit)
Returns a copy of this duration with the specified duration added.
|
Instant |
plusMillis(long millisToAdd)
Returns a copy of this instant with the specified duration in milliseconds added.
|
Instant |
plusNanos(long nanosToAdd)
Returns a copy of this instant with the specified duration in nanoseconds added.
|
Instant |
plusSeconds(long secondsToAdd)
Returns a copy of this instant with the specified duration in seconds added.
|
long |
toEpochMillisLong()
Converts this instant to the number of milliseconds from the epoch
of 1970-01-01T00:00:00Z.
|
BigInteger |
toEpochNanos()
Converts this instant to the number of nanoseconds from the epoch
of 1970-01-01T00:00:00Z expressed as a
BigInteger . |
BigDecimal |
toEpochSeconds()
Converts this instant to the number of seconds from the epoch
of 1970-01-01T00:00:00Z expressed as a
BigDecimal . |
Instant |
toInstant()
Converts this instant to an
Instant , trivially returning this . |
String |
toString()
A string representation of this instant using ISO-8601 representation.
|
public static final Instant EPOCH
public static Instant now()
This will query the system time-source
to obtain the current instant.
Using this method will prevent the ability to use an alternate time-source for testing because the time-source is hard-coded.
public static Instant now(TimeSource timeSource)
This will query the specified time-source to obtain the current time.
Using this method allows the use of an alternate clock for testing.
The alternate clock may be introduced using dependency injection
.
timeSource
- the time-source to use, not nullpublic static Instant ofEpochSeconds(long epochSeconds)
Instant
using seconds from the
epoch of 1970-01-01T00:00:00Z.
The nanosecond field is set to zero.
epochSeconds
- the number of seconds from the epoch of 1970-01-01T00:00:00Zpublic static Instant ofEpochSeconds(long epochSeconds, long nanoAdjustment)
Instant
using seconds from the
epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in the exactly the same instant:
Instant.ofSeconds(3, 1); Instant.ofSeconds(4, -999999999); Instant.ofSeconds(2, 1000000001);
epochSeconds
- the number of seconds from the epoch of 1970-01-01T00:00:00ZnanoAdjustment
- the nanosecond adjustment to the number of seconds, positive or negativeArithmeticException
- if the calculation exceeds the supported rangepublic static Instant ofEpochSeconds(BigDecimal epochSeconds)
Instant
using seconds from the
epoch of 1970-01-01T00:00:00Z.
The seconds and nanoseconds are extracted from the specified BigDecimal
.
If the decimal is larger than Long.MAX_VALUE
or has more than 9 decimal
places then an exception is thrown.
epochSeconds
- the number of seconds, up to scale 9ArithmeticException
- if the calculation exceeds the supported rangepublic static Instant ofEpochMillis(long epochMillis)
Instant
using milliseconds from the
epoch of 1970-01-01T00:00:00Z.
The seconds and nanoseconds are extracted from the specified milliseconds.
epochMillis
- the number of millisecondspublic static Instant ofEpochNanos(long epochNanos)
Instant
using nanoseconds from the
epoch of 1970-01-01T00:00:00Z.
The seconds and nanoseconds are extracted from the specified nanoseconds.
epochNanos
- the number of nanosecondspublic static Instant ofEpochNanos(BigInteger epochNanos)
Instant
using nanoseconds from the
epoch of 1970-01-01T00:00:00Z.
The seconds and nanoseconds are extracted from the specified BigInteger
.
If the resulting seconds value is larger than Long.MAX_VALUE
then an
exception is thrown.
epochNanos
- the number of nanoseconds, not nullArithmeticException
- if the calculation exceeds the supported rangepublic static Instant of(InstantProvider instantProvider)
Instant
from a provider of instants.
In addition to calling InstantProvider.toInstant()
this method
also checks the validity of the result of the provider.
instantProvider
- a provider of instant information, not nullpublic static Instant parse(String text)
Instant
by parsing a string.
This will parse the string produced by toString()
which is
the ISO-8601 format yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ
.
The numbers must be ASCII numerals.
The seconds are mandatory, but the fractional seconds are optional.
There must be no more than 9 digits after the decimal point.
The letters (T and Z) will be accepted in upper or lower case.
The decimal point may be either a dot or a comma.
text
- the text to parse, not nullCalendricalParseException
- if the text cannot be parsed to an Instant
public long getEpochSeconds()
The epoch second count is a simple incrementing count of seconds where
second 0 is 1970-01-01T00:00:00Z.
The nanosecond part of the day is returned by getNanosOfSecond
.
public int getNanoOfSecond()
The nanosecond-of-second value measures the total number of nanoseconds from
the second returned by getEpochSeconds
.
public Instant plus(Duration duration)
This instance is immutable and unaffected by this method call.
duration
- the duration to add, positive or negative, not nullInstant
based on this instant with the specified duration added, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant plus(long amount, TimeUnit unit)
The duration to be added is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
amount
- the duration to add, positive or negativeunit
- the unit that the duration is measured in, not nullInstant
based on this duration with the specified duration added, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant plusSeconds(long secondsToAdd)
This instance is immutable and unaffected by this method call.
secondsToAdd
- the seconds to add, positive or negativeInstant
based on this instant with the specified seconds added, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant plusMillis(long millisToAdd)
This instance is immutable and unaffected by this method call.
millisToAdd
- the milliseconds to add, positive or negativeInstant
based on this instant with the specified milliseconds added, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant plusNanos(long nanosToAdd)
This instance is immutable and unaffected by this method call.
nanosToAdd
- the nanoseconds to add, positive or negativeInstant
based on this instant with the specified nanoseconds added, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant minus(Duration duration)
This instance is immutable and unaffected by this method call.
duration
- the duration to subtract, positive or negative, not nullInstant
based on this instant with the specified duration subtracted, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant minus(long amount, TimeUnit unit)
The duration to be subtracted is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
amount
- the duration to subtract, positive or negativeunit
- the unit that the duration is measured in, not nullDuration
based on this duration with the specified duration subtracted, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant minusSeconds(long secondsToSubtract)
This instance is immutable and unaffected by this method call.
secondsToSubtract
- the seconds to subtract, positive or negativeInstant
based on this instant with the specified seconds subtracted, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant minusMillis(long millisToSubtract)
This instance is immutable and unaffected by this method call.
millisToSubtract
- the milliseconds to subtract, positive or negativeInstant
based on this instant with the specified milliseconds subtracted, never nullArithmeticException
- if the calculation exceeds the supported rangepublic Instant minusNanos(long nanosToSubtract)
This instance is immutable and unaffected by this method call.
nanosToSubtract
- the nanoseconds to subtract, positive or negativeInstant
based on this instant with the specified nanoseconds subtracted, never nullArithmeticException
- if the calculation exceeds the supported rangepublic BigDecimal toEpochSeconds()
BigDecimal
.public BigInteger toEpochNanos()
BigInteger
.public long toEpochMillisLong()
If this instant represents a point on the time-line too far in the future
or past to fit in a long
milliseconds, then an exception is thrown.
If this instant has greater than millisecond precision, then the conversion will drop any excess precision information as though the amount in nanoseconds was subject to integer division by one million.
ArithmeticException
- if the calculation exceeds the supported rangepublic Instant toInstant()
Instant
, trivially returning this
.toInstant
in interface InstantProvider
this
, never nullpublic int compareTo(Instant otherInstant)
The comparison is based on the time-line position of the instants.
compareTo
in interface Comparable<Instant>
otherInstant
- the other instant to compare to, not nullNullPointerException
- if otherInstant is nullpublic boolean isAfter(Instant otherInstant)
The comparison is based on the time-line position of the instants.
otherInstant
- the other instant to compare to, not nullNullPointerException
- if otherInstant is nullpublic boolean isBefore(Instant otherInstant)
The comparison is based on the time-line position of the instants.
otherInstant
- the other instant to compare to, not nullNullPointerException
- if otherInstant is nullpublic boolean equals(Object otherInstant)
The comparison is based on the time-line position of the instants.
public int hashCode()
Copyright © 2014. All rights reserved.