no.petroware.uom

Class UnitManager

java.lang.Object

no.petroware.uom.UnitManager

public final class UnitManager
extends Object

Units of measurement manager.

Singleton instance and main access point for quantities, units and unit conversions.

This class is thread-safe.

Author:

Petroware AS

Method Summary

Modifier and Type	Method and Description
void	addQuantity(Quantity quantity) Add the specified quantity to this unit manager.
void	addUnitAlias(String unitSymbolAlias, String unitSymbol) Add specified alias to be associated with the given official unit symbol.
boolean	canConvert(String unitSymbol1, String unitSymbol2) Check if it is possible to convert between the two specified units.
boolean	canConvert(Unit unit1, Unit unit2) Check if it is possible to convert between the two specified units.
double	convert(String fromUnitSymbol, String toUnitSymbol, double value) Convert the specified value between the two given units.
static double	convert(Unit fromUnit, Unit toUnit, double value) Convert the specified value between the two given units.
List<Unit>	findConvertibleUnits(String unitSymbol) Return all units that are convertible with the unit of the specified symbol.
List<Unit>	findConvertibleUnits(Unit unit) Return all units that are convertible with the specified unit.
List<Quantity>	findQuantities(String unitSymbol) Return all quantities that includes the unit of the specified symbol.
List<Quantity>	findQuantities(Unit unit) Return all quantities that includes the specified unit.
Quantity	findQuantity(String quantityName) Find quantity of the given name.
Quantity	findQuantity(Unit unit) Find quantity of the specified unit.
Unit	findUnit(String unitSymbol) Find corresponding unit instance for the given unit symbol.
String	getDisplaySymbol(String unitSymbol) Return the display symbol for the corresponding unit symbol.
String	getDisplaySymbol(Unit unit) Return the display symbol for the specified unit.
static UnitManager	getInstance() Return the sole instance of this class.
List<Quantity>	getQuantities() Return all quantities known by this unit manager.
void	setDisplaySymbol(String unitSymbol, String displaySymbol) Set the specified display symbol for the given unit symbol.
void	setDisplaySymbol(Unit unit, String displaySymbol) Set the specified display symbol for the given unit.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getInstance

public static UnitManager getInstance()

Return the sole instance of this class.

Returns:

The sole instance of this class. Never null.

addUnitAlias

public void addUnitAlias(String unitSymbolAlias,
                         String unitSymbol)

Add specified alias to be associated with the given official unit symbol.

The alias will be used when identifying Unit instances from unit symbols and affects all methods of this class taking unit symbol as argument.

Multiple aliases can be added for each unit symbol.

Parameters:

unitSymbolAlias - Alias to add. Non-null.

unitSymbol - Unit symbol to associated alias with. Non-null.

Throws:

IllegalArgumentException - If unitSymbolAlias or unitSymbol is null.

setDisplaySymbol

public void setDisplaySymbol(String unitSymbol,
                             String displaySymbol)

Set the specified display symbol for the given unit symbol.

Parameters:

unitSymbol - Official unit symbol. Non-null.

displaySymbol - Associated display symbol. Non-null.

Throws:

IllegalArgumentException - If unitSymbol or displaySymbol is null.

setDisplaySymbol

public void setDisplaySymbol(Unit unit,
                             String displaySymbol)

Set the specified display symbol for the given unit.

Parameters:

unit - Unit to set display symbol of. Non-null.

displaySymbol - Associated display symbol. Non-null.

Throws:

IllegalArgumentException - If unitSymbol or displaySymbol is null.

getQuantities

public List<Quantity> getQuantities()

Return all quantities known by this unit manager.

Returns:

All quantities. Never null.

addQuantity

public void addQuantity(Quantity quantity)

Add the specified quantity to this unit manager.

Parameters:

quantity - Quantity to add. Non-null.

Throws:

IllegalArgumentException - If quantity is null or already contained in this manager.

findQuantity

public Quantity findQuantity(String quantityName)

Find quantity of the given name.

Parameters:

quantityName - Name of quantity to find. Non-null.

Returns:

Requested quantity or null if not found.

Throws:

IllegalArgumentException - If quantityName is null.

findUnit

public Unit findUnit(String unitSymbol)

Find corresponding unit instance for the given unit symbol.

The alias mapping is considered, and units are searched both case sensitive and case insensitive.

Parameters:

unitSymbol - Unit symbol to find unit for. May be null for unitless.

Returns:

Associated unit, or null if not found.

findConvertibleUnits

public List<Unit> findConvertibleUnits(Unit unit)

Return all units that are convertible with the specified unit.

Parameters:

unit - Unit to consider. Non-null.

Returns:

All convertible units. Never null.

Throws:

IllegalArgumentException - If unit is null.

findConvertibleUnits

public List<Unit> findConvertibleUnits(String unitSymbol)

Return all units that are convertible with the unit of the specified symbol.

Parameters:

unitSymbol - Symbol of unit to consider. Null if unitless.

Returns:

All convertible units. Never null.

findQuantities

public List<Quantity> findQuantities(Unit unit)

Return all quantities that includes the specified unit.

Parameters:

unit - Unit to consider. Non-null.

Returns:

Requested quantities. Never null.

Throws:

IllegalArgumentException - If unit is null.

findQuantities

public List<Quantity> findQuantities(String unitSymbol)

Return all quantities that includes the unit of the specified symbol.

Parameters:

unitSymbol - Unit symbol of unit to consider. Null if unitless.

Returns:

Requested quantities. Never null.

findQuantity

public Quantity findQuantity(Unit unit)

Find quantity of the specified unit.

Note that a unit may be contained in multiple quantities. This method is convenient if the client knows that the unit exists in one quantity only. If it exists in more than one quantity, the first one encountered is returned.

Parameters:

unit - Unit to consider. Non-null.

Returns:

Requested quantity or null if none found.

Throws:

IllegalArgumentException - If unit is null.

canConvert

public boolean canConvert(Unit unit1,
                          Unit unit2)

Check if it is possible to convert between the two specified units.

Parameters:

unit1 - First unit to consider. Non-null.

unit2 - Second unit to consider. Non-null.

Returns:

True if it is possible to convert between the two, false otherwise.

Throws:

IllegalArgumentException - If unit1 or unit2 is null.

canConvert

public boolean canConvert(String unitSymbol1,
                          String unitSymbol2)

Check if it is possible to convert between the two specified units.

Parameters:

unitSymbol1 - Unit symbol of first unit to consider. Null if unitless.

unitSymbol2 - Unit symbol of second unit to consider. Null if unitless.

Returns:

True if it is possible to convert between the two, false otherwise.

convert

public static double convert(Unit fromUnit,
                             Unit toUnit,
                             double value)

Convert the specified value between the two given units.

Note that it is the client responsibility to check if it makes sense to convert between the given units. This method simply converts the value to base of the from unit, and convert this result from base of the to unit, without considering the compatibility between the two.

Parameters:

fromUnit - Current unit of value. Non-null.

toUnit - Unit to convert to. Non-null.

value - Value to convert.

Returns:

Converted value.

Throws:

IllegalArgumentException - If fromUnit or toUnit is null.

convert

public double convert(String fromUnitSymbol,
                      String toUnitSymbol,
                      double value)

Convert the specified value between the two given units.

Note that it is the client responsibility to check if it makes sense to convert between the given units. This method simply converts the value to base of the from unit, and convert this result from base of the to unit, without considering the compatibility between the two.

Parameters:

fromUnitSymbol - Unit symbol of current unit of value. Non-null.

toUnitSymbol - Unit symbol of unit to convert to. Non-null.

value - Value to convert.

Returns:

Converted value, or the input value it unit symbols are unknown.

Throws:

IllegalArgumentException - If fromUnitSymbol or toUnitSymbol is null.

getDisplaySymbol

public String getDisplaySymbol(String unitSymbol)

Return the display symbol for the corresponding unit symbol.

Parameters:

unitSymbol - Unit symbol to get display symbol of. As a convenience for the client, null is allowed, in case an empty string is returned.

Returns:

Display symbol of specified unit symbol. Empty string if unitless. Never null.

getDisplaySymbol

public String getDisplaySymbol(Unit unit)

Return the display symbol for the specified unit.

Parameters:

unit - Unit to get display symbol of. May be null in case an empty string is returned.

Returns:

Display symbol of specified unit. Empty string if unitless. Never null.

toString

public String toString()

Overrides:

toString in class Object