01: /*
02: * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
03: * Copyright (C) 2007 - JScience (http://jscience.org/)
04: * All rights reserved.
05: *
06: * Permission to use, copy, modify, and distribute this software is
07: * freely granted, provided that this notice is preserved.
08: */
09: package javax.measure;
10:
11: import javax.measure.quantity.Quantity;
12: import javax.measure.unit.Unit;
13:
14: /**
15: * <p> This interface represents the measurable, countable, or comparable
16: * property or aspect of a thing.</p>
17: *
18: * <p> Implementing instances are typically the result of a measurement:[code]
19: * Measurable<Mass> weight = Measure.valueOf(180.0, POUND);
20: * [/code]
21: * They can also be created from custom classes:[code]
22: * class Delay implements Measurable<Duration> {
23: * private long nanoSeconds; // Implicit internal unit.
24: * public double doubleValue(Unit<Velocity> unit) { ... }
25: * public long longValue(Unit<Velocity> unit) { ... }
26: * }
27: * Thread.wait(new Delay(24, HOUR)); // Assuming Thread.wait(Measurable<Duration>) method.
28: * [/code]</p>
29: *
30: * <p> Although measurable instances are for the most part scalar quantities;
31: * more complex implementations (e.g. vectors, data set) are allowed as
32: * long as an aggregate magnitude can be determined. For example:[code]
33: * class Velocity3D implements Measurable<Velocity> {
34: * private double x, y, z; // Meter per seconds.
35: * public double doubleValue(Unit<Velocity> unit) { ... } // Returns vector norm.
36: * ...
37: * }
38: * class Sensors<Q extends Quantity> extends Measure<double[], Q> {
39: * public doubleValue(Unit<Q> unit) { ... } // Returns median value.
40: * ...
41: * } [/code]</p>
42: *
43: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
44: * @version 4.1, June 8, 2007
45: */
46: public interface Measurable<Q extends Quantity> extends
47: Comparable<Measurable<Q>> {
48:
49: /**
50: * Returns the value of this measurable stated in the specified unit as
51: * a <code>double</code>. If the measurable has too great a magnitude to
52: * be represented as a <code>double</code>, it will be converted to
53: * <code>Double.NEGATIVE_INFINITY</code> or
54: * <code>Double.POSITIVE_INFINITY</code> as appropriate.
55: *
56: * @param unit the unit in which this measurable value is stated.
57: * @return the numeric value after conversion to type <code>double</code>.
58: */
59: double doubleValue(Unit<Q> unit);
60:
61: /**
62: * Returns the estimated integral value of this measurable stated in
63: * the specified unit as a <code>long</code>.
64: *
65: * <p> Note: This method differs from the <code>Number.longValue()</code>
66: * in the sense that the closest integer value is returned
67: * and an ArithmeticException is raised instead
68: * of a bit truncation in case of overflow (safety critical).</p>
69: *
70: * @param unit the unit in which the measurable value is stated.
71: * @return the numeric value after conversion to type <code>long</code>.
72: * @throws ArithmeticException if this quantity cannot be represented
73: * as a <code>long</code> number in the specified unit.
74: */
75: long longValue(Unit<Q> unit) throws ArithmeticException;
76:
77: }
|