LeapSeconds (Time4J-Core 2.2 API)

java.lang.Object
- net.time4j.scale.LeapSeconds

All Implemented Interfaces:

Iterable<LeapSecondEvent>
```
public final class LeapSeconds
extends Object
implements Iterable<LeapSecondEvent>
```
Holds all leap seconds 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 leap second shift in ISO-8601-format (for example 1972-07-01). The second column determines the sign of the leap second (+/-).

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 leap seconds shall not be used.

The system property "time4j.scale.leapseconds.suppressed" determines if leap seconds shall be active at all. If this system property has the value true then this class will never register any leap seconds equal if the underlying sources are filled or not. Furthermore, the system property "time4j.scale.leapseconds.final" determines if leap seconds 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 leap seconds can be loaded only one time at system start.
`static String`	`PATH_TO_LEAPSECONDS` System property "net.time4j.scale.leapseconds.path" which determines the path of the leap second file.
`static boolean`	`SUPPRESS_UTC_LEAPSECONDS` System property "net.time4j.scale.leapseconds.suppressed" which determines that no leap seconds shall be loaded and used.

Method Summary

Methods
Modifier and Type	Method and Description
`long`	`enhance(long unixTime)` Enhances an UNIX-timestamp with leap seconds and converts it to an UTC-timestamp.
`int`	`getCount()` Yields the count of all registered leap seconds.
`static LeapSeconds`	`getInstance()` Returns the singleton instance.
`LeapSecondEvent`	`getNextEvent(long utc)` Yields the next leap second event after given UTC time point.
`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 leap second or not.
`boolean`	`isEnabled()` Queries if the leap second support is activated.
`boolean`	`isExtensible()` Queries if a lazy registration of leap seconds is possible.
`boolean`	`isPositiveLS(long utc)` Queries if given UTC-timestamp represents a registered positive leap second.
`Iterator<LeapSecondEvent>`	`iterator()` Iterates over all leap second events in descending temporal order.
`void`	`registerNegativeLS(int year, int month, int dayOfMonth)` Registers a new negative leap second by defining the switch-over-day.
`void`	`registerPositiveLS(int year, int month, int dayOfMonth)` Registers a new positive leap second by defining the switch-over-day.
`long`	`strip(long utc)` Converts given UTC-timestamp to an UNIX-timestamp without leap seconds.
`boolean`	`supportsNegativeLS()` Queries if negative leap seconds are supported.
`String`	`toString()` For debugging purposes.

Methods inherited from class java.lang.Object
clone, equals, finalize, 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 leap seconds 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 leap seconds can be loaded only one time at system start.
    
    Defined values: "true" (final) or "false" (enables lazy regisration - default).
  - PATH_TO_LEAPSECONDS
```
public static final String PATH_TO_LEAPSECONDS
```
    System property "net.time4j.scale.leapseconds.path" which determines the path of the leap second file.
    
    The file will be choosen if there is no other LeapSecondProvider which has registered more leap seconds. The path is an URL which must be understood by ClassLoader.getResourceAsStream(String). The default value is: "data/leapseconds.data" (relative to class path).
    
    Since:
    
    2.1.2
- Method Detail
  - getInstance
```
public static LeapSeconds getInstance()
```
    Returns the singleton instance.
    
    Returns:
    singleton instance
  - isEnabled
```
public boolean isEnabled()
```
    Queries if the leap second 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 leap seconds is possible.
    
    If the leap second support is switched off then a registration of leap seconds 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 leap seconds.
    
    Returns:
    count of registered leap seconds
  - registerPositiveLS
```
public void registerPositiveLS(int year,
                      int month,
                      int dayOfMonth)
```
    Registers a new positive leap second 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 leap second 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 leap seconds are supported.
    
    Returns:
    true if negative leap seconds are supported else false
    See Also:
    LeapSecondProvider.supportsNegativeLS()
  - iterator
```
public Iterator<LeapSecondEvent> iterator()
```
    Iterates over all leap second 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 leap second 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 leap second, no leap second or a negative leap second
  - getNextEvent
```
public LeapSecondEvent getNextEvent(long utc)
```
    Yields the next leap second event after given UTC time point.
    
    Parameters:
    utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
    
    Returns:
    following leap second event or null if not known
    Since:
    
    2.1
  - enhance
```
public long enhance(long unixTime)
```
    Enhances an UNIX-timestamp with leap seconds and converts it to an UTC-timestamp.
    
    Note: A leap second 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 leap second.
    
    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 leap seconds.
    
    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 leap second.
    
    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

PATH_TO_LEAPSECONDS

Method Detail

getInstance

isEnabled

isExtensible

getCount

registerPositiveLS

registerNegativeLS

supportsNegativeLS

iterator

getShift

getShift

getNextEvent

enhance

strip

isPositiveLS

toString