net.time4j.tz.ZoneProvider Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2015 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.2
* @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.2
* @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 a {@code Set} of preferred timezone IDs for given
* ISO-3166-country code.
*
* This information is necessary to enable parsing of
* timezone names.
*
* @param locale ISO-3166-alpha-2-country to be evaluated
* @param smart if {@code true} then try to select zone ids such
* that there is only one preferred id per zone name
* @return unmodifiable set of preferred timezone ids
*/
/*[deutsch]
* Liefert die für einen gegebenen ISO-3166-Ländercode
* bevorzugten Zeitzonenkennungen.
*
* Diese Information ist für die Interpretation von Zeitzonennamen
* notwendig.
*
* @param locale ISO-3166-alpha-2-country to be evaluated
* @param smart if {@code true} then try to select zone ids such
* that there is only one preferred id per zone name
* @return unmodifiable set of preferred timezone ids
*/
Set getPreferredIDs(
Locale locale,
boolean smart
);
/**
* 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 history for given timezone id.
*
* The argument never contains the provider name as prefix. It is
* instead the part after the "~"-char (if not absent).
*
* @param zoneID timezone id (i.e. "Europe/London")
* @return timezone history or {@code null} if there are no data
* @throws IllegalArgumentException if given id is wrong
* @throws IllegalStateException if timezone database is broken
* @see #getAvailableIDs()
* @see #getAliases()
* @see java.util.TimeZone#getTimeZone(String)
*/
/*[deutsch]
* Lädt die Zeitzonendaten zur angegebenen Zonen-ID.
*
* Das erste Argument enthält nie den Provider-Namen als
* Präfix. Stattdessen ist es der Teil nach dem Zeichen
* "~" (falls vorhanden).
*
* @param zoneID timezone id (i.e. "Europe/London")
* @return timezone history or {@code null} if there are no data
* @throws IllegalArgumentException if given id is wrong
* @throws IllegalStateException if timezone database is broken
* @see #getAvailableIDs()
* @see #getAliases()
* @see java.util.TimeZone#getTimeZone(String)
*/
TransitionHistory load(String zoneID);
/**
* Determines if in case of a failed search another {@code ZoneProvider}
* should be called as alternative with possibly different rules.
*
* The special name "DEFAULT" can be used to denote the
* default zone provider. Note that the fallback provider will only affect
* the rules but not the id or display names of a new timezone.
*
* @return name of alternative provider or empty if no fallback happens
* @see #load(String)
*/
/*[deutsch]
* Legt fest, ob ein alternativer {@code ZoneProvider} mit eventuell
* anderen Regeln gerufen werden soll, wenn die Suche nach einer Zeitzone
* erfolglos war.
*
* Der spezielle Name "DEFAULT" kann verwendet werden, um
* den Standard-{@code ZoneProvider} anzuzeigen. Zu beachten: Die
* Alternative wird nur die Regeln betreffen, nicht aber die ID oder
* Anzeigenamen einer neuen Zeitzone.
*
* @return name of alternative provider or empty if no fallback happens
* @see #load(String)
*/
String getFallback();
/**
* Gets the name of the underlying repository.
*
* The Olson/IANA-repository (and any provider which makes use of
* these data (direct or indirect)) has the name "TZDB".
* The names "java.util.TimeZone" and "DEFAULT"
* are reserved and cannot be used.
*
* @return String
*/
/*[deutsch]
* Gibt den Namen dieser Zeitzonendatenbank an.
*
* Die Olson/IANA-Zeitzonendatenbank hat den Namen
* "TZDB". Jeder {@code ZoneProvider}, der sich auf diese
* Daten bezieht, muß diesen Namen haben. Die Namen
* "java.util.TimeZone" and "DEFAULT" sind
* reserviert und können nicht verwendet werden.
*
* @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();
/**
* Returns the name of this timezone suitable for presentation to
* users in given style and locale.
*
* The first argument never contains the provider name as prefix. It is
* instead the part after the "~"-char (if not absent).
*
* @param zoneID timezone id (i.e. "Europe/London")
* @param style name style
* @param locale language setting
* @return localized timezone name for display purposes
* or empty if not supported
* @see java.util.TimeZone#getDisplayName(boolean,int,Locale)
* java.util.TimeZone.getDisplayName(boolean,int,Locale)
*/
/*[deutsch]
* Liefert den anzuzeigenden Zeitzonennamen.
*
* Das erste Argument enthält nie den Provider-Namen als
* Präfix. Stattdessen ist es der Teil nach dem Zeichen
* "~" (falls vorhanden).
*
* @param zoneID timezone id (i.e. "Europe/London")
* @param style name style
* @param locale language setting
* @return localized timezone name for display purposes
* or empty if not supported
* @see java.util.TimeZone#getDisplayName(boolean,int,Locale)
* java.util.TimeZone.getDisplayName(boolean,int,Locale)
*/
String getDisplayName(
String zoneID,
NameStyle style,
Locale locale
);
}