UNITSOFMEASUREMENT-94: Explain that formulas with units may be different

than formulas with numerical values 

Task-Url: https://java.net/jira/browse/UNITSOFMEASUREMENT-94

src/main/java/javax/measure/quantity/ElectricCapacitance.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric capacitance.
+ * The metric system unit for this quantity is "F" (Farad).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricCapacitance extends Quantity<ElectricCapacitance> {
+
+}

src/main/java/javax/measure/quantity/ElectricCharge.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric charge.
+ * The metric system unit for this quantity is "C" (Coulomb).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricCharge extends Quantity<ElectricCharge> {
+
+}

src/main/java/javax/measure/quantity/ElectricConductance.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric conductance.
+ * The metric system unit for this quantity "S" (Siemens).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricConductance extends Quantity<ElectricConductance> {
+
+}

src/main/java/javax/measure/quantity/ElectricCurrent.java

@@ -0,0 +1,19 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents the amount of electric charge flowing past
+ * a specified circuit point per unit time.
+ * The metric system unit for this quantity is "A" (Ampere).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricCurrent extends Quantity<ElectricCurrent> {
+
+}

src/main/java/javax/measure/quantity/ElectricInductance.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric inductance.
+ * The metric system unit for this quantity is "H" (Henry).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricInductance extends Quantity<ElectricInductance> {
+
+}

src/main/java/javax/measure/quantity/ElectricPotential.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric potential or electromotive force.
+ * The metric system unit for this quantity is "V" (Volt).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricPotential extends Quantity<ElectricPotential> {
+
+}

src/main/java/javax/measure/quantity/ElectricResistance.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents an electric resistance.
+ * The metric system unit for this quantity is "Ohm" (Ω).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface ElectricResistance extends Quantity<ElectricResistance> {
+
+}

src/main/java/javax/measure/quantity/LuminousFlux.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents a luminous flux.
+ * The metric system unit for this quantity is "lm" (lumen).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface LuminousFlux extends Quantity<LuminousFlux> {
+
+}

src/main/java/javax/measure/quantity/LuminousIntensity.java

@@ -0,0 +1,19 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents the luminous flux density per solid angle as
+ * measured in a given direction relative to the emitting source.
+ * The metric system unit for this quantity is "cd" (candela).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface LuminousIntensity extends Quantity<LuminousIntensity> {
+
+}

src/main/java/javax/measure/quantity/MagneticFlux.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents a magnetic flux.
+ * The metric system unit for this quantity is "Wb" (Weber).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface MagneticFlux extends Quantity<MagneticFlux> {
+
+}

src/main/java/javax/measure/quantity/MagneticFluxDensity.java

@@ -0,0 +1,18 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+/**
+ * Represents a magnetic flux density.
+ * The metric system unit for this quantity is "T" (Tesla).
+ * 
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.0, April 15, 2009
+ */
+public interface MagneticFluxDensity extends Quantity<MagneticFluxDensity> {
+
+}

src/main/java/javax/measure/quantity/Quantity.java

@@ -0,0 +1,91 @@
+/**
+ *   Copyright (c) 2005-2010, Jean-Marie Dautelle, Werner Keil
+ *   All rights reserved.
+ *
+ *   See LICENSE.txt for the Specification License
+ */
+package javax.measure.quantity;
+
+import javax.measure.unit.Unit;
+
+/**
+ * <p> Represents a quantitative properties or attributes of thing.
+ *     Mass, time, distance, heat, and angular separation
+ *     are among the familiar examples of quantitative properties.</p>
+ *
+ * <p> {@link QuantityFactory} can be used to generate simple instances of this class.[code]
+ *         Time duration = QuantityFactory.getInstance(Time.class).create(12, MILLI(SECOND));
+ *         Length distance = QuantityFactory.getInstance(Length.class).create(37.4, MILES);
+ *     [/code]</p>
+ *
+ * <p> Quantities are used to specify the quantitative property associated
+ *     to a class through class parameterization.[code]
+ *          Unit<Mass> pound = ...
+ *          Sensor<Temperature> thermometer = ...
+ *          Vector3D<Velocity> aircraftSpeed = ...
+ *     [/code] </p>
+ *
+ * @param <Q> The type of the quantity.
+ *
+ * @author  <a href="mailto:[email protected]">Martin Desruisseaux</a>
+ * @author  <a href="mailto:[email protected]">Werner Keil</a>
+ * @author  <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
+ * @version 1.7 ($Revision: 198 $), $Date: 2010-02-24 19:53:02 +0100 (Mi, 24 Feb 2010) $
+ * @see <a href="http://en.wikipedia.org/wiki/Quantity">Wikipedia: Quantity</a>
+ */
+public interface Quantity<Q extends Quantity<Q>> extends Comparable<Quantity<Q>> {
+
+    /**
+     * Returns the magnitude or multitude value of this quantity stated in this
+     * quantity {@linkplain #getUnit() unit}.
+     *
+     * @return the numeric value of this quantity in the units returned by {@link #getUnit()}.
+     */
+    Number getValue();
+
+    /**
+     * Returns the original unit of this quantity (the one specified at creation).
+     *
+     * @return the original unit of this quantity.
+     */
+    Unit<Q> getUnit();
+
+    /**
+     * Returns the value of this quantity stated in the specified unit. 
+     * This method is recommended over <code>
+     * q.getUnit().getConverterTo(unit).convert(q.getValue())</code>,
+     * it is not only faster but also detects potential overflow if the
+     * value stated in the specific unit cannot be represented or rounded.
+     *
+     * @param unit the unit in which the returned value is stated.
+     * @return the value of this quantity when stated in the specified unit.
+     * @throws ArithmeticException if this quantity cannot be converted to
+     *         when stated in the specified unit (e.g. overflow).
+     */
+    Number getValue(Unit<Q> unit) throws ArithmeticException;
+
+    /**
+     * Returns the value of this quantity as <code>double</code> stated
+     * in the specified unit. This method is recommended over <code>
+     * q.getUnit().getConverterTo(unit).convert(q.getValue()).doubleValue()</code>
+     *
+     * @param unit the unit in which the returned value is stated.
+     * @return the value of this quantity when stated in the specified unit.
+     */
+    double doubleValue(Unit<Q> unit);
+
+    /**
+     * Returns the value of this quantity as <code>long</code> stated
+     * in the specified unit. This method is recommended over <code>
+     * q.getUnit().getConverterTo(unit).convert(q.getValue()).longValue()</code>,
+     * it is not only faster but also detects potential overflow if the
+     * value stated in the specific unit cannot be represented as
+     * <code>long</code>.
+     *
+     * @param unit the unit in which the returned value is stated.
+     * @return the value of this quantity when stated in the specified unit.
+     * @throws ArithmeticException if this quantity cannot represented as
+     *         a <code>long</code> when stated in the specified unit (e.g. overflow).
+     */
+    long longValue(Unit<Q> unit) throws ArithmeticException;
+}