javax.realtime

Interface Chronograph

All Known Implementing Classes:

Clock

public interface Chronograph

The interface for all devices that support the measurement of time with great accuracy.

Since:

RTSJ 2.0

Method Summary

Modifier and Type	Method and Description
RelativeTime	getEpochOffset() Determines the difference between the epoch of this clock from the Epoch.
RelativeTime	getEpochOffset(RelativeTime dest) Determines the difference between the epoch of this clock from the Epoch.
default RelativeTime	getQueryPrecision() Obtains the precision with which time can be read, i.e., the nominal interval between ticks.
RelativeTime	getQueryPrecision(RelativeTime dest) Obtains the precision with which time can be read, i.e., the nominal interval between ticks.
AbsoluteTime	getTime() Determines the current time.
AbsoluteTime	getTime(AbsoluteTime dest) Obtains the current time.
default boolean	isUpdated() Determine whether or not this time keeper is asynchronously synchronized with an external time source.
default AbsoluteTime	lastSynchronized() Determine the last time this chronograph was synchronized.
default AbsoluteTime	lastSynchronized(AbsoluteTime result) Determine the last time this chronograph was synchronized with an external time source.

Method Detail

getEpochOffset

RelativeTime getEpochOffset()
                     throws StaticUnsupportedOperationException,
                            UninitializedStateException

Determines the difference between the epoch of this clock from the Epoch. For the UTC, the result is always a RelativeTime value equal to zero. For other clocks, it is a value representing the difference between zero on that clock and zero on the UTC measured on the UTC, where a positive epoc is later than the EPOC.

Returns:

a newly allocated RelativeTime object in the current execution context with the UTC as its chronograph and containing the time when this chronograph was zero.

Throws:

StaticUnsupportedOperationException - when the chronograph does not have the concept of date.

UninitializedStateException - when UTC time is not yet available.

getEpochOffset

RelativeTime getEpochOffset(RelativeTime dest)
                     throws StaticUnsupportedOperationException,
                            UninitializedStateException

Determines the difference between the epoch of this clock from the Epoch. For the UTC, the result is always a RelativeTime value equal to zero. For other clocks, it is a value representing the difference between zero on that clock and zero on the UTC measured on the UTC.

Parameters:

dest - An instance of RelativeTime object which will be updated in place.

Returns:

the instance of RelativeTime passed as parameter, or a new object when dest is null. The returned object represents the time differnce between its associated chronograph and the Epoch.

Throws:

StaticUnsupportedOperationException - when the chronograph does not have the concept of date.

UninitializedStateException - when UTC time is not yet available.

getTime

AbsoluteTime getTime()

Determines the current time. This method returns an absolute time value representing the chronograph's notion of absolute time. For chronographs that do not measure calendar time, this absolute time may not represent a wall clock time.

Returns:

a newly allocated instance of AbsoluteTime in the current allocation context, representing the current time. The returned object has the chronograph from this.

getTime

AbsoluteTime getTime(AbsoluteTime dest)

Obtains the current time. The time represented by the given AbsoluteTime is changed at some time between the invocation of the method and the return of the method. This method will return an absolute time value that represents this chronographs's notion of the absolute time. For chronographs that do not measure calendar time, this absolute time may not represent a wall clock time.

Parameters:

dest - The instance of AbsoluteTime object which will be updated in place.

Returns:

the instance of AbsoluteTime passed as parameter, or a new object when dest is null. The returned object represents the current time and is associated with this chronograph.

isUpdated

default boolean isUpdated()

Determine whether or not this time keeper is asynchronously synchronized with an external time source. Synchronization requires the ability to adjust the time to compensate for drift. For example, a UTC is continually synchronized with an external time source, but realtime clocks are not.

Returns:

true for chronographs that are synchronized and false otherwise.

lastSynchronized

default AbsoluteTime lastSynchronized()
                               throws StaticUnsupportedOperationException

Determine the last time this chronograph was synchronized. It is the same as calling lastSynchronized(AbsoluteTime) with null as an argument.

Returns:

a newly allocated time value holding last synchronized time.

Throws:

StaticUnsupportedOperationException - when the chronograph will never be updated, i.e., is never synchronized with an external time source.

lastSynchronized

default AbsoluteTime lastSynchronized(AbsoluteTime result)
                               throws StaticUnsupportedOperationException

Determine the last time this chronograph was synchronized with an external time source.

Parameters:

result - a time object to hold the result.

Returns:

when result is null, a newly allocated time value holding the value corresponding to the last synchronized time; otherwise result updated with that current value.

Throws:

StaticUnsupportedOperationException - when the chronograph will never be updated, i.e., is never synchronized with an external time source.

getQueryPrecision

default RelativeTime getQueryPrecision()

Obtains the precision with which time can be read, i.e., the nominal interval between ticks. It is the same as calling getQueryPrecision(RelativeTime) with null as an argument.

Returns:

a newly allocated time value holding the read precision.

getQueryPrecision

RelativeTime getQueryPrecision(RelativeTime dest)

Obtains the precision with which time can be read, i.e., the nominal interval between ticks.

Parameters:

dest - The time object in which to return the results.

Returns:

the read precision in dest, when dest is not null, or in a newly created object otherwise.