Class TimePoint<U,T extends TimePoint<U,T>>
 Type Parameters:
U
 generic type of time units compatible toChronoUnit
T
 generic type of self reference
 All Implemented Interfaces:
Serializable
,Comparable<T>
,ChronoDisplay
 Direct Known Subclasses:
Calendrical
,EthiopianTime
,HebrewTime
,Moment
,PlainTime
,PlainTimestamp
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):
 [20110831] + [P1M] = [20110930]
 [20110930] + [P1M] = [20111030]
 [20110831] + [P2M] = [20111031]
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 only for a time point which even has nanoseconds.
 The natural order should be consistent with
equals()
.
 Author:
 Meno Hochschild
 See Also:
Chronology
,TimeAxis
,Temporal

Constructor Summary

Method Summary
Modifier and TypeMethodDescriptionabstract int
Compares two time points preferably by their temporal positions on the common time axis.abstract boolean
Compares the whole state of this instance with given object.abstract int
hashCode()
Subclasses must redefine this method corresponding to the behaviour ofequals()
.static <U, T extends TimePoint<U, T>>
Tmax(T t1, T t2)
Determines the maximum of both time points.static <U, T extends TimePoint<U, T>>
Tmin(T t1, T t2)
Determines the minimum of both time points.Subtracts given amount in units from this time point and yields the result of subtraction.Subtracts given time span from this time point and yields the result of subtraction.Adds given amount in units to this time point and yields the result of addition.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
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, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

Constructor Details

TimePoint
public TimePoint()


Method Details

compareTo
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 interfaceComparable<U>
 See Also:
equals(Object)

plus
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 implementBasicUnit
to yield a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflow See Also:
minus(TimeSpan)

minus
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 implementBasicUnit
to yield a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflow See Also:
plus(TimeSpan)

plus
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: [20110531].plus(1, <MONTHS>) = [20110630]
 [20110531].plus(4, <DAYS>) = [20110604]
 [20110604].plus(4, <DAYS>) = [20110531]
 [20100429].plus(397, <DAYS>) = [20110531]
 [20100429].plus(13, <MONTHS>) = [20110529]
 [20100429].plus(2, <MONTHS>) = [20100228]
 [20100429].plus(1, <YEARS>) = [20110429]
 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 given time unit is not registered and does also not implementBasicUnit
to yield a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflow See Also:
plus(TimeSpan)

minus
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 given time unit is not registered and does also not implementBasicUnit
to yield a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflow See Also:
plus(long, U)

until
Calculates the (most normalized) time span between this time point and given end time point using the given metric.
 Type Parameters:
P
 generic type of time span result Parameters:
end
 end time pointmetric
 temporal distance metric Returns:
 difference between this and given end time point expressed as time span
 Throws:
ArithmeticException
 in case of numerical overflow

until
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: [20110531].until([20110604], <MONTHS>) = 0
 [20110531].until([20110604], <DAYS>) = 4
 [20110604].until([20110531], <DAYS>) = 4
 [20100429].until([20110531], <DAYS>) = 397
 [20100429].until([20110531], <MONTHS>) = 13
 [20100429].until([20110531], <YEARS>) = 1
 [20100531].until([20110531], <YEARS>) = 1
 [20100601].until([20110531], <YEARS>) = 0
 Parameters:
end
 end time pointunit
 time unit Returns:
 difference between this and given end time point as count of given time unit
 Throws:
RuleNotFoundException
 if given time unit is not registered and does also not implementBasicUnit
to yield a suitable unit rule for the underlying time axisArithmeticException
 in case of numerical overflow See Also:
until(TimePoint, TimeMetric)

min
Determines the minimum of both time points.
 Type Parameters:
U
 generic type of time units compatible toChronoUnit
T
 generic type of self reference Parameters:
t1
 first time pointt2
 second time point Returns:
 minimum of t1 and t2

max
Determines the maximum of both time points.
 Type Parameters:
U
 generic type of time units compatible toChronoUnit
T
 generic type of self reference Parameters:
t1
 first time pointt2
 second time point Returns:
 maximum of t1 and t2

equals
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 classObject
 See Also:
compareTo(TimePoint)

hashCode
public abstract int hashCode()Subclasses must redefine this method corresponding to the behaviour of
equals()
. 
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).
