javax.realtime

Class RelativeTime

java.lang.Object

javax.realtime.HighResolutionTime<RelativeTime>

javax.realtime.RelativeTime

All Implemented Interfaces:

Cloneable, Comparable<RelativeTime>

Direct Known Subclasses:

RationalTime

public class RelativeTime
extends HighResolutionTime<RelativeTime>

Jamaica Real-Time Specification for Java class RelativeTime.

An instance of this class represents an interval of time measured by a Chronograph. 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(Chronograph chronograph) Constructor to create the empty interval bound to the provided chronograph.
RelativeTime(Clock clock) Deprecated. since version 2.0
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, Chronograph chronograph) Constructor to create an interval using the provided interval that is bound to the default RealtimeClock.
RelativeTime(long ms, int ns, Clock clock) Deprecated. since version 2.0
RelativeTime(RelativeTime time) Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same chronograph association.
RelativeTime(RelativeTime time, Chronograph chronograph) Constructor to create a new RelativeTime object that represents the same interval as the given RelativeTime and that has the same chronograph association or the chronograph association provided as the clock parameter.
RelativeTime(RelativeTime time, Clock clock) Deprecated. since version 2.0

Method Summary

Modifier and Type	Method and Description
AbsoluteTime	absolute(Chronograph chronograph) absolute creates a new instance of absolute time for the point in time given by the current time of the given chronograph.
AbsoluteTime	absolute(Chronograph chronograph, 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 chronograph.
AbsoluteTime	absolute(Clock clock) Deprecated. since RTSJ 2.0
AbsoluteTime	absolute(Clock clock, AbsoluteTime destination) Deprecated. since RTSJ 2.0
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.
RelativeTime	apportion(int factor) multiply the current time by an integral scaling factor.
RelativeTime	apportion(int factor, RelativeTime destination) Divide the current time by an integral factor.
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	multiply(float factor, RelativeTime dest) Multiply this relative time by a floating point factor.
RelativeTime	negate() Multiply the current time by -1.
RelativeTime	negate(RelativeTime destination) Multiply the current time by -1.
RelativeTime	relative(Chronograph chronograph) relative returns a new instance of this interval with the given chronograph association.
RelativeTime	relative(Chronograph chronograph, RelativeTime destination) relative returns a copy of this interval with the given chronograph association.
RelativeTime	relative(Clock clock) Deprecated. since RTSJ 2.0
RelativeTime	relative(Clock clock, RelativeTime destination) Deprecated. since RTSJ 2.0
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.
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, getChronograph, getClock, getMilliseconds, getNanoseconds, hashCode, set, 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).

Throws:

StaticIllegalArgumentException - if normalization of millis and nanos caused an overflow.

Parameters:

ms - the milliseconds part of the interval

ns - the nanoseconds part of the interval.

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

Parameters:

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

RelativeTime

public RelativeTime(Chronograph chronograph)

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

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

Parameters:

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

RelativeTime

@Deprecated
public RelativeTime(Clock clock)

Deprecated. since version 2.0

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,
                    Chronograph chronograph)

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

Throws:

StaticIllegalArgumentException - if normalization of millis and nanos caused an overflow.

Parameters:

ms - the milliseconds part of the interval

ns - the nanoseconds part of the interval.

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

RelativeTime

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

Deprecated. since version 2.0

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

Throws:

StaticIllegalArgumentException - if normalization of millis and nanos caused an overflow.

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

RelativeTime

public RelativeTime(RelativeTime time,
                    Chronograph chronograph)

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

Throws:

StaticIllegalArgumentException - if time is null.

Parameters:

time - the original RelativeTime.

chronograph - the chronograph association. May be null to use time.getChronograph().

RelativeTime

@Deprecated
public RelativeTime(RelativeTime time,
                                Clock clock)

Deprecated. since version 2.0

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.

Throws:

StaticIllegalArgumentException - if time is null.

Parameters:

time - the original RelativeTime.

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

Method Detail

absolute

public AbsoluteTime absolute(Chronograph chronograph,
                             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 chronograph.

Specified by:

absolute in class HighResolutionTime<RelativeTime>

Throws:

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

Parameters:

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

destination - the destination absolute time object.

Returns:

destination or a new absolute time object.

absolute

@Deprecated
public AbsoluteTime absolute(Clock clock,
                                         AbsoluteTime destination)

Deprecated. since RTSJ 2.0

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

Throws:

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

Parameters:

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

destination - the destination absolute time object.

Returns:

destination or a new absolute time object.

absolute

public AbsoluteTime absolute(Chronograph chronograph)

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

Specified by:

absolute in class HighResolutionTime<RelativeTime>

Throws:

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

Parameters:

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

Returns:

a new absolute time object.

absolute

@Deprecated
public AbsoluteTime absolute(Clock clock)

Deprecated. since RTSJ 2.0

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

Throws:

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

Parameters:

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

Returns:

a new absolute time object.

relative

public RelativeTime relative(Chronograph chronograph)

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

Specified by:

relative in class HighResolutionTime<RelativeTime>

Parameters:

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

Returns:

A new instance with same parameters

relative

@Deprecated
public RelativeTime relative(Clock clock)

Deprecated. since RTSJ 2.0

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

Specified by:

relative in class HighResolutionTime<RelativeTime>

Parameters:

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

Returns:

A new instance with same parameters

relative

public RelativeTime relative(Chronograph chronograph,
                             RelativeTime destination)

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

Specified by:

relative in class HighResolutionTime<RelativeTime>

Parameters:

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

destination - the destination relative time object.

Returns:

destination or a new relative time object.

relative

@Deprecated
public RelativeTime relative(Clock clock,
                                         RelativeTime destination)

Deprecated. since RTSJ 2.0

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

Specified by:

relative in class HighResolutionTime<RelativeTime>

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.

Throws:

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

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.

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.

Throws:

ArithmeticException - when the negation results in an overflow.

Parameters:

destination - the destination relative time object.

Returns:

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

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.

Throws:

ArithmeticException - when the negation results in an overflow.

Returns:

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

scale

public RelativeTime scale(int factor,
                          RelativeTime destination)

Multiply the current time by an integral factor.

Throws:

ArithmeticException - when the scaling results in an overflow.

StaticIllegalArgumentException - when factor is negative.

Parameters:

factor - by which to scale this time, which must not be negative.

destination - the destination relative time object.

Returns:

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

scale

public RelativeTime scale(int factor)

multiply the current time by an integral scaling factor.

Throws:

ArithmeticException - when the scaling results in an overflow.

Parameters:

factor - by which to scale this time.

Returns:

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

apportion

public RelativeTime apportion(int factor,
                              RelativeTime destination)

Divide the current time by an integral factor.

Throws:

StaticIllegalArgumentException - when factor is zero or negative.

Parameters:

factor - by which to divide this time, which must be greater than zero.

destination - the destination relative time object.

Returns:

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

apportion

public RelativeTime apportion(int factor)

multiply the current time by an integral scaling factor.

Throws:

ArithmeticException - when the scaling results in an overflow.

Parameters:

factor - by which to apportion this time.

Returns:

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

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.

Throws:

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

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.

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.

Throws:

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

StaticIllegalArgumentException - if time is null or time.getChronograph() != getChronograph().

Parameters:

time - the time to be added.

Returns:

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

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.

Throws:

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

StaticIllegalArgumentException - if time is null or time.getChronograph() != getChronograph().

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.

addInterarrivalTo

@Deprecated
public void addInterarrivalTo(AbsoluteTime destination)
                                   throws NullPointerException

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

addInterarrivalTo adds this to the given absolute time.

Throws:

NullPointerException

Parameters:

destination -

getInterarrivalTime

@Deprecated
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

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

Throws:

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

Parameters:

time - the time to be added.

Returns:

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

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.

Throws:

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

StaticIllegalArgumentException - if time is null or time.getChronograph() != getChronograph().

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.

multiply

public RelativeTime multiply(float factor,
                             RelativeTime dest)

Multiply this relative time by a floating point factor.

Parameters:

factor - the factor by which to multiply.

dest - an object into which to place the result.

Returns:

dest, when not null, or a new object holding the result.

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

the String representation