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
final class ConventionalUnit<Q extends javax.measure.Quantity<Q>> extends AbstractUnit<Q>
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

    Fields
    Modifier and Type
    Field
    Description
    private static final long
    serialVersionUID
    For cross-version compatibility.
    private final AbstractUnit<Q>
    target
    The base, derived or alternate units to which this ConventionalUnit is related.
    (package private) final javax.measure.UnitConverter
    toTarget
    The conversion from this unit to the target unit.

    Fields inherited from class org.apache.sis.measure.AbstractUnit

    DIVIDE, epsg, MULTIPLY, scope

  • Constructor Summary

    Constructors
    Constructor
    Description
    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.

  • Method Summary

    Modifier and Type
    Method
    Description
    javax.measure.Unit<Q>
    alternate(String symbol)
    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 the toTarget conversion factor on the result of raising the system unit to the given power.
    <T extends javax.measure.Quantity<T>>
    javax.measure.Unit<T>
    asType(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.
    (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
    ensureRatioScale()
    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>
    forSymbol(String symbol)
    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>
    getBaseSystemUnits()
    Returns the base units used by Apache SIS implementations.
    Map<SystemUnit<?>,Integer>
    getBaseUnits()
    Returns the base units and their exponent whose product is the system unit, or null 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
    getDimension()
    Returns the dimension of this unit.
    SystemUnit<Q>
    getSystemUnit()
    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
    pow(String symbol, int n, boolean root)
    Raises the given symbol to the given power.
    (package private) static int
    power(String symbol)
    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>
    unique(String symbol)
    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

    Methods inherited from class java.lang.Object

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

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • target

      private final AbstractUnit<Q extends javax.measure.Quantity<Q>> target
      The base, derived or alternate units to which this ConventionalUnit is related. This is called "preferred unit" in GML. This is usually an instance of SystemUnit, but may also be another ConventionalUnit 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 toTarget
      The 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 this ConventionalUnit is related.
      toTarget - the conversion from this unit to the target unit.
      symbol - the unit symbol, or null 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 the target unit.

    • unique

      final ConventionalUnit<Q> unique(String symbol)
      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

      private static String pow(String symbol, int n, boolean root)
      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

      static int power(String symbol)
      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 the SystemUnit.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 units u1 and u2 are compatible if and only if u1.getDimension().equals(u2.getDimension()).
      Returns:
      the dimension of this unit.
      See Also:

    • getSystemUnit

      public SystemUnit<Q> getSystemUnit()
      Returns the unscaled system unit from which this unit is derived.
      Specified by:
      getSystemUnit in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
      Specified by:
      getSystemUnit in class AbstractUnit<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

      public Map<SystemUnit<?>,Integer> getBaseUnits()
      Returns the base units and their exponent whose product is the system unit, or null if the system unit is a base unit (not a product of existing units).
      Specified by:
      getBaseUnits in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
      Specified by:
      getBaseUnits in class AbstractUnit<Q extends javax.measure.Quantity<Q>>
      Returns:
      the base units and their exponent making up the system unit.

    • getBaseSystemUnits

      final Map<SystemUnit<?>,Fraction> getBaseSystemUnits()
      Returns the base units used by Apache SIS implementations. Contrarily to getBaseUnits(), this method never returns null.
      Specified by:
      getBaseSystemUnits in class AbstractUnit<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 a ClassCastException 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 with that unit.
      See Also:

    • forSymbol

      final ConventionalUnit<Q> forSymbol(String symbol)
      Returns a new unit identical to this unit except for the symbol, which is set to the given value. This is used by UnitFormat mostly; we do not provide public API for setting a unit symbol on a conventional unit.

    • alternate

      public javax.measure.Unit<Q> alternate(String symbol)
      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 - if n == 0.

    • applyConversion

      private javax.measure.Unit<?> applyConversion(javax.measure.Unit<?> result, int n, boolean root)
      Applies the toTarget conversion factor on the result of raising the system unit to the given power. This method shall be invoked only if ensureRatioScale() 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 since create(AbstractUnit, UnitConverter) can infer the symbol automatically (including its prefix), but this is useful for non SI units like "mi²"
      Parameters:
      result - the result of SystemUnit.pow(int) or SystemUnit.root(int).
      n - the power by which the target has been raised for producing result.
      root - true if the power is 1/n instead of n.

    • transform

      public javax.measure.Unit<Q> transform(javax.measure.UnitConverter operation)
      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

      public boolean equals(Object other, ComparisonMode mode)
      Compares this unit with the given object for equality, optionally ignoring metadata and rounding errors.
      Specified by:
      equals in interface LenientComparable
      Overrides:
      equals in class AbstractUnit<Q extends javax.measure.Quantity<Q>>
      Parameters:
      other - the other object to compare with this unit, or null.
      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 class AbstractUnit<Q extends javax.measure.Quantity<Q>>