Package javax.time

Class Instant

java.lang.Object
javax.time.Instant
All Implemented Interfaces:
Serializable, Comparable<Instant>, InstantProvider

public final class Instant extends Object implements InstantProvider, Comparable<Instant>, Serializable
An instantaneous point on the time-line.

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.

Time-scale

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.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final BigInteger
    BigInteger constant for a billion.
    static final Instant
    Constant for the 1970-01-01T00:00:00Z epoch instant.
    private final int
    The number of nanoseconds, later along the time-line, from the seconds field.
    private static final int
    Constant for nanos per second.
    private final long
    The number of seconds from the epoch of 1970-01-01T00:00:00Z.
    private static final long
    Serialization version.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Instant(long epochSeconds, int nanos)
    Constructs an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) static void
    checkNotNull(Object object, String errorMessage)
    Validates that the input value is not null.
    int
    compareTo(Instant otherInstant)
    Compares this instant to the specified instant.
    private static Instant
    create(long seconds, int nanoOfSecond)
    Obtains an instance of Instant using seconds and nanoseconds.
    boolean
    equals(Object otherInstant)
    Checks if this instant is equal to the specified instant.
    long
    Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.
    int
    Gets the number of nanoseconds, later along the time-line, from the start of the second.
    int
    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.
    minus(long amount, TimeUnit unit)
    Returns a copy of this duration with the specified duration subtracted.
    minus(Duration duration)
    Returns a copy of this instant with the specified duration subtracted.
    minusMillis(long millisToSubtract)
    Returns a copy of this instant with the specified duration in milliseconds subtracted.
    minusNanos(long nanosToSubtract)
    Returns a copy of this instant with the specified duration in nanoseconds subtracted.
    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(long epochNanos)
    Obtains an instance of Instant using nanoseconds from the epoch of 1970-01-01T00:00:00Z.
    static Instant
    Obtains an instance of Instant using nanoseconds 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
    ofEpochSeconds(BigDecimal epochSeconds)
    Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z.
    static Instant
    parse(String text)
    Obtains an instance of Instant by parsing a string.
    private Instant
    plus(long secondsToAdd, long nanosToAdd)
    Returns a copy of this instant with the specified duration added.
    plus(long amount, TimeUnit unit)
    Returns a copy of this duration with the specified duration added.
    plus(Duration duration)
    Returns a copy of this instant with the specified duration added.
    plusMillis(long millisToAdd)
    Returns a copy of this instant with the specified duration in milliseconds added.
    plusNanos(long nanosToAdd)
    Returns a copy of this instant with the specified duration in nanoseconds added.
    plusSeconds(long secondsToAdd)
    Returns a copy of this instant with the specified duration in seconds added.
    private Object
    Resolves singletons.
    long
    Converts this instant to the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.
    Converts this instant to the number of nanoseconds from the epoch of 1970-01-01T00:00:00Z expressed as a BigInteger.
    Converts this instant to the number of seconds from the epoch of 1970-01-01T00:00:00Z expressed as a BigDecimal.
    Converts this instant to an Instant, trivially returning this.
    A string representation of this instant using ISO-8601 representation.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • EPOCH

      public static final Instant EPOCH
      Constant for the 1970-01-01T00:00:00Z epoch instant.
    • serialVersionUID

      private static final long serialVersionUID
      Serialization version.
      See Also:
    • NANOS_PER_SECOND

      private static final int NANOS_PER_SECOND
      Constant for nanos per second.
      See Also:
    • BILLION

      static final BigInteger BILLION
      BigInteger constant for a billion.
    • seconds

      private final long seconds
      The number of seconds from the epoch of 1970-01-01T00:00:00Z.
    • nanos

      private final int nanos
      The number of nanoseconds, later along the time-line, from the seconds field. This is always positive, and never exceeds 999,999,999.
  • Constructor Details

    • Instant

      private Instant(long epochSeconds, int nanos)
      Constructs an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
      Parameters:
      epochSeconds - the number of seconds from the epoch
      nanos - the nanoseconds within the second, must be positive
  • Method Details

    • checkNotNull

      static void checkNotNull(Object object, String errorMessage)
      Validates that the input value is not null.
      Parameters:
      object - the object to check
      errorMessage - the error to throw
      Throws:
      NullPointerException - if the object is null
    • now

      public static Instant now()
      Obtains the current instant from the system time-source in the default time-zone.

      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.

      Returns:
      the current instant using the system clock, never null
    • now

      public static Instant now(TimeSource timeSource)
      Obtains the current instant from the specified clock.

      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.

      Parameters:
      timeSource - the time-source to use, not null
      Returns:
      the current instant, never null
    • ofEpochSeconds

      public static Instant ofEpochSeconds(long epochSeconds)
      Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z.

      The nanosecond field is set to zero.

      Parameters:
      epochSeconds - the number of seconds from the epoch of 1970-01-01T00:00:00Z
      Returns:
      an instant, never null
    • ofEpochSeconds

      public 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.

      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);
       
      Parameters:
      epochSeconds - the number of seconds from the epoch of 1970-01-01T00:00:00Z
      nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative
      Returns:
      an instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • ofEpochSeconds

      public static Instant ofEpochSeconds(BigDecimal epochSeconds)
      Obtains an instance of 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.

      Parameters:
      epochSeconds - the number of seconds, up to scale 9
      Returns:
      an instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • ofEpochMillis

      public static Instant ofEpochMillis(long epochMillis)
      Obtains an instance of Instant using milliseconds from the epoch of 1970-01-01T00:00:00Z.

      The seconds and nanoseconds are extracted from the specified milliseconds.

      Parameters:
      epochMillis - the number of milliseconds
      Returns:
      an instant, never null
    • ofEpochNanos

      public static Instant ofEpochNanos(long epochNanos)
      Obtains an instance of Instant using nanoseconds from the epoch of 1970-01-01T00:00:00Z.

      The seconds and nanoseconds are extracted from the specified nanoseconds.

      Parameters:
      epochNanos - the number of nanoseconds
      Returns:
      an instant, never null
    • ofEpochNanos

      public static Instant ofEpochNanos(BigInteger epochNanos)
      Obtains an instance of 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.

      Parameters:
      epochNanos - the number of nanoseconds, not null
      Returns:
      an instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • of

      public static Instant of(InstantProvider instantProvider)
      Obtains an instance of Instant from a provider of instants.

      In addition to calling InstantProvider.toInstant() this method also checks the validity of the result of the provider.

      Parameters:
      instantProvider - a provider of instant information, not null
      Returns:
      an instant, never null
    • parse

      public static Instant parse(String text)
      Obtains an instance of 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.

      Parameters:
      text - the text to parse, not null
      Returns:
      an instant, never null
      Throws:
      CalendricalParseException - if the text cannot be parsed to an Instant
    • create

      private static Instant create(long seconds, int nanoOfSecond)
      Obtains an instance of Instant using seconds and nanoseconds.
      Parameters:
      seconds - the length of the duration in seconds
      nanoOfSecond - the nano-of-second, from 0 to 999,999,999
    • readResolve

      private Object readResolve()
      Resolves singletons.
      Returns:
      the resolved instance, never null
    • getEpochSeconds

      public long getEpochSeconds()
      Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.

      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.

      Returns:
      the seconds from the epoch of 1970-01-01T00:00:00Z
    • getNanoOfSecond

      public int getNanoOfSecond()
      Gets the number of nanoseconds, later along the time-line, from the start of the second.

      The nanosecond-of-second value measures the total number of nanoseconds from the second returned by getEpochSeconds.

      Returns:
      the nanoseconds within the second, always positive, never exceeds 999,999,999
    • plus

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

      This instance is immutable and unaffected by this method call.

      Parameters:
      duration - the duration to add, positive or negative, not null
      Returns:
      an Instant based on this instant with the specified duration added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • plus

      public Instant plus(long amount, TimeUnit unit)
      Returns a copy of this duration with the specified duration added.

      The duration to be added is measured in terms of the specified unit.

      This instance is immutable and unaffected by this method call.

      Parameters:
      amount - the duration to add, positive or negative
      unit - the unit that the duration is measured in, not null
      Returns:
      an Instant based on this duration with the specified duration added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • plusSeconds

      public Instant plusSeconds(long secondsToAdd)
      Returns a copy of this instant with the specified duration in seconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      secondsToAdd - the seconds to add, positive or negative
      Returns:
      an Instant based on this instant with the specified seconds added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • plusMillis

      public Instant plusMillis(long millisToAdd)
      Returns a copy of this instant with the specified duration in milliseconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      millisToAdd - the milliseconds to add, positive or negative
      Returns:
      an Instant based on this instant with the specified milliseconds added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • plusNanos

      public Instant plusNanos(long nanosToAdd)
      Returns a copy of this instant with the specified duration in nanoseconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      nanosToAdd - the nanoseconds to add, positive or negative
      Returns:
      an Instant based on this instant with the specified nanoseconds added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • plus

      private Instant plus(long secondsToAdd, long nanosToAdd)
      Returns a copy of this instant with the specified duration added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      secondsToAdd - the seconds to add, positive or negative
      nanosToAdd - the nanos to add, positive or negative
      Returns:
      an Instant based on this instant with the specified seconds added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minus

      public Instant minus(Duration duration)
      Returns a copy of this instant with the specified duration subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      duration - the duration to subtract, positive or negative, not null
      Returns:
      an Instant based on this instant with the specified duration subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minus

      public Instant minus(long amount, TimeUnit unit)
      Returns a copy of this duration with the specified duration subtracted.

      The duration to be subtracted is measured in terms of the specified unit.

      This instance is immutable and unaffected by this method call.

      Parameters:
      amount - the duration to subtract, positive or negative
      unit - the unit that the duration is measured in, not null
      Returns:
      a Duration based on this duration with the specified duration subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minusSeconds

      public Instant minusSeconds(long secondsToSubtract)
      Returns a copy of this instant with the specified duration in seconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      secondsToSubtract - the seconds to subtract, positive or negative
      Returns:
      an Instant based on this instant with the specified seconds subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minusMillis

      public Instant minusMillis(long millisToSubtract)
      Returns a copy of this instant with the specified duration in milliseconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      millisToSubtract - the milliseconds to subtract, positive or negative
      Returns:
      an Instant based on this instant with the specified milliseconds subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minusNanos

      public Instant minusNanos(long nanosToSubtract)
      Returns a copy of this instant with the specified duration in nanoseconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      nanosToSubtract - the nanoseconds to subtract, positive or negative
      Returns:
      an Instant based on this instant with the specified nanoseconds subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • toEpochSeconds

      public BigDecimal toEpochSeconds()
      Converts this instant to the number of seconds from the epoch of 1970-01-01T00:00:00Z expressed as a BigDecimal.
      Returns:
      the number of seconds since the epoch of 1970-01-01T00:00:00Z, scale 9, never null
    • toEpochNanos

      public BigInteger toEpochNanos()
      Converts this instant to the number of nanoseconds from the epoch of 1970-01-01T00:00:00Z expressed as a BigInteger.
      Returns:
      the number of nanoseconds since the epoch of 1970-01-01T00:00:00Z, never null
    • toEpochMillisLong

      public long toEpochMillisLong()
      Converts this instant to the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.

      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.

      Returns:
      the number of milliseconds since the epoch of 1970-01-01T00:00:00Z
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • toInstant

      public Instant toInstant()
      Converts this instant to an Instant, trivially returning this.
      Specified by:
      toInstant in interface InstantProvider
      Returns:
      this, never null
    • compareTo

      public int compareTo(Instant otherInstant)
      Compares this instant to the specified instant.

      The comparison is based on the time-line position of the instants.

      Specified by:
      compareTo in interface Comparable<Instant>
      Parameters:
      otherInstant - the other instant to compare to, not null
      Returns:
      the comparator value, negative if less, positive if greater
      Throws:
      NullPointerException - if otherInstant is null
    • isAfter

      public boolean isAfter(Instant otherInstant)
      Checks if this instant is after the specified instant.

      The comparison is based on the time-line position of the instants.

      Parameters:
      otherInstant - the other instant to compare to, not null
      Returns:
      true if this instant is after the specified instant
      Throws:
      NullPointerException - if otherInstant is null
    • isBefore

      public boolean isBefore(Instant otherInstant)
      Checks if this instant is before the specified instant.

      The comparison is based on the time-line position of the instants.

      Parameters:
      otherInstant - the other instant to compare to, not null
      Returns:
      true if this instant is before the specified instant
      Throws:
      NullPointerException - if otherInstant is null
    • equals

      public boolean equals(Object otherInstant)
      Checks if this instant is equal to the specified instant.

      The comparison is based on the time-line position of the instants.

      Overrides:
      equals in class Object
      Parameters:
      otherInstant - the other instant, null returns false
      Returns:
      true if the other instant is equal to this one
    • hashCode

      public int hashCode()
      Returns a hash code for this instant.
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code
    • toString

      public String toString()
      A string representation of this instant using ISO-8601 representation.

      The format of the returned string will be yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ.

      Overrides:
      toString in class Object
      Returns:
      an ISO-8601 representation of this instant, never null