public abstract class ZoneRulesProvider extends Object
このクラスはタイムゾーン・ルールの構成を管理します。 staticメソッドは、プロバイダの管理に使用できるpublic APIを提供します。 抽象メソッドは、ルールが提供されることを許可するSPIを提供します。
ZoneRulesProviderは、拡張クラス(通常の拡張ディレクトリに配置されるjarファイル)として、Javaプラットフォームのインスタンスにインストールできます。 インストールされたプロバイダは、ServiceLoader
クラスで定義されているサービス・プロバイダのロード機能を使用してロードされます。 ZoneRulesProviderは、リソース・ディレクトリMETA-INF/services
内のjava.time.zone.ZoneRulesProvider
というプロバイダ構成ファイルを使用して自身を識別します。 このファイルは、完全修飾された具象ゾーン・ルール・プロバイダ・クラス名を指定する行を含んでいるはずです。 プロバイダは、クラスパスにそれらを追加するか、registerProvider(java.time.zone.ZoneRulesProvider)
メソッド経由で自身を登録することによって、使用可能にすることもできます。
Java仮想マシンは、IANAタイムゾーン・データベース(TZDB)で定義されるタイムゾーンにゾーン・ルールを提供するデフォルト・プロバイダを持っています。 システム・プロパティjava.time.zone.DefaultZoneRulesProvider
が定義されている場合は、システム・クラス・ローダーを使用して、デフォルト・プロバイダとしてロードされる具体的なZoneRulesProviderクラスの完全修飾名になります。 このシステム・プロパティが定義されていない場合、システム・デフォルト・プロバイダがロードされ、デフォルト・プロバイダとして機能します。
ルールは、ZoneId
で使用されるゾーンIDによって主に参照されます。 ゾーン地域IDのみが使用できます。ここではゾーン・オフセットIDは使用されません。
タイムゾーン・ルールは政治的であるため、データはいつでも変わる可能性があります。 各プロバイダはゾーンIDごとに最新ルールを提供しますが、ルールがどのように変更されたかの履歴を提供することもできます。
- 実装要件:
- このインタフェースは複数スレッドで呼び出せるサービス・プロバイダです。 実装は不変かつスレッドセーフである必要があります。
プロバイダは、ルールがアプリケーションから見られるようになったら、ルールが継続的に使用可能であることを保証する必要があります。
プロバイダは意味のある
toString
メソッドを実装することが奨励されます。多くのシステムでは、JVMを停止せずにタイムゾーン・ルールを動的に更新することが求められます。 詳細に調べると、これは複合的な問題です。 プロバイダは動的更新を扱うことを選択できますが、デフォルト・プロバイダは扱いません。
- 導入されたバージョン:
- 1.8
-
コンストラクタのサマリー
コンストラクタ 修飾子 コンストラクタ 説明 protected
ZoneRulesProvider()
コンストラクタです。 -
メソッドのサマリー
修飾子と型 メソッド 説明 static Set<String>
getAvailableZoneIds()
利用可能なゾーンIDのセットを取得します。static ZoneRules
getRules(String zoneId, boolean forCaching)
ゾーンIDのルールを取得します。static NavigableMap<String,ZoneRules>
getVersions(String zoneId)
ゾーンIDのルールの履歴を取得します。protected boolean
provideRefresh()
基礎となるデータ・プロバイダからのルールをリフレッシュするSPIメソッド。protected abstract ZoneRules
provideRules(String zoneId, boolean forCaching)
ゾーンIDのルールを取得するSPIメソッド。protected abstract NavigableMap<String,ZoneRules>
provideVersions(String zoneId)
ゾーンIDのルールの履歴を取得するSPIメソッド。protected abstract Set<String>
provideZoneIds()
使用可能なゾーンIDを取得するSPIメソッド。static boolean
refresh()
基礎となるデータ・プロバイダからのルールをリフレッシュします。static void
registerProvider(ZoneRulesProvider provider)
ゾーン・ルール・プロバイダを登録します。
-
コンストラクタの詳細
-
ZoneRulesProvider
protected ZoneRulesProvider()コンストラクタです。
-
-
メソッドの詳細
-
getAvailableZoneIds
利用可能なゾーンIDのセットを取得します。これらのIDは
ZoneId
の文字列形式です。- 戻り値:
- ゾーンIDの変更不可能なセット、nullではない
-
getRules
ゾーンIDのルールを取得します。ゾーンIDの最新の使用可能なルールを返します。
このメソッドは、構成されているタイムゾーン・データ・プロバイダ・ファイルに依存します。 これらは、
ServiceLoader
を使用してロードされます。キャッシュ・フラグは、ルールが
ZoneId
にキャッシュされるのをプロバイダ実装が回避できるように設計されています。 通常の状況では、ゾーン・ルールをキャッシュすることは高いパフォーマンスを提供するため強く推奨されます。 ただし、キャッシュが推奨されないユース・ケースがあります。provideRules(java.lang.String, boolean)
を参照してください。- パラメータ:
zoneId
-ZoneId
で定義されるゾーンID、nullでないforCaching
- ルールのキャッシュが問い合わせられているかどうか、返されるルールがZoneId
によってキャッシュされる場合はtrue、ZoneId
にキャッシュされずにユーザーに返される場合はfalse- 戻り値:
- ルール、
forCaching
がtrueであり、これがZoneId
へのキャッシュを回避することを望む動的プロバイダの場合はnull、それ以外の場合はnullでない - 例外:
ZoneRulesException
- ゾーンIDのルールを取得できない場合
-
getVersions
public static NavigableMap<String,ZoneRules> getVersions(String zoneId)ゾーンIDのルールの履歴を取得します。タイムゾーンは政府によって定義されるため、頻繁に変わります。 このメソッドを使って、アプリケーションは単一ゾーンIDのルールへの変更の履歴を探すことができます。 このマップのキーは文字列(ルールに関連付けられたバージョン文字列)です。
バージョンの正確な意味およびフォーマットはプロバイダ固有です。 バージョンは辞書式順序に従う必要があるため、返されるマップは最も古い既知のルールから最も新しい使用可能なルールまでの順序になります。 デフォルトの'TZDB'グループは、年に続く文字で構成されるバージョン番号付け('2009e'や'2012f'など)を使用します。
実装は、有効なゾーンIDごとに結果を提供する必要がありますが、ルールの履歴を提供する必要はありません。 したがって、マップには常に1要素が含まれます。履歴ルール情報が利用できる場合のみ、複数の要素が含まれます。
- パラメータ:
zoneId
-ZoneId
で定義されるゾーンID、nullでない- 戻り値:
- IDのルールの履歴の変更可能コピー、最も古いものから最も新しいものへソートされる、nullでない
- 例外:
ZoneRulesException
- ゾーンIDの履歴を取得できない場合
-
registerProvider
public static void registerProvider(ZoneRulesProvider provider)ゾーン・ルール・プロバイダを登録します。これは、現在使用できるものに新しいプロバイダを追加します。 プロバイダは1つ以上のゾーンIDのルールを提供します。 すでに登録されているゾーンIDを提供するプロバイダは登録できません。
ZoneId
のタイムゾーンIDについての注意事項を参照してください(特に、IDを一意にする"グループ"の概念の使用に関するセクション)。タイムゾーンの整合性がすでに作成されていることを確認するために、プロバイダを登録解除する方法はありません。
- パラメータ:
provider
- 登録するプロバイダ、nullでない- 例外:
ZoneRulesException
- ゾーンIDがすでに登録されている場合
-
refresh
public static boolean refresh()基礎となるデータ・プロバイダからのルールをリフレッシュします。このメソッドによりアプリケーションは、提供されたルールへの更新をプロバイダが確認することを要求できます。 このメソッドを呼び出した後に、
ZonedDateTime
に格納されているオフセットはゾーンIDに対して無効になる場合があります。ルールの動的更新は複合的な問題なので、ほとんどのアプリケーションはこのメソッドまたは動的ルールを使用しないでください。 動的ルールを実現するには、プロバイダ実装はこのクラスの仕様に従ってを記述される必要があります。 さらに、
ZoneRules
のインスタンスはアプリケーション内にキャッシュしないでください。最新でなくなるためです。 ただし、provideRules(String, boolean)
のブール・フラグによりプロバイダ実装はZoneId
のキャッシュを制御できるため、潜在的にシステム内のすべてのオブジェクトが新しいルールを見ることが保証されます。 動的ルール・プロバイダのパフォーマンスのコストになる可能性があることに注意してください。 また、動的ルール・プロバイダがこの仕様にないことにも注意してください。- 戻り値:
- ルールが更新された場合はtrue
- 例外:
ZoneRulesException
- リフレッシュ時にエラーが発生した場合
-
provideZoneIds
使用可能なゾーンIDを取得するSPIメソッド。これは、この
ZoneRulesProvider
が提供するIDを取得します。 プロバイダは少なくとも1つのゾーンIDのデータを提供してください。返されるゾーンIDは引き続き利用可能であり、アプリケーションの存続期間有効です。 動的プロバイダは、より多くのデータが利用可能になるにつれてIDセットを増やすことができます。
- 戻り値:
- 提供されるゾーンIDのセット、nullでない
- 例外:
ZoneRulesException
- IDの提供中に問題が発生した場合
-
provideRules
ゾーンIDのルールを取得するSPIメソッド。これは、指定されたゾーンIDのルールをロードします。 プロバイダ実装は、ゾーンIDが有効かつ利用可能であることを検証する必要があります。そうでない場合は
ZoneRulesException
をスローします。 有効な場合のメソッドの結果はキャッシュ・フラグによって異なります。プロバイダ実装が動的でない場合、メソッドの結果はIDで選択されたnull以外のルール・セットである必要があります。
プロバイダ実装が動的な場合、フラグは返されるルールが
ZoneId
にキャッシュされるのを回避するオプションを提供します。 フラグがtrueの場合、プロバイダはnullを返すことができます。nullはルールがZoneId
にキャッシュされることを回避します。 フラグがfalseの場合、プロバイダはnull以外のルールを返す必要があります。- パラメータ:
zoneId
-ZoneId
で定義されるゾーンID、nullでないforCaching
- ルールのキャッシュが問い合わせられているかどうか、返されるルールがZoneId
によってキャッシュされる場合はtrue、ZoneId
にキャッシュされずにユーザーに返される場合はfalse- 戻り値:
- ルール、
forCaching
がtrueであり、これがZoneId
へのキャッシュを回避することを望む動的プロバイダの場合はnull、それ以外の場合はnullでない - 例外:
ZoneRulesException
- ゾーンIDのルールを取得できない場合
-
provideVersions
protected abstract NavigableMap<String,ZoneRules> provideVersions(String zoneId)ゾーンIDのルールの履歴を取得するSPIメソッド。これは、バージョン文字列をキーとする履歴ルールのマップを返します。 バージョンの正確な意味およびフォーマットはプロバイダ固有です。 バージョンは辞書式順序に従う必要があるため、返されるマップは最も古い既知のルールから最も新しい使用可能なルールまでの順序になります。 デフォルトの'TZDB'グループは、年に続く文字で構成されるバージョン番号付け('2009e'や'2012f'など)を使用します。
実装は、有効なゾーンIDごとに結果を提供する必要がありますが、ルールの履歴を提供する必要はありません。 したがって、マップには少なくとも1つの要素が含まれ、履歴ルール情報が使用できる場合のみ複数の要素が含まれます。
返されるバージョンは引き続き利用可能であり、アプリケーションの存続期間有効です。 動的プロバイダは、より多くのデータが利用可能になるにつれてバージョン・セットを増やすことができます。
- パラメータ:
zoneId
-ZoneId
で定義されるゾーンID、nullでない- 戻り値:
- IDのルールの履歴の変更可能コピー、最も古いものから最も新しいものへソートされる、nullでない
- 例外:
ZoneRulesException
- ゾーンIDの履歴を取得できない場合
-
provideRefresh
protected boolean provideRefresh()基礎となるデータ・プロバイダからのルールをリフレッシュするSPIメソッド。このメソッドは、プロバイダが基礎となるデータ・プロバイダを動的に再チェックして最新のルールを見つける機会を提供します。 これは、JVMを停止せずに新しいルールをロードするために使用できます。 動的な動作は完全にオプションであり、ほとんどのプロバイダはサポートしません。
この実装はfalseを返します。
- 戻り値:
- ルールが更新された場合はtrue
- 例外:
ZoneRulesException
- リフレッシュ時にエラーが発生した場合
-