net.time4j.tz.ZoneProvider Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2014 Meno Hochschild, SPI interface which encapsulates the timezone repository and
* provides all necessary data for a given timezone id.
*
* Implementations are usually stateless and should normally not
* try to manage a cache. Instead Time4J uses its own cache. The
* fact that this interface is used per {@code java.util.ServiceLoader}
* requires a concrete implementation to offer a public no-arg
* constructor.
*
* @author Meno Hochschild
* @since 2.0
* @see java.util.ServiceLoader
*/
/*[deutsch]
* SPI-Interface, das eine Zeitzonendatenbank kapselt und passend zu
* einer Zeitzonen-ID (hier als String statt als {@code TZID}) die
* Zeitzonendaten liefert.
*
* Implementierungen sind in der Regel zustandslos und halten keinen
* Cache. Letzterer sollte normalerweise der Klasse {@code Timezone}
* vorbehalten sein. Weil dieses Interface mittels eines
* {@code java.util.ServiceLoader} genutzt wird, muß eine
* konkrete Implementierung einen öffentlichen Konstruktor ohne
* Argumente definieren.
*
* @author Meno Hochschild
* @since 2.0
* @see java.util.ServiceLoader
*/
public interface ZoneProvider {
//~ Methoden ----------------------------------------------------------
/**
* Gets all available and supported timezone identifiers.
*
* @return unmodifiable set of timezone ids
* @see java.util.TimeZone#getAvailableIDs()
*/
/*[deutsch]
* Liefert alle verfügbaren Zeitzonenkennungen.
*
* @return unmodifiable set of timezone ids
* @see java.util.TimeZone#getAvailableIDs()
*/
Set getAvailableIDs();
/**
* Gets an alias table whose keys represent alternative identifiers
* mapped to other aliases or finally canonical timezone IDs..
*
* Example: "PST" => "America/Los_Angeles".
*
* @return map from all timezone aliases to canoncial ids
*/
/*[deutsch]
* Liefert eine Alias-Tabelle, in der die Schlüssel alternative
* Zonen-IDs darstellen und in der die zugeordneten Werte wieder
* Aliasnamen oder letztlich kanonische Zonen-IDs sind.
*
* Beispiel: "PST" => "America/Los_Angeles".
*
* @return map from all timezone aliases to canoncial ids
*/
Map getAliases();
/**
* Loads an offset transition table for given timezone id.
*
* This callback method has a second argument which indicates if
* Time4J wants this method to return exactly matching data (default)
* or permits the use of aliases (only possible if the method
* {@code isFallbackEnabled()} returns {@code true}).
*
* @param zoneID timezone id (i.e. "Europe/London")
* @param fallback fallback allowed if a timezone id cannot be
* found, not even by alias?
* @return timezone history or {@code null} if there are no data
* @throws IllegalStateException if timezone database is broken
* @see #getAvailableIDs()
* @see #getAliases()
* @see #isFallbackEnabled()
* @see java.util.TimeZone#getTimeZone(String)
*/
/*[deutsch]
* Lädt die Zeitzonendaten zur angegebenen Zonen-ID.
*
* Diese Methode wird von {@code Timezone} aufgerufen. Das zweite
* Argument ist normalerweise {@code false}, so daß es sich um
* eine exakte Suchanforderung handelt. Nur wenn die Methode
* {@code isFallbackEnabled()} den Wert {@code true} zurückgibt
* und vorher weder die exakte Suche noch die Alias-Suche erfolgreich
* waren, kann ein erneuter Aufruf mit dem zweiten Argument
* {@code true} erfolgen.
*
* @param zoneID timezone id (i.e. "Europe/London")
* @param fallback fallback allowed if a timezone id cannot be
* found, not even by alias?
* @return timezone history or {@code null} if there are no data
* @throws IllegalStateException if timezone database is broken
* @see #getAvailableIDs()
* @see #getAliases()
* @see #isFallbackEnabled()
* @see java.util.TimeZone#getTimeZone(String)
*/
TransitionHistory load(
String zoneID,
boolean fallback
);
/**
* Determines if in case of a failed search another timezone should
* be permitted as alternative with possibly different rules.
*
* @return boolean
* @see #load(String, boolean)
*/
/*[deutsch]
* Soll eine alternative Zeitzone mit eventuell anderen Regeln
* geliefert werden, wenn die Suche nach einer Zeitzone erfolglos
* war?
*
* @return boolean
* @see #load(String, boolean)
*/
boolean isFallbackEnabled();
/**
* Gets the name of the underlying repository.
*
* The Olson/IANA-repository has the name
* "TZDB".
*
* @return String
*/
/*[deutsch]
* Gibt den Namen dieser Zeitzonendatenbank an.
*
* Die Olson/IANA-Zeitzonendatenbank hat den Namen
* "TZDB".
*
* @return String
*/
String getName();
/**
* Describes the location or source of the repository.
*
* @return String which refers to an URI or empty if unknown
*/
/*[deutsch]
* Beschreibt die Quelle der Zeitzonendatenbank.
*
* @return String which refers to an URI or empty if unknown
*/
String getLocation();
/**
* Queries the version of the underlying repository.
*
* In most cases the version has the Olson format starting with
* a four-digit year number followed by a small letter in range
* a-z.
*
* @return String (for example "2011n") or empty if unknown
*/
/*[deutsch]
* Liefert die Version der Zeitzonendatenbank.
*
* Meist liegt die Version im Olson-Format vor. Dieses Format sieht
* als Versionskennung eine 4-stellige Jahreszahl gefolgt von einem
* Buchstaben im Bereich a-z vor.
*
* @return String (for example "2011n") or empty if unknown
*/
String getVersion();
}