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

インタフェースInstantSource

既知のすべての実装クラス:
Clock
public interface InstantSource
現在のインスタントにアクセスできます。

このインタフェースのインスタンスは、現在のインスタントのプラガブル表現にアクセスするために使用されます。 たとえば、System.currentTimeMillis()のかわりにInstantSourceを使用できます。

この抽象化の主要な目的は、代替インスタント・ソースを必要に応じて接続できるようにすることです。 アプリケーションはstaticメソッドではなくオブジェクトを使用して現在時間を取得します。 これによりテストを単純化できます。

そのため、このインタフェースは、実際にタイムライン上の現在のインスタントを表す結果を保証するものではありません。 かわりに、アプリケーションは現在の瞬間に対する制御されたビューを提供できます。

アプリケーションのベスト・プラクティスは、現在の瞬間が必要なメソッドにInstantSourceを渡すことです。 これを実現するための1つの方法が、Dependency Injectionフレームワークです。 

  public class MyBean {
    private InstantSource source;  // dependency inject
    ...
    public void process(Instant endInstant) {
      if (source.instant().isAfter(endInstant) {
        ...
      }
    }
  }
このアプローチにより、テスト中にfixedやoffsetなどの代替ソースを使用できます。

systemファクトリ・メソッドは、使用可能なシステム・クロックに基づいたソースを提供します。 これは、System.currentTimeMillis()、またはより分解能の高いクロック(利用できる場合)を使用します。

実装要件:
このインタフェースは、他のクラスが正常に動作するように、注意して実装する必要があります。 すべての実装がスレッド・セーフである必要がある - 1つのインスタンスは、競合状態などの悪影響なく、複数のスレッドから起動できる必要があります。

主要メソッドは例外のスローを許可するように定義されています。 通常の使用では例外はスローされませんが、唯一可能な実装は、中央の時間サーバーからネットワーク経由で時間を取得します。 このケースでは明らかに、ルックアップが失敗する可能性があるため、そのメソッドは例外をスローすることが許可されます。

InstantSourceから返された時間は、Instantで説明されているように、うるう秒を無視する時間スケールで動作します。 うるう秒情報を提供するソースを実装がラップしている場合、うるう秒を調整するメカニズムを使用することをお薦めします。 Javaタイム・スケールではUTC-SLSの使用が義務付けられていますが、実装では、動作方法を文書化するかぎり、タイム・スケールにどの程度正確であるかを選択できます。 したがって実装は、実際にUTC-SLS slewを実行する必要はなく、そうでない場合でもうるう秒を意識する必要はありません。

実装は、可能な場合は常にSerializableを実装するようにしてください。さらに、実装が直列化をサポートするかどうかをドキュメント化する必要があります。

実装上のノート:
ここで説明する実装は、System.currentTimeMillis()と同じベースとなるシステム・クロックに基づいていますが、使用可能な場合はミリ秒より精度が高くなる可能性があります。 ただし、基礎となるシステム・クロックの精度についてはほとんど保証されません。 より正確なシステム・クロックを必要とするアプリケーションは、NTPサーバーなどの別の外部システム・クロックを使用してこの抽象クラスを実装する必要があります。
導入されたバージョン:
17