javax.measure.Measurable Maven / Gradle / Ivy
/*
* JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
* Copyright (C) 2007 - JScience (http://jscience.org/)
* All rights reserved.
*
* Permission to use, copy, modify, and distribute this software is
* freely granted, provided that this notice is preserved.
*/
package javax.measure;
import javax.measure.quantity.Quantity;
import javax.measure.unit.Unit;
/**
* This interface represents the measurable, countable, or comparable
* property or aspect of a thing.
*
* Implementing instances are typically the result of a measurement:[code]
* Measurable weight = Measure.valueOf(180.0, POUND);
* [/code]
* They can also be created from custom classes:[code]
* class Delay implements Measurable {
* private long nanoSeconds; // Implicit internal unit.
* public double doubleValue(Unit unit) { ... }
* public long longValue(Unit unit) { ... }
* }
* Thread.wait(new Delay(24, HOUR)); // Assuming Thread.wait(Measurable) method.
* [/code]
*
* Although measurable instances are for the most part scalar quantities;
* more complex implementations (e.g. vectors, data set) are allowed as
* long as an aggregate magnitude can be determined. For example:[code]
* class Velocity3D implements Measurable {
* private double x, y, z; // Meter per seconds.
* public double doubleValue(Unit unit) { ... } // Returns vector norm.
* ...
* }
* class Sensors extends Measure {
* public doubleValue(Unit unit) { ... } // Returns median value.
* ...
* } [/code]
*
* @author Jean-Marie Dautelle
* @version 4.1, June 8, 2007
*/
public interface Measurable extends Comparable> {
/**
* Returns the value of this measurable stated in the specified unit as
* a double. If the measurable has too great a magnitude to
* be represented as a double, it will be converted to
* Double.NEGATIVE_INFINITY or
* Double.POSITIVE_INFINITY as appropriate.
*
* @param unit the unit in which this measurable value is stated.
* @return the numeric value after conversion to type double.
*/
double doubleValue(Unit unit);
/**
* Returns the estimated integral value of this measurable stated in
* the specified unit as a long.
*
* Note: This method differs from the Number.longValue()
* in the sense that the closest integer value is returned
* and an ArithmeticException is raised instead
* of a bit truncation in case of overflow (safety critical).
*
* @param unit the unit in which the measurable value is stated.
* @return the numeric value after conversion to type long.
* @throws ArithmeticException if this quantity cannot be represented
* as a long number in the specified unit.
*/
long longValue(Unit unit) throws ArithmeticException;
}