Top Description Fields Constructors Methods
org.threeten.extra.scale

public abstract Class UtcRules

extends Object
Class Inheritance
Known Direct Subclasses
org.threeten.extra.scale.SystemUtcRules
Imports
java.time.DateTimeException, .Instant, java.util.ConcurrentModificationException
Rules defining the UTC time-scale, notably when leap seconds occur.

This class defines the UTC time-scale including when leap seconds occur. Subclasses obtain the data from a suitable source, such as a file.

The static methods on this class provide access to the system leap second rules. These are used by default in UtcInstant and TaiInstant. Using other rules requires manual use of this class.

The system rules can be updated using a LeapSeconds.txt} file. You can create your own version of this file and place it in on the classpath and it will be used. Due to Java 9 module restrictions, the file is located under META-INF to avoid module encapsulation problems - META-INF/org/threeten/extra/scale/LeapSeconds.txt.

Implementation Requirements:

This is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All implementations must be final, immutable and thread-safe. Subclasses should be Serializable wherever possible.

Field Summary

Modifier and TypeField and Description
pack-priv static final long
NANOS_PER_SECOND

Constant for nanos per standard second: 1,000,000,000.

pack-priv static final int
OFFSET_MJD_EPOCH

Constant for the offset from MJD day 0 to the Java Epoch of 1970-01-01: 40587.

pack-priv static final int
OFFSET_MJD_TAI

Constant for the offset from MJD day 0 to TAI day 0 of 1958-01-01: 36204.

pack-priv static final long
SECS_PER_DAY

Constant for number of seconds per standard day: 86,400.

Constructor Summary

AccessConstructor and Description
protected
UtcRules()

Creates an instance of the rules.

Method Summary

Modifier and TypeMethod and Description
public Instant

Returns:

the converted instant, not null
convertToInstant(UtcInstant
the UTC instant to convert, not null
utcInstant)

Converts a UtcInstant to an Instant.

public Instant

Returns:

the converted instant, not null
convertToInstant(TaiInstant
the TAI instant to convert, not null
taiInstant)

Converts a TaiInstant to an Instant.

public TaiInstant

Returns:

the converted TAI instant, not null
convertToTai(UtcInstant
the UTC instant to convert, not null
utcInstant)

Converts a UtcInstant to a TaiInstant.

public TaiInstant

Returns:

the converted instant, not null
convertToTai(Instant
the instant to convert, not null
instant)

Converts an Instant to a TaiInstant.

public abstract UtcInstant

Returns:

the converted UTC instant, not null
convertToUtc(TaiInstant
the TAI instant to convert, not null
taiInstant)

Converts a TaiInstant to a UtcInstant.

public UtcInstant

Returns:

the converted UTC instant, not null
convertToUtc(Instant
the instant to convert, not null
instant)

Converts an Instant to a UtcInstant.

public abstract int

Returns:

the number of seconds added, or removed, from the date, either -1 or 1
getLeapSecondAdjustment(long
the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
mjDay)

Gets the leap second adjustment on the specified date.

public abstract long[]

Returns:

an array of leap second dates expressed as Modified Julian Day values, not null
getLeapSecondDates()

Gets all known leap second dates.

public abstract String

Returns:

the name, not null
getName()

The name of these rules.

public abstract int

Returns:

the TAI offset in seconds
getTaiOffset(long
the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
mjDay)

Gets the offset to TAI on the specified date.

public static void
registerLeapSecond(long
the Modified Julian Day that the leap second occurs at the end of
mjDay, int
the leap seconds to add/remove at the end of the day, either -1 or 1
leapAdjustment)

Adds a new leap second to the system default leap second rules.

public static UtcRules

Returns:

the system rules, not null
system()

Gets the system default leap second rules.

public String

Returns:

the string representation, not null
toString()

Overrides java.lang.Object.toString.

A string representation of these rules.

public void
validateModifiedJulianDay(long
the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
mjDay, long
the nanoseconds within the day, including leap seconds
nanoOfDay)

Validates combination of Modified Julian Day and nanosecond-of-day.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

NANOS_PER_SECONDback to summary
pack-priv static final long NANOS_PER_SECOND

Constant for nanos per standard second: 1,000,000,000.

OFFSET_MJD_EPOCHback to summary
pack-priv static final int OFFSET_MJD_EPOCH

Constant for the offset from MJD day 0 to the Java Epoch of 1970-01-01: 40587.

OFFSET_MJD_TAIback to summary
pack-priv static final int OFFSET_MJD_TAI

Constant for the offset from MJD day 0 to TAI day 0 of 1958-01-01: 36204.

SECS_PER_DAYback to summary
pack-priv static final long SECS_PER_DAY

Constant for number of seconds per standard day: 86,400.

Constructor Detail

UtcRulesback to summary
protected UtcRules()

Creates an instance of the rules.

Method Detail

convertToInstantback to summary
public Instant convertToInstant(UtcInstant utcInstant)

Converts a UtcInstant to an Instant.

This method converts from the UTC time-scale to one with 86400 subdivisions per day using the leap-second rules of the implementation.

The standard implementation uses the UTC-SLS algorithm. Overriding this algorithm is possible, however doing so will conflict other parts of the specification.

The algorithm calculates the UTC-SLS nanos-of-day US from the UTC nanos-of day U.
Let L = getLeapAdjustment(mjd).
Let B = 86400 + L - 1000.
Let US = U - L * (U - B) / 1000.
Where the algorithm is applied while U >= B.

Parameters
utcInstant:UtcInstant

the UTC instant to convert, not null

Returns:Instant

the converted instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
convertToInstantback to summary
public Instant convertToInstant(TaiInstant taiInstant)

Converts a TaiInstant to an Instant.

This method converts from the TAI time-scale to one with 86400 subdivisions per day using the leap-second rules of the implementation.

The standard implementation uses UTC-SLS. It uses convertToUtc(TaiInstant) and convertToInstant(UtcInstant).

Parameters
taiInstant:TaiInstant

the TAI instant to convert, not null

Returns:Instant

the converted instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
convertToTaiback to summary
public TaiInstant convertToTai(UtcInstant utcInstant)

Converts a UtcInstant to a TaiInstant.

This method converts from the UTC to the TAI time-scale using the leap-second rules of the implementation.

Parameters
utcInstant:UtcInstant

the UTC instant to convert, not null

Returns:TaiInstant

the converted TAI instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
convertToTaiback to summary
public TaiInstant convertToTai(Instant instant)

Converts an Instant to a TaiInstant.

This method converts from an instant with 86400 subdivisions per day to the TAI time-scale using the leap-second rules of the implementation.

The standard implementation uses the UTC-SLS algorithm. It uses convertToUtc(TaiInstant) and convertToInstant(UtcInstant).

Parameters
instant:Instant

the instant to convert, not null

Returns:TaiInstant

the converted instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
convertToUtcback to summary
public abstract UtcInstant convertToUtc(TaiInstant taiInstant)

Converts a TaiInstant to a UtcInstant.

This method converts from the TAI to the UTC time-scale using the leap-second rules of the implementation.

Parameters
taiInstant:TaiInstant

the TAI instant to convert, not null

Returns:UtcInstant

the converted UTC instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
convertToUtcback to summary
public UtcInstant convertToUtc(Instant instant)

Converts an Instant to a UtcInstant.

This method converts from an instant with 86400 subdivisions per day to the UTC time-scale using the leap-second rules of the implementation.

The standard implementation uses the UTC-SLS algorithm. Overriding this algorithm is possible, however doing so will conflict other parts of the specification.

The algorithm calculates the UTC nanos-of-day U from the UTC-SLS nanos-of day US.
Let L = getLeapAdjustment(mjd).
Let B = 86400 + L - 1000.
Let U = B + ((US - B) * 1000) / (1000 - L).
Where the algorithm is applied while US >= B.
(This algorithm has been tuned for integer arithmetic from the UTC-SLS specification.)

Parameters
instant:Instant

the instant to convert, not null

Returns:UtcInstant

the converted UTC instant, not null

Exceptions
DateTimeException:
if the valid range is exceeded
ArithmeticException:
if numeric overflow occurs
getLeapSecondAdjustmentback to summary
public abstract int getLeapSecondAdjustment(long mjDay)

Gets the leap second adjustment on the specified date.

The UTC standard restricts the adjustment on any day to -1 or 1.

Any leap seconds are added to, or removed from, the end of the specified date.

If the UTC specification is altered to allow multiple leap seconds at once, then the result of this method would return a number with an absolute value greater than one.

Parameters
mjDay:long

the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)

Returns:int

the number of seconds added, or removed, from the date, either -1 or 1

getLeapSecondDatesback to summary
public abstract long[] getLeapSecondDates()

Gets all known leap second dates.

The dates are returned as Modified Julian Day values. The leap second is added to, or removed from, the end of the specified dates. The dates will be sorted from earliest to latest.

Returns:long[]

an array of leap second dates expressed as Modified Julian Day values, not null

getNameback to summary
public abstract String getName()

The name of these rules.

Returns:String

the name, not null

getTaiOffsetback to summary
public abstract int getTaiOffset(long mjDay)

Gets the offset to TAI on the specified date.

The TAI offset starts at 10 in 1972 and varies from then on based on the dates of leap seconds. The offset will apply for the whole of the date.

Parameters
mjDay:long

the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)

Returns:int

the TAI offset in seconds

registerLeapSecondback to summary
public static void registerLeapSecond(long mjDay, int leapAdjustment)

Adds a new leap second to the system default leap second rules.

This method registers a new leap second with the system leap second rules. Once registered, there is no way to deregister the leap second.

Calling this method is thread-safe. Its effects are immediately visible in all threads. Where possible, only call this method from a single thread to avoid the possibility of a ConcurrentModificationException.

If the leap second being added matches a previous definition, then the method returns normally. If the date is before the last registered date and does not match a previous definition, then an exception is thrown.

Parameters
mjDay:long

the Modified Julian Day that the leap second occurs at the end of

leapAdjustment:int

the leap seconds to add/remove at the end of the day, either -1 or 1

Exceptions
IllegalArgumentException:
  • if the leap adjustment is invalid
  • if the day is before or equal the last known leap second day and the definition does not match a previously registered leap
ConcurrentModificationException:
if another thread updates the rules at the same time
systemback to summary
public static UtcRules system()

Gets the system default leap second rules.

The system default rules are serializable, immutable and thread-safe. They will remain up to date as new leap seconds are added.

Returns:UtcRules

the system rules, not null

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

A string representation of these rules.

Returns:String

the string representation, not null

Annotations
@Override
validateModifiedJulianDayback to summary
public void validateModifiedJulianDay(long mjDay, long nanoOfDay)

Validates combination of Modified Julian Day and nanosecond-of-day.

Modified Julian Day is a simple incrementing count of days where day 0 is 1858-11-17. Nanosecond-of-day is a simple count of nanoseconds from the start of the day including any additional leap-second. This method validates the nanosecond-of-day value against the Modified Julian Day.

The nanosecond-of-day value has a valid range from 0 to 86,400,000,000,000 - 1 on most days, and a larger or smaller range on leap-second days.

Parameters
mjDay:long

the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)

nanoOfDay:long

the nanoseconds within the day, including leap seconds

Exceptions
DateTimeException:
if nanoOfDay is out of range