Package net.time4j.engine

Class TimeAxis<U,T extends TimePoint<U,T>>

java.lang.Object

net.time4j.engine.Chronology<T>

net.time4j.engine.TimeAxis<U,T>

Type Parameters:

U - generic type of time units

T - generic type of time context compatible to TimePoint

All Implemented Interfaces:

Comparator<T>, ChronoMerger<T>, TimeLine<T>

public final class TimeAxis<U,T extends TimePoint<U,T>>
extends Chronology<T>
implements TimeLine<T>

A time axis is a dynamic view on a chronology where a system of registered time units is used to define a time arithmetic for any time points belonging to this time axis respective chronology.

Author:

Meno Hochschild

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TimeAxis.Builder<U,T extends TimePoint<U,T>>	Creates a builder for a new time axis respective chronology and will only be used during loading a class of type TimePoint (T) in a static initializer.

Method Summary

Modifier and Type	Method	Description
int	compare(T first, T second)	Compares points in time by their temporal position on the timeline.
T	createFrom(ChronoEntity<?> entity, AttributeQuery attributes, boolean lenient, boolean preparsing)	Creates a new entity of type T based on given chronological data.
ChronoElement<T>	element()	Yields this time axis as chronological self-referencing element.
U	getBaseUnit(ChronoElement<?> element)	Returns the base unit of given element if available.
CalendarSystem<T>	getCalendarSystem()	Returns the associated calendar system if available.
CalendarSystem<T>	getCalendarSystem(String variant)	Returns the calendar system for given calendar variant if available.
double	getLength(U unit)	Returns the length of given time unit in seconds as it is usual or estimated on this time axis.
T	getMaximum()	Yields the maximum of this time axis.
T	getMinimum()	Yields the minimum of this time axis.
Set<U>	getRegisteredUnits()	Returns all registered time units.
Class<U>	getUnitType()	Returns the type of supported time units.
boolean	hasBaseUnit(ChronoElement<?> element)	Queries if given element has a base unit.
boolean	hasCalendarSystem()	Queries if this chronology has a calendar system.
boolean	isCalendrical()	Determines if this timeline is calendrical or not.
boolean	isConvertible(U unit1, U unit2)	Queries if given time units are convertible.
boolean	isRegistered(U unit)	Queries if given time unit is registered.
boolean	isSupported(U unit)	Queries if given time unit is supported.
T	stepBackwards(T timepoint)	Move given point in time backwards by one step.
T	stepForward(T timepoint)	Move given point in time forward by one step.
Comparator<? super U>	unitComparator()	Compares time units by ascending precision (that is descending length).

Methods inherited from class net.time4j.engine.Chronology

createFrom, getCalendarSystem, getChronoType, getDefaultPivotYear, getDefaultStartOfDay, getExtensions, getFormatPattern, getRegisteredElements, isRegistered, isSupported, lookup, preformat, preparser

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.time4j.engine.ChronoMerger

getFormatPattern

Methods inherited from interface java.util.Comparator

equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Method Details

getUnitType

public Class<U> getUnitType()

Returns the type of supported time units.

Returns:

reified type of time unit

getRegisteredUnits

public Set<U> getRegisteredUnits()

Returns all registered time units.

Returns:

unmodifiable set of registered units without duplicates

isRegistered

public boolean isRegistered(U unit)

Queries if given time unit is registered.

Parameters:

unit - time unit (optional)

Returns:

true if registered else false

isSupported

public boolean isSupported(U unit)

Queries if given time unit is supported.

A time unit is supported if it is either registered or if it defines a suitable rule.

Parameters:

unit - time unit (optional)

Returns:

true if supported else false

See Also:

BasicUnit.derive(Chronology)

getLength

public double getLength(U unit)

Returns the length of given time unit in seconds as it is usual or estimated on this time axis.

Example: In ISO-systems the year has 365.2425 * 86400 seconds by default (mean average), in a julian calender 365.25 * 86400 seconds however. Daylight-saving-transitions or UTC-leapseconds are not counted here.

Note: If given time unit is not registered then Time4J tries to interprete the unit as ChronoUnit. If this fails, too, then the length is not calculatable.

Parameters:

unit - time unit

Returns:

estimated standard length in seconds or Double.NaN if not calculatable

See Also:

ChronoUnit

isConvertible

public boolean isConvertible(U unit1,
 U unit2)

Queries if given time units are convertible.

Convertibility means that there exists a fixed integer factor for conversion between the units. Examples for convertible units are weeks/days (factor 7) or years/months (factor 12) in ISO-systems. Otherwise minutes and seconds will only be convertible with factor 60 if there is no UTC-context with possible leap seconds.

If two time units are convertible then the length of a time unit (getLength()) can be used to convert time units by applying the rounded quotient of lengths of units.

Parameters:

unit1 - first time unit

unit2 - second time unit

Returns:

true if convertible else false

See Also:

getLength(U)

hasBaseUnit

public boolean hasBaseUnit(ChronoElement<?> element)

Queries if given element has a base unit.

Parameters:

element - chronological element (optional)

Returns:

true if given element has a base unit else false

See Also:

getBaseUnit(ChronoElement)

getBaseUnit

public U getBaseUnit(ChronoElement<?> element)

Returns the base unit of given element if available.

Only registred elements can have a base unit unless the element is a BasicElement and refers another registered element with a base unit.

Parameters:

element - chronological element

Returns:

found base unit

Throws:

ChronoException - if there is no base unit

See Also:

hasBaseUnit(ChronoElement), BasicElement.getParent()

unitComparator

public Comparator<? super U> unitComparator()

Compares time units by ascending precision (that is descending length).

Note: Before release v4.21, the time axis implemented Comparator<U>, not Comparator<T>. This new method serves as the replacement for the old comparator method.

Returns:

Comparator

Since:

3.25/4.21

See Also:

compare(TimePoint, TimePoint)

compare

public int compare(T first,
 T second)

Compares points in time by their temporal position on the timeline.

Specified by:

compare in interface Comparator<U>

Parameters:

first - the first point in comparison

second - the second point in comparison

Returns:

positive, zero or negative number if first is later, simultaneous or earlier than second

Since:

3.25/4.21

getMinimum

public T getMinimum()

Yields the minimum of this time axis.

Specified by:

getMinimum in interface TimeLine<U>

Returns:

earliest possible time point

getMaximum

public T getMaximum()

Yields the maximum of this time axis.

Specified by:

getMaximum in interface TimeLine<U>

Returns:

latest possible time point

isCalendrical

public boolean isCalendrical()

Description copied from interface: TimeLine

Determines if this timeline is calendrical or not.

Specified by:

isCalendrical in interface TimeLine<U>

Returns:

boolean

See Also:

CalendarDate

hasCalendarSystem

public boolean hasCalendarSystem()

Description copied from class: Chronology

Queries if this chronology has a calendar system.

Overrides:

hasCalendarSystem in class Chronology<T extends TimePoint<U,T>>

Returns:

true if this chronology has a calendar system else false

See Also:

Chronology.getCalendarSystem()

getCalendarSystem

public CalendarSystem<T> getCalendarSystem()

Description copied from class: Chronology

Returns the associated calendar system if available.

Overrides:

getCalendarSystem in class Chronology<T extends TimePoint<U,T>>

Returns:

calendar system, not null

See Also:

Chronology.hasCalendarSystem()

getCalendarSystem

public CalendarSystem<T> getCalendarSystem(String variant)

Description copied from class: Chronology

Returns the calendar system for given calendar variant if available.

Overrides:

getCalendarSystem in class Chronology<T extends TimePoint<U,T>>

Parameters:

variant - name of calendar variant

Returns:

calendar system, not null

See Also:

VariantSource.getVariant()

createFrom

public T createFrom(ChronoEntity<?> entity,
 AttributeQuery attributes,
 boolean lenient,
 boolean preparsing)

Description copied from interface: ChronoMerger

Creates a new entity of type T based on given chronological data.

Typically the method will query the given entity with different priorities for elements which can compose a new chronological entity (per group). For example a calendar date can be composed either by epoch days or the group (year)-(month)-(day-of-month) or the group (year)-(day-of-year) etc.

A text parser will call this method after having resolved a text into single chronological elements and values. Implementations should always validate the parsed values. In case of error, they are free to either throw an IllegalArgumentException or to generate and to save an error message by mean of the expression entity.with(ValidationElement.ERROR_MESSAGE, message.

Specified by:

createFrom in interface ChronoMerger<U>

Overrides:

createFrom in class Chronology<T extends TimePoint<U,T>>

Parameters:

entity - any chronological entity like parsed elements with their values

attributes - configuration attributes given by parser

lenient - controls the leniency how to interprete invalid values

preparsing - preparsing phase active?

Returns:

new time context or null if given data are insufficient

See Also:

ValidationElement.ERROR_MESSAGE

element

public ChronoElement<T> element()

Yields this time axis as chronological self-referencing element.

Returns:

self-referencing element

stepForward

public T stepForward(T timepoint)

Description copied from interface: TimeLine

Move given point in time forward by one step.

Specified by:

stepForward in interface TimeLine<U>

Parameters:

timepoint - point in time to be moved forward

Returns:

new point in time one step after given argument or null if applied on the maximum of timeline

stepBackwards

public T stepBackwards(T timepoint)

Description copied from interface: TimeLine

Move given point in time backwards by one step.

Specified by:

stepBackwards in interface TimeLine<U>

Parameters:

timepoint - point in time to be moved backwards

Returns:

new point in time one step before given argument or null if applied on the minimum of timeline