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

Jamaica Real-Time Specification for Java class RelativeTime.

An instance of this class represents an interval of time measured by a Clock. The interval is given as a tuple of milliseconds and nanoseconds. The set of intervals that can be represented by this class ranges from -2⁶³ms - 999,999ns to 2⁶³ms - 1ns (more than 292 billion years back and into the future).

Constructor Summary

Constructors

Constructor and Description
RelativeTime() Constructor to create the empty interval bound to the default RealtimeClock.
RelativeTime(Clock clock) Constructor to create the empty interval bound to the provided clock.
RelativeTime(long ms, int ns) Constructor to create an interval using the provided interval that is bound to the default RealtimeClock.
RelativeTime(long ms, int ns, Clock clock) Constructor to create an interval using the provided interval that is bound to the default RealtimeClock.
RelativeTime(RelativeTime time) Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same clock association.
RelativeTime(RelativeTime time, Clock clock) Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same clock association or the clock association provided as a non-null clock parameter.

Method Summary

Modifier and Type	Method and Description
AbsoluteTime	absolute(Clock clock) absolute creates a new instance of absolute time for the point in time given by the current time of the given clock.
AbsoluteTime	absolute(Clock clock, AbsoluteTime destination) absolute converts this relative time into an instance of absolute time for the point in time given by the current time of the given clock.
RelativeTime	add(long millis, int nanos) add adds time given in milliseconds and nanoseconds to this relative time.
RelativeTime	add(long millis, int nanos, RelativeTime dest) add adds time given in milliseconds and nanoseconds to this relative time.
RelativeTime	add(RelativeTime time) add adds interval given as an instance of RelativeTime to this relative time.
RelativeTime	add(RelativeTime time, RelativeTime dest) add adds interval given as an instance of RelativeTime to this relative time.
void	addInterarrivalTo(AbsoluteTime destination) Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.
int	compareToZero() compareTo compares this to zero.
RelativeTime	getInterarrivalTime() Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.
RelativeTime	getInterarrivalTime(RelativeTime dest) Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.
RelativeTime	negate() Multiply the current time by -1.
RelativeTime	negate(RelativeTime destination) Multiply the current time by -1.
RelativeTime	relative(Clock clock) relative returns a new instance of this interval with the given clock association.
RelativeTime	relative(Clock clock, RelativeTime destination) relative returns a copy of this interval with the given clock association.
RelativeTime	scale(int factor) multiply the current time by an integral scaling factor.
RelativeTime	scale(int factor, RelativeTime destination) Multiply the current time by an integral factor.
RelativeTime	subtract(RelativeTime time) substract substracts interval given as an instance of RelativeTime from this relative time.
RelativeTime	subtract(RelativeTime time, RelativeTime dest) Subtracts time from this.
java.lang.String	toString() toString returns this interval as a string of the form "(<milli> ms, <nano> ns)".

Methods inherited from class javax.realtime.HighResolutionTime

clone, 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()

Constructor to create the empty interval bound to the default RealtimeClock.

This constructor is equivalent to RelativeTime(0, 0).

RelativeTime

public RelativeTime(long ms,
                    int ns)

Constructor to create an interval using the provided interval that is bound to the default RealtimeClock.

This constructor is equivalent to RelativeTime(ms, ns, null).

Parameters:

ms - the milliseconds part of the interval

ns - the nanoseconds part of the interval.

Throws:

java.lang.IllegalArgumentException - if normalization of millis and nanos caused an overflow.

RelativeTime

public RelativeTime(RelativeTime time)

Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same clock association.

Parameters:

time - the original RelativeTime. + @throws IllegalArgumentException if time is null.

RelativeTime

public RelativeTime(Clock clock)

Constructor to create the empty interval bound to the provided clock.

This constructor is equivalent to RelativeTime(0, 0, clock).

Parameters:

clock - the clock to be associated with this time, null to use Clock.getRealtimeClock().

RelativeTime

public RelativeTime(long ms,
                    int ns,
                    Clock clock)

Constructor to create an interval using the provided interval that is bound to the default RealtimeClock.

Parameters:

ms - the milliseconds part of the interval

ns - the nanoseconds part of the interval.

clock - the clock to be associated with this time, null to use Clock.getRealtimeClock().

Throws:

java.lang.IllegalArgumentException - if normalization of millis and nanos caused an overflow.

RelativeTime

public RelativeTime(RelativeTime time,
                    Clock clock)

Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same clock association or the clock association provided as a non-null clock parameter.

Parameters:

time - the original RelativeTime.

clock - the clock association. May be null to use time.getClock().

Throws:

java.lang.IllegalArgumentException - if time is null.

Method Detail

absolute

public AbsoluteTime absolute(Clock clock,
                             AbsoluteTime destination)

absolute converts this relative time into an instance of absolute time for the point in time given by the current time of the given clock.

Specified by:

absolute in class HighResolutionTime

Parameters:

clock - The clock, null to use Clock.getRealtimeClock().

destination - the destination absolute time object.

Returns:

destination or a new absolute time object.

Throws:

java.lang.ArithmeticException - if the resulting absolute time could not be represented by an instance of AbsoluteTime.

absolute

public AbsoluteTime absolute(Clock clock)

absolute creates a new instance of absolute time for the point in time given by the current time of the given clock.

Specified by:

absolute in class HighResolutionTime

Parameters:

clock - The clock, null to use Clock.getRealtimeClock().

Returns:

a new absolute time object.

Throws:

java.lang.ArithmeticException - if the resulting absolute time could not be represented by an instance of AbsoluteTime.

relative

public RelativeTime relative(Clock clock)

relative returns a new instance of this interval with the given clock association.

Specified by:

relative in class HighResolutionTime

Parameters:

clock - The clock, null to use Clock.getRealtimeClock().

Returns:

A new instance with same parameters

relative

public RelativeTime relative(Clock clock,
                             RelativeTime destination)

relative returns a copy of this interval with the given clock association.

Specified by:

relative in class HighResolutionTime

Parameters:

clock - The clock, null to use Clock.getRealtimeClock().

destination - the destination relative time object.

Returns:

destination or a new relative time object.

add

public RelativeTime add(long millis,
                        int nanos)

add adds time given in milliseconds and nanoseconds to this relative time.

Parameters:

millis - the milliseconds part of the interval to be added.

nanos - the nanoseconds part of the interval to be added.

Returns:

a new instance of RelativeTime specifying the interval of this plus the interval millis / nanos.

Throws:

java.lang.ArithmeticException - if the addition or normalization results in an overflow.

compareToZero

public int compareToZero()

compareTo compares this to zero.

Returns:

< 0 when this is less than 0, = 0 when this is zero, and > 0 when this is greater than 0.

negate

public RelativeTime negate(RelativeTime destination)

Multiply the current time by -1. It gives the same results as scale(int, RelativeTime), where scale is given as -1; however it is much faster.

Parameters:

destination - the destination relative time object.

Returns:

destination or, when null, a new relative time object.

Throws:

java.lang.ArithmeticException - when the negation results in an overflow.

negate

public RelativeTime negate()

Multiply the current time by -1. It gives the same results as scale(int), where scale is given as -1; however it is much faster.

Returns:

a new relative time object having the same magnitude but the opposite sign.

Throws:

java.lang.ArithmeticException - when the negation results in an overflow.

scale

public RelativeTime scale(int factor,
                          RelativeTime destination)

Multiply the current time by an integral factor.

Parameters:

factor - by which to scale this time.

destination - the destination relative time object.

Returns:

destination or, when null, a new relative time object.

Throws:

java.lang.ArithmeticException - when the scaling results in an overflow.

scale

public RelativeTime scale(int factor)

multiply the current time by an integral scaling factor.

Parameters:

factor - by which to scale this time.

Returns:

a new instance of RelativeTime with the result of the scaling.

Throws:

java.lang.ArithmeticException - when the scaling results in an overflow.

add

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

add adds time given in milliseconds and nanoseconds to this relative time. The result will be placed in the preallocated parameter dest if dest != null or in a freshly allocated object if dest == null.

Parameters:

millis - the milliseconds part of the interval to be added.

nanos - the nanoseconds part of the interval to be added.

dest - The preallocated RelativeTime object to hold the result. May be null to indicate that a new object should be allocated.

Returns:

the dest parameter or, if dest is null, a new instance of RelativeTime specifying the interval of this plus the interval millis/ nanos.

Throws:

java.lang.ArithmeticException - if the addition or normalization results in an overflow.

add

public RelativeTime add(RelativeTime time)

add adds interval given as an instance of RelativeTime to this relative time. The result will be placed in a freshly allocated object if dest== null.

Parameters:

time - the time to be added.

Returns:

a new instance of RelativeTime specifying the interval of this plus the interval millis/ nanos.

Throws:

java.lang.ArithmeticException - if the addition or normalization results in an overflow.

java.lang.IllegalArgumentException - if time is null or time.getClock() != getClock().

add

public RelativeTime add(RelativeTime time,
                        RelativeTime dest)

add adds interval given as an instance of RelativeTime to this relative time. The result will be placed in the preallocated parameter dest if dest!= null or in a freshly allocated object if dest== null.

Parameters:

time - the time to be added.

dest - The preallocated RelativeTime object to hold the result. May be null to indicate that a new object should be allocated.

Returns:

the dest parameter or, if dest is null, a new instance of RelativeTime specifying the interval of this plus the interval millis/ nanos.

Throws:

java.lang.ArithmeticException - if the addition or normalization results in an overflow.

java.lang.IllegalArgumentException - if time is null or time.getClock() != getClock().

addInterarrivalTo

public void addInterarrivalTo(AbsoluteTime destination)
                       throws java.lang.NullPointerException

Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.

addInterarrivalTo adds this to the given absolute time.

Parameters:

destination -

Throws:

java.lang.NullPointerException

getInterarrivalTime

public RelativeTime getInterarrivalTime()

Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.

getInterarrivalTime returns the interval defined by this. If this is RationalTime, this is the interval divided by the frequency.

Returns:

a newly allocated instance of RelativeTime.

getInterarrivalTime

public RelativeTime getInterarrivalTime(RelativeTime dest)

Deprecated. RTSJ V1.0.1 this method is only required to support the deprecated RationalTime.

getInterarrivalTime returns the interval defined by this. If this is RationalTime, this is the interval divided by the frequency.

Parameters:

dest - The preallocated RelativeTime object to hold the result. May be null to indicate that a new object should be allocated.

Returns:

dest if dest!= null, else a newly allocated instance.

subtract

public RelativeTime subtract(RelativeTime time)

substract substracts interval given as an instance of RelativeTime from this relative time. The result will be placed in a freshly allocated object if dest== null.

Parameters:

time - the time to be added.

Returns:

a new instance of RelativeTime specifying the interval of this plus the interval millis/ nanos.

Throws:

java.lang.ArithmeticException - if the subsctraction or normalization results in an overflow.

subtract

public RelativeTime subtract(RelativeTime time,
                             RelativeTime dest)

Subtracts time from this. The result will be placed in the pre-allocated parameter dest if dest!= null or in a freshly allocated object if dest== null.

Parameters:

time - the time to be subtracted.

dest - The preallocated RelativeTime object to hold the result. May be null to indicate that a new object should be allocated.

Returns:

the dest parameter or, if dest is null, a new instance of RelativeTime specifying the interval of this plus the interval millis/ nanos.

Throws:

java.lang.ArithmeticException - if the subtraction or normalization results in an overflow.

java.lang.IllegalArgumentException - if time is null or time.getClock() != getClock().

toString

public java.lang.String toString()

toString returns this interval as a string of the form "(<milli> ms, <nano> ns)".

Overrides:

toString in class java.lang.Object

Returns:

the String representation