javax.realtime
Class RelativeTime

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

All Implemented Interfaces:

Cloneable, Comparable

Direct Known Subclasses:

RationalTime

public class RelativeTime

extends HighResolutionTime

An object that represents a time interval millis/1E3 + nanos/1E9 seconds long. It generally is used to represent a time relative to now. If the value of any of the millisecond or nanosecond fields is negative the variable is set to negative value. Although logically this may represent time before the epoch, invalid results may occur if an instance of RelativeTime representing time before the epoch is given as a parameter to the a method. For add and subtract negative values behave just like 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.

Author:

Angelo Corsaro, Morgan Deters

Constructor Summary

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

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

RelativeTime(long millis, int nanos)
Construct a new RelativeTime object from the given millisecond and nanosecond components and associated to the default Clock.

RelativeTime(long millis, int nanos, Clock clock)
Construct a new RelativeTime object from the given millisecond and nanosecond components and associated to the given Clock.

RelativeTime(RelativeTime time)
Construct a new RelativeTime object from the given RelativeTime and associated to the default Clock.

RelativeTime(RelativeTime time, Clock clock)
Construct a new RelativeTime object from the given RelativeTime and associated to the given Clock.

Method Summary

AbsoluteTime	absolute(Clock clock) Convert to absolute time (with respect to a given clock).
AbsoluteTime	absolute(Clock clock, AbsoluteTime dest) Convert to absolute time (with respect to a given clock).
RelativeTime	add(long millis, int nanos) Add a specific number of milli and nano seconds to this .
RelativeTime	add(long millis, int nanos, RelativeTime dest) Add a specific number of milli and nano seconds to this.
RelativeTime	add(RelativeTime time) Return this + time.
RelativeTime	add(RelativeTime time, RelativeTime dest) Return this + time.
void	addInterarrivalTo(AbsoluteTime timeAndDestination) Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.
void	decrement(RelativeTime time) Deprecated. non-RTSJ method, will be removed in future
RelativeTime	getInterarrivalTime() Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.
RelativeTime	getInterarrivalTime(RelativeTime destination) Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.
void	increment(RelativeTime time) Deprecated. non-RTSJ method, will be removed in future
RelativeTime	relative(Clock clock) Convert to relative time (with respect to a given clock).
RelativeTime	relative(Clock clock, RelativeTime dest) Convert to relative time (with respect to a given clock).
RelativeTime	subtract(RelativeTime time) Computes the difference (this - time).
RelativeTime	subtract(RelativeTime time, RelativeTime dest) Computes the difference (this - time).
String	toString() Return a printable version of this time.

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,Clock.getRealtimeClock()).

RelativeTime

public RelativeTime(Clock clock)

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

Parameters:

clock - the Clock to which to associate this RelativeTime; if null, the default Clock is used

RelativeTime

public RelativeTime(long millis,
                    int nanos)

Construct a new RelativeTime object from the given millisecond and nanosecond components and associated to the default Clock.

Parameters:

millis - a long value specifing the milliseconds component

nanos - an int value specifing the nanoseconds component

RelativeTime

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

Construct a new RelativeTime object from the given millisecond and nanosecond components and associated to the given Clock.

Parameters:

millis - a long value specifing the milliseconds component

nanos - an int value specifing the nanoseconds component

clock - the Clock to which to associate this RelativeTime; if null, the default Clock is used

RelativeTime

public RelativeTime(RelativeTime time)

Construct a new RelativeTime object from the given RelativeTime and associated to the default Clock.

Parameters:

time - a RelativeTime value from which the time for this object will be taken

Throws:

IllegalArgumentException - if time is null

RelativeTime

public RelativeTime(RelativeTime time,
                    Clock clock)

Construct a new RelativeTime object from the given RelativeTime and associated to the given Clock.

Parameters:

time - a RelativeTime value from which the time for this object will be taken

clock - the Clock to which to associate this RelativeTime; if null, the default Clock is used

Throws:

IllegalArgumentException - if time is null

Method Detail

absolute

public AbsoluteTime absolute(Clock clock)

Convert to absolute time (with respect to a given clock). Will allocate a destination object if necessary.

Specified by:

absolute in class HighResolutionTime

Parameters:

clock - the clock that will convert the time

Returns:

the new time, or this (if already an absolute time)

absolute

public AbsoluteTime absolute(Clock clock,
                             AbsoluteTime dest)

Convert to absolute time (with respect to a given clock). Will allocate a destination object if necessary.

Specified by:

absolute in class HighResolutionTime

Parameters:

clock - the clock that will convert the time

dest - the destination object

Returns:

a newly allocated AbsoluteTime if dest is null, otherwise dest

relative

public RelativeTime relative(Clock clock)

Convert to relative time (with respect to a given clock). This implementation just returns this, since it is already a relative time.

Specified by:

relative in class HighResolutionTime

Parameters:

clock - the clock that will convert the time

Returns:

this

relative

public RelativeTime relative(Clock clock,
                             RelativeTime dest)

Convert to relative time (with respect to a given clock). This implementation just sets dest to equal this, and returns dest.

Specified by:

relative in class HighResolutionTime

Parameters:

clock - the clock that will convert the time

dest - the destination object

Returns:

a newly allocated RelativeTime if dest is null, otherwise dest

add

public RelativeTime add(RelativeTime time)

Return this + time. A new object is allocated for the result.

Parameters:

time - -the time to add to this.

Returns:

the sum of this and the time passed as argument.

Throws:

IllegalArgumentException - if the Clock associated with this and the Clock associated with the time parameter are different; also thrown when time is null

ArithmeticException - if the result overflows during addition or normalization

add

public RelativeTime add(RelativeTime time,
                        RelativeTime dest)

Return this + time. If destination is non-null, the result is placed there and dest is returned. Otherwise a new object is allocated for the result.

Parameters:

time - the time to add to this.

dest - where the result should be placed.

Returns:

if dest is not null, dest is returned; otherwise a new RelativeTime object is allocated to hold the result, and it is returned

Throws:

IllegalArgumentException - if the Clock associated with this and the Clock associated with the time parameter are different; also thrown when time is null

ArithmeticException - if the result overflows during addition or normalization

add

public RelativeTime add(long millis,
                        int nanos)

Add a specific number of milli and nano seconds to this . A new object is allocated.

Parameters:

millis - milli seconds to add.

nanos - nano seconds to add.

Returns:

A new object containing the result.

Throws:

ArithmeticException - if the result overflows during addition or normalization

add

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

Add a specific number of milli and nano seconds to this.

Parameters:

millis - milliseconds to add

nanos - nanoseconds to add

dest - the destination in which to store the result

Throws:

ArithmeticException - if the result overflows during addition or normalization

subtract

public RelativeTime subtract(RelativeTime time)

Computes the difference (this - time).

Parameters:

time - relative time to subtract from this.

Returns:

The new object is allocated for the result.

Throws:

IllegalArgumentException - if the Clock associated with this and the Clock associated with the time parameter are different; also thrown when time is null

ArithmeticException - if the result overflows during subtraction or normalization

subtract

public RelativeTime subtract(RelativeTime time,
                             RelativeTime dest)

Computes the difference (this - time).

Note that this operation does not atomically change the dest parameter; the dest object may represent several intermediate time representations during the execution of this method, and even if an exception is thrown, the dest object may have been udpated.

Parameters:

time - relative time to subtract from this

dest - the destination object that will hold the result

Returns:

if dest is not null, dest is returned; otherwise a new RelativeTime object is allocated to hold the result, and it is returned

Throws:

IllegalArgumentException - if the Clock associated with this and the Clock associated with the time parameter are different; also thrown when time is null

ArithmeticException - if the result overflows during subtraction or normalization

increment

public void increment(RelativeTime time)

Deprecated. non-RTSJ method, will be removed in future

Increment this time by a given amount. Equivalent to add(time, this).

Parameters:

time - the increment represented by a a RelativeTime value

Throws:

ArithmeticException - if the result overflows during increment or normalization

decrement

public void decrement(RelativeTime time)

Deprecated. non-RTSJ method, will be removed in future

Decrement this time by a given amount. Equivalent to subtract(time, this).

Parameters:

time - the decrement represented by a a RelativeTime value

Throws:

ArithmeticException - if the result overflows during decrement or normalization

toString

public String toString()

Return a printable version of this time.

Returns:

String object converted from this

addInterarrivalTo

public void addInterarrivalTo(AbsoluteTime timeAndDestination)

Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.

Add the interval of this to the given AbsoluteTime.

Parameters:

timeAndDestination - the given AbsoluteTime; also, used to store the result

getInterarrivalTime

public RelativeTime getInterarrivalTime()

Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.

Get the interval defined by this. For an instance of RationalTime it is the interval divided by the frequency. For a non-rational RelativeTime, this method returns a clone of this.

getInterarrivalTime

public RelativeTime getInterarrivalTime(RelativeTime destination)

Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ.

Get the interval defined by this. For an instance of RationalTime it is the interval divided by the frequency. For a non-rational RelativeTime, this method returns a clone of this if destination is null, else it sets destination to this.