javax.realtime

Class AbsoluteTime

java.lang.Object

javax.realtime.HighResolutionTime

javax.realtime.AbsoluteTime

All Implemented Interfaces:

java.lang.Comparable<HighResolutionTime>

@SCJAllowed
public class AbsoluteTime
extends HighResolutionTime

An object that represents a specific point in time given by milliseconds plus nanoseconds past some point in time fixed by the clock. For the default real-time clock the fixed point is the implementation dependent Epoch.
The correctness of the Epoch as a time base depends on the real-time clock synchronization with an external world time reference. This representation was designed to be compatible with the standard Java representation of an absolute time in the java.util.Date class.
A time object in normalized form represents negative time if both components are nonzero and negative, or one is nonzero and negative and the other is zero. For add and subtract negative values behave as they do in arithmetic.
Caution: This class is explicitly unsafe in multi-threaded situations when it is being changed. No synchronization is done. It is assumed that users of this class who are mutating instances will be doing their own synchronization at a higher level.

Version:

1.2; - December 2013

Author:

Anders P. Ravn, Aalborg University, apr@cs.aau.dk,
Hans Søndergaard, VIA University College, Denmark, hso@via.dk

Relative_to_SCJ_Draft_Version_0.94:

- semantic issue: Java arithmetic is assumed for numeric values. Thus there is no concept of overflow in milliseconds.
- semantic issue: If AbsoluteTime time in subtract is null, an IllegalArgumentException is thrown.
- semantic issue: If clocks are different in AbsoluteTime subtract, an IllegalArgumentException is thrown.

Constructor Summary

Constructors

Constructor and Description
AbsoluteTime() Equivalent to new AbsoluteTime(0,0).
AbsoluteTime(AbsoluteTime time) Make a new AbsoluteTime object from the given AbsoluteTime object.
AbsoluteTime(Clock clock) Equivalent to AbsoluteTime(0,0,clock).
AbsoluteTime(long millis, int nanos) Constructs an AbsoluteTime object with millisecond and nanosecond components past the real-time clock's Epoch.
AbsoluteTime(long millis, int nanos, Clock clock) Constructs an AbsoluteTime object with time millisecond and nanosecond components past the clock's Epoch.

Method Summary

Methods

Modifier and Type	Method and Description
AbsoluteTime	add(long millis, int nanos) Creates a new object representing the result of adding millis and nanos to the values from this and normalizing the result.
AbsoluteTime	add(long millis, int nanos, AbsoluteTime dest) Returns an object containing the value resulting from adding millis and nanos to the values from this and normalizing the result.
AbsoluteTime	add(RelativeTime time) Creates a new instance of AbsoluteTime representing the result of adding time to the value of this and normalizing the result.
AbsoluteTime	add(RelativeTime time, AbsoluteTime dest) Returns an object containing the value resulting from adding time to the value of this and normalizing the result.
RelativeTime	subtract(AbsoluteTime time) Creates a new instance of RelativeTime representing the result of subtracting time from the value of this and normalizing the result.
RelativeTime	subtract(AbsoluteTime time, RelativeTime dest) Returns an object containing the value resulting from subtracting time from the value of this and normalizing the result.
AbsoluteTime	subtract(RelativeTime time) Creates a new instance of AbsoluteTime representing the result of subtracting time from the value of this and normalizing the result.
AbsoluteTime	subtract(RelativeTime time, AbsoluteTime dest) Returns an object containing the value resulting from subtracting time from the value of this and normalizing the result.

Methods inherited from class javax.realtime.HighResolutionTime

compareTo, equals, getClock, getMilliseconds, getNanoseconds, hashCode, set, set, set, toString

Methods inherited from class java.lang.Object

equals, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AbsoluteTime

public AbsoluteTime()

Equivalent to new AbsoluteTime(0,0).
The clock association is implicitly made with the real-time clock.

AbsoluteTime

public AbsoluteTime(long millis,
            int nanos)

Constructs an AbsoluteTime object with millisecond and nanosecond components past the real-time clock's Epoch.
The actual value is the result of parameter normalization.
The clock association is implicitly made with the real-time clock.

Parameters:

millis - is the desired value for the millisecond component. The actual value is the result of parameter normalization.

nanos - is the desired value for the nanosecond component. The actual value is the result of parameter normalization.

AbsoluteTime

public AbsoluteTime(AbsoluteTime time)

Make a new AbsoluteTime object from the given AbsoluteTime object.
This constructor requires that the time.getClock() argument resides in a scope that encloses the current scope.


Parameters:

time - the object copied

Throws:

java.lang.IllegalArgumentException - if the time parameter is null.

AbsoluteTime

public AbsoluteTime(long millis,
            int nanos,
            Clock clock)

Constructs an AbsoluteTime object with time millisecond and nanosecond components past the clock's Epoch.
This constructor requires that the >clock object resides in a scope that encloses the current scope.

Parameters:

millis - is the desired value for the millisecond component.

nanos - is the desired value for the nanosecond component.

clock - is the desired value for the clock.

AbsoluteTime

public AbsoluteTime(Clock clock)

Equivalent to AbsoluteTime(0,0,clock).

Parameters:

clock - is the desired value for the clock.

Method Detail

add

public AbsoluteTime add(long millis,
               int nanos)

Creates a new object representing the result of adding millis and nanos to the values from this and normalizing the result. The result will have the same clock association as this.

Parameters:

millis - is the number of milliseconds to be added to this.

nanos - is the number of nanoseconds to be added to this.

Returns:

a new AbsoluteTime object whose time is the normalization of this plus millis and nanos.

add

public AbsoluteTime add(long millis,
               int nanos,
               AbsoluteTime dest)

Returns an object containing the value resulting from adding millis and nanos to the values from this and normalizing the result. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.
The result will have the same clock association as this, and the clock association with dest is ignored.

Parameters:

millis - is the number of milliseconds to be added to this.

nanos - is the number of nanoseconds to be added to this.

dest - if not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.

Returns:

the result of the normalization of this plus millis and nanos in dest if it is not null, otherwise the result is returned in a newly allocated object.

add

public AbsoluteTime add(RelativeTime time)

Creates a new instance of AbsoluteTime representing the result of adding time to the value of this and normalizing the result.

Parameters:

time - the time to add to this.

Returns:

a new object whose time is the normalization of this plus the parameter time.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.

add

public AbsoluteTime add(RelativeTime time,
               AbsoluteTime dest)

Returns an object containing the value resulting from adding time to the value of this and normalizing the result. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result. The clock associated with this and the clock associated with the time parameter must be the same, and it is used for the result. A clock associated with the dest parameter is ignored.

Parameters:

time - is the time to add to this.

dest - is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.

Returns:

the result in dest if it is not null, otherwise the result is returned in a newly allocated object.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.

subtract

public RelativeTime subtract(AbsoluteTime time)

Creates a new instance of RelativeTime representing the result of subtracting time from the value of this and normalizing the result. The clock associated with this and the clock associated with the time parameter must be the same, and it is used for the result.

Parameters:

time - is the time to subtract from this.

Returns:

a new object whose time is the normalization of this minus time.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.

subtract

public RelativeTime subtract(AbsoluteTime time,
                    RelativeTime dest)

Returns an object containing the value resulting from subtracting time from the value of this and normalizing the result. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.
The clock associated with this and the clock associated with the time parameter must be the same, and it is used for the result. The clock associated with the dest parameter is ignored.

Parameters:

time - is the time to subtract from this.

dest - if not null, the result is placed there and returned.

Returns:

the result of the normalization of this minus time in dest if it is not null, otherwise the result is returned in a newly allocated object.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.

subtract

public AbsoluteTime subtract(RelativeTime time)

Creates a new instance of AbsoluteTime representing the result of subtracting time from the value of this and normalizing the result.
The clock associated with this and the clock associated with the time parameter must be the same, and it is used for the result.

Parameters:

time - is the time to subtract from this.

Returns:

a new AbsoluteTime object whose time is the normalization of this minus time.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different or when the time parameter is null.

subtract

public AbsoluteTime subtract(RelativeTime time,
                    AbsoluteTime dest)

Returns an object containing the value resulting from subtracting time from the value of this and normalizing the result. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.
The clock associated with this and the clock associated with the time parameter must be the same, and it is used for the result. The clock associated with the dest parameter is ignored.

Parameters:

time - is the time to subtract from this.

dest - if not null, the result is placed there and returned.

Returns:

the result of the normalization of this minus time in dest if it is not null, otherwise the result is returned in a newly allocated object.

Throws:

java.lang.IllegalArgumentException - if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.