javax.realtime
Class RelativeTime

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

All Implemented Interfaces:

java.lang.Comparable

public class RelativeTime

extends HighResolutionTime

An object that represents a specific time interval millis/1E3+nanos/1E9 seconds long. It is generally used to represent a time relative to now.

If the value of any millisecond or nanosecond fields is negative the variable is set to a negative value. Although logically this may represent a time before the epoch, invalid results may occur if an instance of AbsoluteTime representing time before the epoch is given as a parameter to a method. For add and substract negative values behave just 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.

Field Summary

Fields inherited from class javax.realtime.HighResolutionTime

millis, myClock, nanos

Constructor Summary

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

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

RelativeTime(long millis, long nanos)
Construct a RelativeTime object representing an interval based on the parameter millis plus the parameter nanos.

RelativeTime(long millis, long 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, long 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, long 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.
java.lang.Object	clone() Return a clone of this.
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

compareTo, compareTo, equals, equals, getClock, getMilliseconds, getNanoseconds, hashCode, normalize, 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.

RelativeTime

public RelativeTime(long millis,
                    long 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,
                    long nanos,
                    Clock clock)

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 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.

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 A HREF="RelativeTime.html"> 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.

Method Detail

clone

public java.lang.Object clone()

Description copied from class: HighResolutionTime

Return a clone of this. This method should behave effectively as if it constructed a new object with the visible values of this. The new object is created in the current allocation context.

Specified by:

clone in class HighResolutionTime

Returns:

the cloned object

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,
                        long 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,
                        long 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 new RelativeTime

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 new RelativeTime

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.

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.

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.

subtract

public final 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 final 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. if null.

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.

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 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.

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)"

Returns:

String object converted from the time given by this.