java.timeを使いこなす！Javaの日時操作の決定版ガイド

Java 8が2014年にリリースされるまで、Java開発者は日付と時刻の扱いに長年頭を悩ませてきました。その原因は、初期のJavaから提供されていたjava.util.Dateクラスと、その後追加されたjava.util.Calendarクラスにありました。

これらの問題を解決するために、JSR 310という仕様改善提案のもとで、全く新しい日時APIが開発されました。それが、Java 8で標準搭載された`java.time`パッケージです。

`java.time` APIは、以下のような優れた設計思想に基づいています。

`java.time`の最も基本的なクラスは、タイムゾーン情報を持たないローカルな日付・時刻を扱います。

`LocalDate` – 日付のみを扱う

`LocalDate`は、タイムゾーン情報を含まない「年月日」を表現するクラスです。誕生日や記念日など、時刻が関係ない日付を扱うのに適しています。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalDate;
import java.time.Month;

public class LocalDateExample {
    public static void main(String[] args) {
        // 1. 現在の日付を取得
        LocalDate today = LocalDate.now();
        System.out.println("今日の日付: " + today); // 例: 2025-07-12

        // 2. 特定の日付を生成
        LocalDate specificDate = LocalDate.of(2025, Month.DECEMBER, 25);
        System.out.println("特定の日付: " + specificDate); // 2025-12-25

        // 3. 日付の計算 (イミュータブルなので新しいインスタンスが返る)
        LocalDate nextWeek = today.plusWeeks(1);
        System.out.println("一週間後の日付: " + nextWeek);

        LocalDate previousMonth = today.minusMonths(1);
        System.out.println("一ヶ月前の日付: " + previousMonth);

        // 4. 年や月、日を取得
        int year = today.getYear();
        Month month = today.getMonth(); // Month列挙型
        int dayOfMonth = today.getDayOfMonth();
        System.out.println("年: " + year + ", 月: " + month.getValue() + ", 日: " + dayOfMonth);
    }
}

`LocalTime` – 時刻のみを扱う

`LocalTime`は、日付情報を含まない「時分秒ナノ秒」を表現します。開店時間やアラームの時刻設定など、日付が関係ない時刻の表現に利用します。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalTime;

public class LocalTimeExample {
    public static void main(String[] args) {
        // 1. 現在の時刻を取得
        LocalTime now = LocalTime.now();
        System.out.println("現在の時刻: " + now); // 例: 22:10:30.123456789

        // 2. 特定の時刻を生成
        LocalTime lunchTime = LocalTime.of(12, 30);
        System.out.println("ランチタイム: " + lunchTime); // 12:30

        // 3. 時刻の計算
        LocalTime after30Minutes = now.plusMinutes(30);
        System.out.println("30分後の時刻: " + after30Minutes);

        // 4. 時、分、秒を取得
        int hour = now.getHour();
        int minute = now.getMinute();
        System.out.println("時: " + hour + ", 分: " + minute);
    }
}

`LocalDateTime` – 日付と時刻の両方を扱う

`LocalDateTime`は、`LocalDate`と`LocalTime`を組み合わせたもので、タイムゾーン情報を含まない「年月日・時分秒ナノ秒」を表現します。 会議の予約やシステムのログ記録など、特定の日時をタイムゾーンなしで扱う場合に最もよく使われるクラスです。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalDateTime;
import java.time.Month;

public class LocalDateTimeExample {
    public static void main(String[] args) {
        // 1. 現在の日時を取得
        LocalDateTime currentDateTime = LocalDateTime.now();
        System.out.println("現在の日時: " + currentDateTime);

        // 2. 特定の日時を生成
        LocalDateTime eventDateTime = LocalDateTime.of(2026, Month.JANUARY, 1, 10, 0, 0);
        System.out.println("イベント日時: " + eventDateTime);

        // 3. LocalDateとLocalTimeから生成
        LocalDate datePart = LocalDate.of(2025, 8, 15);
        LocalTime timePart = LocalTime.of(19, 0);
        LocalDateTime combinedDateTime = LocalDateTime.of(datePart, timePart);
        System.out.println("結合した日時: " + combinedDateTime);

        // 4. 日時の計算
        LocalDateTime twoHoursLater = currentDateTime.plusHours(2);
        System.out.println("2時間後の日時: " + twoHoursLater);

        // 5. 日付部分や時刻部分の抽出
        LocalDate extractedDate = currentDateTime.toLocalDate();
        LocalTime extractedTime = currentDateTime.toLocalTime();
        System.out.println("抽出した日付: " + extractedDate);
        System.out.println("抽出した時刻: " + extractedTime);
    }
}

グローバルなアプリケーションや、異なる地域のユーザーを相手にするシステムでは、タイムゾーンの考慮が不可欠です。`java.time`では、`ZonedDateTime`クラスがこの役割を担います。

`ZonedDateTime`は、`LocalDateTime`に加えてタイムゾーン情報（例: `Asia/Tokyo`）と、UTCからの時差（オフセット、例: `+09:00`）を保持します。これにより、サマータイム（夏時間）の変更などを自動的に処理できます。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;

public class ZonedDateTimeExample {
    public static void main(String[] args) {
        // 1. 特定のタイムゾーンで現在日時を取得
        ZoneId tokyoZone = ZoneId.of("Asia/Tokyo");
        ZonedDateTime tokyoTime = ZonedDateTime.now(tokyoZone);
        System.out.println("東京の現在日時: " + tokyoTime);

        ZoneId londonZone = ZoneId.of("Europe/London");
        ZonedDateTime londonTime = ZonedDateTime.now(londonZone);
        System.out.println("ロンドンの現在日時: " + londonTime);

        // 2. LocalDateTimeにZoneIdを付与して生成
        LocalDateTime localDateTime = LocalDateTime.of(2025, 7, 20, 10, 0);
        ZonedDateTime eventInTokyo = ZonedDateTime.of(localDateTime, tokyoZone);
        System.out.println("東京でのイベント日時: " + eventInTokyo);

        // 3. タイムゾーンの変換
        // withZoneSameInstantは、同じ「瞬間」を別のタイムゾーンで表現します。
        // 東京の午前10時は、ロンドンの何時かを計算できます。
        ZonedDateTime eventInLondon = eventInTokyo.withZoneSameInstant(londonZone);
        System.out.println("同じ瞬間のロンドン日時: " + eventInLondon);

        // withZoneSameLocalは、ローカル日時を維持したままタイムゾーンを変更します。
        // 各都市で「現地時間の10時」にイベントを開始する場合などに使えます。
        ZonedDateTime localEventInLondon = eventInTokyo.withZoneSameLocal(londonZone);
        System.out.println("現地時間10時のロンドン日時: " + localEventInLondon);
    }
}

`withZoneSameInstant`は、国際電話の時間を調整するようなケースで非常に強力です。一方、`withZoneSameLocal`は、各拠点でのローカル時間を基準にした処理で役立ちます。

「2つの日時の間の時間」や「ある時点から3週間後」といった時間の長さを扱うために、`java.time`は2つの専用クラスを提供します。これらは明確に使い分ける必要があります。

`Duration` の使用例

<?xml version="1.0" encoding="UTF-8"?>
import java.time.Duration;
import java.time.LocalDateTime;
import java.time.LocalTime;

public class DurationExample {
    public static void main(String[] args) {
        LocalDateTime start = LocalDateTime.of(2025, 1, 1, 10, 0, 0);
        LocalDateTime end = LocalDateTime.of(2025, 1, 1, 12, 30, 15);

        // 1. 2つのLocalDateTime間のDurationを計算
        Duration duration = Duration.between(start, end);
        System.out.println("Duration: " + duration); // PT2H30M15S (ISO-8601形式)

        // 2. 時間、分、秒単位で取得
        long hours = duration.toHours();
        long minutes = duration.toMinutes();
        System.out.println("合計時間: " + hours); // 2
        System.out.println("合計分: " + minutes); // 150

        // 3. 特定の単位でDurationを生成
        Duration twoHours = Duration.ofHours(2);
        LocalTime time = LocalTime.of(9, 0);
        LocalTime newTime = time.plus(twoHours);
        System.out.println("2時間後の時刻: " + newTime); // 11:00
    }
}

`Period` の使用例

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalDate;
import java.time.Period;

public class PeriodExample {
    public static void main(String[] args) {
        LocalDate startDate = LocalDate.of(2025, 2, 10);
        LocalDate endDate = LocalDate.of(2026, 4, 25);

        // 1. 2つのLocalDate間のPeriodを計算
        Period period = Period.between(startDate, endDate);
        System.out.println("Period: " + period); // P1Y2M15D (ISO-8601形式)

        // 2. 年、月、日の単位で取得
        int years = period.getYears();
        int months = period.getMonths();
        int days = period.getDays();
        System.out.println(years + "年 " + months + "ヶ月 " + days + "日");

        // 3. 特定の単位でPeriodを生成
        Period threeWeeks = Period.ofWeeks(3);
        LocalDate today = LocalDate.now();
        LocalDate afterThreeWeeks = today.plus(threeWeeks);
        System.out.println("3週間後の日付: " + afterThreeWeeks);
    }
}

`Instant`クラスは、人間が直感的に理解しやすい「年月日時分秒」とは異なり、コンピュータにとって扱いやすい単一のタイムライン上の点を表現します。 具体的には、エポック（1970年1月1日 00:00:00 UTC）からの経過時間をナノ秒精度で保持します。

これは、旧来の`java.util.Date`がミリ秒精度で保持していた値と概念的に似ており、主にシステムのタイムスタンプや、イベントの発生順序を記録するような、機械的な時間の扱いに適しています。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;

public class InstantExample {
    public static void main(String[] args) {
        // 1. 現在のInstantを取得 (UTC基準)
        Instant now = Instant.now();
        System.out.println("現在のInstant: " + now);

        // 2. エポック秒から生成
        Instant fromEpochSecond = Instant.ofEpochSecond(1735689600); // 2025-01-01 00:00:00 UTC
        System.out.println("エポック秒から: " + fromEpochSecond);

        // 3. InstantとZonedDateTimeの変換
        ZonedDateTime zonedDateTime = now.atZone(ZoneId.of("Asia/Tokyo"));
        System.out.println("東京時間での表現: " + zonedDateTime);

        Instant fromZonedDateTime = zonedDateTime.toInstant();
        System.out.println("ZonedDateTimeからInstantへ: " + fromZonedDateTime);

        // 4. タイムスタンプとして利用
        long epochMilli = now.toEpochMilli();
        System.out.println("エポックからのミリ秒: " + epochMilli);
    }
}

`Instant`は常にUTC基準であり、タイムゾーン情報を持たないため、タイムゾーンを意識した日時に変換するには`atZone()`メソッドを使って`ZonedDateTime`にする必要があります。

日時オブジェクトを「2025年07月12日」のような特定の書式の文字列に変換したり、その逆を行ったりする処理は非常によく発生します。この役割を担うのが`DateTimeFormatter`クラスです。

`DateTimeFormatter`もイミュータブルでスレッドセーフです。一度フォーマッタを作成すれば、複数のスレッドから安全に利用できます。

書式指定の方法

フォーマッタを作成するには、主に3つの方法があります。

1. 事前定義された定数を使用する: `ISO_LOCAL_DATE` (`2011-12-03`) や `ISO_DATE_TIME` (`2011-12-03T10:15:30`) など、ISO標準形式のフォーマッタが定数として用意されています。
2. パターン文字を使用してカスタム定義する: `ofPattern()`メソッドに`”yyyy/MM/dd HH:mm:ss”`のようなパターン文字列を渡して、独自のフォーマッタを作成します。
3. ローカライズされたスタイルを使用する: `ofLocalizedDate()`などに`FormatStyle`（`FULL`, `LONG`, `MEDIUM`, `SHORT`）を指定して、ロケールに応じたフォーマットを作成します。

フォーマット（日時 → 文字列）とパース（文字列 → 日時）

<?xml version="1.0" encoding="UTF-8"?>
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Locale;

public class DateTimeFormatterExample {
    public static void main(String[] args) {
        LocalDateTime now = LocalDateTime.now();

        // --- フォーマット (日時オブジェクトを文字列に) ---
        // 1. 事前定義フォーマッタ
        String isoFormatted = now.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
        System.out.println("ISOフォーマット: " + isoFormatted);

        // 2. カスタムパターン
        DateTimeFormatter customFormatter1 = DateTimeFormatter.ofPattern("yyyy年MM月dd日(E) HH時mm分ss秒");
        String customFormatted1 = now.format(customFormatter1);
        System.out.println("カスタムフォーマット1: " + customFormatted1); // 例: 2025年07月12日(土) 10時30分55秒

        DateTimeFormatter customFormatter2 = DateTimeFormatter.ofPattern("uuuu/MM/dd");
        System.out.println("カスタムフォーマット2: " + now.format(customFormatter2)); // 例: 2025/07/12

        // 3. ローカライズスタイル
        DateTimeFormatter localizedFormatter = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.FULL)
                                                                  .withLocale(Locale.JAPAN);
        System.out.println("日本ロケール(FULL): " + now.format(localizedFormatter));


        // --- パース (文字列を日時オブジェクトに) ---
        String dateTimeString = "2025/08/20 15:00";
        DateTimeFormatter parser = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm");

        try {
            LocalDateTime parsedDateTime = LocalDateTime.parse(dateTimeString, parser);
            System.out.println("パース結果: " + parsedDateTime);
        } catch (java.time.format.DateTimeParseException e) {
            System.err.println("パースに失敗しました: " + e.getMessage());
        }
    }
}

データベースとの連携

JDBC 4.2以降（Java 8と同時にリリース）では、`PreparedStatement`の`setObject`メソッドと`ResultSet`の`getObject`メソッドを使って、`java.time`の各クラスを直接データベースのカラムにマッピングできます。

• `LocalDate` ↔ `DATE`型
• `LocalTime` ↔ `TIME`型
• `LocalDateTime` ↔ `TIMESTAMP`型
• `OffsetDateTime` ↔ `TIMESTAMP WITH TIME ZONE`型

これにより、面倒な型変換なしに、Javaオブジェクトとデータベース間で日時データをやり取りできます。

旧API (`Date`, `Calendar`) との相互変換

既存のライブラリや古いコードとの互換性のために、旧APIとの変換が必要になることがあります。`Instant`を介して変換するのが最も簡単で確実です。

<?xml version="1.0" encoding="UTF-8"?>
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.util.Date;

public class ConversionExample {
    public static void main(String[] args) {
        // --- Date → LocalDateTime ---
        Date oldDate = new Date();
        Instant instant = oldDate.toInstant();
        LocalDateTime newDateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault());
        System.out.println("DateからLocalDateTimeへ: " + newDateTime);

        // --- LocalDateTime → Date ---
        LocalDateTime now = LocalDateTime.now();
        Instant instantFromNew = now.atZone(ZoneId.systemDefault()).toInstant();
        Date newToOldDate = Date.from(instantFromNew);
        System.out.println("LocalDateTimeからDateへ: " + newToOldDate);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
// 間違ったコード
LocalDate date = LocalDate.of(2025, 1, 1);
date.plusDays(10); // この戻り値を捨ててしまっている！
System.out.println(date); // 結果は "2025-01-01"。date自体の値は変わらない。

// 正しいコード
LocalDate date = LocalDate.of(2025, 1, 1);
LocalDate futureDate = date.plusDays(10); // 新しいインスタンスを受け取る
System.out.println(futureDate); // 結果は "2025-01-11"

Java 8で導入された`java.time` APIは、それまでの日時操作の複雑さや曖昧さを一掃し、堅牢で直感的なプログラミングを可能にしました。

イミュータブルな設計によるスレッドセーフティの確保、目的に応じて使い分ける明確なクラス群、そして流れるようなAPIは、現代のJava開発において必須の知識です。 最初は多くのクラスがあって戸惑うかもしれませんが、`LocalDate`, `LocalDateTime`, `ZonedDateTime`といった中心的なクラスから使い方をマスターすれば、Javaでの日時処理が格段に楽になり、コードの品質も向上するでしょう。