Package org.osgi.util.measurement

Class Measurement

  • All Implemented Interfaces:
    java.lang.Comparable<java.lang.Object>
    public class Measurement
extends java.lang.Object
implements java.lang.Comparable<java.lang.Object>
    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).

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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: