javax.realtime
Class HighResolutionTime

java.lang.Object
  javax.realtime.HighResolutionTime

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:

AbsoluteTime, RelativeTime

public abstract class HighResolutionTime
extends java.lang.Object
implements java.lang.Comparable, java.lang.Cloneable

Class HighResolutionTime is the base class for AbsoluteTime, RelativeTime, RationalTime. Used to express time with nanosecond accuracy. This class is never used directly: it is abstract and has no public constructor. Instead, one of its subclasses AbsoluteTime, RelativeTime, or RationalTime should be used. 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.

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.

Method Summary

abstract AbsoluteTime	absolute(Clock clock) Convert the time of this to an absolute time, using the given instance of Clock to determine the current time when necessary.
abstract 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 when necessary.
java.lang.Object	clone() Return a clone of this.
int	compareTo(HighResolutionTime time) Compares this HighResolutionTime with the specified HighResolutionTime time.
int	compareTo(java.lang.Object object) For the Comparable interface.
boolean	equals(HighResolutionTime time) Returns true if the argument time has the same type and values as this.
boolean	equals(java.lang.Object object) Returns true if the argument object has the same type and values as this.
Clock	getClock() Returns a reference to the clock associated with this.
long	getMilliseconds() Returns the milliseconds component of this.
int	getNanoseconds() Returns the nanoseconds component of this.
int	hashCode() Returns a hash code for this object in accordance with the general contract of Object.hashCode().
abstract RelativeTime	relative(Clock clock) Convert the time of this to a relative time, using the given instance of Clock to determine the current time when necessary.
abstract RelativeTime	relative(Clock clock, RelativeTime dest) Convert the time of this to a relative time, using the given instance of Clock to determine the current time when necessary.
void	set(HighResolutionTime time) Change the value represented by this to that of the given time.
void	set(long millis) Sets the millisecond component of this to the given argument, and the nanosecond component of this to 0.
void	set(long millis, int nanos) Sets the millisecond and nanosecond components of this.
static void	waitForObject(java.lang.Object target, HighResolutionTime time) Behaves exactly like target.wait() but with the enhancement that it waits with a precision of HighResolutionTime.As for target.wait(), there is the possibility of spurious wakeup behavior.

Methods inherited from class java.lang.Object

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

Method Detail

waitForObject

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

Behaves exactly like target.wait() but with the enhancement that it waits with a precision of HighResolutionTime.As for target.wait(), there is the possibility of spurious wakeup behavior.

The wait time may be relative or absolute, and it is controlled by the clock associated with it. If the wait time is relative, then the calling thread is blocked waiting on target for the amount of time given by time, and measured by the associated clock. If the wait time is absolute, then the calling thread is blocked waiting on target until the indicated time value is reached by the associated clock.

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 it is RelativeTime(0,0) then wait indefinitely. If it is null then wait indefinitely.

Throws:

java.lang.InterruptedException - Thrown if this schedulable object is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while it is waiting.

java.lang.IllegalArgumentException - Thrown if time represents a relative time less than zero.

java.lang.IllegalMonitorStateException - Thrown if target is not locked by the caller.

java.lang.UnsupportedOperationException - Thrown if the wait operation is not supported using the clock associated with time.

See Also:

Object.wait(), Object.wait(long), Object.wait(long,int)

absolute

public abstract AbsoluteTime absolute(Clock clock)

Convert the time of this to an absolute time, using the given instance of Clock to determine the current time when necessary. 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. See the derived class comments for more specific information.

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.

absolute

public abstract 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 when necessary. 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. See the derived class comments for more specific information.

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.

clone

public java.lang.Object clone()

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.

Overrides:

clone in class java.lang.Object

Since:

1.0.1

compareTo

public int compareTo(HighResolutionTime time)

Compares this HighResolutionTime with the specified HighResolutionTime time.

Parameters:

time - Compares with the time of this.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.ClassCastException - Thrown if the time parameter is not of the same class as this.

java.lang.IllegalArgumentException - Thrown if the time parameter is not associated with the same clock as this, or when the time parameter is null.

compareTo

public int compareTo(java.lang.Object object)

For the Comparable interface.

Specified by:

compareTo in interface java.lang.Comparable

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.IllegalArgumentException - Thrown if the object parameter is not associated with the same clock as this, or when the object parameter is null.

java.lang.ClassCastException - Thrown if the specified object's type prevents it from being compared to this Object.

equals

public boolean equals(HighResolutionTime time)

Returns true if the argument time has the same type and values as this. Equality includes clock association.

Parameters:

time - Value compared to this.

Returns:

true if the parameter time is of the same type and has the same values as this.

equals

public boolean equals(java.lang.Object object)

Returns true if the argument object has the same type and values as this.
Equality includes clock association.

Overrides:

equals in class java.lang.Object

Parameters:

object - Value compared to this.

Returns:

true if the parameter object is of the same type and has the same values as this.

getClock

public Clock getClock()

Returns a reference to the clock associated with this.

Returns:

A reference to the clock associated with this.

Since:

1.0.1

getMilliseconds

public final long getMilliseconds()

Returns the milliseconds component of this.

Returns:

The milliseconds component of the time represented by this.

getNanoseconds

public final int getNanoseconds()

Returns the nanoseconds component of this.

Returns:

The nanoseconds component of the time represented by this.

hashCode

public int hashCode()

Returns a hash code for this object in accordance with the general contract of Object.hashCode(). Time objects that are equal have the same hash code.

Overrides:

hashCode in class java.lang.Object

Returns:

The hashcode value for this instance.

relative

public abstract RelativeTime relative(Clock clock)

Convert the time of this to a relative time, using the given instance of Clock to determine the current time when necessary. 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. See the derived class comments for more specific information.

Parameters:

clock - The instance of Clock used to convert the time of this into relative time, and the new clock association for the result.

Returns:

The RelativeTime conversion in a newly allocated object, associated with the clock parameter.

relative

public abstract RelativeTime relative(Clock clock,
                                      RelativeTime dest)

Convert the time of this to a relative time, using the given instance of Clock to determine the current time when necessary. 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. See the derived class comments for more specific information.

Parameters:

clock - The instance of Clock used to convert the time of this into relative 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 RelativeTime 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.

set

public void set(HighResolutionTime time)

Change the value represented by this to that of the given time. If the time parameter is null this method will throw IllegalArgumentException. If the type of this and the type of the given time are not the same this method will throw ClassCastException. The clock associated with this is set to be the clock associated with the time parameter.

Parameters:

time - The new value for this.

Throws:

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

java.lang.ClassCastException - Thrown if the type of this and the type of the parameter time are not the same.

Since:

1.0.1 The description of the method in 1.0 was erroneous.

set

public void set(long millis)

Sets the millisecond component of this to the given argument, and the nanosecond component of this to 0. This method is equivalent to set(millis, 0).

Parameters:

millis - This value shall be the value of the millisecond component of this at the completion of the call.

set

public void set(long millis,
                int nanos)

Sets the millisecond and nanosecond components of this. The setting is subject to parameter normalization. If there is an overflow in the millisecond component while normalizing then an IllegalArgumentException will be thrown. If after normalization the time is negative then the time represented by this is set to a negative value, but note that negative times are not supported everywhere. For instance, a negative relative time is an invalid value for a periodic thread's period.

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - Thrown if there is an overflow in the millisecond component while normalizing.