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 を使うことです。