- java.lang.Object
-
- org.threeten.extra.scale.UtcRules
-
public abstract class UtcRules extends Object
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
andTaiInstant
. 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 beSerializable
wherever possible.
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
UtcRules()
Creates an instance of the rules.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description Instant
convertToInstant(TaiInstant taiInstant)
Converts aTaiInstant
to anInstant
.Instant
convertToInstant(UtcInstant utcInstant)
Converts aUtcInstant
to anInstant
.TaiInstant
convertToTai(Instant instant)
Converts anInstant
to aTaiInstant
.TaiInstant
convertToTai(UtcInstant utcInstant)
Converts aUtcInstant
to aTaiInstant
.UtcInstant
convertToUtc(Instant instant)
Converts anInstant
to aUtcInstant
.abstract UtcInstant
convertToUtc(TaiInstant taiInstant)
Converts aTaiInstant
to aUtcInstant
.abstract int
getLeapSecondAdjustment(long mjDay)
Gets the leap second adjustment on the specified date.abstract long[]
getLeapSecondDates()
Gets all known leap second dates.abstract String
getName()
The name of these rules.abstract int
getTaiOffset(long mjDay)
Gets the offset to TAI on the specified date.static void
registerLeapSecond(long mjDay, int leapAdjustment)
Adds a new leap second to the system default leap second rules.static UtcRules
system()
Gets the system default leap second rules.String
toString()
A string representation of these rules.void
validateModifiedJulianDay(long mjDay, long nanoOfDay)
Validates combination of Modified Julian Day and nanosecond-of-day.
-
-
-
Method Detail
-
system
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:
- the system rules, not null
-
registerLeapSecond
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
- the Modified Julian Day that the leap second occurs at the end ofleapAdjustment
- the leap seconds to add/remove at the end of the day, either -1 or 1- Throws:
IllegalArgumentException
- if the leap adjustment is invalidIllegalArgumentException
- if the day is before or equal the last known leap second day and the definition does not match a previously registered leapConcurrentModificationException
- if another thread updates the rules at the same time
-
getName
public abstract String getName()
The name of these rules.- Returns:
- the name, not null
-
getLeapSecondAdjustment
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
or1
.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
- the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)- Returns:
- the number of seconds added, or removed, from the date, either -1 or 1
-
getTaiOffset
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
- the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)- Returns:
- the TAI offset in seconds
-
getLeapSecondDates
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:
- an array of leap second dates expressed as Modified Julian Day values, not null
-
validateModifiedJulianDay
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
to86,400,000,000,000 - 1
on most days, and a larger or smaller range on leap-second days.- Parameters:
mjDay
- the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)nanoOfDay
- the nanoseconds within the day, including leap seconds- Throws:
DateTimeException
- if nanoOfDay is out of range
-
convertToTai
public TaiInstant convertToTai(UtcInstant utcInstant)
Converts aUtcInstant
to aTaiInstant
.This method converts from the UTC to the TAI time-scale using the leap-second rules of the implementation.
- Parameters:
utcInstant
- the UTC instant to convert, not null- Returns:
- the converted TAI instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
convertToUtc
public abstract UtcInstant convertToUtc(TaiInstant taiInstant)
Converts aTaiInstant
to aUtcInstant
.This method converts from the TAI to the UTC time-scale using the leap-second rules of the implementation.
- Parameters:
taiInstant
- the TAI instant to convert, not null- Returns:
- the converted UTC instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
convertToInstant
public Instant convertToInstant(UtcInstant utcInstant)
Converts aUtcInstant
to anInstant
.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 dayU
.
LetL = getLeapAdjustment(mjd)
.
LetB = 86400 + L - 1000
.
LetUS = U - L * (U - B) / 1000
.
Where the algorithm is applied whileU >= B
.- Parameters:
utcInstant
- the UTC instant to convert, not null- Returns:
- the converted instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
convertToUtc
public UtcInstant convertToUtc(Instant instant)
Converts anInstant
to aUtcInstant
.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 dayUS
.
LetL = getLeapAdjustment(mjd)
.
LetB = 86400 + L - 1000
.
LetU = B + ((US - B) * 1000) / (1000 - L)
.
Where the algorithm is applied whileUS >= B
.
(This algorithm has been tuned for integer arithmetic from the UTC-SLS specification.)- Parameters:
instant
- the instant to convert, not null- Returns:
- the converted UTC instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
convertToInstant
public Instant convertToInstant(TaiInstant taiInstant)
Converts aTaiInstant
to anInstant
.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)
andconvertToInstant(UtcInstant)
.- Parameters:
taiInstant
- the TAI instant to convert, not null- Returns:
- the converted instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
convertToTai
public TaiInstant convertToTai(Instant instant)
Converts anInstant
to aTaiInstant
.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)
andconvertToInstant(UtcInstant)
.- Parameters:
instant
- the instant to convert, not null- Returns:
- the converted instant, not null
- Throws:
DateTimeException
- if the valid range is exceededArithmeticException
- if numeric overflow occurs
-
-