AbsoluteDate (parent patrimoine de base SIRIUS 3.3 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.orekit.time
Class AbsoluteDate

java.lang.Object
  org.orekit.time.AbsoluteDate

All Implemented Interfaces:: Serializable, Comparable<AbsoluteDate>, TimeShiftable<AbsoluteDate>, TimeStamped

Direct Known Subclasses:: DateDPFacade

public class AbsoluteDate
extends Object
implements TimeStamped, TimeShiftable<AbsoluteDate>, Comparable<AbsoluteDate>, Serializable
extends Object
implements TimeStamped, TimeShiftable<AbsoluteDate>, Comparable<AbsoluteDate>, Serializable

This class represents a specific instant in time.

Instances of this class are considered to be absolute in the sense that each one represent the occurrence of some event and can be compared to other instances or located in any time scale. In other words the different locations of an event with respect to two different time scale (say TAI and UTC for example) are simply different perspective related to a single object. Only one AbsoluteDate instance is needed, both representations being available from this single instance by specifying the time scales as parameter when calling the ad-hoc methods.

Since an instance is not bound to a specific time-scale, all methods related to the location of the date within some time scale require to provide the time scale as an argument. It is therefore possible to define a date in one time scale and to use it in another one. An example of such use is to read a date from a file in UTC and write it in another file in TAI. This can be done as follows:

   DateTimeComponents utcComponents = readNextDate();
   AbsoluteDate date = new AbsoluteDate(utcComponents, TimeScalesFactory.getUTC());
   writeNextDate(date.getComponents(TimeScalesFactory.getTAI()));

Two complementary views are available:

location view (mainly for input/output or conversions)

locations represent the coordinate of one event with respect to a time scale. The related methods are AbsoluteDate(DateComponents, TimeComponents, TimeScale), AbsoluteDate(int, int, int, int, int, double, TimeScale), AbsoluteDate(int, int, int, TimeScale), AbsoluteDate(Date, TimeScale), createGPSDate(int, double), parseCCSDSCalendarSegmentedTimeCode(byte, byte[]), toString()toDate(TimeScale), toString(timeScale), toString(), and timeScalesOffset(org.orekit.time.TimeScale, org.orekit.time.TimeScale).
offset view (mainly for physical computation)

offsets represent either the flow of time between two events (two instances of the class) or durations. They are counted in seconds, are continuous and could be measured using only a virtually perfect stopwatch. The related methods are AbsoluteDate(AbsoluteDate, double), parseCCSDSUnsegmentedTimeCode(byte, byte, byte[], AbsoluteDate), parseCCSDSDaySegmentedTimeCode(byte, byte[], DateComponents), durationFrom(AbsoluteDate), compareTo(AbsoluteDate), equals(Object) and hashCode().

A few reference epochs which are commonly used in space systems have been defined. These epochs can be used as the basis for offset computation. The supported epochs are: JULIAN_EPOCH, MODIFIED_JULIAN_EPOCH, FIFTIES_EPOCH_TT, CCSDS_EPOCH, GALILEO_EPOCH, GPS_EPOCH, J2000_EPOCH, JAVA_EPOCH. In addition to these reference epochs, two other constants are defined for convenience: PAST_INFINITY and FUTURE_INFINITY, which can be used either as dummy dates when a date is not yet initialized, or for initialization of loops searching for a min or max date.

Instances of the AbsoluteDate class are guaranteed to be immutable.

Author:: Luc Maisonobe
See Also:: TimeScale, TimeStamped, ChronologicalComparator, Serialized Form

Field Summary
`static AbsoluteDate`	`CCSDS_EPOCH` Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01T00:00:00 International Atomic Time (not UTC).
`static AbsoluteDate`	`FIFTIES_EPOCH_TAI` Reference epoch for 1950 dates: 1950-01-01T00:00:00 TAI.
`static AbsoluteDate`	`FIFTIES_EPOCH_TT` Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.
`static AbsoluteDate`	`FIFTIES_EPOCH_UTC` Reference epoch for 1950 dates: 1950-01-01T00:00:00 UTC.
`static AbsoluteDate`	`FUTURE_INFINITY` Dummy date at infinity in the future direction.
`static AbsoluteDate`	`GALILEO_EPOCH` Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.
`static AbsoluteDate`	`GPS_EPOCH` Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
`static AbsoluteDate`	`J2000_EPOCH` J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (not UTC).
`static AbsoluteDate`	`JAVA_EPOCH` Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate is equivalent to Java Reference epoch: 1970-01-01T00:00:08 TAI.
`static AbsoluteDate`	`JULIAN_EPOCH` Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.
`static AbsoluteDate`	`MODIFIED_JULIAN_EPOCH` Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.
`static AbsoluteDate`	`PAST_INFINITY` Dummy date at infinity in the past direction.

Constructor Summary
`AbsoluteDate()` Create an instance with a default value (`J2000_EPOCH`).
`AbsoluteDate(AbsoluteDate since, double elapsedDuration)` Build an instance from an elapsed duration since to another instant.
`AbsoluteDate(AbsoluteDate reference, double apparentOffset, TimeScale timeScale)` Build an instance from an apparent clock offset with respect to another instant in the perspective of a specific `time scale`.
`AbsoluteDate(DateComponents date, TimeComponents time, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(DateComponents date, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(DateTimeComponents location, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(Date location, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(int year, int month, int day, int hour, int minute, double second, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(int year, int month, int day, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(int year, Month month, int day, int hour, int minute, double second, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(int year, Month month, int day, TimeScale timeScale)` Build an instance from a location in a `time scale`.
`AbsoluteDate(long epoch, double offset)` Create an instance with epoch and offset directly. WARNING : this constructor is meant for advanced users only, since epoch and offset have special constraints and values that are not checked or enforced here.
`AbsoluteDate(String location, TimeScale timeScale)` Build an instance from a location (parsed from a string) in a `time scale`.

Method Summary
`int`	`compareTo(AbsoluteDate date)` Compare the instance with another date.
`static AbsoluteDate`	`createGPSDate(int weekNumber, double milliInWeek)` Build an instance corresponding to a GPS date.
`double`	`durationFrom(AbsoluteDate instant)` Compute the physically elapsed duration between two instants.
`boolean`	`equals(Object date)` Check if the instance represent the same time as another instance.
`DateTimeComponents`	`getComponents(TimeScale timeScale)` Split the instance into date/time components.
`AbsoluteDate`	`getDate()` Get the date.
`long`	`getEpoch()` Returns the epoch attribute. May be used, with a matching offset value, to rebuild an AbsoluteDate with the `AbsoluteDate(long, double)` constructor.
`double`	`getOffset()` Returns the offset attribute. May be used, with a matching epoch value, to rebuild an AbsoluteDate with the `AbsoluteDate(long, double)` constructor.
`int`	`hashCode()` Get a hashcode for this date.
`double`	`offsetFrom(AbsoluteDate instant, TimeScale timeScale)` Compute the apparent clock offset between two instant in the perspective of a specific `time scale`.
`static AbsoluteDate`	`parseCCSDSCalendarSegmentedTimeCode(byte preambleField, byte[] timeField)` Build an instance from a CCSDS Calendar Segmented Time Code (CCS).
`static AbsoluteDate`	`parseCCSDSDaySegmentedTimeCode(byte preambleField, byte[] timeField, DateComponents agencyDefinedEpoch)` Build an instance from a CCSDS Day Segmented Time Code (CDS).
`static AbsoluteDate`	`parseCCSDSUnsegmentedTimeCode(byte preambleField1, byte preambleField2, byte[] timeField, AbsoluteDate agencyDefinedEpoch)` Build an instance from a CCSDS Unsegmented Time Code (CUC).
`AbsoluteDate`	`shiftedBy(double dt)` Get a time-shifted date.
`double`	`timeScalesOffset(TimeScale scale1, TimeScale scale2)` Compute the offset between two time scales at the current instant.
`Date`	`toDate(TimeScale timeScale)` Convert the instance to a Java `Date`.
`String`	`toString()` Get a String representation of the instant location in TAI time scale.
`String`	`toString(int precision)` Get a String representation of the instant location in TAI time scale.
`String`	`toString(int precision, TimeScale timeScale)` Get a String representation of the instant location.
`String`	`toString(TimeScale timeScale)` Get a String representation of the instant location.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

JULIAN_EPOCH

public static final AbsoluteDate JULIAN_EPOCH

Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.

Both java.util.Date and DateComponents classes follow the astronomical conventions and consider a year 0 between years -1 and +1, hence this reference date lies in year -4712 and not in year -4713 as can be seen in other documents or programs that obey a different convention (for example the convcal utility).

MODIFIED_JULIAN_EPOCH

public static final AbsoluteDate MODIFIED_JULIAN_EPOCH

Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.

FIFTIES_EPOCH_TT

public static final AbsoluteDate FIFTIES_EPOCH_TT

Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.

FIFTIES_EPOCH_TAI

public static final AbsoluteDate FIFTIES_EPOCH_TAI

Reference epoch for 1950 dates: 1950-01-01T00:00:00 TAI.

FIFTIES_EPOCH_UTC

public static final AbsoluteDate FIFTIES_EPOCH_UTC

Reference epoch for 1950 dates: 1950-01-01T00:00:00 UTC.

CCSDS_EPOCH

public static final AbsoluteDate CCSDS_EPOCH

Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01T00:00:00 International Atomic Time (not UTC).

GALILEO_EPOCH

public static final AbsoluteDate GALILEO_EPOCH

Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.

GPS_EPOCH

public static final AbsoluteDate GPS_EPOCH

Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.

J2000_EPOCH

public static final AbsoluteDate J2000_EPOCH

J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (not UTC).

JAVA_EPOCH

public static final AbsoluteDate JAVA_EPOCH

Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate is equivalent to Java Reference epoch: 1970-01-01T00:00:08 TAI.

PAST_INFINITY

public static final AbsoluteDate PAST_INFINITY

Dummy date at infinity in the past direction.

FUTURE_INFINITY

public static final AbsoluteDate FUTURE_INFINITY

Dummy date at infinity in the future direction.

Constructor Detail

AbsoluteDate

public AbsoluteDate()

Create an instance with a default value (J2000_EPOCH).

AbsoluteDate

public AbsoluteDate(long epoch,
                    double offset)

Create an instance with epoch and offset directly.
WARNING : this constructor is meant for advanced users only, since epoch and offset have special constraints and values that are not checked or enforced here. Use at own risk!

Parameters:: epoch - epoch value; offset - offset value

AbsoluteDate

public AbsoluteDate(String location,
                    TimeScale timeScale)

Build an instance from a location (parsed from a string) in a time scale.

The supported formats for location are mainly the ones defined in ISO-8601 standard, the exact subset is explained in DateTimeComponents.parseDateTime(String), DateComponents.parseDate(String) and TimeComponents.parseTime(String).

As CCSDS ASCII calendar segmented time code is a trimmed down version of ISO-8601, it is also supported by this constructor.

Parameters:: location - location in the time scale, must be in a supported format; timeScale - time scale
Throws:: IllegalArgumentException - if location string is not in a supported format