public abstract class UTCRules extends Object
This class defines the UTC time-scale including when leap seconds occur. Subclasses obtain the data from a suitable source, such as TZDB or GPS.
The static methods on this class provide access to the system leap second rules. These are used by default.
UTCRules 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.
Modifier and Type | Field and Description |
---|---|
protected static long |
NANOS_PER_SECOND
Constant for nanos per standard second: 1,000,000,000.
|
protected static int |
OFFSET_MJD_EPOCH
Constant for the offset from MJD day 0 to the Java Epoch of 1970-01-01: 40587.
|
protected static int |
OFFSET_MJD_TAI
Constant for the offset from MJD day 0 to TAI day 0 of 1958-01-01: 36204.
|
protected static long |
SECS_PER_DAY
Constant for number of seconds per standard day: 86,400.
|
Modifier | Constructor and Description |
---|---|
protected |
UTCRules()
Creates an instance of the rules.
|
Modifier and Type | Method and Description |
---|---|
protected Instant |
convertToInstant(UTCInstant utcInstant)
Converts a
UTCInstant to an Instant . |
protected TAIInstant |
convertToTAI(UTCInstant utcInstant)
Converts a
UTCInstant to a TAIInstant . |
protected UTCInstant |
convertToUTC(Instant instant)
Converts an
Instant to a UTCInstant . |
protected abstract UTCInstant |
convertToUTC(TAIInstant taiInstant)
Converts a
TAIInstant to a UTCInstant . |
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 |
registerSystemLeapSecond(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.
|
protected static final int OFFSET_MJD_EPOCH
protected static final int OFFSET_MJD_TAI
protected static final long SECS_PER_DAY
protected static final long NANOS_PER_SECOND
public static UTCRules system()
The system default rules are serializable, immutable and thread-safe. They will remain up to date as new leap seconds are added.
public static void registerSystemLeapSecond(long mjDay, int leapAdjustment)
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 doesn't match, then an exception is thrown.
mjDay
- the modified julian date that the leap second occurs at the end ofleapAdjustment
- the leap seconds to add/remove at the end of the day, either -1 or 1IllegalArgumentException
- 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 timepublic abstract String getName()
public abstract int getLeapSecondAdjustment(long mjDay)
The UTC standard restricts the adjustment to a day to -1
or 1
.
Any leap seconds are added to, or removed from, the end of the specified date.
NOTE: If the UTC specification is altered to allow multiple leap seconds at once, then the result of this method would change.
mjDay
- the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)public abstract int getTAIOffset(long mjDay)
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.
mjDay
- the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)public abstract long[] getLeapSecondDates()
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.
protected TAIInstant convertToTAI(UTCInstant utcInstant)
UTCInstant
to a TAIInstant
.
This method converts from the UTC to the TAI time-scale using the leap-second rules of the implementation.
The standard implementation uses getTAIOffset
.
utcInstant
- the UTC instant to convert, not nullArithmeticException
- if the capacity is exceededprotected abstract UTCInstant convertToUTC(TAIInstant taiInstant)
TAIInstant
to a UTCInstant
.
This method converts from the TAI to the UTC time-scale using the leap-second rules of the implementation.
taiInstant
- the TAI instant to convert, not nullArithmeticException
- if the capacity is exceededprotected Instant convertToInstant(UTCInstant utcInstant)
UTCInstant
to an Instant
.
This method converts from the UTC time-scale to one with 86400 seconds 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
.
utcInstant
- the UTC instant to convert, not nullArithmeticException
- if the capacity is exceededprotected UTCInstant convertToUTC(Instant instant)
Instant
to a UTCInstant
.
This method converts from an instant with 86400 seconds 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.)
instant
- the instant to convert, not nullArithmeticException
- if the capacity is exceededCopyright © 2014. All rights reserved.