パッケージ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
-
クラスのサマリー クラス 説明 Clock タイムゾーンを使用して現在の時点、日付および時間へのアクセスを提供するクロックです。Duration 時間ベースの時間(「34.5秒」など)。Instant 時系列の時点。LocalDate ISO-8601暦体系のタイムゾーンのない日付、2007-12-03
など。LocalDateTime ISO-8601暦体系のタイムゾーンのない日付/時間、2007-12-03T10:15:30
など。LocalTime ISO-8601暦体系における、タイムゾーンのない時間(10:15:30
など)。MonthDay ISO-8601暦体系における月日(--12-03
など)。OffsetDateTime ISO-8601暦体系におけるUTC/グリニッジからのオフセット付きの日時(2007-12-03T10:15:30+01:00
など)。OffsetTime ISO-8601暦体系におけるUTC/グリニッジからのオフセット付きの時間(10:15:30+01:00
など)。Period ISO-8601暦体系における日付ベースの時間の量(「2年3か月と4日」など)。Year ISO-8601暦体系における年(2007
など)。YearMonth ISO-8601暦体系における年月(2007-12
など)。ZonedDateTime ISO-8601の暦体系によるタイムゾーン付きの日付/時間です(2007-12-03T10:15:30+01:00 Europe/Paris
など)。ZoneId タイムゾーンID(ヨーロッパ/パリ
など)。ZoneOffset グリニッジ/UTCからのタイムゾーン・オフセット(+02:00
など)。 -
例外のサマリー Exception 説明 DateTimeException 日付/時間の計算時の問題を示すために使用される例外。