既知のすべての実装クラス:: 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

メソッドのサマリー

修飾子と型

メソッド

説明

static InstantSource

fixed(Instant fixedInstant)

常に同じインスタントを返すソースを取得します。

Instant

instant()

ソースの現在のインスタントを取得します。

default long

millis()

ソースの現在のミリ秒のインスタントを取得します。

static InstantSource

offset(InstantSource baseSource, Duration offsetDuration)

指定された継続時間が追加された、指定されたソースから瞬間を返すソースを取得します。

static InstantSource

system()

使用可能な最高のシステム・クロックを使用して現在のインスタントを返すソースを取得します。

static InstantSource

tick(InstantSource baseSource, Duration tickDuration)

指定されたソースから、指定した期間の最も近い出現まで切り捨てられるソースを取得します。

default Clock

withZone(ZoneId zone)

指定されたタイムゾーンの時計を返します。

メソッドの詳細
- system
  
  static InstantSource system()
  
  使用可能な最高のシステム・クロックを使用して現在のインスタントを返すソースを取得します。
  このソースは、利用可能なシステム・クロックに基づいています。 System.currentTimeMillis()を使用するか、システム・クロックが使用可能な場合は高解像度のクロックを使用できます。
  返される実装は、不変、スレッドセーフおよびSerializableです。
  
  戻り値:
  
  NULLではなく、使用可能なシステム・クロックを使用するソース
- tick
  
  static InstantSource tick(InstantSource baseSource, Duration tickDuration)
  
  指定されたソースから、指定した期間の最も近い出現まで切り捨てられるソースを取得します。
  このソースは、指定した期間のみチェックします。したがって、デュレーションが半秒の場合、ソース定数は半秒に切り捨てられます。
  ティック・デュレーションは正である必要があります。整数ミリ秒より小さい部分がある場合、整数デュレーションは1秒に割り振る(余りなし)必要があります。通常のすべてのティック・デュレーションは、これらの条件(時、分、秒およびミリ秒の倍数、さらに知覚可能なナノ秒デュレーション(20ナノ秒、250,000ナノ秒、500,000ナノ秒など)を含みます)に一致します。
  0または1ナノ秒デュレーションには切捨て効果はありません。これらのいずれかを渡すと、基礎となるソースが返されます。
  実装は、パフォーマンス上の理由からキャッシュ戦略を使用できます。そのため、このソースを介して観測されたリクエスト期間の開始は、基礎となるソースを介して直接観測された期間より後である可能性があります。
  戻される実装は、ベース・ソースを提供する不変でスレッド・セーフかつSerializableです。
  
  パラメータ:
  
  baseSource - ティック・ソースのベースとなるベース・ソース。nullではありません
  
  tickDuration - 表示される各ティックのデュレーション、負でない、nullでない
  
  戻り値:
  
  NULLではなく、期間全体単位でチェックするソース
  
  例外:
  
  IllegalArgumentException - デュレーションが負の場合、またはデュレーションに整数ミリ秒よりも小さい部分がある(整数デュレーションを1秒に割り振れない)場合
  
  ArithmeticException - デュレーションが大きすぎてナノとして表現できない場合
- fixed
  
  static InstantSource fixed(Instant fixedInstant)
  
  常に同じインスタントを返すソースを取得します。
  このソースは、単に指定したインスタントを返します。そのため、現在のインスタントを表すソースではありません。この主なユースケースはテスト中であり、固定ソースがテストを現在のソースに依存しないことを確認します。
  返される実装は、不変、スレッドセーフおよびSerializableです。
  
  パラメータ:
  
  fixedInstant - 使用するインスタント(nullではない)
  
  戻り値:
  
  NULLではなく、常に同じインスタントを返すソース
- offset
  
  static InstantSource offset(InstantSource baseSource, Duration offsetDuration)
  
  指定された継続時間が追加された、指定されたソースから瞬間を返すソースを取得します。
  このソースは別のソースをラップします。定数は、指定された期間後に返されます。デュレーションが負の場合、時点は現在の日付/時間より前になります。これの主要ユース・ケースは、将来または過去での実行をシミュレートすることです。
  デュレーション・ゼロは、オフセット効果なしです。ゼロを渡すと、基礎となるソースが返されます。
  戻される実装は、ベース・ソースを提供する不変でスレッド・セーフかつSerializableです。
  
  パラメータ:
  
  baseSource - 期間を追加するベース・ソース(nullではない)
  
  offsetDuration - 追加するデュレーション、nullでない
  
  戻り値:
  
  期間が追加されたベース・ソースに基づくソース(nullではない)
- instant
  
  Instant instant()
  
  ソースの現在のインスタントを取得します。
  これにより、ソースによって定義された現在のインスタントを表すインスタントが返されます。
  
  戻り値:
  
  このソースからの現在のインスタント(nullではない)
  
  例外:
  
  DateTimeException - 時点を取得できない場合、ほとんどの実装ではスローされない
- millis
  
  default long millis()
  
  ソースの現在のミリ秒のインスタントを取得します。
  これは、1970-01-01T00:00Z (UTC)から測定された、ミリ秒ベースの時点を返します。これは、System.currentTimeMillis()の定義と同等です。
  ほとんどのアプリケーションは、生のミリ秒値ではなく時系列のインスタントを表す場合は、このメソッドを使用せずInstantを使用することをお薦めします。このメソッドは、オブジェクトの作成が不許容になる高パフォーマンスのユースケースでソースを使用できるようにするために提供されています。
  
  実装要件:
  
  デフォルトの実装ではinstant()をコールします。
  
  戻り値:
  
  1970-01-01T00:00Z (UTC)のJavaエポックから測定された、このソースからの現在のミリ秒の瞬間(nullではない)
  
  例外:
  
  DateTimeException - 時点を取得できない場合、ほとんどの実装ではスローされない
- withZone
  
  default Clock withZone(ZoneId zone)
  
  指定されたタイムゾーンの時計を返します。
  これにより、Clockが返されます。これは、このソースと指定したタイムゾーンを組み合せたこのインタフェースの拡張です。
  返される実装は、このソースが適切であることを示す不変で、スレッド・セーフおよびSerializableです。
  
  実装要件:
  
  デフォルトの実装では、このソースと指定したゾーンを組み合せるClockの不変でスレッド・セーフなサブクラスおよびSerializableサブクラスが返されます。
  
  パラメータ:
  
  zone - 使用するタイムゾーン、null以外
  
  戻り値:
  
  指定されたタイムゾーンでこのソースに基づく時計。nullではありません

インタフェースInstantSource

メソッドのサマリー

メソッドの詳細

system

tick

fixed

offset

instant

millis

withZone