Class PeriodUnit
- All Implemented Interfaces:
Serializable
,Comparable<PeriodUnit>
- Direct Known Subclasses:
CopticChronology.Months
,CopticChronology.Years
,HistoricChronology.Months
,HistoricChronology.Years
,ISOChronology.Unit
,JulianChronology.Months
,JulianChronology.Years
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.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final List
<PeriodField> The cache of periods equivalent to this unit, not null.private final Duration
The estimated duration of the unit, not null.private final int
The cache of the unit hash code.private final String
The name of the unit, not null.private static final long
The serialization version. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
PeriodUnit
(String name, PeriodField equivalentPeriod) Constructor to create a unit that is derived from another smaller unit.(package private)
PeriodUnit
(String name, PeriodField equivalentPeriod, Duration estimatedDuration) Constructor used by ISOChronology.protected
PeriodUnit
(String name, Duration estimatedDuration) Constructor to create a base unit that cannot be derived. -
Method Summary
Modifier and TypeMethodDescriptionprivate static List
<PeriodField> buildEquivalentPeriods
(PeriodField equivalentPeriod) Helper method for constructors to built the equivalent periods.int
compareTo
(PeriodUnit other) Compares this unit to another.boolean
Compares two units based on the name, estimated duration and equivalent period.Gets the base unit of this unit.getEquivalentPeriod
(PeriodUnit requiredUnit) Gets the period in the specified unit that is equivalent to this unit.Gets the periods that are equivalent to this unit.Gets an estimate of the duration of the unit in seconds.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.toString()
Returns a string representation of the unit.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDThe serialization version.- See Also:
-
name
The name of the unit, not null. -
estimatedDuration
The estimated duration of the unit, not null. -
equivalentPeriods
The cache of periods equivalent to this unit, not null. -
hashCode
private final transient int hashCodeThe cache of the unit hash code.
-
-
Constructor Details
-
PeriodUnit
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
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
-
PeriodUnit
PeriodUnit(String name, PeriodField equivalentPeriod, Duration estimatedDuration) Constructor used by ISOChronology.- Parameters:
name
- the name of the type, not nullequivalentPeriod
- the period this is derived from, null if no equivalentestimatedDuration
- the estimated duration of one unit of this period, not null- Throws:
ArithmeticException
- if the equivalent period calculation overflows
-
-
Method Details
-
buildEquivalentPeriods
Helper method for constructors to built the equivalent periods.- Parameters:
equivalentPeriod
- the period this is derived from, null if no equivalent- Returns:
- the list of equivalent periods, never null
-
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
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
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
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
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
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
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
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. -
toString
Returns a string representation of the unit.The string representation is the same as the name.
-