public abstract class PeriodUnit extends Object implements Comparable<PeriodUnit>, Serializable
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.
Modifier | Constructor and Description |
---|---|
protected |
PeriodUnit(String name,
Duration estimatedDuration)
Constructor to create a base unit that cannot be derived.
|
protected |
PeriodUnit(String name,
PeriodField equivalentPeriod)
Constructor to create a unit that is derived from another smaller unit.
|
Modifier and Type | Method and 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.
|
protected PeriodUnit(String name, Duration estimatedDuration)
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
.
name
- the name of the type, not nullestimatedDuration
- the estimated duration of one unit of this period, not nullIllegalArgumentException
- if the duration is zero or negativeprotected PeriodUnit(String name, PeriodField equivalentPeriod)
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
.
name
- the name of the type, not nullequivalentPeriod
- the period this is derived from, not nullIllegalArgumentException
- if the period is zero or negativeArithmeticException
- if the equivalent period calculation overflowspublic String getName()
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.
public List<PeriodField> getEquivalentPeriods()
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.
public PeriodField getEquivalentPeriod(PeriodUnit requiredUnit)
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.
requiredUnit
- the required unit, not nullpublic boolean isConvertibleTo(PeriodUnit 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.
unit
- the unit, null returns falsepublic PeriodUnit getBaseUnit()
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.
public Duration getEstimatedDuration()
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
.
public int compareTo(PeriodUnit other)
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.
compareTo
in interface Comparable<PeriodUnit>
other
- the other type to compare to, not nullNullPointerException
- if other is nullpublic boolean equals(Object obj)
public int hashCode()
Copyright © 2014. All rights reserved.