agi.foundation.time

(agi.foundation.core-2024r3.jar)

Class LeapSecondFile

java.lang.Object

agi.foundation.time.LeapSecondFile

public final class LeapSecondFile
extends Object

Contains static methods to read and write leap second data in a standard format.

This example shows how to load leap second data from a file and use it in the current calculation context:

LeapSecondsFacet leapSeconds = LeapSecondFile.readLeapSeconds(filename);
leapSeconds.useInCurrentContext();

This example shows how to download leap second data over the internet from an AGI server, and use it in the current calculation context:

LeapSecondsFacet leapSeconds = LeapSecondFile.downloadLeapSeconds();
leapSeconds.useInCurrentContext();

The LeapSecond.dat file is an ASCII text file which contains the dates of all historical and announced leap seconds that would affect the conversion between the UTC time scale and other time scales.

The latest file containing all known leap seconds can be found at https://ftp.agi.com/pub/STKData/Astro/LeapSecond.dat. The information in the file is obtained from the U.S Naval Observatory leap second information file.

The format of the LeapSecond.dat file consists of an initial line with an integer value indicating the number of leap second entries that the file contains, followed by a leap second entry on each subsequent line of the file.

A leap second entry consists of the following space-delimited information:

• The Gregorian calendar 4-digit year, abbreviated month name, and day of the date immediately following the leap second.
• The corresponding Julian date.
• The difference between TAI and UTC time scales (the accumulated number of leap seconds) as of the corresponding date.
• The modified Julian date of the epoch at which the following rate is established. Obsolete as of 1 Jan 1972. Since then, the value of this epoch has been defined as 41317.0. This value is not read from the file, and is not used.
• The rate at which the UTC time scale is slowing with respect to the TAI time scale. Obsolete as of 1 Jan 1972. Since then, the value of this rate has been defined as 0.0. This value is not read from the file, and is not used.

The following is an example of a leap second file in this format:

 28
  1972 JAN  1   2441317.5     10.0        41317.  0.0
  1972 JUL  1   2441499.5     11.0        41317.  0.0
  1973 JAN  1   2441683.5     12.0        41317.  0.0
  1974 JAN  1   2442048.5     13.0        41317.  0.0
  1975 JAN  1   2442413.5     14.0        41317.  0.0
  1976 JAN  1   2442778.5     15.0        41317.  0.0
  1977 JAN  1   2443144.5     16.0        41317.  0.0
  1978 JAN  1   2443509.5     17.0        41317.  0.0
  1979 JAN  1   2443874.5     18.0        41317.  0.0
  1980 JAN  1   2444239.5     19.0        41317.  0.0
  1981 JUL  1   2444786.5     20.0        41317.  0.0
  1982 JUL  1   2445151.5     21.0        41317.  0.0
  1983 JUL  1   2445516.5     22.0        41317.  0.0
  1985 JUL  1   2446247.5     23.0        41317.  0.0
  1988 JAN  1   2447161.5     24.0        41317.  0.0
  1990 JAN  1   2447892.5     25.0        41317.  0.0
  1991 JAN  1   2448257.5     26.0        41317.  0.0
  1992 JUL  1   2448804.5     27.0        41317.  0.0
  1993 JUL  1   2449169.5     28.0        41317.  0.0
  1994 JUL  1   2449534.5     29.0        41317.  0.0
  1996 JAN  1   2450083.5     30.0        41317.  0.0
  1997 JUL  1   2450630.5     31.0        41317.  0.0
  1999 JAN  1   2451179.5     32.0        41317.  0.0
  2006 JAN  1   2453736.5     33.0        41317.  0.0
  2009 JAN  1   2454832.5     34.0        41317.  0.0
  2012 JUL  1   2456109.5     35.0        41317.  0.0
  2015 JUL  1   2457204.5     36.0        41317.  0.0
  2017 JAN  1   2457754.5     37.0        41317.  0.0
 

EarthOrientationParametersFile contains EarthOrientationParameters which describe the motion of the Earth's spin axis (pole wander) and the irregular rotation rate of the Earth. These parameters are used in the computation of the transformation between the Earth centered fixed reference frame and Earth centered inertial frames. At the time of a leap second, the time history of the Earth's irregular rotation rate experiences a discontinuity of 1 second. It is therefore important that the Earth orientation parameters and leap second information be updated together to properly establish the existence of the new leap second.

See Also:

LeapSecond, EarthOrientationParameters, EarthOrientationParametersFile

Method Summary

Modifier and Type	Method and Description
static LeapSecondsFacet	downloadLeapSeconds() Downloads the latest leap second file (LeapSecond.dat) from an AGI server.
static LeapSecondsFacet	downloadLeapSeconds(Proxy proxy) Downloads the latest leap second file (LeapSecond.dat) from an AGI server.
static LeapSecondsFacet	readLeapSeconds(BufferedReader source) Reads an STK leap second file and returns a new LeapSecondsFacet instance initialized with the contents of the file.
static LeapSecondsFacet	readLeapSeconds(String fileName) Reads an STK leap second file and returns a new LeapSecondsFacet instance initialized with the contents of the file.
static void	writeLeapSeconds(Writer writer, LeapSecondsFacet leapSeconds) Writes the specified LeapSecondsFacet instance to a stream in STK leap second file format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

downloadLeapSeconds

@Nonnull
public static LeapSecondsFacet downloadLeapSeconds()

Downloads the latest leap second file (LeapSecond.dat) from an AGI server. This method connects via HTTPS to ftp.agi.com.

Note that an internet connection is required to use this method successfully.

Returns:

A new LeapSecondsFacet initialized with the contents of the file.

Throws:

InvalidDataException - Thrown when there is an error parsing the leap second data.

DataUnavailableException - Thrown when the data cannot be retrieved from the server.

downloadLeapSeconds

@Nonnull
public static LeapSecondsFacet downloadLeapSeconds(@Nullable
                                                             Proxy proxy)

Downloads the latest leap second file (LeapSecond.dat) from an AGI server. This method connects via HTTPS to ftp.agi.com.

Note that an internet connection is required to use this method successfully.

Parameters:

proxy - Proxy to use when connecting. Optional, default is null.

Returns:

A new LeapSecondsFacet initialized with the contents of the file.

Throws:

InvalidDataException - Thrown when there is an error parsing the leap second data.

DataUnavailableException - Thrown when the data cannot be retrieved from the server.

readLeapSeconds

@Nonnull
public static LeapSecondsFacet readLeapSeconds(@Nonnull
                                                         String fileName)

Reads an STK leap second file and returns a new LeapSecondsFacet instance initialized with the contents of the file.

Parameters:

fileName - The name of the file from which to read.

Returns:

A new LeapSecondsFacet initialized with the contents of the file.

Throws:

ArgumentNullException - Thrown when fileName is null.

InvalidDataException - Thrown when there is an error parsing the leap second data.

readLeapSeconds

@Nonnull
public static LeapSecondsFacet readLeapSeconds(@Nonnull
                                                         BufferedReader source)

Reads an STK leap second file and returns a new LeapSecondsFacet instance initialized with the contents of the file.

Parameters:

source - The stream from which to read.

Returns:

A new LeapSecondsFacet initialized with the contents of the file.

Throws:

ArgumentNullException - Thrown when source is null.

InvalidDataException - Thrown when there is an error parsing the leap second data.

writeLeapSeconds

public static void writeLeapSeconds(@Nonnull
                                    Writer writer,
                                    @Nonnull
                                    LeapSecondsFacet leapSeconds)

Writes the specified LeapSecondsFacet instance to a stream in STK leap second file format.

Parameters:

writer - The writer to which data will be written.

leapSeconds - The leap second data to write.

Throws:

ArgumentNullException - Thrown when writer or leapSeconds is null.