U
 generic type of time units compatible to ChronoUnit
T
 generic type of self referencepublic abstract class TimePoint<U,T extends TimePoint<U,T>> extends ChronoEntity<T> implements Comparable<T>, Serializable
Represents an immutable time point along a time axis which is directed into the future.
Display and change chronological element values
The time point consists of chronological elements. This base class
delegates the time arithmetic to the associated time axis respective to
the underlying rules of elements and units. However, any concrete subclass
is required to define the state and reflect it in all get()
methods
and also to specify the serialization behaviour.
Element values can only be changed by creating a new immutable copy
of the original instance. This is done via all with()
methods.
Time axis
If the referenced time axis is the UTCtimeline (that is a time point
is defined relative to the start of UTC epoch  see
package summary) then any implementation
must also implement the interface UniversalTime
.
In every other case we have a local time axis. All time units are to be
defined referencing the time axis. For example, second units are interpreted
as local UT1seconds on a local timestamp but on a UniversalTime
before 1972 as global UT1seconds and after 1972 as atomic SIseconds.
Hence Time4J has even defined different second units in the main package.
Applications should therefore take much care if they transform a duration
from one time axis to another one.
Sorting
Unless explicitly stated otherwise sorting of time points is always
in strict temporal order and consistent with equals()
. In case
of doubt the documentation of the subclass is leading. Alternatively,
subclasses are free to implement the interface Temporal
to
enable a temporal order. A pure temporal state of any implementation
is strongly recommended.
Addition (or subtraction) of a time span to a time point
These operations are performed by all plus()
 and minus()

methods. A time span can either be a single time unit, or it consists of
several time units.
If given time unit does not have a fixed length (for example months) then the result of an addition can deviate from the expected element value to be considered. In case of multiple additions care is required. In case of doubt the original value should be saved for a later addition. Example with additions of months in one or two steps (pseudocode):
Difference of time points
The difference of time points results in a time span. The result can either be expressed in one time unit only, or in multiple units which represent the base unit of associated chronological element. In latter case users have to define a metric, too.
Implementation notes
equals()
. Chronology
,
TimeAxis
,
Temporal
Constructor and Description 

TimePoint() 
Modifier and Type  Method and Description 

abstract int 
compareTo(T timePoint)
Compares two time points preferably by their temporal positions
on the common time axis.

abstract boolean 
equals(Object obj)
Compares the whole state of this instance with given object.

abstract int 
hashCode()
Subclasses must redefine this method corresponding to the
behaviour of
equals() . 
static <U,T extends TimePoint<U,T>> 
max(T t1,
T t2)
Determines the maximum of both time points.

static <U,T extends TimePoint<U,T>> 
min(T t1,
T t2)
Determines the minimum of both time points.

T 
minus(long amount,
U unit)
Subtracts given amount in units from this time point and
yields the result of subtraction.

T 
minus(TimeSpan<? extends U> timeSpan)
Subtracts given time span from this time point and yields
the result of subtraction.

T 
plus(long amount,
U unit)
Adds given amount in units to this time point and yields the
result of addition.

T 
plus(TimeSpan<? extends U> timeSpan)
Adds the given time span to this time point and yields
the result of the addition.

abstract String 
toString()
Provides a complete textual representation of the state of
this time point.

<P> P 
until(T end,
TimeMetric<? extends U,P> metric)
Calculates the (most normalized) time span between this time point
and given end time point using the given metric.

long 
until(T end,
U unit)
Calculates the temporal distance between this time point and
given end time point in only one time unit.

contains, get, get, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with
public abstract int compareTo(T timePoint)
Compares two time points preferably by their temporal positions on the common time axis.
Implementation note: In order to make the natural order consistent
with equals()
the whole state must be taken into account,
with preference for those attributes which define the temporal
position on the time axis.
compareTo
in interface Comparable<T extends TimePoint<U,T>>
equals(Object)
public T plus(TimeSpan<? extends U> timeSpan)
Adds the given time span to this time point and yields the result of the addition.
Delegates to TimeSpan.addTo(TimePoint)
.
timeSpan
 time span to be added to this instanceRuleNotFoundException
 if any time unit is not registered
and does also not implement BasicUnit
to yield
a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflowminus(TimeSpan)
public T minus(TimeSpan<? extends U> timeSpan)
Subtracts given time span from this time point and yields the result of subtraction.
Delegiert an TimeSpan.subtractFrom(TimePoint)
.
timeSpan
 time span to be subtracted from this instanceRuleNotFoundException
 if any time unit is not registered
and does also not implement BasicUnit
to yield
a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflowplus(TimeSpan)
public T plus(long amount, U unit)
Adds given amount in units to this time point and yields the result of addition.
Similar to plus(TimeSpan)
but with the difference
that the timespan is only given in one single time unit. Example
in pseudocode:
amount
 amount to be added (maybe negative)unit
 time unitRuleNotFoundException
 if given time unit is not registered
and does also not implement BasicUnit
to yield
a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflowplus(TimeSpan)
public T minus(long amount, U unit)
Subtracts given amount in units from this time point and yields the result of subtraction.
amount
 amount to be subtracted (maybe negative)unit
 time unitRuleNotFoundException
 if given time unit is not registered
and does also not implement BasicUnit
to yield
a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflowplus(long, U)
public <P> P until(T end, TimeMetric<? extends U,P> metric)
Calculates the (most normalized) time span between this time point and given end time point using the given metric.
P
 generic type of time span resultend
 end time pointmetric
 temporal distance metricArithmeticException
 in case of numerical overflowpublic long until(T end, U unit)
Calculates the temporal distance between this time point and given end time point in only one time unit.
Similar to until(TimePoint, TimeMetric)
but with the
difference that the time span is onyl calculated in one time unit
as longprimitive. In many cases a remainder of subtraction will
be left if given unit is not the smallest possible unit. Time points
whose element values differ less than one base unit will be
considered as equal. Examples in pseudocode:
end
 end time pointunit
 time unitRuleNotFoundException
 if given time unit is not registered
and does also not implement BasicUnit
to yield
a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflowuntil(TimePoint, TimeMetric)
public static <U,T extends TimePoint<U,T>> T min(T t1, T t2)
Determines the minimum of both time points.
U
 generic type of time units compatible to ChronoUnit
T
 generic type of self referencet1
 first time pointt2
 second time pointpublic static <U,T extends TimePoint<U,T>> T max(T t1, T t2)
Determines the maximum of both time points.
U
 generic type of time units compatible to ChronoUnit
T
 generic type of self referencet1
 first time pointt2
 second time pointpublic abstract boolean equals(Object obj)
Compares the whole state of this instance with given object.
Implementations will usually define their state only based on the temporal position on the time axis because this is the most intuitive approach. Exceptions from this rule should be explicitly documented and reasoned.
equals
in class Object
compareTo(TimePoint)
public abstract int hashCode()
Subclasses must redefine this method corresponding to the
behaviour of equals()
.
public abstract String toString()
Provides a complete textual representation of the state of this time point.
The textual description often follows the conventions of ISO8601. Usually the description starts with the chronological informations which are coarsegrained and ends with those ones which are finegrained (for example the ISOnotation YYYYMMDD).
Copyright © 2014–2020. All rights reserved.