001/*
002 * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
003 * Copyright (C) 2007 - JScience (http://jscience.org/)
004 * All rights reserved.
005 * 
006 * Permission to use, copy, modify, and distribute this software is
007 * freely granted, provided that this notice is preserved.
008 */
009package javax.measure;
010
011import javax.measure.quantity.Quantity;
012import javax.measure.unit.Unit;
013
014/**
015 * <p> This interface represents the measurable, countable, or comparable 
016 *     property or aspect of a thing.</p>
017 *     
018 * <p> Implementing instances are typically the result of a measurement:[code]
019 *         Measurable<Mass> weight = Measure.valueOf(180.0, POUND);
020 *     [/code]
021 *     They can also be created from custom classes:[code]
022 *     class Delay implements Measurable<Duration> {
023 *          private long nanoSeconds; // Implicit internal unit.
024 *          public double doubleValue(Unit<Velocity> unit) { ... }
025 *          public long longValue(Unit<Velocity> unit) { ... }
026 *     }
027 *     Thread.wait(new Delay(24, HOUR)); // Assuming Thread.wait(Measurable<Duration>) method.
028 *     [/code]</p>
029 *     
030 * <p> Although measurable instances are for the most part scalar quantities; 
031 *     more complex implementations (e.g. vectors, data set) are allowed as 
032 *     long as an aggregate magnitude can be determined. For example:[code]
033 *     class Velocity3D implements Measurable<Velocity> {
034 *          private double x, y, z; // Meter per seconds.
035 *          public double doubleValue(Unit<Velocity> unit) { ... } // Returns vector norm.
036 *          ... 
037 *     }
038 *     class Sensors<Q extends Quantity> extends Measure<double[], Q> {
039 *          public doubleValue(Unit<Q> unit) { ... } // Returns median value. 
040 *          ...
041 *     } [/code]</p>
042 *     
043 * @author  <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
044 * @version 4.1, June 8, 2007
045 */
046public interface Measurable<Q extends Quantity> extends Comparable<Measurable<Q>> {
047    
048    /**
049     * Returns the value of this measurable stated in the specified unit as 
050     * a <code>double</code>. If the measurable has too great a magnitude to 
051     * be represented as a <code>double</code>, it will be converted to 
052     * <code>Double.NEGATIVE_INFINITY</code> or
053     * <code>Double.POSITIVE_INFINITY</code> as appropriate.
054     * 
055     * @param unit the unit in which this measurable value is stated.
056     * @return the numeric value after conversion to type <code>double</code>.
057     */
058    double doubleValue(Unit<Q> unit);
059
060    /**
061     * Returns the estimated integral value of this measurable stated in 
062     * the specified unit as a <code>long</code>. 
063     * 
064     * <p> Note: This method differs from the <code>Number.longValue()</code>
065     *           in the sense that the closest integer value is returned 
066     *           and an ArithmeticException is raised instead
067     *           of a bit truncation in case of overflow (safety critical).</p> 
068     * 
069     * @param unit the unit in which the measurable value is stated.
070     * @return the numeric value after conversion to type <code>long</code>.
071     * @throws ArithmeticException if this quantity cannot be represented 
072     *         as a <code>long</code> number in the specified unit.
073     */
074    long longValue(Unit<Q> unit) throws ArithmeticException;
075    
076}