net.time4j.scale

Class LeapSeconds

java.lang.Object

net.time4j.scale.LeapSeconds

All Implemented Interfaces:

Iterable<LeapSecondEvent>

public final class LeapSeconds
extends Object
implements Iterable<LeapSecondEvent>

Holds all leapseconds occurred since the official start of UTC in 1972.

The source is either an implementation of the SPI-interface Provider loaded by a ServiceLoader or an internal standard implementation of Provider which accesses the file "leapseconds.data". This resource file must be in the classpath (in folder data). It has the format of a CSV-ASCII-text which has two columns separated by comma. The first column denotes the calendar day after the leapsecond-shift in ISO-8601-format (for example 1972-07-01). The second column determines the sign of the leapsecond (+/-).

The source will mainly be loaded by the context classloader else by application classloader. If there is no source at all then Time4J assumes that leapseconds shall not be used.

The system property "time4j.scale.leapseconds.suppressed" determines if leapseconds shall be active at all. If this system property has the value true then this class will never register any leapseconds equal if the underlying sources are filled or not. Furthermore, the system property "time4j.scale.leapseconds.final" determines if leapseconds are only registered at system start or if new ones can be lazily registered at runtime using the methods registerXYZ(). Setting one of both properties can improve the performance.

Author:

Meno Hochschild

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	LeapSeconds.Provider This SPI-interface describes when UTC-leapseconds were introduced.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	FINAL_UTC_LEAPSECONDS System property "net.time4j.scale.leapseconds.final" which determines that leapseconds can be laoded only one time at system start.
static boolean	SUPPRESS_UTC_LEAPSECONDS System property "net.time4j.scale.leapseconds.suppressed" which determines that no leapseconds shall be loaded and used.

Method Summary

Methods

Modifier and Type	Method and Description
long	enhance(long unixTime) Enhances an UNIX-timestamp with leapseconds and converts it to an UTC-timestamp.
int	getCount() Yields the count of all registered leapseconds.
static LeapSeconds	getInstance() Returns the singleton instance.
int	getShift(GregorianDate date) Yields the shift in seconds suitable for the last minute of given calendar date.
int	getShift(long utc) Yields the shift in seconds dependent on if given UTC time point represents a leapsecond or not.
boolean	isEnabled() Queries if the leapsecond support is activated.
boolean	isExtensible() Queries if a lazy registration of leapseconds is possible.
boolean	isPositiveLS(long utc) Queries if given UTC-timestamp represents a registered positive leapsecond.
Iterator<LeapSecondEvent>	iterator() Iterates over all leapsecond events in descending temporal order.
void	registerNegativeLS(int year, int month, int dayOfMonth) Registers a new negative leapsecond by defining the switch-over-day.
void	registerPositiveLS(int year, int month, int dayOfMonth) Registers a new positive leapsecond by defining the switch-over-day.
long	strip(long utc) Converts given UTC-timestamp to an UNIX-timestamp without leapseconds.
boolean	supportsNegativeLS() Queries if negative leapseconds are supported.
String	toString() For debugging purposes.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SUPPRESS_UTC_LEAPSECONDS

public static final boolean SUPPRESS_UTC_LEAPSECONDS

System property "net.time4j.scale.leapseconds.suppressed" which determines that no leapseconds shall be loaded and used.

Defined values: "true" (suppressed) or "false" (active - default).

FINAL_UTC_LEAPSECONDS

public static final boolean FINAL_UTC_LEAPSECONDS

System property "net.time4j.scale.leapseconds.final" which determines that leapseconds can be laoded only one time at system start.

Defined values: "true" (final) or "false" (enables lazy regisration - default).

Method Detail

getInstance

public static LeapSeconds getInstance()

Returns the singleton instance.

Returns:

singleton instance

isEnabled

public boolean isEnabled()

Queries if the leapsecond support is activated.

Returns:

true if leap seconds are supported and are also registered else false

See Also:

SUPPRESS_UTC_LEAPSECONDS

isExtensible

public boolean isExtensible()

Queries if a lazy registration of leapseconds is possible.

If the leapsecond support is switched off then a registration of leapseconds is never possible so this method will be ignored.

Returns:

true if the method registerXYZ() can be called without exception else false

See Also:

registerPositiveLS(int, int, int), registerNegativeLS(int, int, int), FINAL_UTC_LEAPSECONDS, isEnabled()

getCount

public int getCount()

Yields the count of all registered leapseconds.

Returns:

count of registered leap seconds

registerPositiveLS

public void registerPositiveLS(int year,
                      int month,
                      int dayOfMonth)

Registers a new positive leapsecond by defining the switch-over-day.

Parameters:

year - proleptic iso year

month - gregorian month in range (1-12)

dayOfMonth - day of month in range (1-31)

Throws:

IllegalStateException - if support of leap seconds is switched off by configuration or if the value of system property "net.time4j.utc.leapseconds.final" is true

IllegalArgumentException - if the new event is not after the last stored event or if the date is invalid

See Also:

isExtensible(), isEnabled(), SUPPRESS_UTC_LEAPSECONDS, FINAL_UTC_LEAPSECONDS

registerNegativeLS

public void registerNegativeLS(int year,
                      int month,
                      int dayOfMonth)

Registers a new negative leapsecond by defining the switch-over-day.

Parameters:

year - proleptic iso year

month - gregorian month in range (1-12)

dayOfMonth - day of month in range (1-31)

Throws:

IllegalStateException - if support of leap seconds is switched off by configuration or if the value of system property "net.time4j.utc.leapseconds.final" is true

IllegalArgumentException - if the new event is not after the last stored event or if the date is invalid

See Also:

isExtensible(), isEnabled(), SUPPRESS_UTC_LEAPSECONDS, FINAL_UTC_LEAPSECONDS

supportsNegativeLS

public boolean supportsNegativeLS()

Queries if negative leapseconds are supported.

Returns:

true if negative leap seconds are supported else false

See Also:

LeapSeconds.Provider.supportsNegativeLS()

iterator

public Iterator<LeapSecondEvent> iterator()

Iterates over all leapsecond events in descending temporal order.

Specified by:

iterator in interface Iterable<LeapSecondEvent>

Returns:

Iterator over all stored leap second events which enables for-each-support

getShift

public int getShift(GregorianDate date)

Yields the shift in seconds suitable for the last minute of given calendar date.

The result of this method can be added to the second value 59 in order to calculate the maximum of the element SECOND_OF_MINUTE in given time context. The behaviour of the method is undefined if given calendar date is undefined.

Parameters:

date - day of possible leap second event in the last minute

Returns:

shift of second element (most of the times just 0)

getShift

public int getShift(long utc)

Yields the shift in seconds dependent on if given UTC time point represents a leapsecond or not.

Parameters:

utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds

Returns:

1, 0, -1 if the argument denotes a positive leapsecond no leapsecond or a negative leapsecond

enhance

public long enhance(long unixTime)

Enhances an UNIX-timestamp with leapseconds and converts it to an UTC-timestamp.

Note: A leapsecond itself cannot be restored because the mapping between UNIX- and UTC-time is not bijective. Hence the result of this method can not represent a leapsecond.

Parameters:

unixTime - elapsed time in seconds relative to UNIX epoch [1970-01-01T00:00:00Z] without leap seconds

Returns:

elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds

See Also:

strip(long)

strip

public long strip(long utc)

Converts given UTC-timestamp to an UNIX-timestamp without leapseconds.

This method is the reversal of enhance(). Note that there is no bijective mapping, that is sometimes the expression enhance(strip(val)) != val is true.

Parameters:

utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds

Returns:

elapsed time in seconds relative to UNIX epoch [1970-01-01T00:00:00Z] without leap seconds

See Also:

enhance(long)

isPositiveLS

public boolean isPositiveLS(long utc)

Queries if given UTC-timestamp represents a registered positive leapsecond.

Parameters:

utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds

Returns:

true if the argument represents a registered positive leap second else false

toString

public String toString()

For debugging purposes.

Overrides:

toString in class Object

Returns:

table of leap seconds as String