Package tech.units.indriya

Class AbstractUnit<Q extends javax.measure.Quantity<Q>>

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<javax.measure.Unit<Q>>, javax.measure.Unit<Q>, ComparableUnit<Q>
    Direct Known Subclasses:
    AlternateUnit, AnnotatedUnit, BaseUnit, ProductUnit, TransformedUnit
    public abstract class AbstractUnit<Q extends javax.measure.Quantity<Q>>
extends java.lang.Object
implements ComparableUnit<Q>

    The class represents units founded on the seven SI base units for seven base quantities assumed to be mutually independent.

    For all physics units, unit conversions are symmetrical: u1.getConverterTo(u2).equals(u2.getConverterTo(u1).inverse()). Non-physical units (e.g. currency units) for which conversion is not symmetrical should have their own separate class hierarchy and are considered distinct (e.g. financial units), although they can always be combined with physics units (e.g. "€/Kg", "$/h").

    Since:
    1.0
    Version:
    1.2, April 11, 2018
    See Also:
    Wikipedia: International System of Units, Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  AbstractUnit.Equalizer
      Utility class for number comparison and equality

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String name
      Holds the name.
      static javax.measure.Unit<javax.measure.quantity.Dimensionless> ONE
      Holds the dimensionless unit ONE.
      private static long serialVersionUID  
      private java.lang.String symbol
      Holds the symbol.
      protected static java.util.Map<java.lang.String,​javax.measure.Unit<?>> SYMBOL_TO_UNIT
      Holds the unique symbols collection (base units or alternate units).

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected AbstractUnit()
      Default constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      javax.measure.Unit<Q> alternate​(java.lang.String symbol)  
      javax.measure.Unit<Q> annotate​(java.lang.String annotation)
      Annotates the specified unit.
      <T extends javax.measure.Quantity<T>>
      AbstractUnit<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 (regardless whether or not the dimensions are independent or not).
      int compareTo​(javax.measure.Unit<Q> that)
      Compares this unit to the specified unit.
      (package private) static javax.measure.UnitConverter converterOf​(double factor)  
      javax.measure.Unit<Q> divide​(double divisor)
      Returns the result of dividing this unit by the specified divisor.
      javax.measure.Unit<?> divide​(javax.measure.Unit<?> that)
      Returns the quotient of this unit with the one specified.
      protected javax.measure.Unit<?> divide​(AbstractUnit<?> that)
      Returns the quotient of this physical unit with the one specified.
      abstract boolean equals​(java.lang.Object obj)  
      protected java.lang.reflect.Type getActualType()  
      abstract java.util.Map<? extends javax.measure.Unit<?>,​java.lang.Integer> getBaseUnits()  
      javax.measure.UnitConverter getConverterTo​(javax.measure.Unit<Q> that)  
      javax.measure.UnitConverter getConverterToAny​(javax.measure.Unit<?> that)  
      abstract javax.measure.Dimension getDimension()  
      java.lang.String getName()  
      java.lang.String getSymbol()  
      abstract javax.measure.UnitConverter getSystemConverter()
      Returns the converter from this unit to its unscaled System Unit unit.
      javax.measure.Unit<Q> getSystemUnit()
      Returns the system unit (unscaled SI unit) from which this unit is derived.
      abstract int hashCode()  
      private javax.measure.UnitConverter internalGetConverterTo​(javax.measure.Unit<Q> that, boolean useEquals)  
      private boolean internalIsCompatible​(javax.measure.Unit<?> that, boolean checkEquals)
      Internal helper for isCompatible
      javax.measure.Unit<?> inverse()
      Returns the inverse of this physical unit.
      boolean isCompatible​(javax.measure.Unit<?> that)
      Indicates if this unit is compatible with the unit specified.
      boolean isEquivalentOf​(javax.measure.Unit<Q> that)
      Compares two instances of , doing the conversion of unit if necessary.
      private static boolean isLongValue​(double value)  
      boolean isSystemUnit()
      Indicates if this unit belongs to the set of coherent SI units (unscaled SI units).
      javax.measure.Unit<Q> multiply​(double factor)  
      javax.measure.Unit<?> multiply​(javax.measure.Unit<?> that)
      Returns the product of this unit with the one specified.
      protected javax.measure.Unit<?> multiply​(AbstractUnit<?> that)
      Returns the product of this physical unit with the one specified.
      static javax.measure.Unit<?> parse​(java.lang.CharSequence charSequence)
      Returns the abstract unit represented by the specified characters as per default format.
      javax.measure.Unit<?> pow​(int n)
      Returns a unit equals to this unit raised to an exponent.
      AbstractUnit<Q> prefix​(Prefix prefix)  
      javax.measure.Unit<?> root​(int n)
      Returns a unit equals to the given root of this unit.
      protected void setName​(java.lang.String name)  
      protected void setSymbol​(java.lang.String s)  
      javax.measure.Unit<Q> shift​(double offset)  
      java.lang.String toString()
      Returns the standard representation of this physics unit.
      protected abstract javax.measure.Unit<Q> toSystemUnit()
      Returns the unscaled SI unit from which this unit is derived.
      javax.measure.Unit<Q> transform​(javax.measure.UnitConverter operation)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • name

        protected java.lang.String name
        Holds the name.

      • symbol

        private java.lang.String symbol
        Holds the symbol.

      • SYMBOL_TO_UNIT

        protected static final java.util.Map<java.lang.String,​javax.measure.Unit<?>> SYMBOL_TO_UNIT
        Holds the unique symbols collection (base units or alternate units).

    • Constructor Detail

      • AbstractUnit

        protected AbstractUnit()
        Default constructor.

    • Method Detail

      • getActualType

        protected java.lang.reflect.Type getActualType()

      • isSystemUnit

        public boolean isSystemUnit()
        Indicates if this unit belongs to the set of coherent SI units (unscaled SI units). The base and coherent derived units of the SI form a coherent set, designated the set of coherent SI units. The word coherent is used here in the following sense: when coherent units are used, equations between the numerical values of quantities take exactly the same form as the equations between the quantities themselves. Thus if only units from a coherent set are used, conversion factors between units are never required.
        Specified by:
        isSystemUnit in interface ComparableUnit<Q extends javax.measure.Quantity<Q>>
        Returns:
        equals(toSystemUnit())

      • toSystemUnit

        protected abstract javax.measure.Unit<Q> toSystemUnit()
        Returns the unscaled SI unit from which this unit is derived. The SI unit can be be used to identify a quantity given the unit. For example: static boolean isAngularVelocity(AbstractUnit unit) { return unit.toSystemUnit().equals(RADIAN.divide(SECOND)); } assert(REVOLUTION.divide(MINUTE).isAngularVelocity()); // Returns true.
        Returns:
        the unscaled metric unit from which this unit is derived.

      • getSystemConverter

        public abstract javax.measure.UnitConverter getSystemConverter()
        Returns the converter from this unit to its unscaled System Unit unit.
        Returns:
        getConverterTo(this.toSystemUnit())
        See Also:
        toSystemUnit()

      • annotate

        public javax.measure.Unit<Q> annotate​(java.lang.String annotation)
        Annotates the specified unit. Annotation does not change the unit semantic. Annotations are often written between curly braces behind units. For example:
        Unit PERCENT_VOL = ((AbstractUnit)Units.PERCENT).annotate("vol"); // "%{vol}" Unit KG_TOTAL = ((AbstractUnit)Units.KILOGRAM).annotate("total"); // "kg{total}" Unit RED_BLOOD_CELLS = ((AbstractUnit)Units.ONE).annotate("RBC"); // "{RBC}" Note: Annotation of system units are not considered themselves as system units.
        Parameters:
        annotation - the unit annotation.
        Returns:
        the annotated unit.

      • parse

        public static javax.measure.Unit<?> parse​(java.lang.CharSequence charSequence)
        Returns the abstract unit represented by the specified characters as per default format. Locale-sensitive unit parsing could be handled using LocalUnitFormat in subclasses of AbstractUnit.

        Note: The standard format supports dimensionless units. AbstractUnit PERCENT = AbstractUnit.parse("100").inverse().asType(Dimensionless.class);

        Parameters:
        charSequence - the character sequence to parse.
        Returns:
        SimpleUnitFormat.getInstance().parse(csq, new ParsePosition(0))
        Throws:
        javax.measure.format.ParserException - if the specified character sequence cannot be correctly parsed (e.g. not UCUM compliant).

      • toString

        public java.lang.String toString()
        Returns the standard representation of this physics unit. The string produced for a given unit is always the same; it is not affected by the locale. It can be used as a canonical string representation for exchanging units, or as a key for a Hashtable, etc. Locale-sensitive unit parsing could be handled using LocalUnitFormat in subclasses of AbstractUnit.
        Specified by:
        toString in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Overrides:
        toString in class java.lang.Object
        Returns:
        SimpleUnitFormat.getInstance().format(this)

      • getSystemUnit

        public final javax.measure.Unit<Q> getSystemUnit()
        Returns the system unit (unscaled SI unit) from which this unit is derived. They can be be used to identify a quantity given the unit. For example:
        static boolean isAngularVelocity(AbstractUnit unit) {
          return unit.getSystemUnit().equals(RADIAN.divide(SECOND));
        }
        assert(REVOLUTION.divide(MINUTE).isAngularVelocity()); // Returns true.
        Specified by:
        getSystemUnit in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Returns:
        the unscaled metric unit from which this unit is derived.

      • isCompatible

        public final boolean isCompatible​(javax.measure.Unit<?> that)
        Indicates if this unit is compatible with the unit specified. To be compatible both units must be physics units having the same fundamental dimension.
        Specified by:
        isCompatible in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        that - the other unit.
        Returns:
        true if this unit and that unit have equals fundamental dimension according to the current physics model; false otherwise.

      • asType

        public final <T extends javax.measure.Quantity<T>> AbstractUnit<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 (regardless whether or not the dimensions are independent or not).
        Specified by:
        asType in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        type - the quantity class identifying the nature of the unit.
        Throws:
        java.lang.ClassCastException - if the dimension of this unit is different from the SI dimension of the specified type.
        See Also:
        AbstractSystemOfUnits.getUnit(Class)

      • getBaseUnits

        public abstract java.util.Map<? extends javax.measure.Unit<?>,​java.lang.Integer> getBaseUnits()
        Specified by:
        getBaseUnits in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • getDimension

        public abstract javax.measure.Dimension getDimension()
        Specified by:
        getDimension in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • setName

        protected void setName​(java.lang.String name)

      • getName

        public java.lang.String getName()
        Specified by:
        getName in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • getSymbol

        public java.lang.String getSymbol()
        Specified by:
        getSymbol in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • setSymbol

        protected void setSymbol​(java.lang.String s)

      • getConverterTo

        public final javax.measure.UnitConverter getConverterTo​(javax.measure.Unit<Q> that)
                                                 throws javax.measure.UnconvertibleException
        Specified by:
        getConverterTo in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Throws:
        javax.measure.UnconvertibleException

      • getConverterToAny

        public final javax.measure.UnitConverter getConverterToAny​(javax.measure.Unit<?> that)
                                                    throws javax.measure.IncommensurableException,
                                                           javax.measure.UnconvertibleException
        Specified by:
        getConverterToAny in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Throws:
        javax.measure.IncommensurableException
        javax.measure.UnconvertibleException

      • alternate

        public final javax.measure.Unit<Q> alternate​(java.lang.String symbol)
        Specified by:
        alternate in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • transform

        public final javax.measure.Unit<Q> transform​(javax.measure.UnitConverter operation)
        Specified by:
        transform in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • shift

        public final javax.measure.Unit<Q> shift​(double offset)
        Specified by:
        shift in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • multiply

        public final javax.measure.Unit<Q> multiply​(double factor)
        Specified by:
        multiply in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>

      • internalIsCompatible

        private final boolean internalIsCompatible​(javax.measure.Unit<?> that,
                                           boolean checkEquals)
        Internal helper for isCompatible

      • internalGetConverterTo

        private final javax.measure.UnitConverter internalGetConverterTo​(javax.measure.Unit<Q> that,
                                                                 boolean useEquals)
                                                          throws javax.measure.UnconvertibleException
        Throws:
        javax.measure.UnconvertibleException

      • isLongValue

        private static boolean isLongValue​(double value)

      • converterOf

        static javax.measure.UnitConverter converterOf​(double factor)

      • multiply

        public final javax.measure.Unit<?> multiply​(javax.measure.Unit<?> that)
        Returns the product of this unit with the one specified.

        Note: If the specified unit (that) is not a physical unit, then that.multiply(this) is returned.

        Specified by:
        multiply in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        that - the unit multiplicand.
        Returns:
        this * that

      • multiply

        protected final javax.measure.Unit<?> multiply​(AbstractUnit<?> that)
        Returns the product of this physical unit with the one specified.
        Parameters:
        that - the physical unit multiplicand.
        Returns:
        this * that

      • inverse

        public final javax.measure.Unit<?> inverse()
        Returns the inverse of this physical unit.
        Specified by:
        inverse in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Returns:
        1 / this

      • divide

        public final javax.measure.Unit<Q> divide​(double divisor)
        Returns the result of dividing this unit by the specified divisor. If the factor is an integer value, the division is exact. For example: 
         
    QUART = GALLON_LIQUID_US.divide(4); // Exact definition.
        Specified by:
        divide in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        divisor - the divisor value.
        Returns:
        this unit divided by the specified divisor.

      • divide

        public final javax.measure.Unit<?> divide​(javax.measure.Unit<?> that)
        Returns the quotient of this unit with the one specified.
        Specified by:
        divide in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        that - the unit divisor.
        Returns:
        this.multiply(that.inverse())

      • divide

        protected final javax.measure.Unit<?> divide​(AbstractUnit<?> that)
        Returns the quotient of this physical unit with the one specified.
        Parameters:
        that - the physical unit divisor.
        Returns:
        this.multiply(that.inverse())

      • root

        public final javax.measure.Unit<?> root​(int n)
        Returns a unit equals to the given root of this unit.
        Specified by:
        root in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        n - the root's order.
        Returns:
        the result of taking the given root of this unit.
        Throws:
        java.lang.ArithmeticException - if n == 0 or if this operation would result in an unit with a fractional exponent.

      • pow

        public final javax.measure.Unit<?> pow​(int n)
        Returns a unit equals to this unit raised to an exponent.
        Specified by:
        pow in interface javax.measure.Unit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        n - the exponent.
        Returns:
        the result of raising this unit to the exponent.

      • compareTo

        public int compareTo​(javax.measure.Unit<Q> that)
        Compares this unit to the specified unit. The default implementation compares the name and symbol of both this unit and the specified unit.
        Specified by:
        compareTo in interface java.lang.Comparable<Q extends javax.measure.Quantity<Q>>
        Returns:
        a negative integer, zero, or a positive integer as this unit is less than, equal to, or greater than the specified unit.

      • isEquivalentOf

        public boolean isEquivalentOf​(javax.measure.Unit<Q> that)
        Description copied from interface: ComparableUnit
        Compares two instances of , doing the conversion of unit if necessary.
        Specified by:
        isEquivalentOf in interface ComparableUnit<Q extends javax.measure.Quantity<Q>>
        Parameters:
        that - the Unit<Q> to be compared with this instance.
        Returns:
        true if that < this.

      • equals

        public abstract boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public abstract int hashCode()
        Overrides:
        hashCode in class java.lang.Object