org.osgi.util.measurement
Class Measurement

java.lang.Object
  org.osgi.util.measurement.Measurement

All Implemented Interfaces:

java.lang.Comparable

public class Measurement
extends java.lang.Object
implements java.lang.Comparable

Represents a value with an error, a unit and a time-stamp.

A Measurement object is used for maintaining the tuple of value, error, unit and time-stamp. The value and error are represented as doubles and the time is measured in milliseconds since midnight, January 1, 1970 UTC.

Mathematic methods are provided that correctly calculate taking the error into account. A runtime error will occur when two measurements are used in an incompatible way. E.g., when a speed (m/s) is added to a distance (m). The measurement class will correctly track changes in unit during multiplication and division, always coercing the result to the most simple form. See Unit for more information on the supported units.

Errors in the measurement class are absolute errors. Measurement errors should use the P95 rule. Actual values must fall in the range value +/- error 95% or more of the time.

A Measurement object is immutable in order to be easily shared.

Note: This class has a natural ordering that is inconsistent with equals. See compareTo(Object).

Immutable

Constructor Summary

Measurement(double value)
Create a new Measurement object with an error of 0.0, a unit of Unit.unity and a time of zero.

Measurement(double value, double error, Unit unit)
Create a new Measurement object with a time of zero.

Measurement(double value, double error, Unit unit, long time)
Create a new Measurement object.

Measurement(double value, Unit unit)
Create a new Measurement object with an error of 0.0 and a time of zero.

Method Summary

Measurement	add(double d) Returns a new Measurement object that is the sum of this object added to the specified value.
Measurement	add(double d, Unit u) Returns a new Measurement object that is the sum of this object added to the specified value.
Measurement	add(Measurement m) Returns a new Measurement object that is the sum of this object added to the specified object.
int	compareTo(java.lang.Object obj) Compares this object with the specified object for order.
Measurement	div(double d) Returns a new Measurement object that is the quotient of this object divided by the specified value.
Measurement	div(double d, Unit u) Returns a new Measurement object that is the quotient of this object divided by the specified value.
Measurement	div(Measurement m) Returns a new Measurement object that is the quotient of this object divided by the specified object.
boolean	equals(java.lang.Object obj) Returns whether the specified object is equal to this object.
double	getError() Returns the error of this Measurement object.
long	getTime() Returns the time at which this Measurement object was taken.
Unit	getUnit() Returns the Unit object of this Measurement object.
double	getValue() Returns the value of this Measurement object.
int	hashCode() Returns a hash code value for this object.
Measurement	mul(double d) Returns a new Measurement object that is the product of this object multiplied by the specified value.
Measurement	mul(double d, Unit u) Returns a new Measurement object that is the product of this object multiplied by the specified value.
Measurement	mul(Measurement m) Returns a new Measurement object that is the product of this object multiplied by the specified object.
Measurement	sub(double d) Returns a new Measurement object that is the subtraction of the specified value from this object.
Measurement	sub(double d, Unit u) Returns a new Measurement object that is the subtraction of the specified value from this object.
Measurement	sub(Measurement m) Returns a new Measurement object that is the subtraction of the specified object from this object.
java.lang.String	toString() Returns a String object representing this Measurement object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Measurement

public Measurement(double value,
                   double error,
                   Unit unit,
                   long time)

Create a new Measurement object.

Parameters:

value - The value of the Measurement.

error - The error of the Measurement.

unit - The Unit object in which the value is measured. If this argument is null, then the unit will be set to Unit.unity.

time - The time measured in milliseconds since midnight, January 1, 1970 UTC.

Measurement

public Measurement(double value,
                   double error,
                   Unit unit)

Create a new Measurement object with a time of zero.

Parameters:

value - The value of the Measurement.

error - The error of the Measurement.

unit - The Unit object in which the value is measured. If this argument is null, then the unit will be set to Unit.unity.

Measurement

public Measurement(double value,
                   Unit unit)

Create a new Measurement object with an error of 0.0 and a time of zero.

Parameters:

value - The value of the Measurement.

unit - The Unit in which the value is measured. If this argument is null, then the unit will be set to Unit.unity.

Measurement

public Measurement(double value)

Create a new Measurement object with an error of 0.0, a unit of Unit.unity and a time of zero.

Parameters:

value - The value of the Measurement.

Method Detail

getValue

public final double getValue()

Returns the value of this Measurement object.

Returns:

The value of this Measurement object as a double.

getError

public final double getError()

Returns the error of this Measurement object. The error is always a positive value.

Returns:

The error of this Measurement as a double.

getUnit

public final Unit getUnit()

Returns the Unit object of this Measurement object.

Returns:

The Unit object of this Measurement object.

See Also:

Unit

getTime

public final long getTime()

Returns the time at which this Measurement object was taken. The time is measured in milliseconds since midnight, January 1, 1970 UTC, or zero when not defined.

Returns:

The time at which this Measurement object was taken or zero.

mul

public Measurement mul(Measurement m)

Returns a new Measurement object that is the product of this object multiplied by the specified object.

Parameters:

m - The Measurement object that will be multiplied with this object.

Returns:

A new Measurement that is the product of this object multiplied by the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be multiplied.

See Also:

Unit

mul

public Measurement mul(double d,
                       Unit u)

Returns a new Measurement object that is the product of this object multiplied by the specified value.

Parameters:

d - The value that will be multiplied with this object.

u - The Unit of the specified value.

Returns:

A new Measurement object that is the product of this object multiplied by the specified value. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Throws:

java.lang.ArithmeticException - If the units of this object and the specified value cannot be multiplied.

See Also:

Unit

mul

public Measurement mul(double d)

Returns a new Measurement object that is the product of this object multiplied by the specified value.

Parameters:

d - The value that will be multiplied with this object.

Returns:

A new Measurement object that is the product of this object multiplied by the specified value. The error of the new object is computed. The unit and time of the new object is set to the unit and time of this object.

div

public Measurement div(Measurement m)

Returns a new Measurement object that is the quotient of this object divided by the specified object.

Parameters:

m - The Measurement object that will be the divisor of this object.

Returns:

A new Measurement object that is the quotient of this object divided by the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be divided.

See Also:

Unit

div

public Measurement div(double d,
                       Unit u)

Returns a new Measurement object that is the quotient of this object divided by the specified value.

Parameters:

d - The value that will be the divisor of this object.

u - The Unit object of the specified value.

Returns:

A new Measurement that is the quotient of this object divided by the specified value. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be divided.

See Also:

Unit

div

public Measurement div(double d)

Returns a new Measurement object that is the quotient of this object divided by the specified value.

Parameters:

d - The value that will be the divisor of this object.

Returns:

A new Measurement object that is the quotient of this object divided by the specified value. The error of the new object is computed. The unit and time of the new object is set to the Unit and time of this object.

add

public Measurement add(Measurement m)

Returns a new Measurement object that is the sum of this object added to the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Parameters:

m - The Measurement object that will be added with this object.

Returns:

A new Measurement object that is the sum of this and m.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be added.

See Also:

Unit

add

public Measurement add(double d,
                       Unit u)

Returns a new Measurement object that is the sum of this object added to the specified value.

Parameters:

d - The value that will be added with this object.

u - The Unit object of the specified value.

Returns:

A new Measurement object that is the sum of this object added to the specified value. The unit of the new object is computed. The error and time of the new object is set to the error and time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified value cannot be added.

See Also:

Unit

add

public Measurement add(double d)

Returns a new Measurement object that is the sum of this object added to the specified value.

Parameters:

d - The value that will be added with this object.

Returns:

A new Measurement object that is the sum of this object added to the specified value. The error, unit, and time of the new object is set to the error, Unit and time of this object.

sub

public Measurement sub(Measurement m)

Returns a new Measurement object that is the subtraction of the specified object from this object.

Parameters:

m - The Measurement object that will be subtracted from this object.

Returns:

A new Measurement object that is the subtraction of the specified object from this object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be subtracted.

See Also:

Unit

sub

public Measurement sub(double d,
                       Unit u)

Returns a new Measurement object that is the subtraction of the specified value from this object.

Parameters:

d - The value that will be subtracted from this object.

u - The Unit object of the specified value.

Returns:

A new Measurement object that is the subtraction of the specified value from this object. The unit of the new object is computed. The error and time of the new object is set to the error and time of this object.

Throws:

java.lang.ArithmeticException - If the Unit objects of this object and the specified object cannot be subtracted.

See Also:

Unit

sub

public Measurement sub(double d)

Returns a new Measurement object that is the subtraction of the specified value from this object.

Parameters:

d - The value that will be subtracted from this object.

Returns:

A new Measurement object that is the subtraction of the specified value from this object. The error, unit and time of the new object is set to the error, Unit object and time of this object.

toString

public java.lang.String toString()

Returns a String object representing this Measurement object.

Overrides:

toString in class java.lang.Object

Returns:

a String object representing this Measurement object.

compareTo

public int compareTo(java.lang.Object obj)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified object.

Note: This class has a natural ordering that is inconsistent with equals. For this method, another Measurement object is considered equal if there is some x such that

 getValue() - getError() <= x <= getValue() + getError()
 

for both Measurement objects being compared.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - The object to be compared.

Returns:

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

Throws:

java.lang.ClassCastException - If the specified object is not of type Measurement.

java.lang.ArithmeticException - If the unit of the specified Measurement object is not equal to the Unit object of this object.

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this object.

equals

public boolean equals(java.lang.Object obj)

Returns whether the specified object is equal to this object. Two Measurement objects are equal if they have same value, error and Unit.

Note: This class has a natural ordering that is inconsistent with equals. See compareTo(Object).

Overrides:

equals in class java.lang.Object

Parameters:

obj - The object to compare with this object.

Returns:

true if this object is equal to the specified object; false otherwise.