javax.realtime
Class HighResolutionTime

java.lang.Object
  javax.realtime.HighResolutionTime

All Implemented Interfaces:

Cloneable, Comparable

Direct Known Subclasses:

AbsoluteTime, RelativeTime

public abstract class HighResolutionTime

extends Object

implements Cloneable, Comparable

Used to express time with nanosecond accuracy. This class is never used directly: it is abstract and has no public constructors. Instead, use one of its subclasses AbsoluteTime, RelativeTime, or RationalTime. When an API is defined that has an HighResolutionTime as a parameter, it can take either an absolute, relative, or rational time and will do something appropriate. All of the arithmetic functions come in both allocating and non-allocating forms. 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 nanosecond resolution, but even a 64 bit real-time clock based in nanoseconds would be problematic in some situations, so a compound format composed of 64 bits of millisecond timing, and 32 bits of nanoseconds within a millisecond, was chosen.

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

Method Summary

abstract AbsoluteTime	absolute(Clock clock) Convert to absolute time (with respect to a given clock).
abstract AbsoluteTime	absolute(Clock clock, AbsoluteTime dest) Convert to absolute time (with respect to a given clock).
Object	clone() Clone this HighResolutionTime.
int	compareTo(HighResolutionTime time) Compares this to another time object.
int	compareTo(Object time) Compares this to another time object.
boolean	equals(HighResolutionTime time) Determines whether this time equals a given other time.
boolean	equals(Object time) Determines whether this time equals a given other time.
Clock	getClock() Get the clock associated to this.
long	getMilliseconds() Gets the milliseconds component associated with this time.
int	getNanoseconds() Gets the nanoseconds component associated with this time.
int	hashCode()
abstract RelativeTime	relative(Clock clock) Convert to relative time (with respect to a given clock).
abstract RelativeTime	relative(Clock clock, RelativeTime dest) Convert to relative time (with respect to a given clock).
void	set(HighResolutionTime time) Changes the time represented by the argument to some time between the invocation of the method and the return of the method.
void	set(long millis) Sets the millisecond component of this to the given argument.
void	set(long millis, int nanos) Sets the millisecond and nanosecond components of this.
static void	waitForObject(Object target, HighResolutionTime time) Behaves exactly like target.wait() but with the enhancement that it waits with a precision of HighResolutionTime. Implementation Note: This method, as it is, really makes sense only if the time being passed is a RelativeTime (otherwise a clock should have been provided.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

absolute

public abstract AbsoluteTime absolute(Clock clock)

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

Parameters:

clock - the clock that will convert the time

Returns:

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

absolute

public abstract AbsoluteTime absolute(Clock clock,
                                      AbsoluteTime dest)

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

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 abstract RelativeTime relative(Clock clock)

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

Parameters:

clock - the clock that will convert the time

Returns:

the new time, or this (if already a relative time)

relative

public abstract RelativeTime relative(Clock clock,
                                      RelativeTime dest)

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

RTSJ compliance note: This signature disagrees with the online version of the RTSJ. The RTSJ appears to support this definition in spirit, as subclasses implement (in an attempted override) methods with this signature. We'll have to revisit this later.

Parameters:

clock - the clock that will convert the time

dest - the destination object

Returns:

a newly allocated RelativeTime if dest is null, otherwise dest

compareTo

public int compareTo(Object time)

Compares this to another time object.

Specified by:

compareTo in interface Comparable

Parameters:

time - the time against which "this" time has to be compared.

Returns:

-1 if the time represented by this object is less than the time represented by the object passed as arguemt, 0 if they are the same, and 1 if "this time" is greater.

compareTo

public int compareTo(HighResolutionTime time)

Compares this to another time object.

Parameters:

time - the time against which "this" time has to be compared.

Returns:

-1 if the time represented by this object is less than the time represented by the object passed as arguemt, 0 if they are the same, and 1 if "this time" is greater.

equals

public boolean equals(HighResolutionTime time)

Determines whether this time equals a given other time.

Parameters:

time - the time value compared to this.

Returns:

true if the time passes as argument and this time are the same

equals

public boolean equals(Object time)

Determines whether this time equals a given other time.

Parameters:

time - the time value compared to this.

Returns:

true if the time passes as argument and this time are the same

getMilliseconds

public final long getMilliseconds()

Gets the milliseconds component associated with this time.

Returns:

the milliseconds components

getNanoseconds

public final int getNanoseconds()

Gets the nanoseconds component associated with this time.

Returns:

the nano components.

hashCode

public int hashCode()

set

public void set(HighResolutionTime time)

Changes the time represented by the argument to some time between the invocation of the method and the return of the method.

Parameters:

time - The HighResolutionTime which will be set to represent the current time.

set

public void set(long millis)

Sets the millisecond component of this to the given argument.

Parameters:

millis - This value will be the value of the millisecond component of this at the completion of the call. If millis is negative the millisecond value of this is set to negative value. Although logically this may represent time before the epoch, invalid resultsmayoccur if a HighResolutionTime representing time before the epoch is given as a parameter to the methods.

set

public void set(long millis,
                int nanos)

Sets the millisecond and nanosecond components of this.

Parameters:

millis - Value to set millisecond part of this. If millis is negative the millisecond value of this is set to negative value. Although logically this may represent time before the epoch, invalid resultsmayoccur if a HighResolutionTime representing time before the epoch is given as a parameter to the methods.

nanos - Value to set nanosecond part of this. If nanos is negative the millisecond value of this is set to negative value. Although logically this may represent time before the epoch, invalid resultsmayoccur if a HighResolutionTime representing time before the epoch is given as a parameter to the methods.

getClock

public Clock getClock()

Get the clock associated to this.

Returns:

the clock assocated to this

waitForObject

public static void waitForObject(Object target,
                                 HighResolutionTime time)
                          throws InterruptedException

Behaves exactly like target.wait() but with the enhancement that it waits with a precision of HighResolutionTime.

Implementation Note: This method, as it is, really makes sense only if the time being passed is a RelativeTime (otherwise a clock should have been provided. In the current implementation, it throws a class cast exception if the time being passed is not a RelativeTime.

Parameters:

target - The object on which to wait. The current thread must have a lock on the object.

time - The time for which to wait. If this is RelativeTime(0,0) then wait indefinitely.

Throws:

InterruptedException - If another threads interrupts this thread while its waiting.

clone

public Object clone()

Clone this HighResolutionTime.