 java.lang.Object

 org.threeten.extra.scale.UtcInstant

 All Implemented Interfaces:
Serializable
,Comparable<UtcInstant>
public final class UtcInstant extends Object implements Comparable<UtcInstant>, Serializable
An instantaneous point on the timeline measured in the UTC timescale with leap seconds.The
java.time
classes use the Java timescale for simplicity. That scale works on the assumption that the timeline is simple, there are no leapseconds and there are always 24 * 60 * 60 seconds in a day. Unfortunately, the Earth's rotation is not straightforward, and a solar day does not match this definition.This class is an alternative representation based on the UTC timescale which includes leapseconds. Leapseconds are additional seconds that are inserted into the yearmonthdayhourminutesecond timeline in order to keep UTC in line with the solar day. When a leap second occurs, an accurate clock will show the time
23:59:60
just before midnight.Leapseconds are announced in advance, typically at least six months. The
UtcRules
class models which dates have leapseconds. All the methods on this class use the latest available system rules.The system leapsecond rules fix the start point of UTC as 1972. This date was chosen as UTC was more complex before 1972.
The duration between two points on the UTC timescale is calculated solely using this class. Do not use the
between
method onDuration
as that will lose information. Instead usedurationUntil(UtcInstant)
on this class.It is intended that most applications will use the
Instant
class which uses the UTCSLS mapping from UTC to guarantee 86400 seconds per day. Specialist applications with access to an accurate timesource may find this class useful.Timescale
The length of the solar day is the standard way that humans measure time. As the Earth's rotation changes, the length of the day varies. In general, a solar day is slightly longer than 86400 SI seconds. The actual length is not predictable and can only be determined by measurement. The UT1 timescale captures these measurements.
The UTC timescale is a standard approach to bundle up all the additional fractions of a second from UT1 into whole seconds, known as leapseconds. A leapsecond may be added or removed depending on the Earth's rotational changes. If it is removed, then the relevant date will have no time of
23:59:59
. If it is added, then the relevant date will have an extra second of23:59:60
.The modern UTC timescale was introduced in 1972, introducing the concept of whole leapseconds. Between 1958 and 1972, the definition of UTC was complex, with minor subsecond leaps and alterations to the length of the notional second.
This class may be used for instants in the far past and far future. Since some instants will be prior to 1972, it is not strictly an implementation of UTC. Instead, it is a proleptic timescale based on TAI and equivalent to it since 1972.
Implementation Requirements:
This class is immutable and threadsafe.This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.
 See Also:
 Serialized Form


Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(UtcInstant otherInstant)
Compares this instant to another based on the timeline.Duration
durationUntil(UtcInstant utcInstant)
Returns the duration between this instant and the specified instant.boolean
equals(Object otherInstant)
Checks if this instant is equal to the specifiedUtcInstant
.long
getModifiedJulianDay()
Gets the Modified Julian Day (MJD).long
getNanoOfDay()
Gets the number of nanoseconds, later along the timeline, from the start of the Modified Julian Day.int
hashCode()
Returns a hash code for this instant.boolean
isAfter(UtcInstant otherInstant)
Checks if this instant is after the specified instant.boolean
isBefore(UtcInstant otherInstant)
Checks if this instant is before the specified instant.boolean
isLeapSecond()
Checks if the instant is within a leap second.UtcInstant
minus(Duration duration)
Returns a copy of this instant with the specified duration subtracted.static UtcInstant
of(Instant instant)
Obtains an instance ofUtcInstant
from anInstant
.static UtcInstant
of(TaiInstant instant)
Obtains an instance ofUtcInstant
from aTaiInstant
.static UtcInstant
ofModifiedJulianDay(long mjDay, long nanoOfDay)
Obtains an instance ofUtcInstant
from a Modified Julian Day with a nanosecond fraction of day.static UtcInstant
parse(CharSequence text)
Obtains an instance ofUtcInstant
from a text string, such as20071203T10:15:30.00Z
.UtcInstant
plus(Duration duration)
Returns a copy of this instant with the specified duration added.Instant
toInstant()
Converts this instant to anInstant
.String
toString()
A string representation of this instant.TaiInstant
toTaiInstant()
Converts this instant to aTaiInstant
.UtcInstant
withModifiedJulianDay(long mjDay)
Returns a copy of thisUtcInstant
with the Modified Julian Day (MJD) altered.UtcInstant
withNanoOfDay(long nanoOfDay)
Returns a copy of thisUtcInstant
with the nanoofday altered.



Method Detail

ofModifiedJulianDay
public static UtcInstant ofModifiedJulianDay(long mjDay, long nanoOfDay)
Obtains an instance ofUtcInstant
from a Modified Julian Day with a nanosecond fraction of day.Modified Julian Day is a simple incrementing count of days where day 0 is 18581117. Nanosecondofday is a simple count of nanoseconds from the start of the day including any additional leapsecond. This method validates the nanosecondofday value against the Modified Julian Day.
The nanosecondofday value has a valid range from
0
to86,400,000,000,000  1
on most days, and a larger or smaller range on leapsecond days.The nanosecond value must be positive even for negative values of Modified Julian Day. One nanosecond before Modified Julian Day zero will be
1
days and the maximum nanosecond value. Parameters:
mjDay
 the date as a Modified Julian Day (number of days from the epoch of 18581117)nanoOfDay
 the nanoseconds within the day, including leap seconds Returns:
 the UTC instant, not null
 Throws:
IllegalArgumentException
 if nanoOfDay is out of range

of
public static UtcInstant of(Instant instant)
Obtains an instance ofUtcInstant
from anInstant
.Converting a UTCSLS instant to UTC requires leap second rules. This method uses the latest available system rules.
Conversion from an
Instant
will not be completely accurate near a leap second in accordance with UTCSLS. Parameters:
instant
 the instant to convert, not null Returns:
 the UTC instant, not null
 Throws:
DateTimeException
 if the range ofUtcInstant
is exceededArithmeticException
 if numeric overflow occurs

of
public static UtcInstant of(TaiInstant instant)
Obtains an instance ofUtcInstant
from aTaiInstant
.Converting a TAI instant to UTC requires leap second rules. This method uses the latest available system rules.
The
UtcInstant
will represent exactly the same point on the timeline as per the available leapsecond rules. If the leapsecond rules change then conversion back to TAI may result in a different instant. Parameters:
instant
 the instant to convert, not null Returns:
 the UTC instant, not null
 Throws:
DateTimeException
 if the range ofUtcInstant
is exceededArithmeticException
 if numeric overflow occurs

parse
public static UtcInstant parse(CharSequence text)
Obtains an instance ofUtcInstant
from a text string, such as20071203T10:15:30.00Z
.The string must represent a valid instant in UTC and is parsed using
DateTimeFormatter.ISO_INSTANT
with leap seconds handled. Parameters:
text
 the text to parse such as "20071203T10:15:30.00Z", not null Returns:
 the parsed instant, not null
 Throws:
DateTimeParseException
 if the text cannot be parsedDateTimeException
 if parsed text represents an invalid leap second

getModifiedJulianDay
public long getModifiedJulianDay()
Gets the Modified Julian Day (MJD).The Modified Julian Day is a simple incrementing count of days where day 0 is 18581117. The nanosecond part of the day is returned by
getNanosOfDay
. The day varies in length, being one second longer on a leap day. Returns:
 the Modified Julian Day based on the epoch 18581117

withModifiedJulianDay
public UtcInstant withModifiedJulianDay(long mjDay)
Returns a copy of thisUtcInstant
with the Modified Julian Day (MJD) altered.The Modified Julian Day is a simple incrementing count of days where day 0 is 18581117. The nanosecond part of the day is returned by
getNanosOfDay
. The day varies in length, being one second longer on a leap day.This instance is immutable and unaffected by this method call.
 Parameters:
mjDay
 the date as a Modified Julian Day (number of days from the epoch of 18581117) Returns:
 a
UtcInstant
based on this instant with the requested day, not null  Throws:
DateTimeException
 if nanoOfDay becomes invalid

getNanoOfDay
public long getNanoOfDay()
Gets the number of nanoseconds, later along the timeline, from the start of the Modified Julian Day.The nanosecondofday value measures the total number of nanoseconds within the day from the start of the day returned by
getModifiedJulianDay
. This value will include any additional leap seconds. Returns:
 the nanoseconds within the day, including leap seconds

withNanoOfDay
public UtcInstant withNanoOfDay(long nanoOfDay)
Returns a copy of thisUtcInstant
with the nanoofday altered.The nanosecondofday value measures the total number of nanoseconds within the day from the start of the day returned by
getModifiedJulianDay
. This value will include any additional leap seconds.This instance is immutable and unaffected by this method call.
 Parameters:
nanoOfDay
 the nanoseconds within the day, including leap seconds Returns:
 a
UtcInstant
based on this instant with the requested nanoofday, not null  Throws:
DateTimeException
 if the nanoOfDay value is invalid

isLeapSecond
public boolean isLeapSecond()
Checks if the instant is within a leap second.This method returns true when an accurate clock would return a seconds field of 60.
 Returns:
 true if this instant is within a leap second

plus
public UtcInstant plus(Duration duration)
Returns a copy of this instant with the specified duration added.The duration is added using simple addition of the seconds and nanoseconds in the duration to the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.
This instance is immutable and unaffected by this method call.
 Parameters:
duration
 the duration to add, not null Returns:
 a
UtcInstant
with the duration added, not null  Throws:
ArithmeticException
 if the calculation exceeds the supported range

minus
public UtcInstant minus(Duration duration)
Returns a copy of this instant with the specified duration subtracted.The duration is subtracted using simple subtraction of the seconds and nanoseconds in the duration from the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.
This instance is immutable and unaffected by this method call.
 Parameters:
duration
 the duration to subtract, not null Returns:
 a
UtcInstant
with the duration subtracted, not null  Throws:
ArithmeticException
 if the calculation exceeds the supported range

durationUntil
public Duration durationUntil(UtcInstant utcInstant)
Returns the duration between this instant and the specified instant.This calculates the duration between this instant and another based on the UTC timescale. Any leap seconds that occur will be included in the duration. Adding the duration to this instant using
plus(java.time.Duration)
will always result in an instant equal to the specified instant. Parameters:
utcInstant
 the instant to calculate the duration until, not null Returns:
 the duration until the specified instant, may be negative, not null
 Throws:
ArithmeticException
 if the calculation exceeds the supported range

toInstant
public Instant toInstant()
Converts this instant to anInstant
.Converting a UTC instant to UTCSLS requires leap second rules. This method uses the latest available system rules.
Conversion to an
Instant
will not be completely accurate near a leap second in accordance with UTCSLS. Returns:
 an
Instant
representing the best approximation of this instant, not null  Throws:
DateTimeException
 if the range ofInstant
is exceededArithmeticException
 if numeric overflow occurs

toTaiInstant
public TaiInstant toTaiInstant()
Converts this instant to aTaiInstant
.Converting a UTC instant to TAI requires leap second rules. This method uses the latest available system rules.
The
TaiInstant
will represent exactly the same point on the timeline as per the available leapsecond rules. If the leapsecond rules change then conversion back to UTC may result in a different instant. Returns:
 a
TaiInstant
representing the same instant, not null  Throws:
DateTimeException
 if the range ofTaiInstant
is exceededArithmeticException
 if numeric overflow occurs

compareTo
public int compareTo(UtcInstant otherInstant)
Compares this instant to another based on the timeline.The comparison is based first on the Modified Julian Day, then on the nanoofday. It is "consistent with equals", as defined by
Comparable
. Specified by:
compareTo
in interfaceComparable<UtcInstant>
 Parameters:
otherInstant
 the other instant to compare to, not null Returns:
 the comparator value, negative if less, positive if greater

isAfter
public boolean isAfter(UtcInstant otherInstant)
Checks if this instant is after the specified instant.The comparison is based on the timeline 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(UtcInstant otherInstant)
Checks if this instant is before the specified instant.The comparison is based on the timeline 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 specifiedUtcInstant
.The comparison is based on the Modified Julian Day, then on the nanoofday.

hashCode
public int hashCode()
Returns a hash code for this instant.

toString
public String toString()
A string representation of this instant.The string is formatted using ISO8601. The output includes seconds, 9 nanosecond digits and a trailing 'Z'. The timeofday will be 23:59:60 during a positive leap second.

