javax.units
Class Unit

Object
  Unit

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BaseUnit, DerivedUnit

public abstract class Unit

extends Object

implements Serializable

This class represents a unit of physical quantity.

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 system unit. Such units may appear in derivative quantities. For example °C/m is a 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.

Instances of this class (and sub-classes) are immutable and unique.

See Also:

Serialized Form

Field Summary

static Unit

ONE Holds the dimensionless unit ONE.

Method Summary

Unit	add(double offset) Returns the result of adding an offset to this unit.
Unit	alternate(String symbol) Returns a unit compatible to this unit except it uses the specified symbol.
StringBuffer	appendTo(StringBuffer sb) Appends the text representation of this Unit to the StringBuffer argument.
Unit	divide(Unit that) Returns the quotient of this unit with the one specified.
abstract boolean	equals(Object that) Indicates if this unit is equal to the object specified.
Converter	getConverterTo(Unit that) Returns a converter of numeric values from this unit to another unit.
Unit	getDimension() Returns the units identifying the dimension of this unit.
protected static Unit	getInstance(Unit template) This method returns an Unit from the collection equals to the specified template.
static Collection	getInstances() Returns a read-only list of the currently-defined units.
abstract Unit	getSystemUnit() Returns the system unit for this unit.
int	hashCode() Returns a hash code value for this unit.
boolean	isCompatible(Unit that) Indicates if this unit is compatible with the unit specified.
boolean	isSystemUnit() Indicates if this unit is a system unit.
Unit	multiply(double scale) Returns the result of multiplying this unit by a scale factor.
Unit	multiply(Unit that) Returns the product of this unit with the one specified.
Unit	pow(int n) Returns a unit equals to this unit raised to an exponent.
protected Object	readResolve() Overrides readResolve() to ensure that deserialization maintains unit's unicity.
Unit	root(int n) Returns a unit equals to the given root of this unit.
static Unit	searchSymbol(CharSequence symbol) Retrieves a unit from its symbol.
String	toString() Returns the standard String representation of this unit.
static Unit	valueOf(CharSequence chars) Returns a unit instance that is defined from the specified character sequence.

Methods inherited from class Object

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

Field Detail

ONE

public static final Unit ONE

Holds the dimensionless unit ONE.

Method Detail

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:

true if both units have the same dimension; false otherwise.

See Also:

getDimension()

getDimension

public final Unit getDimension()

Returns the units identifying the dimension of this unit. The dimension returned is context-sensitve and based upon the current base units' dimensions.

Returns:

the dimensional unit for this unit.

See Also:

BaseUnit.setDimension(javax.units.Unit, javax.units.Converter)

getConverterTo

public final Converter getConverterTo(Unit that)
                               throws ConversionException

Returns a converter of numeric values from this unit to another 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 conveter cannot be constructed (e.g. !this.isCompatible(that)).

isSystemUnit

public final boolean isSystemUnit()

Indicates if this unit is a system unit. A system unit is either a base unit, an alternate unit or a product of base units and alternate units.

Returns:

true if this unit is a system unit; false otherwise.

See Also:

getSystemUnit()

getSystemUnit

public abstract Unit getSystemUnit()

Returns the system unit for this unit. The system unit identifies the nature of the quantity being measured using this unit.

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

Returns:

the system unit for this unit.

See Also:

isSystemUnit()

alternate

public final Unit alternate(String symbol)

Returns a unit compatible to this unit except it uses the specified symbol. The alternate unit can itself be used to form expressions and symbols for other derived units. For example:

   RADIAN = ONE.alternate("rad");
   NEWTON = METER.multiply(KILOGRAM).divide(SECOND.pow(2)).alternate("N");
   PASCAL = NEWTON.divide(METER.pow(2)).alternate("Pa");
 

Parameters:

symbol - the unique symbol for the alternate unit.

Returns:

a unit compatible with this unit but of different nature.

Throws:

IllegalArgumentException - if the specified symbol is currently associated to a different unit.

UnsupportedOperationException - if the specified unit is not a system unit.

See Also:

isSystemUnit()

add

public final Unit add(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.add(273.15)).

Returns:

this + offset.

multiply

public final Unit multiply(double scale)

Returns the result of multiplying this unit by a scale factor. The returned unit is convertible with all units that are convertible with this unit.

Parameters:

scale - the scale factor (e.g. KILOMETER = METER.multiply(1000)).

Returns:

this * scale

multiply

public final Unit multiply(Unit that)

Returns the product of this unit with the one specified.

Parameters:

that - the unit multiplicand.

Returns:

this * that

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:

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(CharSequence chars)

Returns a unit instance that is defined from the specified character sequence. If the specified character sequence is a combination of units (e.g. ProductUnit), then the corresponding unit is created if not already defined.

Examples of valid entries (all for meters per second squared) are:

• m s-2
• m/s²
• m·s-²
• m*s**-2
• m^+1 s^-2
• m¹·s^-2

For better parsing control, UnitFormat.parseObject(java.lang.String, java.text.ParsePosition) is recommended.

Parameters:

chars - the character sequence.

Returns:

the unit with the specified representation.

Throws:

IllegalArgumentException - if the specified character sequence cannot be correctly parsed (e.g. symbol unknown).

getInstances

public static Collection getInstances()

Returns a read-only list of the currently-defined units. The collection returned is backed by the actual collection of units -- so it grows as more units are defined.

Returns:

an unmodifiable view of the units collection.

searchSymbol

public static Unit searchSymbol(CharSequence symbol)

Retrieves a unit from its symbol.

Note: Unlike valueOf(CharSequence), this method does not parse the given string (it does not raise an exception either if the specified symbol is not yet defined).

Parameters:

symbol - the symbol searched for.

Returns:

the unit with the specified symbol or null if such unit cannot be found.

toString

public final String toString()

Returns the standard String representation of this unit.

Returns:

appendTo(new StringBuffer()).toString()

appendTo

public final StringBuffer appendTo(StringBuffer sb)

Appends the text representation of this Unit to the StringBuffer argument. For better formatting control, UnitFormat.format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition) is recommended.

Parameters:

sb - the StrinBuffer to append.

Returns:

UnitFormat.getStandardInstance().format(this, sb, null)

See Also:

UnitFormat.getStandardInstance()

equals

public abstract boolean equals(Object that)

Indicates if this unit is equal to the object specified. Units are unique and immutable, therefore users might want to use == to test for equality.

Parameters:

that - the object to compare for equality.

Returns:

true if this unit and the specified object are considered equal; false otherwise.

hashCode

public final int hashCode()

Returns a hash code value for this unit. Equals object have equal hash codes.

Returns:

this unit hash code value.

See Also:

equals(java.lang.Object)

getInstance

protected static Unit getInstance(Unit template)

This method returns an Unit from the collection equals to the specified template. If the unit is not found, the specified template is added to the collection and being returned. This method is typically used by sub-classes to ensure unicity of Unit instances.

Parameters:

template - the unit template for comparaison.

Returns:

a unit from the collection equals to the specified template; or the template itself.

Throws:

UnsupportedOperationException - if the template cannot be added to the collection (e.g. symbol already taken by a different unit).

See Also:

equals(java.lang.Object)

readResolve

protected Object readResolve()

Overrides readResolve() to ensure that deserialization maintains unit's unicity.

Returns:

a new unit or an existing unit.