net.time4j.tz

Interface TransitionHistory

public interface TransitionHistory

Keeps all offset transitions and rules of a timezone.

Note: This interface can be considered as stable since version v2.2. Preliminary experimental versions of this interface existed since v1.0 but there was originally not any useable implementation.

Author:

Meno Hochschild

Specification:

All implementations must be immutable, thread-safe and serializable.

Method Summary

Modifier and Type	Method and Description
void	dump(Appendable buffer) Creates a dump of this history and writes it to the given buffer.
default Optional<ZonalTransition>	findConflictTransition(GregorianDate localDate, WallTime localTime) Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.
default Optional<ZonalTransition>	findNextTransition(UnixTime ut) Queries the next transition after given global timestamp.
default Optional<ZonalTransition>	findPreviousTransition(UnixTime ut) Queries the previous transition which defines the offset for a global timestamp immediately before given reference timestamp.
default Optional<ZonalTransition>	findStartTransition(UnixTime ut) Queries the last transition which defines the offset for given global timestamp.
ZonalTransition	getConflictTransition(GregorianDate localDate, WallTime localTime) Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.
ZonalOffset	getInitialOffset() Return the initial offset no matter if there are any transitions defined or not.
ZonalTransition	getNextTransition(UnixTime ut) Deprecated. Use the equivalent findNextTransition(UnixTime)
ZonalTransition	getStartTransition(UnixTime ut) Queries the last transition which defines the offset for given global timestamp.
List<ZonalTransition>	getStdTransitions() Return the offset transitions from UNIX epoch [1970-01-01T00:00Z] until about one year after the current timestamp.
List<ZonalTransition>	getTransitions(UnixTime startInclusive, UnixTime endExclusive) Returns the defined transitions in given POSIX-interval.
List<ZonalOffset>	getValidOffsets(GregorianDate localDate, WallTime localTime) Determines the suitable offsets at given local timestamp..
boolean	isEmpty() Determines if this history does not have any transitions.

Method Detail

getInitialOffset

ZonalOffset getInitialOffset()

Return the initial offset no matter if there are any transitions defined or not.

If any transition is defined then the initial offset is identical to the shift getPreviousOffset() of the first defined transition in history.

Returns:

fixed initial shift in full seconds

getStartTransition

ZonalTransition getStartTransition(UnixTime ut)

Queries the last transition which defines the offset for given global timestamp.

For standard use cases, users can use the alternative method findStartTransition() unless performance considerations prohibit the usage of class Optional.

Parameters:

ut - unix reference time

Returns:

ZonalTransition or null if given reference time is before first defined transition

See Also:

findStartTransition(UnixTime)

getConflictTransition

ZonalTransition getConflictTransition(GregorianDate localDate,
                                      WallTime localTime)

Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.

Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

For standard use cases, users can use the alternative method findConflictTransition() unless performance considerations prohibit the usage of class Optional.

Parameters:

localDate - local date in timezone

localTime - local wall time in timezone

Returns:

conflict transition on the local time axis for gaps or overlaps else null

See Also:

getValidOffsets(GregorianDate,WallTime), findConflictTransition(GregorianDate, WallTime)

getNextTransition

@Deprecated
ZonalTransition getNextTransition(UnixTime ut)

Deprecated. Use the equivalent findNextTransition(UnixTime)

Queries the next transition after given global timestamp.

Parameters:

ut - unix reference time

Returns:

ZonalTransition or null if given reference time is after any defined transition

getValidOffsets

List<ZonalOffset> getValidOffsets(GregorianDate localDate,
                                  WallTime localTime)

Determines the suitable offsets at given local timestamp..

The offset list is empty if the local timestamp falls in a gap on the local timeline. The list has exactly two offsets sorted by size if the local timestamp belongs to two different timepoints on the POSIX timescale due to an overlap. Otherwise the offset list will contain exactly one suitable offset.

Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

Parameters:

localDate - local date in timezone

localTime - local wall time in timezone

Returns:

unmodifiable list of shifts in full seconds which fits the given local time

See Also:

findConflictTransition(GregorianDate,WallTime)

getStdTransitions

List<ZonalTransition> getStdTransitions()

Return the offset transitions from UNIX epoch [1970-01-01T00:00Z] until about one year after the current timestamp.

Indeed, a potentially bigger interval is obtainable by getTransitions(UnixTime,UnixTime), but earlier or later timepoints are usually not reliable. For example the wide-spread IANA/Olson-repository is only designed for times since UNIX epoch and offers some selected older data to the best of our knowledge. Users must be aware that even older data can be changed as side effect of data corrections. Generally the timezone concept was invented in 19th century. And future transitions are even less reliable due to political arbitrariness.

Returns:

unmodifiable list of standard transitions (after 1970-01-01) maybe empty

getTransitions

List<ZonalTransition> getTransitions(UnixTime startInclusive,
                                     UnixTime endExclusive)

Returns the defined transitions in given POSIX-interval.

Parameters:

startInclusive - start time on POSIX time scale

endExclusive - end time on POSIX time scale

Returns:

unmodifiable list of transitions maybe empty

Throws:

IllegalArgumentException - if start is after end

See Also:

getStdTransitions()

isEmpty

boolean isEmpty()

Determines if this history does not have any transitions.

Returns:

true if there are no transitions else false

dump

void dump(Appendable buffer)
   throws IOException

Creates a dump of this history and writes it to the given buffer.

Parameters:

buffer - buffer to write the dump to

Throws:

IOException - in any case of I/O-errors

findStartTransition

default Optional<ZonalTransition> findStartTransition(UnixTime ut)

Queries the last transition which defines the offset for given global timestamp.

Parameters:

ut - unix reference time

Returns:

ZonalTransition, not present if given reference time is before first defined transition

Since:

4.18

findConflictTransition

default Optional<ZonalTransition> findConflictTransition(GregorianDate localDate,
                                                         WallTime localTime)

Returns the conflict transition where given local timestamp falls either in a gap or in an overlap on the local timeline.

Note that only the expression localDate.getYear() is used to determine the daylight saving rules to be applied in calculation. This is particularly important if there is a wall time of 24:00. Here only the date before merging to next day matters, not the date of the whole timestamp.

Parameters:

localDate - local date in timezone

localTime - local wall time in timezone

Returns:

optional conflict transition on the local time axis for gaps or overlaps if present

Since:

4.18

See Also:

getValidOffsets(GregorianDate,WallTime)

findNextTransition

default Optional<ZonalTransition> findNextTransition(UnixTime ut)

Queries the next transition after given global timestamp.

Parameters:

ut - unix reference time

Returns:

ZonalTransition, not present if given reference time is after any defined transition

Since:

4.18

findPreviousTransition

default Optional<ZonalTransition> findPreviousTransition(UnixTime ut)

Queries the previous transition which defines the offset for a global timestamp immediately before given reference timestamp.

Parameters:

ut - unix reference time

Returns:

ZonalTransition, not present if given reference time is not after any defined transition

Since:

4.18