HOWTO · Java
Java Date と LocalDate
このチュートリアルでは、Java での date と localdate の違いを示します。
このページの内容
Java の Date と LocalDate は、異なるものを表します。Date は、ミリ秒精度の時系列上の瞬間を表します。LocalDate は、誕生日のような暦上の日付を表し、時刻やタイムゾーンは含みません。値が特定の瞬間なのか、暦上の日付なのかに応じて選びましょう。
Java の Date と LocalDate の違い
java.util.Date はレガシー型です。保持する値は瞬間を特定しますが、暦上のタイムゾーンは保存しません。書式化したり暦のフィールドに変換したりするとき、その瞬間は指定したタイムゾーン(多くの場合はシステムのデフォルト)で解釈されます。そのため、表示される日付はタイムゾーンによって異なることがあります。
java.time.LocalDate は java.time パッケージの型です。不変で、年・月・日のフィールドを持ちますが、時刻、オフセット、タイムゾーンは含みません。単独では一意の瞬間を特定できません。日数を加算または減算すると、元の値が変わるのではなく、新しい LocalDate が返されます。
| 項目 | java.util.Date |
java.time.LocalDate |
|---|---|---|
| 意味 | 時系列上の瞬間 | 暦上の日付 |
| タイムゾーン | 保存しない。変換または表示時に指定する | なし。瞬間を特定しない |
| 精度 | ミリ秒 | 日単位 |
| 可変性 | 可変 | 不変 |
| 主な用途 | Date を必要とするAPIとの連携 |
誕生日、期限日など、日付のみを扱う値 |
名前に「日付」とあっても、Date は日付のみを表す型ではありません。特定の瞬間に起きる予定を扱う場合は、瞬間を表す型を使い、表示時にタイムゾーンを適用します。見る人の場所にかかわらず同じ日付であるべき業務上の日付には、LocalDate を使います。
Date とレガシーAPIの連携
既存のライブラリやインターフェースでは、今も java.util.Date を受け取ったり返したりすることがあります。その型は互換性が必要な境界で使い、時系列上の瞬間であることを明示するには Instant を使います。Date.toInstant() と Date.from(Instant) で、レガシー型と現代の時刻APIとの間を変換できます。
次の例を実行します。
このセクションのコードと表示されるラベルや出力は英語のままです。
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneId;
import java.util.Date;
public class Main {
public static void main(String[] args) {
Date legacyDate = Date.from(Instant.parse("2024-03-10T00:30:00Z"));
Instant instant = legacyDate.toInstant();
LocalDate dateInNewYork = instant.atZone(ZoneId.of("America/New_York")).toLocalDate();
System.out.println("Instant: " + instant);
System.out.println("New York date: " + dateInNewYork);
}
}
Instant: 2024-03-10T00:30:00Z
New York date: 2024-03-09
このプログラムは固定の瞬間から始め、レガシーAPI用に Date に変換した後、Instant に戻します。ニューヨークのタイムゾーンを適用すると、その場所での暦上の日付が決まります。以下は、提示された実行結果です。
Date が表示に使ったタイムゾーンを保持すると考えてはいけません。同じ瞬間でも、タイムゾーンが異なれば現地の日付が異なる場合があります。既存APIに合わせる際、暦上の日付が必要な箇所では、変換に使うタイムゾーンを明示してください。
LocalDate の作成と使用
システムのデフォルトのタイムゾーンで現在の日付を取得するには LocalDate.now() を使います。特定の場所の日付が必要なら ZoneId を渡します。タイムゾーンによって返される暦上の日付が決まり、返された LocalDate 自体にそのタイムゾーンは保持されません。日付が既知の場合は LocalDate.of(year, month, day) を使います。入力がエポックからの日数、または年内の日番号で表される場合は、ofEpochDay と ofYearDay も利用できます。
次の例を実行します。
このセクションのコードと表示されるラベルや出力は英語のままです。
import java.time.LocalDate;
import java.time.Month;
import java.time.ZoneId;
public class Main {
public static void main(String[] args) {
LocalDate todayInTokyo = LocalDate.now(ZoneId.of("Asia/Tokyo"));
LocalDate dueDate = LocalDate.of(2025, Month.JANUARY, 15);
LocalDate epochDay = LocalDate.ofEpochDay(300);
LocalDate hundredthDay = LocalDate.ofYearDay(2024, 100);
System.out.println("Tokyo date: " + todayInTokyo);
System.out.println("Due date: " + dueDate);
System.out.println("Epoch day 300: " + epochDay);
System.out.println("Day 100 of 2024: " + hundredthDay);
}
}
Tokyo date: 2026-11-04
Due date: 2025-01-15
Epoch day 300: 1970-10-28
Day 100 of 2024: 2024-04-09
LocalDate.now(ZoneId) は、指定したタイムゾーンの日付を取得する有効な方法です。マシンのデフォルトとは異なる業務用タイムゾーンで動作するサービスに役立ちます。of で作成した日付は明示的で安定していますが、now の結果は実行時の時計とタイムゾーンに依存します。上記の東京の日付は、提示された実行結果にある現在日付の行を反映しています。
Date と LocalDate の選び方
値が誕生日、請求日、期限日のように、意味のある時刻を伴わない暦上の日付なら LocalDate を使います。何かがいつ起きたかを表す値には、瞬間を保持する型を使います。特定の場所での現地の日付や時刻が必要な場合は、明示した ZoneId を使ってその瞬間を変換します。
レガシーAPIが必要とする場合は Date を使い、新しい日付のみの処理では主な表現として使うのではなく、APIとの境界で変換します。要点は、暦上の日付には LocalDate、特定の瞬間には瞬間を保持する型、旧式のインターフェースとの互換性には Date を使うことです。