RelativeTime (Synchronization)

javax.realtime
Class RelativeTime

java.lang.Object
  javax.realtime.HighResolutionTime
      javax.realtime.RelativeTime

All Implemented Interfaces:: java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:: RationalTime

public class RelativeTime
extends HighResolutionTime
extends HighResolutionTime

An object that represents a time interval milliseconds/10³ + nanoseconds/10⁹ seconds long. It generally is used to represent a time relative to now.

The time interval is kept in normalized form. The range goes from [(-2⁶³) milliseconds + (-10⁶+1) nanoseconds] to [(2⁶³-1) milliseconds + (10⁶-1) nanoseconds].

A negative interval relative to now represents time in the past. For add and subtract negative values behave as they do in arithmetic.

Caution: This class is explicitly unsafe in multithreaded 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.

Constructor Summary
`RelativeTime()` Equivalent to `new RelativeTime(0,0)`.
`RelativeTime(Clock clock)` Equivalent to `new RelativeTime(0,0,clock)`.
`RelativeTime(long millis, int nanos)` Construct a `RelativeTime` object representing an interval based on the parameter `millis` plus the parameter `nanos`.
`RelativeTime(long millis, int nanos, Clock clock)` Construct a `RelativeTime` object representing an interval based on the parameter `millis` plus the parameter `nanos`.
`RelativeTime(RelativeTime time)` Make a new `RelativeTime` object from the given `RelativeTime` object.
`RelativeTime(RelativeTime time, Clock clock)` Make a new `RelativeTime` object from the given `RelativeTime` object.

Method Summary
`AbsoluteTime`	`absolute(Clock clock)` Convert the time of `this` to an absolute time, using the given instance of `Clock` to determine the current time.
`AbsoluteTime`	`absolute(Clock clock, AbsoluteTime dest)` Convert the time of `this` to an absolute time, using the given instance of `Clock` to determine the current time.
`RelativeTime`	`add(long millis, int nanos)` Create a new object representing the result of adding `millis` and `nanos` to the values from `this` and normalizing the result.
`RelativeTime`	`add(long millis, int nanos, RelativeTime dest)` Return an object containing the value resulting from adding `millis` and `nanos` to the values from `this` and normalizing the result.
`RelativeTime`	`add(RelativeTime time)` Create a new instance of `RelativeTime` representing the result of adding `time` to the value of `this` and normalizing the result.
`RelativeTime`	`add(RelativeTime time, RelativeTime dest)` Return an object containing the value resulting from adding `time` to the value of `this` and normalizing the result.
`void`	`addInterarrivalTo(AbsoluteTime timeAndDestination)` Deprecated. As of RTSJ 1.0.1
`RelativeTime`	`getInterarrivalTime()` Deprecated. As of RTSJ 1.0.1
`RelativeTime`	`getInterarrivalTime(RelativeTime destination)` Deprecated. As of RTSJ 1.0.1
`RelativeTime`	`relative(Clock clock)` Return a copy of `this`.
`RelativeTime`	`relative(Clock clock, RelativeTime dest)` Return a copy of `this`.
`RelativeTime`	`subtract(RelativeTime time)` Create a new instance of `RelativeTime` representing the result of subtracting `time` from the value of `this` and normalizing the result.
`RelativeTime`	`subtract(RelativeTime time, RelativeTime dest)` Return an object containing the value resulting from subtracting the value of `time` from the value of `this` and normalizing the result.
`java.lang.String`	`toString()` Create a printable string of the time given by `this`.

Methods inherited from class javax.realtime.HighResolutionTime
`clone, compareTo, compareTo, equals, equals, getClock, getMilliseconds, getNanoseconds, hashCode, set, set, set, waitForObject`

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

RelativeTime

public RelativeTime()

Equivalent to new RelativeTime(0,0).

The clock association is implicitly made with the real-time clock.

RelativeTime

public RelativeTime(Clock clock)

Equivalent to new RelativeTime(0,0,clock).

The clock association is made with the clock parameter. If clock is null the association is made with the real-time clock.

Parameters:: clock - The clock providing the association for the newly constructed object.
Since:: 1.0.1

RelativeTime

public RelativeTime(long millis,
                    int nanos)

Construct a RelativeTime object representing an interval based on the parameter millis plus the parameter nanos. The construction is subject to millis and nanos parameters normalization. If there is an overflow in the millisecond component when normalizing then an IllegalArgumentException will be thrown.

The clock association is implicitly made with the real-time clock.

Parameters:: millis - The desired value for the millisecond component of this. The actual value is the result of parameter normalization.; nanos - The desired value for the nanosecond component of this. The actual value is the result of parameter normalization.
Throws:: java.lang.IllegalArgumentException - Thrown if there is an overflow in the millisecond component when normalizing.

RelativeTime

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

The clock association is made with the clock parameter. If clock is null the association is made with the real-time clock.

Parameters:: millis - The desired value for the millisecond component of this. The actual value is the result of parameter normalization.; nanos - The desired value for the nanosecond component of this. The actual value is the result of parameter normalization.; clock - The clock providing the association for the newly constructed object.
Throws:: java.lang.IllegalArgumentException - Thrown if there is an overflow in the millisecond component when normalizing.
Since:: 1.0.1

RelativeTime

public RelativeTime(RelativeTime time)

Make a new RelativeTime object from the given RelativeTime object.

The new object will have the same clock association as the time parameter.

Parameters:: time - The RelativeTime object which is the source for the copy.
Throws:: java.lang.IllegalArgumentException - Thrown if the time parameter is null.

RelativeTime

public RelativeTime(RelativeTime time,
                    Clock clock)

Make a new RelativeTime object from the given RelativeTime object.

The clock association is made with the clock parameter. If clock is null the association is made with the real-time clock.

Parameters:: time - The RelativeTime object which is the source for the copy.; clock - The clock providing the association for the newly constructed object.
Throws:: java.lang.IllegalArgumentException - Thrown if the time parameter is null.
Since:: 1.0.1

Method Detail

absolute

public AbsoluteTime absolute(Clock clock)

Convert the time of this to an absolute time, using the given instance of Clock to determine the current time. The calculation is the current time indicated by the given instance of Clock plus the interval given by this. If clock is null the real-time clock is assumed. A destination object is allocated to return the result. The clock association of the result is with the clock passed as a parameter.

Specified by:: absolute in class HighResolutionTime

Parameters:: clock - The instance of Clock used to convert the time of this into absolute time, and the new clock association for the result.
Returns:: The AbsoluteTime conversion in a newly allocated object, associated with the clock parameter.
Throws:: java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

absolute

public AbsoluteTime absolute(Clock clock,
                             AbsoluteTime dest)

Convert the time of this to an absolute time, using the given instance of Clock to determine the current time. The calculation is the current time indicated by the given instance of Clock plus the interval given by this. If clock is null the real-time clock is assumed. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result. The clock association of the result is with the clock passed as a parameter.

Specified by:: absolute in class HighResolutionTime

Parameters:: clock - The instance of Clock used to convert the time of this into absolute time, and the new clock association for the result.; dest - If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.
Returns:: The AbsoluteTime conversion in dest if dest is not null, otherwise the result is returned in a newly allocated object. It is associated with the clock parameter.
Throws:: java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

add

public RelativeTime add(long millis,
                        int nanos)

Create 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. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: millis - The number of milliseconds to be added to this.; nanos - The number of nanoseconds to be added to this.
Returns:: A new RelativeTime object whose time is the normalization of this plus millis and nanos.
Throws:: java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

add

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

Return 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. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: millis - The number of milliseconds to be added to this.; nanos - The number of nanoseconds to be added to this.; dest - If dest is 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 dest is not null, otherwise the result is returned in a newly allocated object.
Throws:: java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

add

public RelativeTime add(RelativeTime time)

Create a new instance of RelativeTime representing the result of adding time to the value of this and normalizing the result. The clock associated with this and the clock associated with the time parameter are expected to be the same, and such association is used for the result. An IllegalArgumentException is thrown if the clock associated with this and the clock associated with the time parameter are different. An IllegalArgumentException is thrown if the time parameter is null. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: time - The time to add to this.
Returns:: A new RelativeTime object whose time is the normalization of this plus the parameter time.
Throws:: java.lang.IllegalArgumentException - Thrown if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.; java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

add

public RelativeTime add(RelativeTime time,
                        RelativeTime dest)

Return 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 are expected to be the same, and such association is used for the result. The clock associated with the dest parameter is ignored. An IllegalArgumentException is thrown if the clock associated with this and the clock associated with the time parameter are different. An IllegalArgumentException is thrown if the time parameter is null. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: time - The time to add to this.; dest - If dest is 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 the RelativeTime parameter time in dest if dest is not null, otherwise the result is returned in a newly allocated object.
Throws:: java.lang.IllegalArgumentException - Thrown if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.; java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

addInterarrivalTo

public void addInterarrivalTo(AbsoluteTime timeAndDestination)

Deprecated. As of RTSJ 1.0.1

Add the interval of this to the given instance of AbsoluteTime.

Parameters:: timeAndDestination - A reference to the given instance of AbsoluteTime and the result.

getInterarrivalTime

public RelativeTime getInterarrivalTime()

Deprecated. As of RTSJ 1.0.1

Gets the interval defined by this. For an instance of RationalTime it is the interval divided by the frequency.

Returns:: A reference to a new instance of RelativeTime with the same interval as this.

getInterarrivalTime

public RelativeTime getInterarrivalTime(RelativeTime destination)

Deprecated. As of RTSJ 1.0.1

Gets the interval defined by this. For an instance of RationalTime it is the interval divided by the frequency.

Parameters:: destination - A reference to the new object holding the result.
Returns:: A reference to an object holding the result.

relative

public RelativeTime relative(Clock clock)

Return a copy of this. A new object is allocated for the result. This method is the implementation of the abstract method of the HighResolutionTime base class. No conversion into RelativeTime is needed in this case. The clock association of the result is with the clock passed as a parameter. If clock is null the association is made with the real-time clock.

Specified by:: relative in class HighResolutionTime

Parameters:: clock - The clock parameter is used only as the new clock association with the result, since no conversion is needed.
Returns:: The copy of this in a newly allocated RelativeTime object, associated with the clock parameter.

relative

public RelativeTime relative(Clock clock,
                             RelativeTime dest)

Return a copy of this. If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result. This method is the implementation of the abstract method of the HighResolutionTime base class. No conversion into RelativeTime is needed in this case. The clock association of the result is with the clock passed as a parameter. If clock is null the association is made with the real-time clock.

Specified by:: relative in class HighResolutionTime

Parameters:: clock - The clock parameter is used only as the new clock association with the result, since no conversion is needed.; dest - If dest is not null, the result is placed there and returned. Otherwise, a new object is allocated for the result.
Returns:: The copy of this in dest if dest is not null, otherwise the result is returned in a newly allocated object. It is associated with the clock parameter.

subtract

public RelativeTime subtract(RelativeTime time)

Create 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 are expected to be the same, and such association is used for the result. An IllegalArgumentException is thrown if the clock associated with this and the clock associated with the time parameter are different. An IllegalArgumentException is thrown if the time parameter is null. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: time - The time to subtract from this.
Returns:: A new RelativeTime object whose time is the normalization of this minus the parameter time parameter time.
Throws:: java.lang.IllegalArgumentException - Thrown if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.; java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

subtract

public RelativeTime subtract(RelativeTime time,
                             RelativeTime dest)

Return an object containing the value resulting from subtracting the value of 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 are expected to be the same, and such association is used for the result. The clock associated with the dest parameter is ignored. An IllegalArgumentException is thrown if the clock associated with this and the clock associated with the time parameter are different. An IllegalArgumentException is thrown if the time parameter is null. An ArithmeticException is thrown if the result does not fit in the normalized format.

Parameters:: time - The time to subtract from this.; dest - If dest is 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 minus the RelativeTime parameter time in dest if dest is not null, otherwise the result is returned in a newly allocated object.
Throws:: java.lang.IllegalArgumentException - Thrown if the if the clock associated with this and the clock associated with the time parameter are different, or when the time parameter is null.; java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.

toString

public java.lang.String toString()

Create a printable string of the time given by this.

The string shall be a decimal representation of the milliseconds and nanosecond values; formatted as follows "(2251 ms, 750000 ns)"

Overrides:: toString in class java.lang.Object

Returns:: String object converted from the time given by this.

javax.realtime Class RelativeTime

RelativeTime

RelativeTime

RelativeTime

RelativeTime

RelativeTime

RelativeTime

absolute

absolute

add

add

add

add

addInterarrivalTo

getInterarrivalTime

getInterarrivalTime

relative

relative

subtract

subtract

toString

javax.realtime
Class RelativeTime