Joda-Time徹底解説：Javaの日付と時刻を直感的に扱う

この記事では、Javaにおける日付と時刻の操作を劇的に改善したライブラリ「Joda-Time」について、その詳細な使い方を解説します。Java 8以前のプロジェクトで日付操作に悩んだことがある方や、Joda-Timeの思想がどのように現代のJavaに受け継がれているかを知りたい方にとって、必見の内容です。

Javaの初期バージョンから提供されていたjava.util.Dateやjava.util.Calendarクラスは、多くの開発者にとって悩みの種でした。これらのクラスには、以下のような根深い問題が存在していました。

• 可変 (Mutable) であること: Dateオブジェクトの状態が変更可能であるため、メソッドに渡したオブジェクトが意図せず変更される可能性があり、バグの温床となっていました。特にマルチスレッド環境では、スレッドセーフ性を担保するための追加のコーディングが必要でした。
• APIが直感的でないこと: 月の表現が0から始まる（1月が0、2月が1…）など、直感に反する仕様が多く存在しました。また、日付の計算を行うためのAPIが非常に貧弱で、複雑な処理を実装するのが困難でした。
• タイムゾーンの扱いにくさ: タイムゾーンの処理が複雑で、間違いやすい構造になっていました。

これらの問題を解決するために登場したのがJoda-Timeです。Joda-Timeは、Java SE 8より前の時代において、Javaの日付時刻処理のデファクトスタンダード（事実上の標準）となりました。

Joda-Timeの主な特徴

Joda-Timeは、以下の優れた特徴によって、多くの開発者から支持されました。

• 不変性 (Immutability): Joda-Timeの主要なクラスはすべて不変（Immutable）です。これにより、オブジェクトの状態が変わらないことが保証され、スレッドセーフなコードを容易に記述できます。日付計算などの操作を行うと、必ず新しいオブジェクトが返されます。
• 直感的なAPI: plusDays(5)やminusMonths(2)のように、メソッド名から処理内容が明確にわかる、流れるような（fluent）APIを提供しています。
• 豊富なクラス体系: タイムゾーンを含む日時を表すDateTime、日付のみを表すLocalDate、時刻のみを表すLocalTimeなど、用途に応じた的確なクラスが用意されています。
• 包括的な機能セット: 期間や間隔を扱うためのDuration, Period, Intervalなど、日付と時刻に関するあらゆる計算をサポートする機能が網羅されています。

Joda-Timeライブラリを利用するには、プロジェクトのビルド設定ファイルに依存関係を追加する必要があります。ここでは、代表的なビルドツールであるMavenとGradleの設定方法を紹介します。

Mavenの場合 (pom.xml)

pom.xmlファイルの<dependencies>セクションに以下の記述を追加します。

<dependency>
  <groupId>joda-time</groupId>
  <artifactId>joda-time</artifactId>
  <version>2.12.7</version> <!-- 執筆時点での比較的新しい安定バージョン。最新版は公式サイトで確認してください -->
</dependency>

Gradleの場合 (build.gradle)

build.gradleファイルのdependenciesブロックに以下の記述を追加します。

dependencies {
  implementation 'joda-time:joda-time:2.12.7' // 執筆時点での比較的新しい安定バージョン。最新版は公式サイトで確認してください
}

上記の設定を追加し、プロジェクトの依存関係を更新すれば、Joda-Timeの各クラスが利用可能になります。

Joda-Timeには多くのクラスがありますが、まずは中核となる3つのクラスを理解することが重要です。それぞれの役割と基本的な使い方をコード例とともに見ていきましょう。

1. DateTime – タイムゾーンを持つ特定の日時

DateTimeは、タイムゾーン情報を含んだ、時間軸上の一点を表現する最も基本的なクラスです。Java標準のjava.util.Calendarに最も近い存在と言えます。

現在日時の取得

引数なしでインスタンス化すると、システムのデフォルトタイムゾーンに基づいた現在日時が取得できます。

import org.joda.time.DateTime;
import org.joda.time.DateTimeZone;

// 現在日時をシステムのデフォルトタイムゾーンで取得
DateTime now = new DateTime();
System.out.println("現在日時: " + now);

// タイムゾーンを指定して現在日時を取得
DateTime nowInTokyo = new DateTime(DateTimeZone.forID("Asia/Tokyo"));
System.out.println("東京の現在日時: " + nowInTokyo);

特定の日時の生成

年月日や時分秒を指定して、特定の日時オブジェクトを生成できます。

// 年, 月, 日, 時, 分, 秒を指定してDateTimeオブジェクトを生成
DateTime specificDateTime = new DateTime(2025, 7, 20, 10, 30, 0);
System.out.println("特定の日時: " + specificDateTime);

// 文字列からパースして生成 (フォーマットについては次章で詳述)
DateTime fromString = new DateTime("2025-08-15T15:00:00.000+09:00");
System.out.println("文字列から生成: " + fromString);

フィールドへのアクセス

getYear()やgetMonthOfYear()などのメソッドで、日時の各要素（フィールド）にアクセスできます。

DateTime dt = new DateTime(2025, 12, 24, 21, 0, 0);

int year = dt.getYear();             // 年: 2025
int month = dt.getMonthOfYear();   // 月: 12
int day = dt.getDayOfMonth();        // 日: 24
int hour = dt.getHourOfDay();        // 時: 21
int minute = dt.getMinuteOfHour();   // 分: 0
int second = dt.getSecondOfMinute(); // 秒: 0
int dayOfWeek = dt.getDayOfWeek();   // 曜日 (1:月曜, 7:日曜)

System.out.println("年は: " + year);
System.out.println("月は: " + month);
System.out.println("曜日は: " + dayOfWeek + " (" + dt.dayOfWeek().getAsText() + ")"); // 曜日をテキストで取得

2. LocalDate – タイムゾーンを持たない日付

LocalDateは、タイムゾーンや時刻情報を持たず、「日付」のみを表現するクラスです。誕生日や記念日など、時刻が関係ない日付を扱う際に非常に便利です。

import org.joda.time.LocalDate;

// 現在の日付を取得
LocalDate today = new LocalDate();
System.out.println("今日の日付: " + today);

// 特定の日付を生成
LocalDate christmas = new LocalDate(2025, 12, 25);
System.out.println("クリスマス: " + christmas);

// 文字列からパースして生成
LocalDate fromStringDate = new LocalDate("2026-01-01");
System.out.println("文字列から生成した日付: " + fromStringDate);

// LocalDateからDateTimeへの変換 (その日の開始時刻として)
DateTime startOfChristmas = christmas.toDateTimeAtStartOfDay();
System.out.println("クリスマスの開始時刻: " + startOfChristmas);

3. LocalTime – タイムゾーンを持たない時刻

LocalTimeは、日付情報を持たず、「時刻」のみを表現するクラスです。営業開始時間や目覚ましの設定時刻など、日付に依存しない時刻を扱うのに適しています。

import org.joda.time.LocalTime;

// 現在の時刻を取得
LocalTime now = new LocalTime();
System.out.println("現在の時刻: " + now);

// 特定の時刻を生成
LocalTime openingTime = new LocalTime(9, 30, 0); // 9時30分0秒
System.out.println("開店時刻: " + openingTime);

// 文字列からパースして生成
LocalTime fromStringTime = new LocalTime("18:00:00");
System.out.println("文字列から生成した時刻: " + fromStringTime);

アプリケーションでは、日付オブジェクトを人間が読める文字列に変換（フォーマット）したり、逆に文字列を日付オブジェクトに変換（パース）したりする処理が頻繁に発生します。Joda-Timeでは、この処理をDateTimeFormatクラスが担います。

DateTimeFormatはスレッドセーフなので、インスタンスをstaticに保持して使い回すことができ、効率的です。

フォーマット (DateTime → String)

DateTimeFormat.forPattern()で書式パターンを指定し、フォーマッタを作成します。その後、print()メソッドで文字列に変換します。

import org.joda.time.DateTime;
import org.joda.time.format.DateTimeFormat;
import org.joda.time.format.DateTimeFormatter;
import java.util.Locale;

DateTime dt = new DateTime();

// 一般的な書式パターン
DateTimeFormatter fmt_full = DateTimeFormat.forPattern("yyyy/MM/dd HH:mm:ss.SSS");
System.out.println("完全な形式: " + fmt_full.print(dt));

// 和暦や曜日に対応した書式
DateTimeFormatter fmt_jp = DateTimeFormat.forPattern("GGGGy年M月d日(E) H時m分")
                                            .withLocale(Locale.JAPANESE);
System.out.println("日本語形式: " + fmt_jp.print(dt));

// ISO 8601形式 (toString()のデフォルト)
System.out.println("ISO 8601形式: " + dt.toString());

// 事前定義されたスタイルを使用
DateTimeFormatter fmt_style = DateTimeFormat.forStyle("MS").withLocale(Locale.JAPANESE); // Medium-Short style
System.out.println("スタイル形式: " + fmt_style.print(dt));

パース (String → DateTime)

フォーマットと同様にフォーマッタを作成し、parseDateTime()メソッドで文字列をDateTimeオブジェクトに変換します。

String dateString = "2025年10月31日 20時00分";
DateTimeFormatter parser = DateTimeFormat.forPattern("yyyy年M月d日 H時m分")
                                         .withLocale(Locale.JAPANESE);

try {
  DateTime parsedDateTime = parser.parseDateTime(dateString);
  System.out.println("パース結果: " + parsedDateTime);
} catch (IllegalArgumentException e) {
  System.err.println("日付文字列のパースに失敗しました: " + e.getMessage());
}

書式パターンの主な記号

Joda-Timeが最も得意とする分野の一つが、日付と時刻の計算です。不変オブジェクトの特性を活かし、安全かつ直感的に操作できます。

加算・減算

plusXxx() / minusXxx() メソッドチェーンを使うことで、流れるように計算処理を記述できます。

DateTime baseTime = new DateTime(2025, 3, 15, 12, 0, 0);
System.out.println("基準日時: " + baseTime);

// 1年2ヶ月と3日後
DateTime futureTime = baseTime.plusYears(1).plusMonths(2).plusDays(3);
System.out.println("1年2ヶ月と3日後: " + futureTime);

// 90分前
DateTime pastTime = baseTime.minusMinutes(90);
System.out.println("90分前: " + pastTime);

特定フィールドの変更 (with)

withXxx()メソッドを使うと、特定の日付・時刻フィールドの値を変更した新しいオブジェクトを生成できます。これは「調整」と考えることができます。

DateTime base = new DateTime(2025, 7, 22, 13, 45, 30);
System.out.println("ベース: " + base);

// 年を2030年に変更
DateTime withYear = base.withYear(2030);
System.out.println("年を2030年に: " + withYear);

// 日をその月の15日に変更
DateTime withDay = base.withDayOfMonth(15);
System.out.println("日を15日に: " + withDay);

// 時刻を0時0分0秒にリセット (その日の始まり)
DateTime startOfDay = base.withTimeAtStartOfDay();
System.out.println("その日の始まり: " + startOfDay);

プロパティ (Property) を使った高度な操作

property()メソッド（またはyear(), monthOfYear()などのショートカットメソッド）を使うと、各フィールドのプロパティオブジェクトを取得でき、より高度な操作が可能になります。

DateTime dt = new DateTime(2025, 2, 15, 0, 0, 0);
System.out.println("日時: " + dt);

// その月の最終日を取得
DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
System.out.println("2月の最終日: " + lastDayOfMonth);

// 次の月の最初の日を取得
DateTime firstDayOfNextMonth = dt.plusMonths(1).dayOfMonth().withMinimumValue();
System.out.println("次の月の最初の日: " + firstDayOfNextMonth);

// その日付の曜日をロケール指定でテキスト取得
String dayOfWeekText = dt.dayOfWeek().getAsText(Locale.FRENCH);
System.out.println("曜日(フランス語): " + dayOfWeekText);

// 日付を切り捨てる (月の初めに丸める)
DateTime roundedToMonth = dt.monthOfYear().roundFloorCopy();
System.out.println("月に切り捨て: " + roundedToMonth);

Joda-Timeでは、「時間的な長さ」を表現するためにDuration, Period, Intervalという3つの異なる概念のクラスを提供しています。これらを正しく使い分けることが、高度な日付処理の鍵となります。

Duration: ミリ秒で測る時間

2つのDateTimeの差から生成するのが一般的です。サマータイムの境界をまたぐ場合でも、物理的な経過時間を正確に計算します。

import org.joda.time.DateTime;
import org.joda.time.Duration;

DateTime start = new DateTime(2025, 7, 20, 10, 0, 0);
DateTime end = new DateTime(2025, 7, 20, 12, 30, 0);

Duration duration = new Duration(start, end);
System.out.println("期間(ミリ秒): " + duration.getMillis());
System.out.println("期間(秒): " + duration.getStandardSeconds());
System.out.println("期間(分): " + duration.getStandardMinutes()); // 150分

Period: 人間の感覚に近い期間

「1ヶ月後」の計算などに使います。2月15日の1ヶ月後は3月15日となり、日数の違い（28日や31日）を自動で考慮してくれます。

import org.joda.time.DateTime;
import org.joda.time.Period;
import org.joda.time.format.PeriodFormatter;
import org.joda.time.format.PeriodFormatterBuilder;

DateTime start = new DateTime(2025, 2, 15, 10, 0, 0);
DateTime end = new DateTime(2026, 4, 20, 12, 0, 0);

// 年月日などの単位で期間を計算
Period period = new Period(start, end);

PeriodFormatter formatter = new PeriodFormatterBuilder()
    .appendYears().appendSuffix("年 ")
    .appendMonths().appendSuffix("ヶ月 ")
    .appendDays().appendSuffix("日 ")
    .appendHours().appendSuffix("時間")
    .toFormatter();

System.out.println("期間: " + formatter.print(period.normalizedStandard()));

// 特定の期間を生成して日時に加算
Period p = Period.months(2).plusDays(10);
DateTime result = new DateTime(2025, 1, 30, 0, 0).plus(p);
System.out.println("1月30日の2ヶ月と10日後: " + result); // -> 2025-04-09

Interval: 固定された時間間隔

特定の時間範囲を表現し、その範囲にあるかどうか（contains）や、他の範囲と重なっているか（overlaps）を判定するのに役立ちます。

import org.joda.time.DateTime;
import org.joda.time.Interval;

DateTime meetingStart = new DateTime(2025, 8, 1, 14, 0, 0);
DateTime meetingEnd = new DateTime(2025, 8, 1, 15, 0, 0);
Interval meetingInterval = new Interval(meetingStart, meetingEnd);

DateTime checkTime1 = new DateTime(2025, 8, 1, 14, 30, 0);
DateTime checkTime2 = new DateTime(2025, 8, 1, 16, 0, 0);

System.out.println("会議の時間: " + meetingInterval);
System.out.println(checkTime1 + " は会議中か？ " + meetingInterval.contains(checkTime1)); // -> true
System.out.println(checkTime2 + " は会議中か？ " + meetingInterval.contains(checkTime2)); // -> false

// 他のIntervalとの重複チェック
Interval otherInterval = new Interval(new DateTime(2025, 8, 1, 14, 45, 0), new DateTime(2025, 8, 1, 15, 30, 0));
System.out.println("会議は " + otherInterval + " と重複するか？ " + meetingInterval.overlaps(otherInterval)); // -> true

これまでJoda-Timeの強力な機能を見てきましたが、前述の通り、Java SE 8以降では標準APIであるjava.timeの使用が強く推奨されます。 java.timeはJoda-Timeに多大な影響を受けて設計されており、多くのクラスやメソッドが類似しているため、移行は比較的スムーズに行えます。

ここでは、Joda-Timeの主要クラスと、それに対応するjava.timeのクラスの対応表、そして簡単な移行例を示します。

クラス対応表

移行コード例

以下に、Joda-Timeからjava.timeへの簡単な書き換え例を示します。

例1: 現在日時の取得と計算

// Joda-Time
import org.joda.time.DateTime;
DateTime jodaNow = new DateTime();
DateTime jodaFuture = jodaNow.plusDays(10);

// java.time
import java.time.ZonedDateTime;
ZonedDateTime javaTimeNow = ZonedDateTime.now();
ZonedDateTime javaTimeFuture = javaTimeNow.plusDays(10);

例2: フォーマットとパース

// Joda-Time
import org.joda.time.format.DateTimeFormat;
import org.joda.time.format.DateTimeFormatter;
DateTimeFormatter jodaFmt = DateTimeFormat.forPattern("yyyy/MM/dd");
String jodaStr = jodaFmt.print(new DateTime());

// java.time
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
DateTimeFormatter javaTimeFmt = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String javaTimeStr = javaTimeFmt.format(ZonedDateTime.now());

既存のプロジェクトを移行する際は、単体テストを整備し、挙動が変わらないことを確認しながら少しずつ進めることが重要です。特にフォーマッタの挙動や、Joda-Timeが許容していた曖昧なパースがjava.timeでは厳密にエラーになるケースなど、細かな違いに注意が必要です。

Joda-Timeは、かつてのJavaにおける日付時刻処理の複雑さを解消し、開発者にとっての標準的な解決策となりました。その不変性や直感的なAPIといった設計思想は、現在のJava標準であるjava.timeパッケージに色濃く受け継がれています。

本記事を通じて、Joda-Timeの強力な機能と詳細な使い方を学んでいただけたと思います。しかし最も重要なのは、その歴史的役割を理解し、現代のJava開発ではjava.timeを選択するということです。

レガシーシステムでJoda-Timeに遭遇した際には、この知識が大いに役立つでしょう。そして、新規開発やリファクタリングの機会があれば、ぜひjava.timeへの移行を積極的に検討してください。Joda-Timeの学習は、結果的にjava.timeの深い理解へと繋がるはずです。