net.time4j.engine.ChronoExtension Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2016 Meno Hochschild, Defines a configuration-dependent extension of the chronological
* elements of a {@code Chronology} used in formatting and parsing.
*
* @author Meno Hochschild
*/
/*[deutsch]
* Definiert eine konfigurationsabhängige Erweiterung der
* chronologischen Elemente einer Chronologie und wird beim Formatieren
* und Parsen verwendet.
*
* @author Meno Hochschild
*/
public interface ChronoExtension {
//~ Methoden ----------------------------------------------------------
/**
* Will be called by a {@code java.util.ServiceLoader} in order to determine
* if the given chronological type should register this extension or not.
*
* @param chronoType chronological type
* @return {@code true} if given type should register this extension else {@code false}
* @since 3.0
*/
/*[deutsch]
* Wird von einem {@code java.util.ServiceLoader} aufgerufen, um zu bestimmen,
* ob der angegebene chronologische Typ diese Erweiterung registrieren soll.
*
* @param chronoType chronological type
* @return {@code true} if given type should register this extension else {@code false}
* @since 3.0
*/
boolean accept(Class chronoType);
/**
* Returns the element set for given configuration.
*
* An empty {@code Set} indicates that this extension is not relevant
* for the given configuration.
*
* @param locale language and country setting
* @param attributes global configuration attributes of formatter
* @return extended element model
*/
/*[deutsch]
* Liefert das Elementmodell zur angegebenen Konfiguration.
*
* Ein leeres {@code Set} als Rückgabe signalisiert dem Aufrufer,
* daß für die gegebene Konfiguration die Erweiterung nicht
* relevant ist.
*
* @param locale language and country setting
* @param attributes global configuration attributes of formatter
* @return extended element model
*/
Set> getElements(
Locale locale,
AttributeQuery attributes
);
/**
* Updates the given value source if necessary in order to resolve
* the values of extension elements to values of standard elements.
*
* Implementations are allowed to use {@code null} as pseudo-value
* in order to delete an element from given source via the expression
* {@code entity.with(element, null)}. Note: The argument has
* exceptionally no chronology.
*
* @param entity any kind of map from chronological elements to
* their values (note that the main use case of parsed
* data has no chronology and allows the virtual value
* {@code null} to be set as indication for removing
* associated element)
* @param locale language and country setting
* @param attributes global configuration attributes of parser
* @return eventually changed entity
* @throws IllegalArgumentException if resolving fails due to inconsistencies
* @since 3.0
* @see ChronoEntity#with(ChronoElement, Object) ChronoEntity.with(ChronoElement, V)
*/
/*[deutsch]
* Aktualisiert bei Bedarf die angegebene Wertquelle, um die Werte von
* Erweiterungselementen zu Werten von Standardelementen aufzulösen.
*
*
* Implementierungen dürfen hier auch {@code null} als Pseudo-Wert
* benutzen, um ein Element mittels {@code entity.with(element, null)}
* aus der Wertquelle zu löschen. Zu beachten: Das Argument hat als
* Ausnahmefall keine Chronologie.
*
* @param entity any kind of map from chronological elements to
* their values (note that the main use case of parsed
* data has no chronology and allows the virtual value
* {@code null} to be set as indication for removing
* associated element)
* @param locale language and country setting
* @param attributes global configuration attributes of parser
* @return eventually changed entity
* @throws IllegalArgumentException if resolving fails due to inconsistencies
* @since 3.0
* @see ChronoEntity#with(ChronoElement, Object) ChronoEntity.with(ChronoElement, V)
*/
ChronoEntity resolve(
ChronoEntity entity,
Locale locale,
AttributeQuery attributes
);
/**
* Gives a hint to the parser if the element in question can be resolved by {@code resolve()}.
*
* This method serves for optimization purpose and helps the parser to decide if chronological extensions
* are needed at all during parsing. Subclasses should override this method in most cases.
*
* @param element the element to be checked
* @return {@code true} if this extension can resolve given element else {@code false}
* @see #resolve(ChronoEntity, Locale, AttributeQuery)
* @since 3.40/4.35
*/
/*[deutsch]
* Gibt dem Textinterpretierer einen Hinweis, ob das fragliche Element mittels
* {@code resolve()} aufgelöst werden kann.
*
* Diese Methode dient der Optimierung des Interpretationsvorgangs und hilft zu entscheiden,
* ob chronologische Erweiterungen überhaupt gebraucht werden. Subklassen sollten diese
* Methode in der Regel überschreiben.
*
* @param element the element to be checked
* @return {@code true} if this extension can resolve given element else {@code false}
* @see #resolve(ChronoEntity, Locale, AttributeQuery)
* @since 3.40/4.35
*/
default boolean canResolve(ChronoElement element) {
for (ChronoElement e : this.getElements(Locale.ROOT, Attributes.empty())) {
if (e.getClass().equals(element.getClass())) {
return true;
}
}
return false;
}
}