net.time4j.engine

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

java.lang.Object

net.time4j.engine.ChronoEntity<T>

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

Type Parameters:

U - generic type of time units compatible to ChronoUnit

T - generic type of self reference

All Implemented Interfaces:

Serializable, Comparable<T>

Direct Known Subclasses:

Calendrical, Moment, PlainTime, PlainTimestamp

public 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 UTC-timeline (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 UT1-seconds on a local timestamp but on a UniversalTime before 1972 as global UT1-seconds and after 1972 as atomic SI-seconds. 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.

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 (pseudo-code):

• [2011-08-31] + [P1M] = [2011-09-30]
• [2011-09-30] + [P1M] = [2011-10-30]
• [2011-08-31] + [P2M] = [2011-10-31]

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

• All subclasses must be final und immutable.
• Documentation of supported and registered elements is required.
• For a suitable choice of the type U of time units it should be noted that the time units must correspond to the internal state of a time point because otherwise the calculation of a time span between two time points cannot be complete. For example it would be a mistake to allow milliseconds for a time point which even has nanoseconds.
• The natural order should be consistent with equals().

Author:

Meno Hochschild

See Also:

Chronology, TimeAxis, Temporal, Serialized Form

Constructor Summary

Constructors

Constructor and Description
TimePoint()

Method Summary

Methods

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>> T	max(T t1, T t2) Determines the maximum of both time points.
static <U,T extends TimePoint<U,T>> 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.

Methods inherited from class net.time4j.engine.ChronoEntity

contains, get, get, getMaximum, getMinimum, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TimePoint

public TimePoint()

Method Detail

compareTo

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.

Specified by:

compareTo in interface Comparable<T extends TimePoint<U,T>>

See Also:

equals(Object)

plus

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).

Parameters:

timeSpan - time span to be added to this instance

Returns:

result of addition as changed copy, this instance remains unaffected

Throws:

RuleNotFoundException - if any time unit is not registered and does also not implement UnitRule.Source

ArithmeticException - in case of numerical overflow

See Also:

minus(TimeSpan)

minus

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).

Parameters:

timeSpan - time span to be subtracted from this instance

Returns:

result of subtraction as changed copy, this instance remains unaffected

Throws:

RuleNotFoundException - if any time unit is not registered and does also not implement UnitRule.Source

ArithmeticException - in case of numerical overflow

See Also:

plus(TimeSpan)

plus

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 pseudo-code:

• [2011-05-31].plus(1, <MONTHS>) = [2011-06-30]
• [2011-05-31].plus(4, <DAYS>) = [2011-06-04]
• [2011-06-04].plus(-4, <DAYS>) = [2011-05-31]
• [2010-04-29].plus(397, <DAYS>) = [2011-05-31]
• [2010-04-29].plus(13, <MONTHS>) = [2011-05-29]
• [2010-04-29].plus(-2, <MONTHS>) = [2010-02-28]
• [2010-04-29].plus(1, <YEARS>) = [2011-04-29]

Parameters:

amount - amount to be added (maybe negative)

unit - time unit

Returns:

result of addition as changed copy, this instance remains unaffected

Throws:

RuleNotFoundException - if the time unit is not registered and does also not implement UnitRule.Source

ArithmeticException - in case of numerical overflow

See Also:

plus(TimeSpan)

minus

public T minus(long amount,
      U unit)

Subtracts given amount in units from this time point and yields the result of subtraction.

Parameters:

amount - amount to be subtracted (maybe negative)

unit - time unit

Returns:

result of subtraction as changed copy, this instance remains unaffected

Throws:

RuleNotFoundException - if the time unit is not registered and does also not implement UnitRule.Source

ArithmeticException - in case of numerical overflow

See Also:

plus(long, U)

until

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.

Parameters:

end - end time point

metric - temporal distance metric

Returns:

difference between this and given end time point expressed as time span

Throws:

ArithmeticException - in case of numerical overflow

until

public 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 long-primitive. 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 pseudo-code:

• [2011-05-31].until([2011-06-04], <MONTHS>) = 0
• [2011-05-31].until([2011-06-04], <DAYS>) = 4
• [2011-06-04].until([2011-05-31], <DAYS>) = -4
• [2010-04-29].until([2011-05-31], <DAYS>) = 397
• [2010-04-29].until([2011-05-31], <MONTHS>) = 13
• [2010-04-29].until([2011-05-31], <YEARS>) = 1
• [2010-05-31].until([2011-05-31], <YEARS>) = 1
• [2010-06-01].until([2011-05-31], <YEARS>) = 0

Parameters:

end - end time point

unit - time unit

Returns:

difference between this and given end time point as count of given time unit

Throws:

RuleNotFoundException - if the time unit is not registered and does also not implement UnitRule.Source

ArithmeticException - in case of numerical overflow

See Also:

until(TimePoint, TimeMetric)

min

public static <U,T extends TimePoint<U,T>> T min(T t1,
                                 T t2)

Determines the minimum of both time points.

Type Parameters:

U - generic type of time units compatible to ChronoUnit

T - generic type of self reference

Parameters:

t1 - first time point

t2 - second time point

Returns:

minimum of t1 and t2

max

public static <U,T extends TimePoint<U,T>> T max(T t1,
                                 T t2)

Determines the maximum of both time points.

Type Parameters:

U - generic type of time units compatible to ChronoUnit

T - generic type of self reference

Parameters:

t1 - first time point

t2 - second time point

Returns:

maximum of t1 and t2

equals

public 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.

Overrides:

equals in class Object

See Also:

compareTo(TimePoint)

hashCode

public abstract int hashCode()

Subclasses must redefine this method corresponding to the behaviour of equals().

Overrides:

hashCode in class Object

toString

public abstract String toString()

Provides a complete textual representation of the state of this time point.

The textual description often follows the conventions of ISO-8601. Usually the description starts with the chronological informations which are coarse-grained and ends with those ones which are faine-grained (for example the ISO-notation YYYY-MM-DD).

Overrides:

toString in class Object