Package org.apache.sis.measure
Class ConventionalUnit<Q extends javax.measure.Quantity<Q>>
java.lang.Object
org.apache.sis.measure.AbstractUnit<Q>
org.apache.sis.measure.ConventionalUnit<Q>
- Type Parameters:
Q
- the kind of quantity to be measured using this units.
- All Implemented Interfaces:
Serializable
,javax.measure.Unit<Q>
,LenientComparable
A unit of measure which is related to a base or derived unit through a conversion formula.
- Since:
- 0.8
- Version:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
For cross-version compatibility.private final AbstractUnit
<Q> The base, derived or alternate units to which thisConventionalUnit
is related.(package private) final javax.measure.UnitConverter
The conversion from this unit to the target unit.Fields inherited from class org.apache.sis.measure.AbstractUnit
DIVIDE, epsg, MULTIPLY, scope
-
Constructor Summary
ConstructorsConstructorDescriptionConventionalUnit
(AbstractUnit<Q> target, javax.measure.UnitConverter toTarget, String symbol, byte scope, short epsg) Creates a new unit having the given symbol and EPSG code. -
Method Summary
Modifier and TypeMethodDescriptionjavax.measure.Unit
<Q> Unsupported operation for conventional units, as required by JSR-363 specification.private javax.measure.Unit
<?> applyConversion
(javax.measure.Unit<?> result, int n, boolean root) Applies thetoTarget
conversion factor on the result of raising the system unit to the given power.<T extends javax.measure.Quantity<T>>
javax.measure.Unit<T> Casts this unit to a parameterized unit of specified nature or throw aClassCastException
if the dimension of the specified quantity and this unit's dimension do not match.(package private) static <Q extends javax.measure.Quantity<Q>>
AbstractUnit<Q> create
(AbstractUnit<Q> target, javax.measure.UnitConverter toTarget) Creates a new unit with default name and symbol for the given converter.javax.measure.Unit
<?> divide
(javax.measure.Unit<?> divisor) Returns the quotient of this unit with the one specified.private void
Ensures that the scale of measurement of this units is a ratio scale.boolean
equals
(Object other, ComparisonMode mode) Compares this unit with the given object for equality, optionally ignoring metadata and rounding errors.(package private) final ConventionalUnit
<Q> Returns a new unit identical to this unit except for the symbol, which is set to the given value.(package private) final Map
<SystemUnit<?>, Fraction> Returns the base units used by Apache SIS implementations.Map
<SystemUnit<?>, Integer> Returns the base units and their exponent whose product is the system unit, ornull
if the system unit is a base unit (not a product of existing units).javax.measure.UnitConverter
getConverterTo
(javax.measure.Unit<Q> that) Returns a converter of numeric values from this unit to another unit of same type.javax.measure.UnitConverter
getConverterToAny
(javax.measure.Unit<?> that) Returns a converter from this unit to the specified unit of unknown type.javax.measure.Dimension
Returns the dimension of this unit.Returns the unscaled system unit from which this unit is derived.int
hashCode()
Returns a hash code value for this unit.javax.measure.Unit
<?> multiply
(javax.measure.Unit<?> multiplier) Returns the product of this unit with the one specified.javax.measure.Unit
<?> pow
(int n) Returns a unit equals to this unit raised to an exponent.private static String
Raises the given symbol to the given power.(package private) static int
Returns the positive power after the given unit symbol, or 0 in case of doubt.javax.measure.Unit
<?> root
(int n) Returns a unit equals to the given root of this unit.javax.measure.Unit
<Q> transform
(javax.measure.UnitConverter operation) Returns the unit derived from this unit using the specified converter.(package private) final ConventionalUnit
<Q> Returns a unique instance of this unit if available, or store this unit in the map of existing unit otherwise.Methods inherited from class org.apache.sis.measure.AbstractUnit
divide, equals, getName, getSymbol, incompatible, inferSymbol, inferSymbol, invalidCharForSymbol, inverse, isCompatible, isPrefixable, isPrefixable, isSymbolChar, multiply, readResolve, related, shift, toString
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
target
The base, derived or alternate units to which thisConventionalUnit
is related. This is called "preferred unit" in GML. This is usually an instance ofSystemUnit
, but may also be anotherConventionalUnit
in some rare cases where this conventional unit can be prefixed like a SI units (e.g. litre: L, cl, mL, µL). -
toTarget
final javax.measure.UnitConverter toTargetThe conversion from this unit to the target unit.
-
-
Constructor Details
-
ConventionalUnit
ConventionalUnit(AbstractUnit<Q> target, javax.measure.UnitConverter toTarget, String symbol, byte scope, short epsg) Creates a new unit having the given symbol and EPSG code.- Parameters:
target
- the base or derived units to which thisConventionalUnit
is related.toTarget
- the conversion from this unit to thetarget
unit.symbol
- the unit symbol, ornull
if this unit has no specific symbol.scope
-UnitRegistry.SI
,UnitRegistry.ACCEPTED
, other constants or 0 if unknown.epsg
- the EPSG code, or 0 if this unit has no EPSG code.
-
-
Method Details
-
create
static <Q extends javax.measure.Quantity<Q>> AbstractUnit<Q> create(AbstractUnit<Q> target, javax.measure.UnitConverter toTarget) Creates a new unit with default name and symbol for the given converter.- Parameters:
target
- the base or derived units to which the new unit will be related.toTarget
- the conversion from the new unit to thetarget
unit.
-
unique
Returns a unique instance of this unit if available, or store this unit in the map of existing unit otherwise.- Parameters:
symbol
- the symbol of this unit, which must be non-null.
-
pow
Raises the given symbol to the given power. If the given symbol already contains an exponent, it will be combined with the given power.- Parameters:
symbol
- the symbol to raise to a power.n
- the power to which to raise the given symbol.root
-true
for raising to 1/n instead of n.
-
power
Returns the positive power after the given unit symbol, or 0 in case of doubt. For example, this method returns 1 for “m” and 2 for “m²”. We parse the unit symbol instead than theSystemUnit.dimension
because we cannot extract easily the power from the product of dimensions (e.g. what is the M⋅L²∕T³ power?) Furthermore, the power will be used for choosing a symbol prefix, so we want it to be consistent with the symbol more than the internal representation.If the unit is itself a product of other units, then this method returns the power of the first unit. For example, the power of “m/s²” is 1. This means that the “k” prefix in “km/s²” apply only to the “m” unit.
-
getDimension
public javax.measure.Dimension getDimension()Returns the dimension of this unit. Two unitsu1
andu2
are compatible if and only ifu1.getDimension().equals(u2.getDimension())
.- Returns:
- the dimension of this unit.
- See Also:
-
getSystemUnit
Returns the unscaled system unit from which this unit is derived.- Specified by:
getSystemUnit
in interfacejavax.measure.Unit<Q extends javax.measure.Quantity<Q>>
- Specified by:
getSystemUnit
in classAbstractUnit<Q extends javax.measure.Quantity<Q>>
- Returns:
- the system unit this unit is derived from, or
this
if this unit is a system unit.
-
getBaseUnits
Returns the base units and their exponent whose product is the system unit, ornull
if the system unit is a base unit (not a product of existing units).- Specified by:
getBaseUnits
in interfacejavax.measure.Unit<Q extends javax.measure.Quantity<Q>>
- Specified by:
getBaseUnits
in classAbstractUnit<Q extends javax.measure.Quantity<Q>>
- Returns:
- the base units and their exponent making up the system unit.
-
getBaseSystemUnits
Returns the base units used by Apache SIS implementations. Contrarily togetBaseUnits()
, this method never returnsnull
.- Specified by:
getBaseSystemUnits
in classAbstractUnit<Q extends javax.measure.Quantity<Q>>
-
asType
public <T extends javax.measure.Quantity<T>> javax.measure.Unit<T> asType(Class<T> type) throws ClassCastException Casts this unit to a parameterized unit of specified nature or throw aClassCastException
if the dimension of the specified quantity and this unit's dimension do not match.- Type Parameters:
T
- the type of the quantity measured by the unit.- Parameters:
type
- the quantity class identifying the nature of the unit.- Returns:
- this unit parameterized with the specified type.
- Throws:
ClassCastException
- if the dimension of this unit is different from the specified quantity dimension.
-
getConverterTo
public javax.measure.UnitConverter getConverterTo(javax.measure.Unit<Q> that) throws javax.measure.UnconvertibleException Returns a converter of numeric values from this unit to another unit of same type.- Parameters:
that
- the unit of same type to which to convert the numeric values.- Returns:
- the converter from this unit to
that
unit. - Throws:
javax.measure.UnconvertibleException
- if the converter cannot be constructed.
-
getConverterToAny
public javax.measure.UnitConverter getConverterToAny(javax.measure.Unit<?> that) throws javax.measure.IncommensurableException Returns a converter from this unit to the specified unit of unknown type. This method can be used when the quantity type of the specified unit is unknown at compile-time or when dimensional analysis allows for conversion between units of different type.- Parameters:
that
- the unit to which to convert the numeric values.- Returns:
- the converter from this unit to
that
unit. - Throws:
javax.measure.IncommensurableException
- if this unit is not compatible withthat
unit.- See Also:
-
forSymbol
Returns a new unit identical to this unit except for the symbol, which is set to the given value. This is used byUnitFormat
mostly; we do not provide public API for setting a unit symbol on a conventional unit. -
alternate
Unsupported operation for conventional units, as required by JSR-363 specification.- Parameters:
symbol
- the new symbol for the alternate unit.- Returns:
- the alternate unit.
- Throws:
UnsupportedOperationException
- always thrown since this unit is not an unscaled standard unit.- See Also:
-
ensureRatioScale
private void ensureRatioScale()Ensures that the scale of measurement of this units is a ratio scale. -
multiply
public javax.measure.Unit<?> multiply(javax.measure.Unit<?> multiplier) Returns the product of this unit with the one specified.- Parameters:
multiplier
- the unit multiplier.- Returns:
this
×multiplier
-
divide
public javax.measure.Unit<?> divide(javax.measure.Unit<?> divisor) Returns the quotient of this unit with the one specified.- Parameters:
divisor
- the unit divisor.- Returns:
this
∕divisor
-
pow
public javax.measure.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.
-
root
public javax.measure.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
- ifn == 0
.
-
applyConversion
private javax.measure.Unit<?> applyConversion(javax.measure.Unit<?> result, int n, boolean root) Applies thetoTarget
conversion factor on the result of raising the system unit to the given power. This method shall be invoked only ifensureRatioScale()
succeed (this is not verified). This method tries to build a unit symbol made from the current unit raised to the given power. This is not needed for SI units sincecreate(AbstractUnit, UnitConverter)
can infer the symbol automatically (including its prefix), but this is useful for non SI units like "mi²"- Parameters:
result
- the result ofSystemUnit.pow(int)
orSystemUnit.root(int)
.n
- the power by which thetarget
has been raised for producingresult
.root
-true
if the power is 1/n instead of n.
-
transform
Returns the unit derived from this unit using the specified converter.- Parameters:
operation
- the converter from the transformed unit to this unit.- Returns:
- the unit after the specified transformation.
-
equals
Compares this unit with the given object for equality, optionally ignoring metadata and rounding errors.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractUnit<Q extends javax.measure.Quantity<Q>>
- Parameters:
other
- the other object to compare with this unit, ornull
.mode
- the strictness level of the comparison.- Returns:
true
if the given object is equal to this unit.- See Also:
-
hashCode
public int hashCode()Returns a hash code value for this unit.- Overrides:
hashCode
in classAbstractUnit<Q extends javax.measure.Quantity<Q>>
-