Time This section contains classes that describe high-resolution time.

See:
          Description

Packages
javax.realtime  

 

Time

This section contains classes that describe high-resolution time. These classes:

Definitions

The following terms and abbreviations will be used:

A time object is an instance of AbsoluteTime, RelativeTime, or RationalTime.

A time object is always associated with a clock. By default it is associated with the real-time clock.

The Epoch is the standard base time, conventionally January 1 00:00:00 GMT 1970. It is the point from which the real-time clock measures absolute time.

The time value representation is a compound format composed of 64 bits of millisecond timing, and 32 bits of nanoseconds within a millisecond. The millisecond constituent uses the 64 bits of a Java long while the nanosecond constituent uses the 32 bits of a Java int.

The normalized (canonical) form for time objects uniquely specifies the values for the millisecond and nanosecond components of a point in time, including the case of 0 milliseconds or 0 nanoseconds, and a negative time value, according to the following three rules:

  1. When both millisecond and nanosecond components are nonzero they have the same sign. The algebraic time value of the time object is the algebraic sum of the two components.
  2. The millisecond component represents the algebraic number of milliseconds in the time object, with a range of [-263, 263-1]
  3. The nanosecond component represents the algebraic number of nanoseconds within a millisecond in the time object, that is [-106+1, 106-1].

Instances of HighResolutionTime classes always hold a normalized form of a time value. Values that cannot be normalized are not valid; for example, (MAX_LONG milliseconds, MAX_INT nanoseconds) cannot be normalized and is an illegal value.

The following table has examples of normalized representations.

    time in ns
    millis
    nanos
    2000000
    2
    0
    1999999
    1
    999999
    1000001
    1
    1
    1
    0
    1
    0
    0
    0
    -1
    0
    -1
    -999999
    0
    -999999
    -1000000
    -1
    0
    -1000001
    -1
    -1

Overview

The time classes required by the specification are HighResolutionTime, AbsoluteTime, RelativeTime, and RationalTime (now deprecated).

Instances of HighResolutionTime are not created, as the class exists to provide an implementation of the other three classes. An instance of AbsoluteTime encapsulates an absolute time. An instance of RelativeTime encapsulates a point in time that is relative to some other time value.

Instances of RationalTime (now deprecated) express a frequency by a numerator of type long (the frequency) and a denominator of type RelativeTime. When instances of RationalTime are used they shall behave like RelativeTime objects with a value of interval divided by frequency.

All methods returning a time object come in both allocating and non-allocating form.

Semantics and Requirements

This list establishes the semantics and requirements that are applicable across the classes of this section. Semantics that apply to particular classes, constructors, methods, and fields will be found in the class description and the constructor, method, and field detail sections.
  1. All time objects must maintain nanosecond precision and report their values in terms of millisecond and nanosecond constituents.
  2. Time objects must be constructed from other time objects, from millisecond/nanosecond values, from a java.util.Date or obtained as a result of invocations of methods on instances of the Clock class.
  3. Time objects maintain and report time values in normalized form, but the normalized form is not required for input parameter values. This allows computations individually with time constituent parts using the full signed range and restrictions of the underlying type.
    1. Normalization is accomplished upon method invocation by methods that accept a time object represented with individual component parts, and executed as if:
      1. The nanosecond parameter value, which may be negative, is algebraically added to the scaled millisecond parameter value. The sign of the result provides the sign for any nonzero resulting component.
      2. The absolute of the result is then partitioned, giving the number of integral milliseconds for the millisecond component, while the remaining fractional part provides the number of nanoseconds for the nanosecond component.
      3. The resulting components are then represented, and reported when necessary, with the above computed sign.
    2. Normalization is also performed on the result of operations by methods that perform time object addition and subtraction. Operations are executed using the appropriate arithmetic precision. If the final result of an operation can be represented in normalized form, then the operation must not throw arithmetic exceptions while producing intermediate results.
    3. The results of time objects operations and the normalization of results of operations performed with millis and nanos, individually as Java long and Java int types respectively, are not always equivalent. This is due to the possibility of overflow for nanos values outside of the normalized nanosecond range, that is [-106+1, 106-1], when performing operations as int types, while the same values could be handled with no overflow in time object operations.
    4. When invoking setter methods that take as a parameter only one of the two time value components, the other component has implicitly the value of 0.
  4. Although logically a negative time may represent time before the Epoch or a negative time interval involved in time operations, an Exception may be thrown if a negative absolute time or a negative time interval is given as a parameter to methods. In general, the time values accepted by a method may be a subset of the full time values range, and depend on the method.
  5. A time object is always associated with a clock. By default it is associated with the real-time clock. Clocks are involved both in the setting as well as the usage of time objects, for example in comparisons.
  6. Methods are provided to facilitate the handling of time objects generically via the HighResolutionTime class. These methods allow the conversion, according to a clock, between AbsoluteTime objects and RelativeTime objects. These methods also allow the change of clock association of a time object. Note that the conversions depend on the time at which they are performed. The semantics of these operations are listed in the following table:
    clock association and conversion
    this has clock_a and ms,ns
    returned/updated object
    this_is_absolute.absolute(clock_a)
    clock_a
    ms,ns
    this_is_absolute.absolute(clock_b)
    clock_b
    ms,ns
    this_is_absolute.absolute(null)
    real-time_clock
    ms,ns
    this_is_absolute.relative(clock_a)
    clock_a
    clock_a.getTime().subtract(ms,ns)
    this_is_absolute.relative(clock_b)
    clock_b
    clock_b.getTime().subtract(ms,ns)
    this_is_absolute.relative(null)
    real-time_clock
    real-time_clock.getTime().subtract(ms,ns)
    this_is_relative.relative(clock_a)
    clock_a
    ms,ns
    this_is_relative.relative(clock_b)
    clock_b
    ms,ns
    this_is_relative.relative(null)
    real-time_clock
    ms,ns
    this_is_relative.absolute(clock_a)
    clock_a
    clock_a.getTime().add(ms,ns)
    this_is_relative.absolute(clock_b)
    clock_b
    clock_b.getTime().add(ms,ns)
    this_is_relative.absolute(null)
    real-time_clock
    real-time_clock.getTime().add(ms,ns)
  7. Time objects must implement the Comparable interface if it is available. The compareTo() method must be implemented even if the interface is not available.

Rationale

Time is the essence of real-time systems, and a method of expressing absolute time with sub-millisecond precision is an absolute minimum requirement. Expressing time in terms of nanoseconds has precedent and allows the implementation to provide time-based services, such as timers, using whatever precision it is capable of while the application requirements are expressed to an arbitrary level of precision.

The standard Java java.util.Date class uses milliseconds as its basic unit in order to provide sufficient range for a wide variety of applications. Real-time programming generally requires finer resolution, and nanosecond resolution is fine enough for most purposes, but even a 64 bit real-time clock based in nanoseconds would have insufficient range in some situations, so a compound format composed of 64 bits of millisecond timing, and 32 bits of nanoseconds within a millisecond, was chosen.

The expression of millisecond and nanosecond constituents is consistent with other Java interfaces.

The expression of relative times allows for time-based metaphors such as deadline-based periodic scheduling where the cost of the task is expressed as a relative time and deadlines are usually represented as times relative to the beginning of the period.