* This class manages the configuration of time-zone rules. The static methods provide the public API that can be used * to manage the timezone-rules provider. The abstract methods provide the SPI that allows rules to be provided. *
* If the constant {@code java.time.zone.DefaultZoneRulesProvider} is defined then it is taken to be the fully-qualified * name of a concrete ZoneRulesProvider class to be loaded as the default provider. * If this constant is not defined, the system-default provider will be loaded to serve as the default provider. * It provides rules only for the "GMT" time zone and throws a {@link ZoneRulesException} for any attempt to query * another zone ID. *
* Rules are looked up primarily by zone ID, as used by {@link ZoneId}. Only zone region IDs may be used, zone offset * IDs are not used here. *
* Time-zone rules are political, thus the data can change at any time. Each provider will provide the latest rules for * each zone ID, but they may also provide the history of how the rules changed. *
This interface is a service provider that can be called by multiple threads. Implementations must be * immutable and thread-safe. *
* Providers must ensure that once a rule has been seen by the application, the rule must continue to be available. *
* Providers are encouraged to implement a meaningful {@code toString} method. *
* Many systems would like to update time-zone rules dynamically without stopping the JVM. When examined in detail, this * is a complex problem. Providers may choose to handle dynamic updates, however the default provider does not. */ public abstract class ZoneRulesProvider { private static final String ZONE_RULES_PROVIDER_CONSTANT = "java.time.zone.DefaultZoneRulesProvider"; private static final ZoneRulesProvider ZONE_RULES_PROVIDER; static{ try { Class clazz = Constants.getClass(ZONE_RULES_PROVIDER_CONSTANT); ZONE_RULES_PROVIDER = (ZoneRulesProvider) clazz.newInstance(); } catch (Exception e) { throw new IllegalStateException(e); } } // ------------------------------------------------------------------------- /** * Gets the rules for the zone ID. *
* This returns the latest available rules for the zone ID. *
* This method relies on time-zone data provider files that are configured. These are loaded using a * {@code ServiceLoader}. *
* The caching flag is designed to allow provider implementations to prevent the rules being cached in * {@code ZoneId}. Under normal circumstances, the caching of zone rules is highly desirable as it will provide * greater performance. However, there is a use case where the caching would not be desirable, see * {@link #provideRules}. * * @param zoneId * the zone ID as defined by {@code ZoneId}, not null * @param forCaching * whether the rules are being queried for caching, true if the returned rules will be cached by * {@code ZoneId}, false if they will be returned to the user without being cached in {@code ZoneId} * @return the rules, null if {@code forCaching} is true and this is a dynamic provider that wants to prevent * caching in {@code ZoneId}, otherwise not null * @throws ZoneRulesException * if rules cannot be obtained for the zone ID */ @Nullable public static ZoneRules getRules(String zoneId, boolean forCaching) { Objects.requireNonNull(zoneId, "zoneId"); return ZONE_RULES_PROVIDER.provideRules(zoneId, forCaching); } /** * Gets the history of rules for the zone ID. *
* Time-zones are defined by governments and change frequently. * This method allows applications to find the history of changes to the * rules for a single zone ID. The map is keyed by a string, which is the * version string associated with the rules. *
* The exact meaning and format of the version is provider specific. * The version must follow lexicographical order, thus the returned map will * be ordered from the oldest known rules to the newest available rules. *
* Implementations must provide a result for each valid zone ID, however
* they do not have to provide a history of rules.
* Thus, the map will always contain one element, and will only contain more
* than one element if historical rule information is available.
*
* @param zoneId the zone ID as defined by {@code ZoneId}, not null
* @return a modifiable copy of the history of the rules for the ID, sorted
* from oldest to newest, not null
* @throws ZoneRulesException if history cannot be obtained for the zone ID
*/
public static NavigableMap
* These IDs are the string form of a {@link ZoneId}.
*
* @return a modifiable copy of the set of zone IDs, not null
*/
public static Set
* This method allows an application to request that the providers check for any updates to the provided rules.
* After calling this method, the offset stored in any {@link ZonedDateTime} may be invalid for the zone ID.
*
* Dynamic update of rules is a complex problem and most applications should not use this method or dynamic rules.
* To achieve dynamic rules, a provider implementation will have to be written as per the specification of this
* class. In addition, instances of {@code ZoneRules} must not be cached in the application as they will become
* stale. However, the boolean flag on {@link #provideRules(String, boolean)} allows provider implementations to
* control the caching of {@code ZoneId}, potentially ensuring that all objects in the system see the new rules.
* Note that there is likely to be a cost in performance of a dynamic rules provider. Note also that no dynamic
* rules provider is in this specification.
*
* @return true if the rules were updated
* @throws ZoneRulesException
* if an error occurs during the refresh
*/
public static boolean refresh() {
return ZONE_RULES_PROVIDER.provideRefresh();
}
/**
* Constructor.
*/
protected ZoneRulesProvider() {
}
// -----------------------------------------------------------------------
/**
* SPI method to get the available zone IDs.
*
* This obtains the IDs that this {@code ZoneRulesProvider} provides. A provider should provide data for at least
* one zone ID.
*
* The returned zone IDs remain available and valid for the lifetime of the application. A dynamic provider may
* increase the set of IDs as more data becomes available.
*
* @return the set of zone IDs being provided, not null
* @throws ZoneRulesException
* if a problem occurs while providing the IDs
*/
protected abstract Set
* This loads the rules for the specified zone ID. The provider implementation must validate that the zone ID is
* valid and available, throwing a {@code ZoneRulesException} if it is not. The result of the method in the valid
* case depends on the caching flag.
*
* If the provider implementation is not dynamic, then the result of the method must be the non-null set of rules
* selected by the ID.
*
* If the provider implementation is dynamic, then the flag gives the option of preventing the returned rules from
* being cached in {@link ZoneId}. When the flag is true, the provider is permitted to return null, where null will
* prevent the rules from being cached in {@code ZoneId}. When the flag is false, the provider must return non-null
* rules.
*
* @param zoneId
* the zone ID as defined by {@code ZoneId}, not null
* @param forCaching
* whether the rules are being queried for caching, true if the returned rules will be cached by
* {@code ZoneId}, false if they will be returned to the user without being cached in {@code ZoneId}
* @return the rules, null if {@code forCaching} is true and this is a dynamic provider that wants to prevent
* caching in {@code ZoneId}, otherwise not null
* @throws ZoneRulesException
* if rules cannot be obtained for the zone ID
*/
@Nullable
protected abstract ZoneRules provideRules(String zoneId, boolean forCaching);
/**
* SPI method to get the history of rules for the zone ID.
*
* This returns a map of historical rules keyed by a version string.
* The exact meaning and format of the version is provider specific.
* The version must follow lexicographical order, thus the returned map will
* be ordered from the oldest known rules to the newest available rules.
*
* Implementations must provide a result for each valid zone ID, however
* they do not have to provide a history of rules.
* Thus, the map will contain at least one element, and will only contain
* more than one element if historical rule information is available.
*
* The returned versions remain available and valid for the lifetime of the application.
* A dynamic provider may increase the set of versions as more data becomes available.
*
* @param zoneId the zone ID as defined by {@code ZoneId}, not null
* @return a modifiable copy of the history of the rules for the ID, sorted
* from oldest to newest, not null
* @throws ZoneRulesException if history cannot be obtained for the zone ID
*/
protected abstract NavigableMap
* This method provides the opportunity for a provider to dynamically recheck the underlying data provider to find
* the latest rules. This could be used to load new rules without stopping the JVM. Dynamic behavior is entirely
* optional and most providers do not support it.
*
* This implementation returns false.
*
* @return true if the rules were updated
* @throws ZoneRulesException
* if an error occurs during the refresh
*/
protected boolean provideRefresh() {
return false;
}
}