javax.measure
Class Measure<Q extends Quantity>

java.lang.Object
  javax.measure.Measure<Q>

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Measurable<Q>>, Measurable<Q>

public abstract class Measure<Q extends Quantity>
extends java.lang.Object
implements Measurable<Q>, java.io.Serializable

This class represents the immutable result of a scalar measurement stated in a known unit.

To avoid any lost of precision, known exact measure (e.g. physical constants) should not be created from double constants but from their decimal representation.

         public static final Measure<Velocity> C = Measure.valueOf("299792458 m/s", Velocity.class); // Speed of Light (exact).
    

Measures can be converted to different units, the conversion precision is determined by the specified MathContext.

         Measure<Velocity> milesPerHour = C.to(MILES_PER_HOUR, MathContext.DECIMAL128); // Use BigDecimal implementation.
         System.out.println(milesPerHour);
 
         > 670616629.3843951324266284896206156 [mi_i]/h
     

If no precision is specified double precision is assumed.

         Measure<Velocity> milesPerHour = C.to(MILES_PER_HOUR); // Use double implementation (fast).
         System.out.println(milesPerHour);
 
         > 670616629.3843951 [mi_i]/h
     

Applications may sub-class Measure for particular measurements types.

         // Measurement of type Mass based on <code>double</code> primitive types.
         public class Weight extends Measure<Mass> { 
             private final double _kilograms; // Internal SI representation. 
             private Weight(double kilograms) { _kilograms = kilograms; }
             public static Weight valueOf(double value, Unit<Mass> unit) {
                 return new Weight(unit.getConverterTo(SI.KILOGRAM).convert(value));
             } 
             public Unit<Mass> getUnit() { return SI.KILOGRAM; } 
             public Double getValue() { return _kilograms; } 
             ...
         }
 
         // Complex numbers measurements.
         public class ComplexMeasure<Q extends Quantity> extends Measure<Q> {
             public Complex getValue() { ... } // Assuming Complex is a Number.
             ... 
         }
 
         // Specializations of complex numbers measurements.
         public class Current extends ComplexMeasure<ElectricCurrent> {...} 
         public class Tension extends ComplexMeasure<ElectricPotential> {...}
         

All instances of this class shall be immutable.

Version:

1.0, April 15, 2009

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Constructor Summary

protected

Measure() Default constructor.

Method Summary

boolean	approximates(Measurable<Q> that, double accuracy) Compares this measure and the specified measurable to the given accuracy.
<T extends Quantity> Measure<T>	asType(java.lang.Class<T> type) Casts this measure to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this measure unit's dimension do not match.
int	compareTo(Measurable<Q> that) Compares this measure to the specified measurable quantity.
boolean	equals(java.lang.Object obj) Compares this measure against the specified object for strict equality (same unit and same amount).
float	floatValue(Unit<Q> unit) Returns the float value of this measurable when stated in the specified unit.
abstract Unit<Q>	getUnit() Returns the measurement unit.
abstract java.lang.Number	getValue() Returns the measurement numeric value.
int	hashCode() Returns the hash code for this measure.
int	intValue(Unit<Q> unit) Returns the integral int value of this measurable when stated in the specified unit.
long	longValue(Unit<Q> unit) Returns the integral long value of this measurable when stated in the specified unit.
Measure<Q>	to(Unit<Q> unit) Returns this measure after conversion to specified unit.
Measure<Q>	to(Unit<Q> unit, java.math.MathContext ctx) Returns this measure after conversion to specified unit.
Measure<Q>	toSI() Convenient method equivalent to to(this.getUnit().toSI()).
java.lang.String	toString() Returns the String representation of this measure.
static <Q extends Quantity> Measure<Q>	valueOf(java.math.BigDecimal decimalValue, Unit<Q> unit) Returns the scalar measure for the specified BigDecimal stated in the specified unit.
static Measure<?>	valueOf(java.lang.CharSequence csq) Returns the decimal measure of unknown type corresponding to the specified representation.
static <Q extends Quantity> Measure<Q>	valueOf(double doubleValue, Unit<Q> unit) Returns the scalar measure for the specified double stated in the specified unit.
static <Q extends Quantity> Measure<Q>	valueOf(float floatValue, Unit<Q> unit) Returns the scalar measure for the specified float stated in the specified unit.
static <Q extends Quantity> Measure<Q>	valueOf(int intValue, Unit<Q> unit) Returns the scalar measure for the specified int stated in the specified unit.
static <Q extends Quantity> Measure<Q>	valueOf(long longValue, Unit<Q> unit) Returns the scalar measure for the specified long stated in the specified unit.

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.measure.Measurable

decimalValue, doubleValue

Constructor Detail

Measure

protected Measure()

Default constructor.

Method Detail

getValue

public abstract java.lang.Number getValue()

Returns the measurement numeric value.

Returns:

the measurement value.

getUnit

public abstract Unit<Q> getUnit()

Returns the measurement unit.

Returns:

the measurement unit.

toSI

public Measure<Q> toSI()

Convenient method equivalent to to(this.getUnit().toSI()).

Returns:

this measure or a new measure equivalent to this measure but stated in SI units.

Throws:

java.lang.ArithmeticException - if the result is inexact and the quotient has a non-terminating decimal expansion.

to

public Measure<Q> to(Unit<Q> unit)

Returns this measure after conversion to specified unit. The default implementation returns Measure.valueOf(doubleValue(unit), unit). If this measure is already stated in the specified unit, then this measure is returned and no conversion is performed.

Parameters:

unit - the unit in which the returned measure is stated.

Returns:

this measure or a new measure equivalent to this measure but stated in the specified unit.

Throws:

java.lang.ArithmeticException - if the result is inexact and the quotient has a non-terminating decimal expansion.

to

public Measure<Q> to(Unit<Q> unit,
                     java.math.MathContext ctx)

Returns this measure after conversion to specified unit. The default implementation returns Measure.valueOf(decimalValue(unit, ctx), unit). If this measure is already stated in the specified unit, then this measure is returned and no conversion is performed.

Parameters:

unit - the unit in which the returned measure is stated.

ctx - the math context to use for conversion.

Returns:

this measure or a new measure equivalent to this measure but stated in the specified unit.

Throws:

java.lang.ArithmeticException - if the result is inexact but the rounding mode is UNNECESSARY or mathContext.precision == 0 and the quotient has a non-terminating decimal expansion.

approximates

public boolean approximates(Measurable<Q> that,
                            double accuracy)

Compares this measure and the specified measurable to the given accuracy. Measurements are considered approximately equals if their absolute differences when stated in the same unit is less than the specified accuracy.

Parameters:

that - the measurable to compare with.

accuracy - the absolute error allowed.

Returns:

abs(this.doubleValue(getUnit())- that.doubleValue(getUnit())) <= accuracy

compareTo

public int compareTo(Measurable<Q> that)

Compares this measure to the specified measurable quantity. The default implementation compares the Measurable.doubleValue(Unit) of both this measure and the specified measurable stated in the same unit (this measure's unit).

Specified by:

compareTo in interface java.lang.Comparable<Measurable<Q extends Quantity>>

Returns:

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

equals

public boolean equals(java.lang.Object obj)

Compares this measure against the specified object for strict equality (same unit and same amount).

Similarly to the BigDecimal.equals(java.lang.Object) method which consider 2.0 and 2.00 as different objects because of different internal scales, measurements such as Measure.valueOf(3.0, KILOGRAM) Measure.valueOf(3, KILOGRAM) and Measure.valueOf("3 kg") might not be considered equals because of possible differences in their implementations.

To compare measures stated using different units or using different amount implementations the compareTo(javax.measure.Measurable) or approximates(javax.measure.Measurable, double) methods should be used.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with.

Returns:

this.getUnit.equals(obj.getUnit()) && this.getValue().equals(obj.getValue())

hashCode

public int hashCode()

Returns the hash code for this measure.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value.

toString

public final java.lang.String toString()

Returns the String representation of this measure. The string produced for a given measure is always the same; it is not affected by locale. This means that it can be used as a canonical string representation for exchanging measure, or as a key for a Hashtable, etc. Locale-sensitive measure formatting and parsing is handled by the MeasureFormat class and its subclasses.

Overrides:

toString in class java.lang.Object

Returns:

UnitFormat.getInternational().format(this)

intValue

public final int intValue(Unit<Q> unit)
                   throws java.lang.ArithmeticException

Description copied from interface: Measurable

Returns the integral int value of this measurable when stated in the specified unit.

Note: This method differs from the Number.intValue() in the sense that an ArithmeticException is raised instead of a bit truncation in case of overflow (safety critical).

Specified by:

intValue in interface Measurable<Q extends Quantity>

Parameters:

unit - the unit in which the returned value is stated.

Returns:

the numeric value after conversion to type int.

Throws:

java.lang.ArithmeticException - if this measurable cannot be represented by a int number in the specified unit.

longValue

public long longValue(Unit<Q> unit)
               throws java.lang.ArithmeticException

Description copied from interface: Measurable

Returns the integral long value of this measurable when stated in the specified unit.

Note: This method differs from the Number.longValue() in the sense that an ArithmeticException is raised instead of a bit truncation in case of overflow (safety critical).

Specified by:

longValue in interface Measurable<Q extends Quantity>

Parameters:

unit - the unit in which the returned value is stated.

Returns:

the numeric value after conversion to type long.

Throws:

java.lang.ArithmeticException - if this measurable cannot be represented by a int number in the specified unit.

floatValue

public final float floatValue(Unit<Q> unit)

Description copied from interface: Measurable

Returns the float value of this measurable when stated in the specified unit. If the measurable has too great of a magnitude to be represented as a float, FLOAT.NEGATIVE_INFINITY or FLOAT.POSITIVE_INFINITY is returned as appropriate.

Specified by:

floatValue in interface Measurable<Q extends Quantity>

Parameters:

unit - the unit in which this returned value is stated.

Returns:

the numeric value after conversion to type float.

asType

public final <T extends Quantity> Measure<T> asType(java.lang.Class<T> type)
                                         throws java.lang.ClassCastException

Casts this measure to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this measure unit's dimension do not match. For example:

 
     Measure<Length> length = Measure.valueOf("2 km").asType(Length.class);
 

Parameters:

type - the quantity class identifying the nature of the measure.

Returns:

this measure parameterized with the specified type.

Throws:

java.lang.ClassCastException - if the dimension of this unit is different from the specified quantity dimension.

java.lang.UnsupportedOperationException - if the specified quantity class does not have a public static field named "UNIT" holding the SI unit for the quantity.

See Also:

Unit.asType(Class)

valueOf

public static Measure<?> valueOf(java.lang.CharSequence csq)

Returns the decimal measure of unknown type corresponding to the specified representation. This method can be used to parse dimensionless quantities.

     Measure<Dimensionless> proportion = Measure.valueOf("0.234").asType(Dimensionless.class);
 

Note: This method handles only standard unit format (UCUM based). Locale-sensitive measure formatting and parsing are handled by the MeasureFormat class and its subclasses.

Parameters:

csq - the decimal value and its unit (if any) separated by space(s).

Returns:

MeasureFormat.getInternational().parse(csq, new ParsePosition(0))

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(int intValue,
                                                      Unit<Q> unit)

Returns the scalar measure for the specified int stated in the specified unit.

Parameters:

intValue - the measurement value.

unit - the measurement unit.

Returns:

the corresponding int measure.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(long longValue,
                                                      Unit<Q> unit)

Returns the scalar measure for the specified long stated in the specified unit.

Parameters:

longValue - the measurement value.

unit - the measurement unit.

Returns:

the corresponding long measure.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(float floatValue,
                                                      Unit<Q> unit)

Returns the scalar measure for the specified float stated in the specified unit.

Parameters:

floatValue - the measurement value.

unit - the measurement unit.

Returns:

the corresponding float measure.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(double doubleValue,
                                                      Unit<Q> unit)

Returns the scalar measure for the specified double stated in the specified unit.

Parameters:

doubleValue - the measurement value.

unit - the measurement unit.

Returns:

the corresponding double measure.

valueOf

public static <Q extends Quantity> Measure<Q> valueOf(java.math.BigDecimal decimalValue,
                                                      Unit<Q> unit)

Returns the scalar measure for the specified BigDecimal stated in the specified unit.

Parameters:

decimalValue - the measurement value.

unit - the measurement unit.

Returns:

the corresponding BigDecimal measure.