LeapSeconds (Time4J-Core 2.0 API)

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

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:
    LeapSecondProvider.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

Class LeapSeconds

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SUPPRESS_UTC_LEAPSECONDS

FINAL_UTC_LEAPSECONDS

Method Detail

getInstance

isEnabled

isExtensible

getCount

registerPositiveLS

registerNegativeLS

supportsNegativeLS

iterator

getShift

getShift

enhance

strip

isPositiveLS

toString