javax.measure.unit
Class Unit<Q extends Quantity>

java.lang.Object
  javax.measure.unit.Unit<Q>

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

BaseUnit, DerivedUnit

public abstract class Unit<Q extends Quantity>
extends java.lang.Object
implements java.io.Serializable

This class represents a determinate quantity (as of length, time, heat, or value) adopted as a standard of measurement.

It is helpful to think of instances of this class as recording the history by which they are created. Thus, for example, the string "g/kg" (which is a dimensionless unit) would result from invoking the method toString() on a unit that was created by dividing a gram unit by a kilogram unit. Yet, "kg" divided by "kg" returns ONE and not "kg/kg" due to automatic unit factorization.

This class supports the multiplication of offsets units. The result is usually a unit not convertible to its standard unit. Such units may appear in derivative quantities. For example °C/m is an unit of gradient, which is common in atmospheric and oceanographic research.

Units raised at rational powers are also supported. For example the cubic root of liter is a unit compatible with meter.

Units specializations can only be defined by sub-classing either BaseUnit, DerivedUnit or AnnotatedUnit (the unit constructor is package private).For example:

 
     public LengthUnit extends AnnotatedUnit<Length> { 
         public static LengthUnit METER = new LengthUnit(SI.METER, "myOwnUnitClass"); // Equivalent to SI.METER
         LengthUnit(Unit<Length> realUnit, String annotation) { super(realUnit, annotation); } 
     }

Instances of this class and sub-classes are immutable.

Version:

1.0, April 15, 2009

Author:

Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux

See Also:

Wikipedia: Units of measurement, Serialized Form

Field Summary

static Unit<Dimensionless>

ONE Holds the dimensionless unit ONE.

Method Summary

<A extends Quantity> AlternateUnit<A>	alternate(java.lang.String symbol) Returns a unit equivalent to this unit but used in expressions to distinguish between quantities of a different nature but of the same dimensions.
<T extends Quantity> Unit<T>	asType(java.lang.Class<T> type) Casts this unit to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this unit's dimension do not match.
CompoundUnit<Q>	compound(Unit<Q> that) Returns the combination of this unit with the specified sub-unit.
Unit<Q>	divide(double divisor) Returns the result of dividing this unit by an approximate divisor.
Unit<Q>	divide(long divisor) Returns the result of dividing this unit by an exact divisor.
Unit<?>	divide(Unit<?> that) Returns the quotient of this unit with the one specified.
abstract boolean	equals(java.lang.Object that) Indicates if the specified unit can be considered equals to the one specified.
UnitConverter	getConverterTo(Unit<Q> that) Returns a converter of numeric values from this unit to another unit.
Dimension	getDimension() Returns the dimension of this unit (depends upon the current dimensional model).
abstract int	hashCode() Returns the hash code for this unit.
Unit<?>	inverse() Returns the inverse of this unit.
boolean	isCompatible(Unit<?> that) Indicates if this unit is compatible with the unit specified.
boolean	isSI() Indicates if this unit is a standard unit (base units and alternate units are standard units).
Unit<Q>	plus(double offset) Returns the result of adding an offset to this unit.
Unit<?>	pow(int n) Returns a unit equals to this unit raised to an exponent.
Unit<?>	root(int n) Returns a unit equals to the given root of this unit.
Unit<Q>	times(double factor) Returns the result of multiplying this unit by a an approximate factor.
Unit<Q>	times(long factor) Returns the result of multiplying this unit by an exact factor.
Unit<?>	times(Unit<?> that) Returns the product of this unit with the one specified.
abstract Unit<Q>	toSI() Returns the standard unit from which this unit is derived.
java.lang.String	toString() Returns the international String representation of this unit (UCUM based).
Unit<Q>	transform(UnitConverter operation) Returns the unit derived from this unit using the specified converter.
static Unit<?>	valueOf(java.lang.CharSequence csq) Returns a unit instance that is defined from the specified character sequence using the standard unit format (UCUM based).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ONE

public static final Unit<Dimensionless> ONE

Holds the dimensionless unit ONE.

Method Detail

toSI

public abstract Unit<Q> toSI()

Returns the standard unit from which this unit is derived. The SI unit identifies the "type" of quantity for which this unit is employed. For example:

     boolean isAngularVelocity(Unit<?> u) {
         return u.toSI().equals(RADIAN.divide(SECOND));
     }
     assert(REVOLUTION.divide(MINUTE).isAngularVelocity());
 

Note: Having the same SI unit is not sufficient to ensure that a converter exists between the two units (e.g. °C/m and K/m).

Returns:

the system unit this unit is derived from.

hashCode

public abstract int hashCode()

Returns the hash code for this unit.

Overrides:

hashCode in class java.lang.Object

Returns:

this unit hashcode value.

equals

public abstract boolean equals(java.lang.Object that)

Indicates if the specified unit can be considered equals to the one specified.

Overrides:

equals in class java.lang.Object

Parameters:

that - the object to compare to.

Returns:

true if this unit is considered equal to that unit; false otherwise.

isSI

public boolean isSI()

Indicates if this unit is a standard unit (base units and alternate units are standard units). The standard unit identifies the "type" of quantity for which the unit is employed.

Returns:

this.toSI().equals(this)

isCompatible

public final boolean isCompatible(Unit<?> that)

Indicates if this unit is compatible with the unit specified. Units don't need to be equals to be compatible. For example:

     RADIAN.equals(ONE) == false 
     RADIAN.isCompatible(ONE) == true
 

Parameters:

that - the other unit.

Returns:

this.getDimension().equals(that.getDimension())

See Also:

getDimension()

asType

public final <T extends Quantity> Unit<T> asType(java.lang.Class<T> type)
                                      throws java.lang.ClassCastException

Casts this unit to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this unit's dimension do not match. For example:

      Unit<Length> LIGHT_YEAR = NonSI.C.times(NonSI.YEAR).asType(Length.class);
 

Parameters:

type - the quantity class identifying the nature of the unit.

Returns:

this unit parameterized with the specified type.

Throws:

java.lang.ClassCastException - if the dimension of this unit is different from the specified quantity dimension.

java.lang.UnsupportedOperationException - if the specified quantity class does not have a public static field named "UNIT" holding the SI unit for the quantity.

getDimension

public final Dimension getDimension()

Returns the dimension of this unit (depends upon the current dimensional model).

Returns:

the dimension of this unit for the current model.

getConverterTo

public UnitConverter getConverterTo(Unit<Q> that)
                             throws ConversionException

Returns a converter of numeric values from this unit to another unit. As a minimum unit sub-classes should be able to provide a unit converter to their associated standard unit.

Parameters:

that - the unit to which to convert the numeric values.

Returns:

the converter from this unit to that unit.

Throws:

ConversionException - if the converter cannot be constructed (e.g. !this.isCompatible(that)).

alternate

public final <A extends Quantity> AlternateUnit<A> alternate(java.lang.String symbol)

Returns a unit equivalent to this unit but used in expressions to distinguish between quantities of a different nature but of the same dimensions.

Examples of alternate units:

     Unit<Angle> RADIAN = ONE.alternate("rad"); 
     Unit<Force> NEWTON = METRE.times(KILOGRAM).divide(SECOND.pow(2)).alternate("N");
     Unit<Pressure> PASCAL = NEWTON.divide(METRE.pow(2)).alternate("Pa");
 

Parameters:

symbol - the new symbol for the alternate unit.

Returns:

the alternate unit.

Throws:

java.lang.UnsupportedOperationException - if this unit is not a standard unit.

java.lang.IllegalArgumentException - if the specified symbol is already associated to a different unit.

compound

public final CompoundUnit<Q> compound(Unit<Q> that)

Returns the combination of this unit with the specified sub-unit. Compound units are typically used for formatting purpose. Examples of compound units:

 
     Unit<Length> FOOT_INCH = FOOT.compound(INCH);
     Unit<Duration> HOUR_MINUTE_SECOND = HOUR.compound(MINUTE).compound(SECOND);
 

Parameters:

that - the least significant unit to combine with this unit.

Returns:

the corresponding compound unit.

transform

public final Unit<Q> transform(UnitConverter operation)

Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:

     Unit<Dimensionless> DECIBEL = Unit.ONE.transform(
         new LogConverter(10).inverse().concatenate( 
             new RationalConverter(1, 10)));
 

Parameters:

operation - the converter from the transformed unit to this unit.

Returns:

the unit after the specified transformation.

plus

public final Unit<Q> plus(double offset)

Returns the result of adding an offset to this unit. The returned unit is convertible with all units that are convertible with this unit.

Parameters:

offset - the offset added (expressed in this unit, e.g. CELSIUS = KELVIN.plus(273.15)).

Returns:

this.transform(new AddConverter(offset))

times

public final Unit<Q> times(long factor)

Returns the result of multiplying this unit by an exact factor.

Parameters:

factor - the exact scale factor (e.g. KILOMETRE = METRE.times(1000)).

Returns:

this.transform(new RationalConverter(factor, 1))

times

public final Unit<Q> times(double factor)

Returns the result of multiplying this unit by a an approximate factor.

Parameters:

factor - the approximate factor (e.g. ELECTRON_MASS = KILOGRAM.times(9.10938188e-31)).

Returns:

this.transform(new MultiplyConverter(factor))

times

public final Unit<?> times(Unit<?> that)

Returns the product of this unit with the one specified.

Parameters:

that - the unit multiplicand.

Returns:

this * that

inverse

public final Unit<?> inverse()

Returns the inverse of this unit.

Returns:

1 / this

divide

public final Unit<Q> divide(long divisor)

Returns the result of dividing this unit by an exact divisor.

Parameters:

divisor - the exact divisor. (e.g. QUART = GALLON_LIQUID_US.divide(4)).

Returns:

this.transform(new RationalConverter(1 , divisor))

divide

public final Unit<Q> divide(double divisor)

Returns the result of dividing this unit by an approximate divisor.

Parameters:

divisor - the approximate divisor.

Returns:

this.transform(new MultiplyConverter(1.0 / divisor))

divide

public final Unit<?> divide(Unit<?> that)

Returns the quotient of this unit with the one specified.

Parameters:

that - the unit divisor.

Returns:

this / that

root

public final Unit<?> root(int n)

Returns a unit equals to the given root of this unit.

Parameters:

n - the root's order.

Returns:

the result of taking the given root of this unit.

Throws:

java.lang.ArithmeticException - if n == 0.

pow

public final Unit<?> pow(int n)

Returns a unit equals to this unit raised to an exponent.

Parameters:

n - the exponent.

Returns:

the result of raising this unit to the exponent.

valueOf

public static Unit<?> valueOf(java.lang.CharSequence csq)

Returns a unit instance that is defined from the specified character sequence using the standard unit format (UCUM based). This method is capable of parsing any units representations produced by toString(). Locale-sensitive unit formatting and parsing are handled by the UnitFormat class and its subclasses.

This method can be used to parse dimensionless units.

 Unit<Dimensionless> PERCENT = Unit.valueOf("100").inverse().asType(Dimensionless.class); 

Parameters:

csq - the character sequence to parse.

Returns:

UnitFormat.getStandard().parse(csq, new ParsePosition(0))

Throws:

java.lang.IllegalArgumentException - if the specified character sequence cannot be correctly parsed (e.g. not UCUM compliant).

toString

public java.lang.String toString()

Returns the international String representation of this unit (UCUM based). The string produced for a given unit is always the same; it is not affected by the locale. This means that it can be used as a canonical string representation for exchanging units, or as a key for a Hashtable, etc. Locale-sensitive unit formatting and parsing is handled by the UnitFormat class and its subclasses.

Custom units types should override this method as they will not be recognized by the UCUM format.

Overrides:

toString in class java.lang.Object

Returns:

UnitFormat.getStandard().format(this)