Class PeriodUnit
- java.lang.Object
-
- javax.time.calendar.PeriodUnit
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<PeriodUnit>
- Direct Known Subclasses:
CopticChronology.Months
,CopticChronology.Years
,HistoricChronology.Months
,HistoricChronology.Years
,ISOChronology.Unit
,JulianChronology.Months
,JulianChronology.Years
public abstract class PeriodUnit extends java.lang.Object implements java.lang.Comparable<PeriodUnit>, java.io.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.- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description private java.util.List<PeriodField>
equivalentPeriods
The cache of periods equivalent to this unit, not null.private Duration
estimatedDuration
The estimated duration of the unit, not null.private int
hashCode
The cache of the unit hash code.private java.lang.String
name
The name of the unit, not null.private static long
serialVersionUID
The serialization version.
-
Constructor Summary
Constructors Modifier Constructor Description protected
PeriodUnit(java.lang.String name, PeriodField equivalentPeriod)
Constructor to create a unit that is derived from another smaller unit.(package private)
PeriodUnit(java.lang.String name, PeriodField equivalentPeriod, Duration estimatedDuration)
Constructor used by ISOChronology.protected
PeriodUnit(java.lang.String name, Duration estimatedDuration)
Constructor to create a base unit that cannot be derived.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static java.util.List<PeriodField>
buildEquivalentPeriods(PeriodField equivalentPeriod)
Helper method for constructors to built the equivalent periods.int
compareTo(PeriodUnit other)
Compares this unit to another.boolean
equals(java.lang.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.java.util.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.java.lang.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.java.lang.String
toString()
Returns a string representation of the unit.
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
The serialization version.- See Also:
- Constant Field Values
-
name
private final transient java.lang.String name
The name of the unit, not null.
-
estimatedDuration
private final transient Duration estimatedDuration
The estimated duration of the unit, not null.
-
equivalentPeriods
private final transient java.util.List<PeriodField> equivalentPeriods
The cache of periods equivalent to this unit, not null.
-
hashCode
private final transient int hashCode
The cache of the unit hash code.
-
-
Constructor Detail
-
PeriodUnit
protected PeriodUnit(java.lang.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:
java.lang.IllegalArgumentException
- if the duration is zero or negative
-
PeriodUnit
protected PeriodUnit(java.lang.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:
java.lang.IllegalArgumentException
- if the period is zero or negativejava.lang.ArithmeticException
- if the equivalent period calculation overflows
-
PeriodUnit
PeriodUnit(java.lang.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:
java.lang.ArithmeticException
- if the equivalent period calculation overflows
-
-
Method Detail
-
buildEquivalentPeriods
private static java.util.List<PeriodField> buildEquivalentPeriods(PeriodField equivalentPeriod)
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
public java.lang.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 java.util.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 interfacejava.lang.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:
java.lang.NullPointerException
- if other is null
-
equals
public boolean equals(java.lang.Object obj)
Compares two units based on the name, estimated duration and equivalent period.- Overrides:
equals
in classjava.lang.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 classjava.lang.Object
- Returns:
- a suitable hash code
-
toString
public java.lang.String toString()
Returns a string representation of the unit.The string representation is the same as the name.
- Overrides:
toString
in classjava.lang.Object
- Returns:
- the unit name, never null
-
-