Class PeriodUnit
- java.lang.Object
-
- javax.time.calendar.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 Summary
Constructors Modifier Constructor Description protected
PeriodUnit(String name, PeriodField equivalentPeriod)
Constructor to create a unit that is derived from another smaller unit.protected
PeriodUnit(String name, Duration estimatedDuration)
Constructor to create a base unit that cannot be derived.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(PeriodUnit other)
Compares this unit to another.boolean
equals(Object obj)
Compares two units based on the name, estimated duration and equivalent period.PeriodUnit
getBaseUnit()
Gets the base unit of this unit.PeriodField
getEquivalentPeriod(PeriodUnit requiredUnit)
Gets the period in the specified unit that is equivalent to this unit.List<PeriodField>
getEquivalentPeriods()
Gets the periods that are equivalent to this unit.Duration
getEstimatedDuration()
Gets an estimate of the duration of the unit in seconds.String
getName()
Gets the name of the unit, used as an identifier for the unit.int
hashCode()
Returns a hash code based on the name, estimated duration and equivalent period.boolean
isConvertibleTo(PeriodUnit unit)
Checks whether this unit can be converted to the specified unit.String
toString()
Returns a string representation of the unit.
-
-
-
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 nullestimatedDuration
- 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 nullequivalentPeriod
- the period this is derived from, not null- Throws:
IllegalArgumentException
- if the period is zero or negativeArithmeticException
- 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 interfaceComparable<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.
-
hashCode
public int hashCode()
Returns a hash code based on the name, estimated duration and equivalent period.
-
-