Class PeriodUnit

  • All Implemented Interfaces:
    Serializable, Comparable<PeriodUnit>

    public abstract class PeriodUnit
    extends Object
    implements Comparable<PeriodUnit>, Serializable
    A unit of time for measuring a period, such as 'Days' or 'Minutes'.

    PeriodUnit is an immutable definition of a unit of human-scale time. For example, humans typically measure periods of time in units of years, months, days, hours, minutes and seconds. These concepts are defined by instances of this class defined in the chronology classes.

    Units are either basic or derived. A derived unit can be converted accurately to another smaller unit. A basic unit is fundamental, and has no smaller representation. For example years are a derived unit consisting of 12 months, where a month is a basic unit.

    PeriodUnit is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable implementations must be final, immutable and thread-safe.

    The subclass is fully responsible for serialization as all fields in this class are transient. The subclass must use readResolve to replace the deserialized class with a valid one created via a constructor.

    Author:
    Stephen Colebourne
    See Also:
    Serialized Form
    • Constructor Detail

      • PeriodUnit

        protected PeriodUnit​(String name,
                             Duration estimatedDuration)
        Constructor to create a base unit that cannot be derived.

        A base unit cannot be derived from any smaller unit. For example, an ISO month period cannot be derived from any other smaller period.

        This method is typically only used when writing a Chronology.

        Parameters:
        name - the name of the type, not null
        estimatedDuration - the estimated duration of one unit of this period, not null
        Throws:
        IllegalArgumentException - if the duration is zero or negative
      • PeriodUnit

        protected PeriodUnit​(String name,
                             PeriodField equivalentPeriod)
        Constructor to create a unit that is derived from another smaller unit.

        A derived unit is created as a multiple of a smaller unit. For example, an ISO year period can be derived as 12 ISO month periods.

        The estimated duration is calculated using PeriodField.toEstimatedDuration().

        This method is typically only used when writing a Chronology.

        Parameters:
        name - the name of the type, not null
        equivalentPeriod - the period this is derived from, not null
        Throws:
        IllegalArgumentException - if the period is zero or negative
        ArithmeticException - if the equivalent period calculation overflows
    • Method Detail

      • getName

        public String getName()
        Gets the name of the unit, used as an identifier for the unit.

        Implementations should use the name that best represents themselves. Most units will have a plural name, such as 'Years' or 'Minutes'. The name is not localized.

        Returns:
        the name of the unit, never null
      • getEquivalentPeriods

        public List<PeriodField> getEquivalentPeriods()
        Gets the periods that are equivalent to this unit.

        Most units are related to other units. For example, an hour might be represented as 60 minutes or 3600 seconds. Thus, if this is the 'Hour' unit, then this method would return a list including both '60 Minutes', '3600 Seconds' and any other equivalent periods.

        Registered conversion is stored from larger units to smaller units. Thus, monthsUnit.getEquivalentPeriods() will not contain the unit for years. Note that the returned list does not contain this unit.

        The list will be unmodifiable and sorted, from largest unit to smallest.

        Returns:
        the equivalent periods, may be empty, never null
      • getEquivalentPeriod

        public PeriodField getEquivalentPeriod​(PeriodUnit requiredUnit)
        Gets the period in the specified unit that is equivalent to this unit.

        Most units are related to other units. For example, an hour might be represented as 60 minutes or 3600 seconds. Thus, if this is the 'Hour' unit and the 'Seconds' unit is requested, then this method would return '3600 Seconds'.

        Registered conversion is stored from larger units to smaller units. Thus, monthsUnit.getEquivalentPeriod(yearsUnit) will return null. Note that if the unit specified is this unit, then a period of 1 of this unit is returned.

        Parameters:
        requiredUnit - the required unit, not null
        Returns:
        the equivalent period, null if no equivalent in that unit
      • isConvertibleTo

        public boolean isConvertibleTo​(PeriodUnit unit)
        Checks whether this unit can be converted to the specified unit.

        Most units are related to other units. For example, an hour might be represented as 60 minutes or 3600 seconds. This method checks if this unit has a registered conversion to the specified unit.

        Registered conversion is stored from larger units to smaller units. Thus, monthsUnit.isConvertibleTo(yearsUnit) will return false. Note that this unit is convertible to itself.

        Parameters:
        unit - the unit, null returns false
        Returns:
        true if this unit is convertible or equal to the specified unit
      • getBaseUnit

        public PeriodUnit getBaseUnit()
        Gets the base unit of this unit.

        Most units are related to other units. For example, an hour might be represented as 60 minutes or 3600 seconds. The base unit is the smallest unit that this unit defines an equivalence to.

        For example, most time units are ultimately convertible to nanoseconds, thus nanoseconds is the base unit.

        Returns:
        the base unit, never null
      • getEstimatedDuration

        public Duration getEstimatedDuration()
        Gets an estimate of the duration of the unit in seconds.

        Each unit has a duration which is a reasonable estimate. For those units which can be derived ultimately from nanoseconds, the estimated duration will be accurate. For other units, it will be an estimate.

        One key use for the estimated duration is to implement Comparable.

        Returns:
        the estimate of the duration in seconds, never null
      • compareTo

        public int compareTo​(PeriodUnit other)
        Compares this unit to another.

        The comparison is based primarily on the estimated duration. If that is equal, the name is compared using standard string comparison. Finally, the first equivalent period is checked, with basic units before derived ones.

        Specified by:
        compareTo in interface Comparable<PeriodUnit>
        Parameters:
        other - the other type to compare to, not null
        Returns:
        the comparator result, negative if less, positive if greater, zero if equal
        Throws:
        NullPointerException - if other is null
      • equals

        public boolean equals​(Object obj)
        Compares two units based on the name, estimated duration and equivalent period.
        Overrides:
        equals in class Object
        Parameters:
        obj - the object to compare to, null returns false
        Returns:
        true if the units are the same
      • hashCode

        public int hashCode()
        Returns a hash code based on the name, estimated duration and equivalent period.
        Overrides:
        hashCode in class Object
        Returns:
        a suitable hash code
      • toString

        public String toString()
        Returns a string representation of the unit.

        The string representation is the same as the name.

        Overrides:
        toString in class Object
        Returns:
        the unit name, never null