モジュール java.base

パッケージjava.time

日付、時間、インスタント、デュレーションのメインAPI。

ここで定義されるクラスは主要な日付/時間の概念(時点、デュレーション、日付、時間、タイムゾーン、期間など)を表します。 これらは、先発グレゴリオ暦のルールに従う事実上の世界暦であるISO暦体系に基づいています。 すべてのクラスは不変で、スレッドセーフです。

各日付/時間インスタンスは、APIによって適宜使用可能になるフィールドで構成されます。 フィールドへのより低レベルなアクセスについては、java.time.temporalパッケージを参照してください。 各クラスには、すべての種類の日付/時間を出力および解析するためのサポートが含まれます。 カスタマイズ・オプションについては、java.time.formatパッケージを参照してください。

java.time.chronoパッケージには、暦に依存しないAPIであるChronoLocalDate、ChronoLocalDateTime、ChronoZonedDateTimeおよびEraが含まれています。 これは、ローカライズされた暦を使用するために必要なアプリケーションで使用するためのものです。 このパッケージからのISO-8601日付/時間クラスは、アプリケーションがシステム境界をまたがって(データベース、ネットワーク全体など)使用することが推奨されます。 暦に依存しないAPIは、ユーザーとの相互作用のために予約することをお薦めします。

日付と時刻

Instantは本質的に数値型のタイムスタンプです。 現在のInstantはClockから取得できます。 これは、特定時点のロギングおよび永続性に役立ち、従来はSystem.currentTimeMillis()からの結果の保存に関連付けられていました。

LocalDateは日付を時間なしで格納します。 これは「2010-12-03」のような日付を保存し、誕生日を保存するために使用できます。

LocalTimeは時間を日付なしで保存します。 これは「11:30」のような時間を保存し、開店時間や閉店時間を保存するために使用できます。

LocalDateTimeは日付/時間を保存します。 これは「2010-12-03T11:30」のような日付/時間を保存します。

ZonedDateTimeは日付/時間をタイムゾーン付きで保存します。 これは、ZoneId(「ヨーロッパ/パリ」など)を考慮して日付/時間の正確な計算を実行する場合に役立ちます。 可能であれば、タイムゾーンがない単純なクラスを使用することをお薦めします。 タイムゾーンを広範に使用すると、アプリケーションがかなり複雑になる傾向があります。

デュレーションと期間

このAPIは日付/時間以外に、時間の期間およびデュレーションを保存することもできます。 Durationは、時系列に沿った単純な時間単位(ナノ秒)です。 Periodは人間にとって意味のある単位(年や日など)で時間を表します。

追加の値タイプ

Monthは1つの月を自動的に保存します。 これは、単一の「月」(「DECEMBER」など)を重複せずに保存します。

DayOfWeekは1つの「曜日」を自動的に保存します。 これは、単一の「曜日」(「TUESDAY」など)を重複せずに保存します。

Yearは1つの年を自動的に保存します。 これは、単一の年(「2010」など)を重複せずに保存します。

YearMonthは日または時間なしで年月を保存します。 これは「2010-12」のような年月を保存し、クレジット・カードの有効期限に使用できます。

MonthDayは年または時間なしで月日を保存します。 これは、月と「月の日」(「--12-03」など)を保存し、年の保存なしで誕生日のような毎年のイベントを保存するために使用できます。

OffsetTimeは時間およびUTCからのオフセットを日付なしで保存します。 これは「11:30+01:00」のような日付を保存します。 ZoneOffsetの形式は「+01:00」です。

OffsetDateTimeは日付/時間およびUTCからのオフセットを保存します。 これは「2010-12-03T11:30+01:00」のような日付/時間を保存します。 これは、XMLメッセージおよびその他の永続性形式で見つかることがありますが、完全なタイムゾーンよりも少ない情報が含まれます。

パッケージの仕様

他で指定がない場合、このパッケージの任意のクラスまたはインタフェースのメソッドまたはコンストラクタにnull引数を渡すとNullPointerExceptionがスローされます。 nullの動作のサマリーとしては、Javadocの「@param」の定義が使用されます。 各メソッドのドキュメントに「@throws NullPointerException」は明記されていません。

すべての計算で数値のオーバーフローをチェックし、ArithmeticExceptionまたはDateTimeExceptionをスローするようにしてください。

設計上のノート(規準ではありません)

このAPIはnullを早期に拒否し、この動作について明確にするために設計されています。 重要な例外は、オブジェクトを受け取りブール値を返し(チェックまたは検証のため)、nullの場合は一般的にfalseを返すメソッドです。

このAPIは、メインの高レベルAPIで妥当な場合に型保証されるように設計されています。 したがって、様々な概念の日付、時間、および日付/時間、さらにオフセットおよびタイムゾーン用のバリアントために個別のクラスが用意されています。 クラスが多いように見えるかもしれませんが、ほとんどのアプリケーションは5つの日付/時間タイプだけで始めることができます。

  • Instant - タイムスタンプ
  • LocalDate - 日付。時間、あるいはオフセットまたはタイムゾーンへの参照なし
  • LocalTime - 時間。日付、あるいはオフセットまたはタイムゾーンへの参照なし
  • LocalDateTime - 日付と時間の組合せ、オフセットまたはタイムゾーンなし
  • ZonedDateTime - 完全な日付/時間と、タイムゾーンおよびUTC/グリニッジからの解決されたオフセット

Instantは、java.util.Dateにもっとも近い同等のクラスです。 ZonedDateTimeは、java.util.GregorianCalendarにもっとも近い同等のクラスです。

可能であれば、アプリケーションはドメインをより適切にモデル化するために、LocalDate、LocalTimeおよびLocalDateTimeを使用することをお薦めします。 たとえば、誕生日はコードLocalDateに保存することをお薦めします。 タイムゾーン(「ヨーロッパ/パリ」など)を使用すると、計算の複雑さが増すことを覚えておいてください。 多くのアプリケーションは、ユーザー・インタフェース(UI)・レイヤーで追加されたタイムゾーンとともに、LocalDate、LocalTimeおよびInstantでのみ記述できます。

オフセット・ベースの日付/時間型であるOffsetTimeとOffsetDateTimeは、主にネットワーク・プロトコルおよびデータベース・アクセスで使用するためのものです。 たとえば、ほとんどのデータベースは「ヨーロッパ/パリ」のようなタイムゾーンを自動的に保存できませんが、「+02:00」のようなオフセットを保存できます。

日付のもっとも重要な下位部分のためのクラスも提供されています。たとえば、Month、DayOfWeek、Year、YearMonth、MonthDayなどです。 これらは、より複雑な日付/時間概念をモデル化するために使用できます。 たとえば、YearMonthはクレジット・カードの有効期限を表すために役立ちます。

日付の様々な面を表すクラスはたくさんありますが、時間の様々な面を処理するクラスは比較的少ないことに注意してください。 論理的な結論のために型保証に従うと、時-分、時-分-秒、および時-分-秒-ナノ秒用のクラスになったでしょう。 論理的には純粋ですが、日付と時間の組合せによりクラスの数が約3倍になってしまうため、実用的な選択肢ではありませんでした。 したがって、あらゆる時間精度に対してLocalTimeが使用されます(精度が低いことを暗示するために、ゼロが使用されます)。

究極的な結論のために完全な型保証に従うと、HourOfDay用のクラスやDayOfMonth用のクラスなど、日付/時間のフィールドごとに個別のクラスが必要ではないかと主張されるかもしれません。 このアプローチは試されましたが、Java言語では極端に複雑になり、使いにくくなってしまいました。 同様の問題が期間についても発生します。 期間単位ごとに個別のクラス(Years用の型やMinutes用の型など)の必要性も主張されるかもしれません。 しかし、これは、多くのクラスと、型変換の問題を発生させます。 したがって、提供されている日付/時間型のセットは純粋性と実用性の落とし所です。

このAPIは、メソッド数については比較的大きくなっています。 このことは、一貫性があるメソッド接頭辞を使用することによって管理可能にしています。

  • of - staticファクトリ・メソッド
  • parse - 解析に的を絞ったstaticファクトリ・メソッド
  • get - あるものの値を取得する
  • is - あるものがtrueかどうかをチェックする
  • with - setterと同等な不変メソッド
  • plus - オブジェクトにある量を追加する
  • minus - オブジェクトからある量を引く
  • to - このオブジェクトを別の型に変換する
  • at - このオブジェクトと別のオブジェクトを結合する(date.atTime(time)など)

暦体系が複数の場合は、設計に面倒な問題が増えます。 まず、ほとんどのユーザーは標準のISO暦体系を望んでいます。 そのため、主要なクラスはISOだけです。 次に、ISO以外の暦体系を望むユーザーのほとんどは、ユーザー対話のためにそれを望んでいます。つまり、これはUIローカリゼーションの問題です。 そのような場合は、日付/時間オブジェクトをISOオブジェクトとしてデータ・モデルおよび永続ストレージに保持し、表示のためだけにローカル暦に変換したりローカル暦から変換することをお薦めします。 この暦体系はユーザー設定に別個に保管されます。

一方、次のようなユース・ケースが存在します。つまり、ユーザーがアプリケーション全体で暦体系の日付を自由裁量で決めて保管および使用する必要があると考えている場合です。 これはChronoLocalDateによってサポートされますが、使用する前にこのインタフェースのJavadocで関連するすべての注意事項を読むことが重要です。 要するに、複数の暦体系の間で一般的な相互作用を必要とするアプリケションは、ISOカレンダだけを使用するアプリケーションとはかなり異なる方法で通常は記述する必要があります。こうした事情があるので、ほとんどのアプリケーションではISOのみを使用し、ChronoLocalDateを使用しないことをお薦めします。

このAPIは、ユーザーの拡張使用に対応するようにも設計されています。時間の計算にはさまざまな方法があるためです。 フィールドおよび単位のAPIは、TemporalAccessorおよびTemporal経由でアクセスされることで、アプリケーションにかなりの柔軟性をもたらします。 さらに、TemporalQueryおよびTemporalAdjusterインタフェースにより日付を詳細に操作できるので、コードは業務要件に近づいていくことができます。 

   LocalDate customerBirthday = customer.loadBirthdayFromDatabase();
   LocalDate today = LocalDate.now();
   if (customerBirthday.equals(today)) {
     LocalDate specialOfferExpiryDate = today.plusWeeks(2).with(next(FRIDAY));
     customer.sendBirthdaySpecialOffer(specialOfferExpiryDate);
   }
導入されたバージョン:
1.8