public class AbsoluteDate extends Object implements TimeStamped, TimeShiftable<AbsoluteDate>, Comparable<AbsoluteDate>, Serializable
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(fr.cnes.sirius.patrius.time.TimeScale, fr.cnes.sirius.patrius.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.
TimeScale
,
TimeStamped
,
ChronologicalComparator
,
Serialized FormModifier and Type | Field and Description |
---|---|
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 and Description |
---|
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 epochIn,
double offsetIn)
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 . |
Modifier and Type | Method and Description |
---|---|
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.
|
public static final AbsoluteDate JULIAN_EPOCH
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).
public static final AbsoluteDate MODIFIED_JULIAN_EPOCH
public static final AbsoluteDate FIFTIES_EPOCH_TT
public static final AbsoluteDate FIFTIES_EPOCH_TAI
public static final AbsoluteDate FIFTIES_EPOCH_UTC
public static final AbsoluteDate CCSDS_EPOCH
public static final AbsoluteDate GALILEO_EPOCH
public static final AbsoluteDate GPS_EPOCH
public static final AbsoluteDate J2000_EPOCH
public static final AbsoluteDate JAVA_EPOCH
public static final AbsoluteDate PAST_INFINITY
public static final AbsoluteDate FUTURE_INFINITY
public AbsoluteDate()
J2000_EPOCH
).public AbsoluteDate(long epochIn, double offsetIn)
epochIn
- epoch valueoffsetIn
- offset valuepublic AbsoluteDate(String location, TimeScale timeScale)
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.
location
- location in the time scale, must be in a supported formattimeScale
- time scaleIllegalArgumentException
- if location string is not in a supported formatpublic AbsoluteDate(DateTimeComponents location, TimeScale timeScale)
time scale
.location
- location in the time scaletimeScale
- time scalepublic AbsoluteDate(DateComponents date, TimeComponents time, TimeScale timeScale)
time scale
.date
- date location in the time scaletime
- time location in the time scaletimeScale
- time scalepublic AbsoluteDate(int year, int month, int day, int hour, int minute, double second, TimeScale timeScale)
time scale
.year
- year number (may be 0 or negative for BC years)month
- month number from 1 to 12day
- day number from 1 to 31hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 60.0 (excluded)timeScale
- time scaleIllegalArgumentException
- if inconsistent arguments
are given (parameters out of range)public AbsoluteDate(int year, Month month, int day, int hour, int minute, double second, TimeScale timeScale)
time scale
.year
- year number (may be 0 or negative for BC years)month
- month enumerateday
- day number from 1 to 31hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 60.0 (excluded)timeScale
- time scaleIllegalArgumentException
- if inconsistent arguments
are given (parameters out of range)public AbsoluteDate(DateComponents date, TimeScale timeScale)
time scale
.
The hour is set to 00:00:00.000.
date
- date location in the time scaletimeScale
- time scaleIllegalArgumentException
- if inconsistent arguments
are given (parameters out of range)public AbsoluteDate(int year, int month, int day, TimeScale timeScale)
time scale
.
The hour is set to 00:00:00.000.
year
- year number (may be 0 or negative for BC years)month
- month number from 1 to 12day
- day number from 1 to 31timeScale
- time scaleIllegalArgumentException
- if inconsistent arguments
are given (parameters out of range)public AbsoluteDate(int year, Month month, int day, TimeScale timeScale)
time scale
.
The hour is set to 00:00:00.000.
year
- year number (may be 0 or negative for BC years)month
- month enumerateday
- day number from 1 to 31timeScale
- time scaleIllegalArgumentException
- if inconsistent arguments
are given (parameters out of range)public AbsoluteDate(Date location, TimeScale timeScale)
time scale
.location
- location in the time scaletimeScale
- time scalepublic AbsoluteDate(AbsoluteDate since, double elapsedDuration)
It is important to note that the elapsed duration is not the difference between two readings on a time
scale. As an example, the duration between the two instants leading to the readings 2005-12-31T23:59:59 and
2006-01-01T00:00:00 in the UTC
time scale is not 1 second, but a stop watch would have
measured an elapsed duration of 2 seconds between these two instances because a leap second was introduced at the
end of 2005 in this time scale.
This constructor is the reverse of the durationFrom(AbsoluteDate)
method.
since
- start instant of the measured durationelapsedDuration
- physically elapsed duration from the since
instant, as measured in a regular time scaledurationFrom(AbsoluteDate)
public AbsoluteDate(AbsoluteDate reference, double apparentOffset, TimeScale timeScale)
time scale
.
It is important to note that the apparent clock offset is the difference between two readings on a time
scale and not an elapsed duration. As an example, the apparent clock offset between the two instants
leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the UTC
time scale is 1
second, but the elapsed duration is 2 seconds because a leap second has been introduced at the end of 2005 in
this time scale.
This constructor is the reverse of the offsetFrom(AbsoluteDate, TimeScale)
method.
reference
- reference instantapparentOffset
- apparent clock offset from the reference instant
(difference between two readings in the specified time scale)timeScale
- time scale with respect to which the offset is definedoffsetFrom(AbsoluteDate, TimeScale)
public static AbsoluteDate parseCCSDSUnsegmentedTimeCode(byte preambleField1, byte preambleField2, byte[] timeField, AbsoluteDate agencyDefinedEpoch) throws PatriusException
CCSDS Unsegmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
If the date to be parsed is formatted using version 3 of the standard (CCSDS 301.0-B-3 published in 2002) or if
the extension of the preamble field introduced in version 4 of the standard is not used, then the
preambleField2
parameter can be set to 0.
preambleField1
- first byte of the field specifying the format, often
not transmitted in data interfaces, as it is constant for a given data interfacepreambleField2
- second byte of the field specifying the format
(added in revision 4 of the CCSDS standard in 2010), often not transmitted in data
interfaces, as it is constant for a given data interface (value ignored if presence
not signaled in preambleField1
)timeField
- byte array containing the time codeagencyDefinedEpoch
- reference epoch, ignored if the preamble field
specifies the CCSDS reference epoch
is used (and hence
may be null in this case)PatriusException
- if preamble is inconsistent with Unsegmented Time Code,
or if it is inconsistent with time field, or if agency epoch is needed but not providedpublic static AbsoluteDate parseCCSDSDaySegmentedTimeCode(byte preambleField, byte[] timeField, DateComponents agencyDefinedEpoch) throws PatriusException
CCSDS Day Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
preambleField
- field specifying the format, often not transmitted in
data interfaces, as it is constant for a given data interfacetimeField
- byte array containing the time codeagencyDefinedEpoch
- reference epoch, ignored if the preamble field
specifies the CCSDS reference epoch
is used (and hence
may be null in this case)PatriusException
- if preamble is inconsistent with Day Segmented Time Code,
or if it is inconsistent with time field, or if agency epoch is needed but not provided,
or it UTC time scale cannot be retrievedpublic static AbsoluteDate parseCCSDSCalendarSegmentedTimeCode(byte preambleField, byte[] timeField) throws PatriusException
CCSDS Calendar Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
preambleField
- field specifying the format, often not transmitted in
data interfaces, as it is constant for a given data interfacetimeField
- byte array containing the time codePatriusException
- if preamble is inconsistent with Calendar Segmented Time Code,
or if it is inconsistent with time field, or it UTC time scale cannot be retrievedpublic static AbsoluteDate createGPSDate(int weekNumber, double milliInWeek)
GPS dates are provided as a week number starting at GPS epoch
and as a number of milliseconds
since week start.
weekNumber
- week number since GPS epoch
milliInWeek
- number of milliseconds since week startpublic AbsoluteDate shiftedBy(double dt)
Calling this method is equivalent to call new AbsoluteDate(this, dt)
.
shiftedBy
in interface TimeShiftable<AbsoluteDate>
dt
- time shift in secondsPVCoordinates.shiftedBy(double)
,
Attitude.shiftedBy(double)
,
Orbit.shiftedBy(double)
,
SpacecraftState.shiftedBy(double)
public double durationFrom(AbsoluteDate instant)
The returned duration is the number of seconds physically elapsed between the two instants, measured in a regular
time scale with respect to surface of the Earth (i.e either the TAI scale
, the TT
scale
or the GPS scale
). It is the only method that gives a duration with a physical meaning.
This method gives the same result (with less computation) as calling offsetFrom(AbsoluteDate, TimeScale)
with a second argument set to one of the regular scales cited above.
This method is the reverse of the AbsoluteDate(AbsoluteDate, double)
constructor.
instant
- instant to subtract from the instanceoffsetFrom(AbsoluteDate, TimeScale)
,
AbsoluteDate(AbsoluteDate, double)
public double offsetFrom(AbsoluteDate instant, TimeScale timeScale)
time scale
.
The offset is the number of seconds counted in the given time scale between the locations of the two instants,
with all time scale irregularities removed (i.e. considering all days are exactly 86400 seconds long). This
method will give a result that may not have a physical meaning if the time scale is irregular. For example since
a leap second was introduced at the end of 2005, the apparent offset between 2005-12-31T23:59:59 and
2006-01-01T00:00:00 is 1 second, but the physical duration of the corresponding time interval as returned by the
durationFrom(AbsoluteDate)
method is 2 seconds.
This method is the reverse of the AbsoluteDate(AbsoluteDate, double, TimeScale)
constructor.
instant
- instant to subtract from the instancetimeScale
- time scale with respect to which the offset should
be computeddurationFrom(AbsoluteDate)
,
AbsoluteDate(AbsoluteDate, double, TimeScale)
public double timeScalesOffset(TimeScale scale1, TimeScale scale2)
The offset is defined as l1-l2 where l1 is the location of the
instant in the scale1
time scale and l2 is the location of the instant in the
scale2
time scale.
scale1
- first time scalescale2
- second time scalepublic Date toDate(TimeScale timeScale)
Date
.
Conversion to the Date class induces a loss of precision because the Date class does not provide sub-millisecond information. Java Dates are considered to be locations in some times scales.
timeScale
- time scale to useDate
instance representing the location
of the instant in the time scalepublic DateTimeComponents getComponents(TimeScale timeScale)
timeScale
- time scale to usepublic int compareTo(AbsoluteDate date)
compareTo
in interface Comparable<AbsoluteDate>
date
- other date to compare the instance topublic AbsoluteDate getDate()
getDate
in interface TimeStamped
public boolean equals(Object date)
public int hashCode()
public String toString()
public String toString(int precision)
precision
- digit number of the seconds fractional partpublic String toString(TimeScale timeScale)
timeScale
- time scale to usepublic String toString(int precision, TimeScale timeScale)
precision
- digit number of the seconds fractional parttimeScale
- time scale to usepublic long getEpoch()
AbsoluteDate(long, double)
constructor.public double getOffset()
AbsoluteDate(long, double)
constructor.Copyright © 2018 CNES. All Rights Reserved.