OpenJDK 1.23 · java.time.Instant · APIdia, the JavaDoc alternative

An instantaneous point on the time-line.

This class models a single instantaneous point on the time-line. This might be used to record event time-stamps in the application.

The range of an instant requires the storage of a number larger than a long. To achieve this, the class stores a long representing epoch-seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999. The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z where instants after the epoch have positive values, and earlier instants have negative values. For both the epoch-second and nanosecond parts, a larger value is always later on the time-line than a smaller value.

Time-scale

The length of the solar day is the standard way that humans measure time. This has traditionally been subdivided into 24 hours of 60 minutes of 60 seconds, forming a 86400 second day.

Modern timekeeping is based on atomic clocks which precisely define an SI second relative to the transitions of a Caesium atom. The length of an SI second was defined to be very close to the 86400th fraction of a day.

Unfortunately, as the Earth rotates the length of the day varies. In addition, over time the average length of the day is getting longer as the Earth slows. As a result, the length of a solar day in 2012 is slightly longer than 86400 SI seconds. The actual length of any given day and the amount by which the Earth is slowing are not predictable and can only be determined by measurement. The UT1 time-scale captures the accurate length of day, but is only available some time after the day has completed.

The UTC time-scale is a standard approach to bundle up all the additional fractions of a second from UT1 into whole seconds, known as leap-seconds. A leap-second may be added or removed depending on the Earth's rotational changes. As such, UTC permits a day to have 86399 SI seconds or 86401 SI seconds where necessary in order to keep the day aligned with the Sun.

The modern UTC time-scale was introduced in 1972, introducing the concept of whole leap-seconds. Between 1958 and 1972, the definition of UTC was complex, with minor sub-second leaps and alterations to the length of the notional second. As of 2012, discussions are underway to change the definition of UTC again, with the potential to remove leap seconds or introduce other changes.

Given the complexity of accurate timekeeping described above, this Java API defines its own time-scale, the Java Time-Scale.

The Java Time-Scale divides each calendar day into exactly 86400 subdivisions, known as seconds. These seconds may differ from the SI second. It closely matches the de facto international civil time scale, the definition of which changes from time to time.

The Java Time-Scale has slightly different definitions for different segments of the time-line, each based on the consensus international time scale that is used as the basis for civil time. Whenever the internationally-agreed time scale is modified or replaced, a new segment of the Java Time-Scale must be defined for it. Each segment must meet these requirements:

the Java Time-Scale shall closely match the underlying international civil time scale;
the Java Time-Scale shall exactly match the international civil time scale at noon each day;
the Java Time-Scale shall have a precisely-defined relationship to the international civil time scale.

There are currently, as of 2013, two segments in the Java time-scale.

For the segment from 1972-11-03 (exact boundary discussed below) until further notice, the consensus international time scale is UTC (with leap seconds). In this segment, the Java Time-Scale is identical to UTC-SLS. This is identical to UTC on days that do not have a leap second. On days that do have a leap second, the leap second is spread equally over the last 1000 seconds of the day, maintaining the appearance of exactly 86400 seconds per day.

For the segment prior to 1972-11-03, extending back arbitrarily far, the consensus international time scale is defined to be UT1, applied proleptically, which is equivalent to the (mean) solar time on the prime meridian (Greenwich). In this segment, the Java Time-Scale is identical to the consensus international time scale. The exact boundary between the two segments is the instant where UT1 = UTC between 1972-11-03T00:00 and 1972-11-04T12:00.

Implementations of the Java time-scale using the JSR-310 API are not required to provide any clock that is sub-second accurate, or that progresses monotonically or smoothly. Implementations are therefore not required to actually perform the UTC-SLS slew or to otherwise be aware of leap seconds. JSR-310 does, however, require that implementations must document the approach they use when defining a clock representing the current instant. See Clock for details on the available clocks.

The Java time-scale is used for all date-time classes. This includes Instant, LocalDate, LocalTime, OffsetDateTime, ZonedDateTime and Duration.

This is a value-based class; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail. The equals method should be used for comparisons.

Modifier and Type	Field and Description
public static final Instant	EPOCH Constant for the 1970-01-01T00:00:00Z epoch instant.
public static final Instant	MAX The maximum supported `Instant`, '1000000000-12-31T23:59:59.999999999Z'.
private static final long	MAX_SECOND The maximum supported epoch second.
public static final Instant	MIN The minimum supported `Instant`, '-1000000000-01-01T00:00Z'.
private static final long	MIN_SECOND The minimum supported epoch second.
private final int	nanos The number of nanoseconds, later along the time-line, from the seconds field.
private final long	seconds The number of seconds from the epoch of 1970-01-01T00:00:00Z.
private static final long	serialVersionUID Serialization version.

Access	Constructor and Description
private	Instant(long the number of seconds from 1970-01-01T00:00:00Z epochSecond, int the nanoseconds within the second, must be positive 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 and Description
public Temporal	Returns: the adjusted object, not null adjustInto(Temporal the target object to be adjusted, not null temporal) Implements java.time.temporal.TemporalAdjuster.adjustInto. Adjusts the specified temporal object to have this instant.
public OffsetDateTime	Returns: the offset date-time formed from this instant and the specified offset, not null atOffset(ZoneOffset the offset to combine with, not null offset) Combines this instant with an offset to create an `OffsetDateTime`.
public ZonedDateTime	Returns: the zoned date-time formed from this instant and the specified zone, not null atZone(ZoneId the zone to combine with, not null zone) Combines this instant with a time-zone to create a `ZonedDateTime`.
public int	Returns: the comparator value, that is less than zero if this instant is before `otherInstant`, zero if they are equal, or greater than zero if this instant is after `otherInstant` compareTo(Instant the other instant to compare to, not null otherInstant) Implements java.lang.Comparable.compareTo. Compares this instant to the specified instant.
private static Instant	create(long the length of the duration in seconds seconds, int the nano-of-second, from 0 to 999,999,999 nanoOfSecond) Obtains an instance of `Instant` using seconds and nanoseconds.
public boolean	Returns: true if the other instant is equal to this one equals(Object the other instant, null returns false other) Overrides java.lang.Object.equals. Checks if this instant is equal to the specified instant.
public static Instant	Returns: the instant, not null from(TemporalAccessor the temporal object to convert, not null temporal) Obtains an instance of `Instant` from a temporal object.
public int	Returns: the value for the field get(TemporalField the field to get, not null field) Overrides default java.time.temporal.TemporalAccessor.get. Gets the value of the specified field from this instant as an `int`.
public long	Returns: the seconds from the epoch of 1970-01-01T00:00:00Z getEpochSecond() Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.
public long	Returns: the value for the field getLong(TemporalField the field to get, not null field) Implements java.time.temporal.TemporalAccessor.getLong. Gets the value of the specified field from this instant as a `long`.
public int	Returns: the nanoseconds within the second, always positive, never exceeds 999,999,999 getNano() Gets the number of nanoseconds, later along the time-line, from the start of the second.
public int	Returns: a suitable hash code hashCode() Overrides java.lang.Object.hashCode. Returns a hash code for this instant.
public boolean	Returns: true if this instant is after the specified instant isAfter(Instant the other instant to compare to, not null otherInstant) Checks if this instant is after the specified instant.
public boolean	Returns: true if this instant is before the specified instant isBefore(Instant the other instant to compare to, not null otherInstant) Checks if this instant is before the specified instant.
public boolean	Returns: true if the field is supported on this instant, false if not isSupported(TemporalField the field to check, null returns false field) Implements java.time.temporal.TemporalAccessor.isSupported. Checks if the specified field is supported.
public boolean	Returns: true if the unit can be added/subtracted, false if not isSupported(TemporalUnit the unit to check, null returns false unit) Implements java.time.temporal.Temporal.isSupported. Checks if the specified unit is supported.
private long	microsUntil(Instant end)
private long	millisUntil(Instant end)
public Instant	Returns: an `Instant` based on this instant with the subtraction made, not null minus(TemporalAmount the amount to subtract, not null amountToSubtract) Overrides default java.time.temporal.Temporal.minus. Returns a copy of this instant with the specified amount subtracted.
public Instant	Returns: an `Instant` based on this instant with the specified amount subtracted, not null minus(long the amount of the unit to subtract from the result, may be negative amountToSubtract, TemporalUnit the unit of the amount to subtract, not null unit) Overrides default java.time.temporal.Temporal.minus. Returns a copy of this instant with the specified amount subtracted.
public Instant	Returns: an `Instant` based on this instant with the specified milliseconds subtracted, not null minusMillis(long the milliseconds to subtract, positive or negative millisToSubtract) Returns a copy of this instant with the specified duration in milliseconds subtracted.
public Instant	Returns: an `Instant` based on this instant with the specified nanoseconds subtracted, not null minusNanos(long the nanoseconds to subtract, positive or negative nanosToSubtract) Returns a copy of this instant with the specified duration in nanoseconds subtracted.
public Instant	Returns: an `Instant` based on this instant with the specified seconds subtracted, not null minusSeconds(long the seconds to subtract, positive or negative secondsToSubtract) Returns a copy of this instant with the specified duration in seconds subtracted.
private long	nanosUntil(Instant end)
public static Instant	Returns: the current instant using the system clock, not null now() Obtains the current instant from the system clock.
public static Instant	Returns: the current instant, not null now(Clock the clock to use, not null clock) Obtains the current instant from the specified clock.
public static Instant	Returns: an instant, not null ofEpochMilli(long the number of milliseconds from 1970-01-01T00:00:00Z epochMilli) Obtains an instance of `Instant` using milliseconds from the epoch of 1970-01-01T00:00:00Z.
public static Instant	Returns: an instant, not null ofEpochSecond(long the number of seconds from 1970-01-01T00:00:00Z epochSecond) Obtains an instance of `Instant` using seconds from the epoch of 1970-01-01T00:00:00Z.
public static Instant	Returns: an instant, not null ofEpochSecond(long the number of seconds from 1970-01-01T00:00:00Z epochSecond, long the nanosecond adjustment to the number of seconds, positive or negative nanoAdjustment) Obtains an instance of `Instant` using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
public static Instant	Returns: the parsed instant, not null parse(final CharSequence the text to parse, not null text) Obtains an instance of `Instant` from a text string such as `2007-12-03T10:15:30.00Z`.
public Instant	Returns: an `Instant` based on this instant with the addition made, not null plus(TemporalAmount the amount to add, not null amountToAdd) Overrides default java.time.temporal.Temporal.plus. Returns a copy of this instant with the specified amount added.
public Instant	Returns: an `Instant` based on this instant with the specified amount added, not null plus(long the amount of the unit to add to the result, may be negative amountToAdd, TemporalUnit the unit of the amount to add, not null unit) Implements java.time.temporal.Temporal.plus. Returns a copy of this instant with the specified amount added.
private Instant	Returns: an `Instant` based on this instant with the specified seconds added, not null plus(long the seconds to add, positive or negative secondsToAdd, long the nanos to add, positive or negative nanosToAdd) Returns a copy of this instant with the specified duration added.
public Instant	Returns: an `Instant` based on this instant with the specified milliseconds added, not null plusMillis(long the milliseconds to add, positive or negative millisToAdd) Returns a copy of this instant with the specified duration in milliseconds added.
public Instant	Returns: an `Instant` based on this instant with the specified nanoseconds added, not null plusNanos(long the nanoseconds to add, positive or negative nanosToAdd) Returns a copy of this instant with the specified duration in nanoseconds added.
public Instant	Returns: an `Instant` based on this instant with the specified seconds added, not null plusSeconds(long the seconds to add, positive or negative secondsToAdd) Returns a copy of this instant with the specified duration in seconds added.
public < the type of the result R> R	Returns: the query result, null may be returned (defined by the query) query(TemporalQuery<R> the query to invoke, not null query) Overrides default java.time.temporal.TemporalAccessor.query. Queries this instant using the specified query.
public ValueRange	Returns: the range of valid values for the field, not null range(TemporalField the field to query the range for, not null field) Overrides default java.time.temporal.TemporalAccessor.range. Gets the range of valid values for the specified field.
pack-priv static Instant	readExternal(DataInput in)
private void	readObject(ObjectInputStream the stream to read s) Defend against malicious streams.
private long	secondsUntil(Instant end)
public long	Returns: the number of milliseconds since the epoch of 1970-01-01T00:00:00Z toEpochMilli() Converts this instant to the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.
public String	Returns: an ISO-8601 representation of this instant, not null toString() Overrides java.lang.Object.toString. A string representation of this instant using ISO-8601 representation.
public Instant	Returns: an `Instant` based on this instant with the time truncated, not null truncatedTo(TemporalUnit the unit to truncate to, not null unit) Returns a copy of this `Instant` truncated to the specified unit.
public long	Returns: the amount of time between this instant and the end instant until(Temporal the end date, exclusive, which is converted to an `Instant`, not null endExclusive, TemporalUnit the unit to measure the amount in, not null unit) Implements java.time.temporal.Temporal.until. Calculates the amount of time until another instant in terms of the specified unit.
public Duration	Returns: the `Duration` from this `Instant` until the specified `endExclusive` `Instant` until(Instant the end `Instant`, exclusive, not null endExclusive) Calculates the `Duration` until another `Instant`.
public Instant	Returns: an `Instant` based on `this` with the adjustment made, not null with(TemporalAdjuster the adjuster to use, not null adjuster) Overrides default java.time.temporal.Temporal.with. Returns an adjusted copy of this instant.
public Instant	Returns: an `Instant` based on `this` with the specified field set, not null with(TemporalField the field to set in the result, not null field, long the new value of the field in the result newValue) Implements java.time.temporal.Temporal.with. Returns a copy of this instant with the specified field set to a new value.
pack-priv void	writeExternal(DataOutput out)
private Object	Returns: the instance of `Ser`, not null writeReplace() Writes the object using a dedicated serialized form.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

public final Class Instant

Time-scale

Field Summary

Constructor Summary

Method Summary