Interpretation of Time and FineTime values should be specified

[S-Gaertner]

I suggest the MAL Java API to unambiguously define the interpretation of Time and FineTime values. Time and FineTime are stored as simple integer or long values at the moment, their interpretation is up to the user of the MAL Java API. However, different components might employ different interpretations, making it error-prone and tedious to use them together.

For example: The ESA MAL implementation assigns new Date().getTime() to a newly generated MAL message timestamp. This time value needs to be interpreted in the framework of the UTC scale (i.e. with leap second correction) counting from the Java epoch 1970-01-01T00:00:00 UTC. The DLR implementation of the MAL/SPP binding counts from the same epoch, but using TAI time scale. This means there is a difference of 27 seconds between those two interpretations of the same value for today. One interpretation counts the apparent elapsed milliseconds since the Java epoch, the other the real elapsed seconds.

To elaborate more on that, I even think handling time values the way Java usually tends to handle them (apparent elapsed milliseconds since the Java epoch) is not compliant with the MAL Blue Book. The book states that Time represents an absolute time (4.3.16). Java time values are ambiguous, however: There are time stamps that cannot be displayed as the correct absolute time string. Take the time value 94694399000 for example. It is not possible to tell if I meant to express 1972-12-31T23:59:59.000 or 1972-12-31T23:59:60.000 with this value. So even when not employing two different interpretations of a time value it is easy to handle them in a non-MAL-compliant way.

It is difficult to get time values and their interpretation right. Often there are implicit assumptions that are not communicated between users of different components, giving rise to subtle bugs. In order to prevent these issues in the first place, I suggest the interpretation of time values to be specified.

[SamCooper]

Do you have a suggestion of how to fix this Stefan?

I am guessing this may not have an impact in the API code itself but more in the Magenta Book?

[S-Gaertner]

Yes, this should not affect the API code, only the specification in the Magenta Book.

I suggest to specify an epoch (e.g. CCSDS epoch 1958-01-01T00:00:00), a time scale in which the epoch is given (e.g. TAI), a time scale in which the time value is given (e.g. TAI or UTC) and a time unit (e.g. seconds) for Time and FineTime. For Duration the specification of time scale and time unit is sufficient. This way an unambiguous interpretation of time values should be possible. I guess section 3.3.9 is the right place for that.

Please note that the popular System.currentTimeMillis() or new Date().getTime() Java methods use the Java epoch 1970-01-01T00:00:00, which is given in UTC, UTC as time scale and milliseconds as time unit. Unfortunately leap seconds pose a problem there, because each day is assumed to have 86400 seconds (which is not true for UTC time scale; leap second days have 86401 seconds). This leads to two different interpretations of the value for the very last second of a leap second day, because it can either denote the leap second or the second before the leap second. This is incompatible to the MAL prescription that Time shall represent an absolute time. This should be a note in the specification, so the reader is aware that these popular Java methods cannot be used without proper leap-second handling.

[SamCooper]

So we could specify Java epoch, in UTC, UTC as a time scale and milliseconds as the unit (for Time). And that would be ok? But we should put a note in about the inherent problem with the Java time functions?

I want this to be as Java normal as possible but still correct.

[S-Gaertner]

This sounds like a good solution to me.

[CesarCoelho]

Following the proposed solution for Time, the MAL type FineTime can also be defined as:
Java epoch, in UTC, UTC as a time scale and nanoseconds as the unit.
A note must be written stating the leap seconds problem with Java.
Also, this RID is related with FineTime's resolution problem: SamCooper/MAL_SPEC_RIDS#1

Future implementations must take this RID into consideration when using Time or FineTime.