モジュール java.base
パッケージ java.time.zone

クラスZoneRulesProvider

java.lang.Object
java.time.zone.ZoneRulesProvider
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

  • コンストラクタの詳細

    • ZoneRulesProvider

      protected ZoneRulesProvider()
      コンストラクタです。

  • メソッドの詳細

    • getAvailableZoneIds

      public static Set<String> getAvailableZoneIds()
      利用可能なゾーンIDのセットを取得します。

      これらのIDはZoneIdの文字列形式です。

      戻り値:
      ゾーンIDの変更不可能なセット、nullではない

    • getRules

      public static ZoneRules getRules​(String zoneId, boolean forCaching)
      ゾーン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

      protected abstract Set<String> provideZoneIds()
      使用可能なゾーンIDを取得するSPIメソッド。

      これは、このZoneRulesProviderが提供するIDを取得します。 プロバイダは少なくとも1つのゾーンIDのデータを提供してください。

      返されるゾーンIDは引き続き利用可能であり、アプリケーションの存続期間有効です。 動的プロバイダは、より多くのデータが利用可能になるにつれてIDセットを増やすことができます。

      戻り値:
      提供されるゾーンIDのセット、nullでない
      例外:
      ZoneRulesException - IDの提供中に問題が発生した場合

    • provideRules

      protected abstract ZoneRules provideRules​(String zoneId, boolean forCaching)
      ゾーン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 - リフレッシュ時にエラーが発生した場合