77 lines
3.3 KiB
Java
77 lines
3.3 KiB
Java
/*
|
|
* 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;
|
|
|
|
/**
|
|
* <p> This interface represents the measurable, countable, or comparable
|
|
* property or aspect of a thing.</p>
|
|
*
|
|
* <p> Implementing instances are typically the result of a measurement:[code]
|
|
* Measurable<Mass> weight = Measure.valueOf(180.0, POUND);
|
|
* [/code]
|
|
* They can also be created from custom classes:[code]
|
|
* class Delay implements Measurable<Duration> {
|
|
* private long nanoSeconds; // Implicit internal unit.
|
|
* public double doubleValue(Unit<Velocity> unit) { ... }
|
|
* public long longValue(Unit<Velocity> unit) { ... }
|
|
* }
|
|
* Thread.wait(new Delay(24, HOUR)); // Assuming Thread.wait(Measurable<Duration>) method.
|
|
* [/code]</p>
|
|
*
|
|
* <p> 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<Velocity> {
|
|
* private double x, y, z; // Meter per seconds.
|
|
* public double doubleValue(Unit<Velocity> unit) { ... } // Returns vector norm.
|
|
* ...
|
|
* }
|
|
* class Sensors<Q extends Quantity> extends Measure<double[], Q> {
|
|
* public doubleValue(Unit<Q> unit) { ... } // Returns median value.
|
|
* ...
|
|
* } [/code]</p>
|
|
*
|
|
* @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
|
|
* @version 4.1, June 8, 2007
|
|
*/
|
|
public interface Measurable<Q extends Quantity> extends Comparable<Measurable<Q>> {
|
|
|
|
/**
|
|
* Returns the value of this measurable stated in the specified unit as
|
|
* a <code>double</code>. If the measurable has too great a magnitude to
|
|
* be represented as a <code>double</code>, it will be converted to
|
|
* <code>Double.NEGATIVE_INFINITY</code> or
|
|
* <code>Double.POSITIVE_INFINITY</code> as appropriate.
|
|
*
|
|
* @param unit the unit in which this measurable value is stated.
|
|
* @return the numeric value after conversion to type <code>double</code>.
|
|
*/
|
|
double doubleValue(Unit<Q> unit);
|
|
|
|
/**
|
|
* Returns the estimated integral value of this measurable stated in
|
|
* the specified unit as a <code>long</code>.
|
|
*
|
|
* <p> Note: This method differs from the <code>Number.longValue()</code>
|
|
* 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).</p>
|
|
*
|
|
* @param unit the unit in which the measurable value is stated.
|
|
* @return the numeric value after conversion to type <code>long</code>.
|
|
* @throws ArithmeticException if this quantity cannot be represented
|
|
* as a <code>long</code> number in the specified unit.
|
|
*/
|
|
long longValue(Unit<Q> unit) throws ArithmeticException;
|
|
|
|
}
|