Package javax.measure

Provides strongly typed measurements to enforce compile-time check of parameters consistency and avoid interface errors.

See:
Description

Interface Summary

Measurable<Q extends Quantity>

This interface represents the measurable, countable, or comparable property or aspect of a thing.

Class Summary

Measure<Q extends Quantity>	This class represents the immutable result of a scalar measurement stated in a known unit.
MeasureFormat	This class provides the interface for formatting and parsing measurements.

Package javax.measure Description

Provides strongly typed measurements to enforce compile-time check of parameters consistency and avoid interface errors.

Let's take the following example:

        class Person {
            void setWeight(double weight);
        }

Should the weight be in pound, kilogram ??
Using measures there is no room for error:

        class Person {
            void setWeight(Measurable<Mass> weight);
        }

Not only the interface is cleaner (the weight has to be of mass type); but also there is no confusion on the measurement unit:

        double weightInKg = weight.doubleValue(KILOGRAM);
        double weightInLb = weight.doubleValue(POUND);

Measurable work hand-in-hand with units (also parameterized). For example, the following would result in compile-time error:

        double weightInLiter = weight.doubleValue(LITER); // Compile error, Unit<Mass> required.
        

Users may create their own Measurable implementation:

         public class Period implements Measurable<Duration> {
              long nanoseconds;
              ...
         }
 
         public class Distance implements Measurable<Length> {
              double meters;
              ...
         }
                  
         public class Velocity3D implements Measurable<Velocity> {
              double x, y, z; // In meters.
              public double doubleValue(Unit<Velocity> unit) { ... } // Returns vector norm.
              ...
         }
                 

Users may also combine a definite amount (a number) with a unit and make it a Measure (and a Measurable instance).

           
         person.setWeight(Measure.valueOf(180.0, POUND)); // Measure<Mass>
         timer.setPeriod(Measure.valueOf(20, MILLI(SECOND)); // Measure<Duration>
         circuit.setCurrent(Measure.valueOf(Complex.valueOf(2, -3), AMPERE); // Measure<ElectricCurrent>
         bottle.setPression(Measure.valueOf("23.4 kg/(m.s2)").to(PASCAL)); // Measure<Pressure>
         // or bottle.setPression(Measure.valueOf("23.4 kg/(m.s2)", Pressure.class);
     

Measures may be formatted (or parsed) using either the standard unit format (UCUM based) or a locale sensitive format.

         // Standard format (UCUM). It is used by Measure.valueOf(...) and Measure.toString()
         // This format <b>is not</b> locale-sensitive and can be used for unambiguous
         // electronic communication of quantities together with their units without loss of information.

        Measure<Pressure> pressure = Measure.valueOf("123.45 N/m2", Pressure.class); // Parse (executes MeasureFormat.getStandard().parse("123.45 N/m2")).
        System.out.println(pressure.to(NonSI.BAR)); // Format (executes MeasureFormat.getStandard().format(pressure.to(NonSI.BAR)).

        >  0.0012345 bar

        // Locale format (here French locale). This format is often nicer looking but
        // may result in loss of information/precision.

        Measure<Acceleration> acceleration = Measure.valueOf(54321, MICRO(METRE_PER_SQUARE_SECOND));
        System.out.println(MeasureFormat.getInstance().format(acceleration));
        System.out.println(MeasureFormat.getInstance().format(acceleration.toSI()));

        > 54 321 m/s²/1000000
        > 0,054 m/s²