java.time.Clock

public abstract class Clock
extends Object

タイムゾーンを使用して現在の時点、日付および時間へのアクセスを提供するクロックです。

このクラスのインスタンスは、現在の時点を検索するために使用されます。現在の時点は、保存済みタイムゾーンを使用して現在の日時を検索することで解釈できます。そのためクロックは、System.currentTimeMillis()およびTimeZone.getDefault()のかわりに使用できます。

Clockの使用は任意です。すべての主要な日付/時間クラスには、デフォルト・タイムゾーンのシステム・クロックを使用するnow()ファクトリ・メソッドも用意されています。この抽象の主要目的は、代替クロックを必要なときにプラグインできるようにすることです。アプリケーションはstaticメソッドではなくオブジェクトを使用して現在時間を取得します。これによりテストを単純化できます。

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

  public class MyBean {
    private Clock clock;  // dependency inject
    ...
    public void process(LocalDate eventDate) {
      if (eventDate.isBefore(LocalDate.now(clock)) {
        ...
      }
    }
  }

このアプローチにより、代替クロック(fixedやoffsetなど)をテストで使用できます。

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

実装要件:

この抽象クラスは、他のクラスが確実に正しく動作するように、注意して実装する必要があります。インスタンス化可能なすべての実装は、最終、不変、およびスレッドセーフである必要があります。

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

Clockから返されるインスタントは、「Instant」で説明されているように、うるう秒を無視するタイム・スケールで機能します。うるう秒情報を提供するソースを実装がラップしている場合、うるう秒を調整するメカニズムを使用することをお薦めします。 Javaタイムスケールは、UTC-SLSの使用を義務付けます。ただし、クロック実装は、それらがどのように機能するかをドキュメント化している限り、そのタイム・スケールでの精度を選択できます。したがって実装は、実際にUTC-SLS slewを実行する必要はなく、そうでない場合でもうるう秒を意識する必要はありません。

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

実装上のノート:

ここで提供されるクロックの実装は、System.currentTimeMillis()と同じ基本クロックに基づいていますが、使用可能な場合はミリ秒より細かい精度を持つ場合があります。ただし、基礎クロックの精度についてはほとんど保証されません。より正確なクロックを必要とするアプリケーションは、NTPサーバーなどの別の外部クロックを使用して、この抽象クラスを自身で実装する必要があります。

導入されたバージョン:

1.8

コンストラクタのサマリー

コンストラクタ

修飾子コンストラクタ説明

protected Clock()
サブクラスでアクセスできるコンストラクタです。

メソッドのサマリー

修飾子と型	メソッド	説明
`boolean`	`equals(Object obj)`	このクロックがもう一方のクロックと等しいかどうかを確認します。
`static Clock`	`fixed(Instant fixedInstant, ZoneId zone)`	常に同じインスタントを返すクロックを取得します。
`abstract ZoneId`	`getZone()`	日付と時間を作成するために使用されるタイムゾーンを取得します。
`int`	`hashCode()`	このクロックのハッシュ・コード。
`abstract Instant`	`instant()`	クロックの現在の時点を取得します。
`long`	`millis()`	クロックの現在の時点をミリ秒で取得します。
`static Clock`	`offset(Clock baseClock, Duration offsetDuration)`	指定されたデュレーションを加算して指定されたクロックからインスタントを返すクロックを取得します
`static Clock`	`system(ZoneId zone)`	最高の利用可能なシステム・クロックを使用して現在の瞬間を返すクロックを取得します。
`static Clock`	`systemDefaultZone()`	利用できる最適なシステム・クロックを使用し、デフォルト・タイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。
`static Clock`	`systemUTC()`	利用できる最適なシステム・クロックを使用し、UTCタイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。
`static Clock`	`tick(Clock baseClock, Duration tickDuration)`	指定されたデュレーションの直近値に切り捨てられたインスタントを指定されたクロックから返すクロックを取得します。
`static Clock`	`tickMillis(ZoneId zone)`	最高の利用可能なシステム・クロックを使用して、ミリ秒単位で現在の時刻を返すクロックを取得します。
`static Clock`	`tickMinutes(ZoneId zone)`	最高の利用可能なシステム・クロックを使用して、分単位で現在の時刻を返す時計を取得します。
`static Clock`	`tickSeconds(ZoneId zone)`	最高の利用可能なシステム・クロックを使用して、秒単位で現在のチックを返すクロックを取得します。
`abstract Clock`	`withZone(ZoneId zone)`	別のタイムゾーンを使って、このクロックのコピーを返します。

クラス java.lang.Objectで宣言されたメソッド

clone、finalize、getClass、notify、notifyAll、toString、wait、wait、wait

コンストラクタの詳細
- Clock
  
  protected Clock()
  
  サブクラスでアクセスできるコンストラクタです。
メソッドの詳細
- systemUTC
  
  public static Clock systemUTC()
  
  利用できる最適なシステム・クロックを使用し、UTCタイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。
  日付または時間なしの現在の時点が必要なときは、systemDefaultZone()ではなくこのクロックを使用するようにしてください。
  このクロックは最良の利用可能なシステム・クロックに基づいています。これは、System.currentTimeMillis()、またはより分解能の高いクロック(利用できる場合)を使用します。
  時点から日付または時間への変換にはUTCタイムゾーンが使用されます。
  返される実装は、不変、スレッドセーフおよびSerializableです。これはsystem(ZoneOffset.UTC)と同等です。
  
  戻り値:
  
  UTCゾーンで利用可能な最良のシステム・クロックを使用するクロック、nullでない
- systemDefaultZone
  
  public static Clock systemDefaultZone()
  
  利用できる最適なシステム・クロックを使用し、デフォルト・タイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。
  このクロックは最良の利用可能なシステム・クロックに基づいています。これは、System.currentTimeMillis()、またはより分解能の高いクロック(利用できる場合)を使用します。
  このメソッドを使用すると、デフォルト・タイムゾーンへの依存関係がアプリケーションにハードコードされます。こうなることを避け、可能な場合は常に特定のタイムゾーンを使用することをお薦めします。日付または時間なしの現在の時点が必要な場合は、UTCクロックを使用するようにしてください。
  返される実装は、不変、スレッドセーフおよびSerializableです。これはsystem(ZoneId.systemDefault())と同等です。
  
  戻り値:
  
  デフォルト・ゾーンで利用可能な最良のシステム・クロックを使用するクロック、nullでない
  
  関連項目:
  
  ZoneId.systemDefault()
- system
  
  public static Clock system(ZoneId zone)
  
  最高の利用可能なシステム・クロックを使用して現在の瞬間を返すクロックを取得します。
  このクロックは最良の利用可能なシステム・クロックに基づいています。これは、System.currentTimeMillis()、またはより分解能の高いクロック(利用できる場合)を使用します。
  時点から日付または時間への変換には指定されたタイムゾーンが使用されます。
  返される実装は、不変、スレッドセーフおよびSerializableです。
  
  パラメータ:
  
  zone - 時点を日付/時間に変換するために使用するタイムゾーン、nullでない
  
  戻り値:
  
  指定されたゾーンで利用可能な最良のシステム・クロックを使用するクロック、nullでない
- tickMillis
  
  public static Clock tickMillis(ZoneId zone)
  
  最高の利用可能なシステム・クロックを使用して、ミリ秒単位で現在の時刻を返すクロックを取得します。
  このクロックは、ミリ秒に切り捨てられたナノ秒フィールドを常に持ちます。これによりミリ秒単位で目に見える時間が確実に刻み込まれます。基本となるクロックは最良の利用可能なシステム・クロックで、system(ZoneId)を使用することと同等です。
  実装は、パフォーマンス上の理由からキャッシュ戦略を使用できます。したがって、このクロックを介して観測されるミリ秒の開始は、基礎クロックを介して直接観測されるミリ秒より遅くなる可能性があります。
  返される実装は、不変、スレッドセーフおよびSerializableです。これはtick(system(zone), Duration.ofMillis(1))と等価です。
  
  パラメータ:
  
  zone - 時点を日付/時間に変換するために使用するタイムゾーン、nullでない
  
  戻り値:
  
  指定されたゾーン(ミリ秒単位ではない)を使用してミリ秒単位でティックするクロック
  
  導入されたバージョン:
  
  9
- tickSeconds
  
  public static Clock tickSeconds(ZoneId zone)
  
  最高の利用可能なシステム・クロックを使用して、秒単位で現在のチックを返すクロックを取得します。
  このクロックでは常に、ナノ秒フィールドがゼロに設定されます。これにより、表示される時間が整数秒単位でティックすることが保証されます。基本となるクロックは最良の利用可能なシステム・クロックで、system(ZoneId)を使用することと同等です。
  実装は、パフォーマンス上の理由からキャッシュ戦略を使用できます。その場合、このクロック経由で観察される秒の開始は、基礎となるクロック経由で直接観察される秒よりも遅れる可能性があります。
  返される実装は、不変、スレッドセーフおよびSerializableです。これはtick(system(zone), Duration.ofSeconds(1))と同等です。
  
  パラメータ:
  
  zone - 時点を日付/時間に変換するために使用するタイムゾーン、nullでない
  
  戻り値:
  
  指定されたゾーンを使用して整数秒単位でティックするクロック、nullでない
- tickMinutes
  
  public static Clock tickMinutes(ZoneId zone)
  
  最高の利用可能なシステム・クロックを使用して、分単位で現在の時刻を返す時計を取得します。
  このクロックでは常に、ナノ秒および秒フィールドがゼロに設定されます。これにより、表示される時間が整数分単位でティックすることが保証されます。基本となるクロックは最良の利用可能なシステム・クロックで、system(ZoneId)を使用することと同等です。
  実装は、パフォーマンス上の理由からキャッシュ戦略を使用できます。その場合、このクロック経由で観察される分の開始は、基礎となるクロック経由で直接観察される分よりも遅れる可能性があります。
  返される実装は、不変、スレッドセーフおよびSerializableです。これはtick(system(zone), Duration.ofMinutes(1))と同等です。
  
  パラメータ:
  
  zone - 時点を日付/時間に変換するために使用するタイムゾーン、nullでない
  
  戻り値:
  
  指定されたゾーンを使用して整数分単位でティックするクロック、nullでない
- tick
  
  public static Clock tick(Clock baseClock, Duration tickDuration)
  
  指定されたデュレーションの直近値に切り捨てられたインスタントを指定されたクロックから返すクロックを取得します。
  このクロックは、指定されたデュレーションでのみティックします。つまり、デュレーションが0.5秒の場合、クロックは0.5秒に切り捨てられた時点を返します。
  ティック・デュレーションは正である必要があります。整数ミリ秒より小さい部分がある場合、整数デュレーションは1秒に割り振る(余りなし)必要があります。通常のすべてのティック・デュレーションは、これらの条件(時、分、秒およびミリ秒の倍数、さらに知覚可能なナノ秒デュレーション(20ナノ秒、250,000ナノ秒、500,000ナノ秒など)を含みます)に一致します。
  0または1ナノ秒デュレーションには切捨て効果はありません。これらのいずれかを渡すと基礎となるクロックが返されます。
  実装は、パフォーマンス上の理由からキャッシュ戦略を使用できます。そのため、このクロック経由で観察される、要求されたデュレーションの開始は、基礎となるクロック経由で直接観察される分よりも遅れる可能性があります。
  返される実装は、不変、スレッドセーフおよびSerializableです(ベース・クロックが存在する場合)。
  
  パラメータ:
  
  baseClock - ティックするクロックの基礎となるベース・クロック、nullでない
  
  tickDuration - 表示される各ティックのデュレーション、負でない、nullでない
  
  戻り値:
  
  デュレーションの整数単位でティックするクロック、nullでない
  
  例外:
  
  IllegalArgumentException - デュレーションが負の場合、またはデュレーションに整数ミリ秒よりも小さい部分がある(整数デュレーションを1秒に割り振れない)場合
  
  ArithmeticException - デュレーションが大きすぎてナノとして表現できない場合
- fixed
  
  public static Clock fixed(Instant fixedInstant, ZoneId zone)
  
  常に同じインスタントを返すクロックを取得します。
  このクロックは単純に指定された時点を返します。つまり、従来の意味でのクロックではありません。これの主要ユース・ケースはテスティングです。テストが現在のクロックに依存しないことを、fixedクロックが保証します。
  返される実装は、不変、スレッドセーフおよびSerializableです。
  
  パラメータ:
  
  fixedInstant - クロックとして使用するインスタント、nullでない
  
  zone - 時点を日付/時間に変換するために使用するタイムゾーン、nullでない
  
  戻り値:
  
  常に同じ時点を返すクロック、nullでない
- offset
  
  public static Clock offset(Clock baseClock, Duration offsetDuration)
  
  指定されたデュレーションを加算して指定されたクロックからインスタントを返すクロックを取得します
  このクロックは別のクロックをラップし、指定されたデュレーションだけ後の時点を返します。デュレーションが負の場合、時点は現在の日付/時間より前になります。これの主要ユース・ケースは、将来または過去での実行をシミュレートすることです。
  デュレーション・ゼロは、オフセット効果なしです。ゼロを渡すと、基礎となるクロックが返されます。
  返される実装は、不変、スレッドセーフおよびSerializableです(ベース・クロックが存在する場合)。
  
  パラメータ:
  
  baseClock - デュレーションを追加するベース・クロック、nullでない
  
  offsetDuration - 追加するデュレーション、nullでない
  
  戻り値:
  
  デュレーションが追加された、クロックベース・クロックに基づくクロック、nullでない
- getZone
  
  public abstract ZoneId getZone()
  
  日付と時間を作成するために使用されるタイムゾーンを取得します。
  クロックは通常、現在の時点を取得してから、タイムゾーンを使用してそれを日付または時間に変換します。このメソッドは使用されるタイムゾーンを返します。
  
  戻り値:
  
  時点を解釈するために使用されるタイムゾーン、nullでない
- withZone
  
  public abstract Clock withZone(ZoneId zone)
  
  別のタイムゾーンを使って、このクロックのコピーを返します。
  クロックは通常、現在の時点を取得してから、タイムゾーンを使用してそれを日付または時間に変換します。このメソッドは、プロパティが似ていて異なるタイムゾーンを使用するクロックを返します。
  
  パラメータ:
  
  zone - 変更先のタイムゾーン、null以外
  
  戻り値:
  
  指定されたタイムゾーンの、このクロックに基づくクロック、nullでない
- millis
  
  public long millis()
  
  クロックの現在の時点をミリ秒で取得します。
  これは、1970-01-01T00:00Z (UTC)から測定された、ミリ秒ベースの時点を返します。これは、System.currentTimeMillis()の定義と同等です。
  ほとんどのアプリケーションは、生のミリ秒値ではなく時系列のインスタントを表す場合は、このメソッドを使用せずInstantを使用することをお薦めします。このメソッドは、オブジェクトの作成が受け入れられない負荷の高いユース・ケースで、クロックを使用できるように提供されています。
  デフォルト実装は現在、instant()を呼び出します。
  
  戻り値:
  
  1970-01-01T00:00Z (UTC)のJava epochから測定された、このクロックからの現在のミリ秒時点、nullでない
  
  例外:
  
  DateTimeException - 時点を取得できない場合、ほとんどの実装ではスローされない
- instant
  
  public abstract Instant instant()
  
  クロックの現在の時点を取得します。
  これは、クロックによって定義された現在の時点を表す時点を返します。
  
  戻り値:
  
  このクロックからの現在の時点、nullでない
  
  例外:
  
  DateTimeException - 時点を取得できない場合、ほとんどの実装ではスローされない
- equals
  
  public boolean equals(Object obj)
  
  このクロックがもう一方のクロックと等しいかどうかを確認します。
  クロックは、その状態に基づいてequalsを比較し、Object.equals(java.lang.Object)の規定を満たすように、このメソッドをオーバーライドするはずです。オーバーライドされない場合、動作はObject.equals(java.lang.Object)によって定義されます。
  
  オーバーライド:
  
  equals 、クラス: Object
  
  パラメータ:
  
  obj - チェックするオブジェクト、nullはfalseを返す
  
  戻り値:
  
  これが他方のクロックと等しい場合はtrue
  
  関連項目:
  
  Object.hashCode()、HashMap
- hashCode
  
  public int hashCode()
  
  このクロックのハッシュ・コード。
  クロックは、その状態に基づいて、Object.hashCode()の規定を満たすように、このメソッドをオーバーライドするはずです。オーバーライドされない場合、動作はObject.hashCode()によって定義されます。
  
  オーバーライド:
  
  hashCode 、クラス: Object
  
  戻り値:
  
  適切なハッシュ・コード
  
  関連項目:
  
  Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

クラスClock

コンストラクタのサマリー

メソッドのサマリー

クラス java.lang.Objectで宣言されたメソッド

コンストラクタの詳細

メソッドの詳細