net.time4j.tz.TransitionHistory Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2014 Meno Hochschild, Keeps all offset transitions and rules of a timezone.
*
* @author Meno Hochschild
* @spec All implementations must be immutable, thread-safe and serializable.
*/
/*[deutsch]
* Hält alle Übergänge und Regeln einer Zeitzone.
*
* @author Meno Hochschild
* @spec All implementations must be immutable, thread-safe and serializable.
*/
public interface TransitionHistory {
//~ Methoden ----------------------------------------------------------
/**
* 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 {@code getPreviousOffset()} of
* the first defined transition in history.
*
* @return fixed initial shift
*/
/*[deutsch]
* Ermittelt die initiale Verschiebung unabhängig davon, ob es
* Übergänge gibt oder nicht.
*
* Falls es Übergänge gibt, muß die initiale
* Verschiebung mit der Verschiebung {@code getPreviousOffset()}
* des ersten definierten Übergangs identisch sein.
*
* @return fixed initial shift
*/
ZonalOffset getInitialOffset();
/**
* Queries the last transition which defines the offset
* for given global timestamp.
*
* @param ut unix reference time
* @return {@code ZonalTransition} or {@code null} if given reference time
* is before first defined transition
*/
/*[deutsch]
* Ermittelt den letzten Übergang, der die zur angegebenen
* Referenzzeit zugehörige Verschiebung definiert.
*
* @param ut unix reference time
* @return {@code ZonalTransition} or {@code null} if given reference time
* is before first defined transition
*/
ZonalTransition getStartTransition(UnixTime ut);
/**
* Returns the conflict transition where given local timestamp
* falls either in a gap or in an overlap on the local timeline.
*
* @param localDate local date in timezone
* @param localTime local wall time in timezone
* @return conflict transition on the local time axis for gaps or
* overlaps else {@code null}
* @see #getValidOffsets(GregorianDate,WallTime)
*/
/*[deutsch]
* Bestimmt den passenden Übergang, wenn die angegebene lokale
* Zeit in eine Lücke oder eine Überlappung auf dem lokalen
* Zeitstrahl fällt.
*
* @param localDate local date in timezone
* @param localTime local wall time in timezone
* @return conflict transition on the local time axis for gaps or
* overlaps else {@code null}
* @see #getValidOffsets(GregorianDate,WallTime)
*/
ZonalTransition getConflictTransition(
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 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.
*
* @param localDate local date in timezone
* @param localTime local wall time in timezone
* @return unmodifiable list of shifts which fits the given local time
* @see #getConflictTransition(GregorianDate,WallTime)
*/
/*[deutsch]
* Bestimmt die zur angegebenen lokalen Zeit passenden
* zonalen Verschiebungen.
*
* Die Liste ist leer, wenn die lokale Zeit in eine Lücke auf
* dem lokalen Zeitstrahl fällt. Die Liste hat genau zwei
* Verschiebungen, wenn die lokale Zeit wegen einer Überlappung
* zu zwei verschiedenen Zeitpunkten auf der POSIX-Zeitskala gehört.
* Ansonsten wird die Liste genau eine passende Verschiebung enthalten.
*
* @param localDate local date in timezone
* @param localTime local wall time in timezone
* @return unmodifiable list of shifts which fits the given local time
* @see #getConflictTransition(GregorianDate,WallTime)
*/
List getValidOffsets(
GregorianDate localDate,
WallTime localTime
);
/**
* Return the offset transitions from UNIX epoch [1970-01-01T00:00Z]
* until at maximum the first transition after the current timestamp.
*
* Indeed, a potentially bigger interval is obtainable by
* {@link #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.
*
* @return unmodifiable list of standard transitions (after 1970-01-01)
* maybe empty
*/
/*[deutsch]
* Bestimmt alle vorhandenen zonalen Übergänge ab der
* UNIX-Epoche [1970-01-01T00:00Z] bis maximal zum ersten Übergang
* nach dem aktuellen heutigen Zeitpunkt.
*
* Zwar kann mittels {@link #getTransitions(UnixTime,UnixTime)}
* auch ein potentiell größeres Intervall abgefragt werden,
* jedoch sind frühere oder spätere Zeitpunkte in aller Regel
* mit großen Unsicherheiten verknüpft. Zum Beispiel ist die
* weithin verwendete IANA/Olson-Zeitzonendatenbank nur für Zeiten
* ab der UNIX-Epoche gedacht und bietet ausgewählte ältere
* Zeitzonendaten lediglich nach bestem Wissen und Gewissen an. Anwender
* müssen beachten, daß sich sogar historische alte Daten
* nachträglich ändern können. Generell existiert das
* Zeitzonenkonzept erst ab ca. dem 19. Jahrhundert. Und in der Zukunft
* liegende Zeitzonenänderungen sind wegen politischer Willkür
* sogar noch unsicherer.
*
* @return unmodifiable list of standard transitions (after 1970-01-01)
* maybe empty
*/
List getStdTransitions();
/**
* Returns the previous transitions in descending order if available.
*
* In general, this method will only yield transitions in the interval
* from [1970-01-01T00:00Z] until at maximum the first transition before
* the current timestamp (in descending order on the timeline!).
*
* @param ut unix reference time
* @return previous transitions before reference time
* (only standard transitions after 1970-01-01)
* @see #getStdTransitions()
*/
/*[deutsch]
* Ermittelt die vorherigen Übergänge in zeitlich absteigender
* Reihenfolge, falls vorhanden.
*
* Grundsätzlich liefert die Methode nur Übergänge
* im Intervall von [1970-01-01T00:00Z] bis maximal zum ersten
* Übergang vor dem aktuellen Zeitpunkt (in zeitlich umgekehrter
* Reihenfolge!).
*
* @param ut unix reference time
* @return previous transitions before reference time
* (only standard transitions after 1970-01-01)
* @see #getStdTransitions()
*/
List getStdTransitionsBefore(UnixTime ut);
/**
* Returns the next transitions in ascending order if available.
*
* In general, this method will only yield transitions in the interval
* from [1970-01-01T00:00Z] until at maximum the first transition before
* the current timestamp.
*
* @param ut unix reference time
* @return next transitions after reference time (only standard
* transitions 1970-01-01)
* @see #getStdTransitions()
*/
/*[deutsch]
* Ermittelt die nächsten Übergänge in zeitlich
* aufsteigender Reihenfolge, falls vorhanden.
*
* Grundsätzlich liefert die Methode nur Übergänge im
* Intervall von [1970-01-01T00:00Z] bis maximal zum ersten Übergang
* nach dem aktuellen Zeitpunkt.
*
* @param ut unix reference time
* @return next transitions after reference time (only standard
* transitions 1970-01-01)
* @see #getStdTransitions()
*/
List getStdTransitionsAfter(UnixTime ut);
/**
* Returns the defined transitions in given POSIX-interval.
*
* @param startInclusive start time on POSIX time scale
* @param endExclusive end time on POSIX time scale
* @return unmodifiable list of transitions maybe empty
* @see #getStdTransitions()
*/
/*[deutsch]
* Bestimmt die im angegebenen POSIX-Intervall vorhandenen zonalen
* Übergänge.
*
* @param startInclusive start time on POSIX time scale
* @param endExclusive end time on POSIX time scale
* @return unmodifiable list of transitions maybe empty
* @see #getStdTransitions()
*/
List getTransitions(
UnixTime startInclusive,
UnixTime endExclusive
);
/**
* Determines if this history does not have any transitions.
*
* @return {@code true} if there are no transitions else {@code false}
* @since 1.2.1
*/
/*[deutsch]
* Ermittelt ob diese Historie keine Übergänge kennt.
*
* @return {@code true} if there are no transitions else {@code false}
* @since 1.2.1
*/
boolean isEmpty();
}