7.3. 日付操作(JSR-310 Date and Time API)


7.3.1. Overview

本ガイドラインでは、java.util.Date,java.util.Calendarに比べて、様々な日時計算が提供されている JSR-310 Date and Time API の使用を推奨する。

7.3.2. How to use

Date and Time APIでは、日付のみ扱うクラス、時刻のみ扱うクラスなど、用途に応じた様々なクラスが提供されている。
本ガイドラインでは、java.time.LocalDate、java.time.LocalTime、java.time.LocalDateTimeを中心に説明を進めるが、主要な日時操作については各クラスで提供されるメソッドの接頭辞が同一であるため、適時クラス名を置き換えて解釈されたい。
主に使われるクラスとメソッドを示す。

日時を扱う主なクラス

クラス名

説明

主なファクトリメソッド
java.time.LocalDate
java.time.LocalTime
java.time.LocalDateTime

タイムゾーン・時差の情報を持たない日付・時刻の操作を行うクラス
now : 現在日時で生成
of : 任意日時で生成
parse : 日時文字列から生成
from : 日時情報を持つ他オブジェクトから生成
java.time.OffsetTime
java.time.OffsetDateTime
java.time.ZonedDateTime

タイムゾーン・時差を考慮した日付・時刻の操作を行うクラス

同上
java.time.chrono.JapaneseDate

和暦の操作を行うクラス

同上

期間の情報を扱う主なクラス

クラス名

説明

主なファクトリメソッド
java.time.Period
java.time.Duration

日時ベース、時間ベースの期間を扱うクラス
between : 日時情報を持つ2つのオブジェクトの差から生成
from : 時間量を持つ他オブジェクトから生成
of : 任意期間で生成

クロックを扱う主なクラス

クラス名

説明

主なファクトリメソッド
java.time.Clock

タイムゾーンを使用して現在の時刻、日付、時刻へのアクセスを提供するクラス
fixed : 常に同じ瞬間を返すClockを生成
tick : 指定した瞬間からの変動時刻を返すClockを生成
instant : タイムスタンプを取得

フォーマットを扱うクラス

クラス名

説明

主なファクトリメソッド
java.time.format.DateTimeFormatter
日時のフォーマットに関する操作を行うクラス
ofPattern : 指定されたパターンでフォーマッタを生成

Note

本ガイドラインで触れなかった内容を含め、詳細はJavadocを参照されたい。

Note

Date and Time APIのクラスは、immutableである(日時計算等の結果は新規オブジェクトが返却されており、計算元オブジェクトに変化はない)。

Note

Java SE 17のロケールデータはCLDRがデフォルトとなる。(JEP 252参照。)

Java SE 8以前のロケールデータ(COMPAT)に切り替えたい場合はデフォルトで使用されるロケール・データの変更を参照されたい。


各クラス・メソッドの具体的な利用方法を、以下で説明する。

7.3.2.1. 日時取得

7.3.2.1.1. 現在日時で取得

利用用途に合わせてjava.time.LocalTime、java.time.LocalDate、java.time.LocalDateTimeを使い分けること。
以下に例を示す。

  1. 時刻のみ取得したい場合はjava.time.LocalTimeを使用する。

LocalTime localTime =  LocalTime.now();
LocalTime localTime =  LocalTime.now(clock);

  1. 日付のみ取得したい場合はjava.time.LocalDateを使用する。

LocalDate localDate =  LocalDate.now();
LocalDate localDate =  LocalDate.now(clock);

  1. 日付・時刻を取得したい場合はjava.time.LocalDateTimeを使用する。

LocalDateTime localDateTime = LocalDateTime.now();
LocalDateTime localDateTime = LocalDateTime.now(clock);

7.3.2.1.2. 指定日時でオブジェクトを取得

ofメソッドを使うことで特定の日時を指定することができる。以下に例を示す。

  1. 時刻を指定してjava.time.LocalTimeを取得する。

// 23:30:59
LocalTime localTime =  LocalTime.of(23, 30, 59);

  1. 日付を指定してjava.time.LocalDateを取得する。

// 2015/12/25
LocalDate localDate =  LocalDate.of(2015, 12, 25);

  1. 日付・時刻）を指定してjava.time.LocalDateTimeを取得する。

// 2015/12/25 23:30:59
LocalDateTime localDateTime = LocalDateTime.of(2015, 12, 25, 23, 30, 59);

また、java.time.temporal.TemporalAdjustersを使うことで様々な日時を取得することができる。
// LeapYear(2012/2)
LocalDate localDate1 = LocalDate.of(2012, 2, 1);

// Last day of month(2012/2/29)
LocalDate localDate2 = localDate1.with(TemporalAdjusters.lastDayOfMonth());

// Next monday（2012/2/6）
LocalDate localDate3 = localDate1.with(TemporalAdjusters.next(DayOfWeek.MONDAY));

7.3.2.1.3. タイムゾーンを指定する場合の日時取得

国際的なアプリケーションを作成する場合、タイムゾーンを意識した設計を行う場合がある。
Date and Time APIでは、利用用途に合わせて、java.time.OffsetTime、java.time.OffsetDateTime、java.time.ZonedDateTimeを使い分けること。
以下に例を示す。

  1. 時刻 + UTCとの時差を取得したい場合は、java.time.OffsetTimeを使用する。

// Ex, 12:30:11.567+09:00
OffsetTime offsetTime =  OffsetTime.now();

  1. 日付・時刻 + UTCとの時差を取得したい場合はjava.time.OffsetDateTimeを使用する。

// Ex, 2015-12-25T12:30:11.567+09:00
OffsetDateTime offsetDateTime =  OffsetDateTime.now();

  1. 日付・時刻 + UTCとの時差・地域を取得したい場合はjava.time.ZonedDateTimeを使用する。

// Ex, 2015-12-25T12:30:11.567+09:00[Asia/Tokyo]
ZonedDateTime zonedDateTime = ZonedDateTime.now();
これらのメソッドでは全て、タイムゾーンを表すjava.time.ZoneIdを引数に設定することで、タイムゾーンを考慮した現在日時が取得できる。
以下にjava.time.ZoneIdの例を示す。
ZoneId zoneIdTokyo = ZoneId.of("Asia/Tokyo");
OffsetTime offsetTime =  OffsetTime.now(zoneIdTokyo);
なお、java.time.ZoneIdは地域名/地名形式で定義する方法や、UTCからの時差で定義する方法がある。
ZoneId.of("Asia/Tokyo");
ZoneId.of("UTC+01:00");

java.time.OffsetDateTime,java.time.ZonedDateTimeの2クラスは用途が似ているが、具体的には以下のような違いがある。
作成するシステムの特性に応じて適切なクラスを選択されたい。

クラス名

説明
java.time.OffsetDateTime

定量値（時差のみ）を持つため、各地域の時間の概念に変化がある場合も、システムに変化が起こらない。
java.time.ZonedDateTime

時差に加えて地域の概念があるため、各地域の時間の概念に変化があった場合、システムに変化が起こる。（政策としてサマータイム導入される場合など）

7.3.2.1.4. クロックを指定する場合の日時取得

Clockの取得に関してはシステム時刻を参照されたい。

7.3.2.2. 期間

7.3.2.2.1. 期間の取得

日付ベースの期間を扱う場合は、java.time.Period、時間ベースの期間を扱う場合は、java.time.Durationを使用する。
java.time.Durationで表される1日は厳密に24時間であるため、サマータイムの変化が解釈されずに想定通りの結果にならない可能性がある。
対して、java.time.Periodはサマータイムなどの概念を考慮した1日を表すため、サマータイムを扱うシステムであっても誤差は生じない。
以下に例を示す。
LocalDate date1 = LocalDate.of(2010, 01, 15);
LocalDate date2 = LocalDate.of(2011, 03, 18);
LocalTime time1 = LocalTime.of(11, 50, 50);
LocalTime time2 = LocalTime.of(12, 52, 53);

// One year, two months and three days.
Period pd = Period.between(date1, date2);

// One hour, two minutes and three seconds.
Duration dn = Duration.between(time1, time2);

Note

ofメソッドを利用して、期間を指定して生成する方法もある。詳細はPeriod, DurationのJavadocを参照されたい。


7.3.2.3. 型変換

7.3.2.3.1. Date and Time APIの各クラスの相互運用性

java.time.LocalTime、java.time.LocalDate、java.time.LocalDateTimeはそれぞれ容易に変換が可能である。
以下に例を示す。

  1. java.time.LocalTimeからjava.time.LocalDateTimeへの変換。

// Ex. 12:10:30
LocalTime localTime =  LocalTime.now();

// 2015-12-25 12:10:30
LocalDateTime localDateTime = localTime.atDate(LocalDate.of(2015, 12, 25));

  1. java.time.LocalDateからjava.time.LocalDateTimeへの変換。

// Ex. 2012-12-25
LocalDate localDate =  LocalDate.now();

// 2015-12-25 12:10:30
LocalDateTime localDateTime = localDate.atTime(LocalTime.of(12, 10, 30));

  1. java.time.LocalDateTimeからjava.time.LocalTime,java.time.LocalDateへの変換。

// Ex. 2015-12-25 12:10:30
LocalDateTime localDateTime =  LocalDateTime.now();

// 12:10:30
LocalTime localTime =  localDateTime.toLocalTime();

// 2012-12-25
LocalDate localDate =  localDateTime.toLocalDate();

同様に、java.time.OffsetTime、java.time.OffsetDateTime、java.time.ZonedDateTimeもそれぞれ容易に変換が可能である。
以下に例を示す。

  1. java.time.OffsetTimeから、java.time.OffsetDateTimeへの変換。

// Ex, 12:30:11.567+09:00
OffsetTime offsetTime =  OffsetTime.now();

// 2015-12-25T12:30:11.567+09:00
OffsetDateTime offsetDateTime = offsetTime.atDate(LocalDate.of(2015, 12, 25));

  1. java.time.OffsetDateTimeからjava.time.ZonedDateTimeへの変換。

// Ex, 2015-12-25T12:30:11.567+09:00
OffsetDateTime offsetDateTime =  OffsetDateTime.now();

// 2015-12-25T12:30:11.567+09:00[Asia/Tokyo]
ZonedDateTime zonedDateTime = offsetDateTime.atZoneSameInstant(ZoneId.of("Asia/Tokyo"));

  1. java.time.ZonedDateTimeからjava.time.OffsetDateTime,java.time.OffsetTimeへの変換。

// Ex, 2015-12-25T12:30:11.567+09:00[Asia/Tokyo]
ZonedDateTime zonedDateTime =  ZonedDateTime.now();

// 2015-12-25T12:30:11.567+09:00
OffsetDateTime offsetDateTime =  zonedDateTime.toOffsetDateTime();

// 12:30:11.567+09:00
OffsetTime offsetTime =  zonedDateTime.toOffsetDateTime().toOffsetTime();

また、時差情報を加えることで、java.time.LocalTimeをjava.time.OffsetTimeに変換することも可能である。
// Ex, 12:30:11.567
LocalTime localTime =  LocalTime.now();

// 12:30:11.567+09:00
OffsetTime offsetTime = localTime.atOffset(ZoneOffset.ofHours(9));

この他についても、不足している情報（LocalTimeからLocalDateTimeの変換であれば日付の情報が不足している の要領）を加えることで別のクラスへ変換が可能である。
変換メソッドは接頭辞がatまたはtoで始まる。詳細は各クラスのJavadocを参照されたい。

7.3.2.3.2. java.util.Dateとの相互運用性

java.time.LocalDate等のクラスは、java.time.Instantに変換したうえでjava.util.Dateに変換することが可能である。
以下に例を示す。

  1. java.time.LocalDateTimeから、java.util.Dateへの変換。

LocalDateTime localDateTime = LocalDateTime.now();
Instant instant = localDateTime.toInstant(ZoneOffset.ofHours(9));
Date date = Date.from(instant);

Note

java.time.LocalTime、java.time.LocalDateはInstantを持っていないため、一度java.time.LocalDateTimeに変換する必要がある。

変換方法はDate and Time APIの各クラスの相互運用性を参照されたい。

  1. java.util.Dateからjava.time.LocalDateTimeへの変換。

Date date = new Date();
Instant instant = date.toInstant();
LocalDateTime localDateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault());

7.3.2.3.3. java.sql パッケージとの相互運用性

java.sqlパッケージのクラスは、java.time.Instantに変換せずにjava.time.LocalDate等のクラスと相互変換が可能である。
以下に例を示す。

  1. java.sql.Dateからjava.time.LocalDateへの変換。

java.sql.Date date =  new java.sql.Date(System.currentTimeMillis());
LocalDate localDate = date.toLocalDate();

  1. java.time.LocalDateからjava.sql.Dateへの変換。

LocalDate localDate = LocalDate.now();
java.sql.Date date =  java.sql.Date.valueOf(localDate);

  1. java.sql.Timeからjava.time.LocalTimeへの変換。

java.sql.Time time =  new java.sql.Time(System.currentTimeMillis());
LocalTime localTime = time.toLocalTime();

  1. java.time.LocalTimeからjava.sql.Timeへの変換。

LocalTime localTime = LocalTime.now();
java.sql.Time time =  java.sql.Time.valueOf(localTime);

  1. java.sql.Timestampからjava.time.LocalDateTimeへの変換。

java.sql.Timestamp timestamp =  new java.sql.Timestamp(System.currentTimeMillis());
LocalDateTime localDateTime = timestamp.toLocalDateTime();

  1. java.time.LocalDateTimeからjava.sql.Timestampへの変換。

LocalDateTime localDateTime = LocalDateTime.now();
java.sql.Timestamp timestamp =  java.sql.Timestamp.valueOf(localDateTime);

7.3.2.3.4. 文字列へのフォーマット

日時情報を持つオブジェクトを文字列に変換するには、toStringメソッドを使用する方法と、java.time.fomat.DateTimeFormatterを使用する方法がある。
任意の日時文字列で出力したい場合は、java.time.fomat.DateTimeFormatterを使用し様々な日時文字列へ変換することが出来る。

java.time.fomat.DateTimeFormatterは、事前定義されたISOパターンのフォーマッタを利用する方法と、任意のパターンのフォーマットを定義して利用する方法がある。
DateTimeFormatter formatter1 = DateTimeFormatter.BASIC_ISO_DATE;

DateTimeFormatter formatter2 = DateTimeFormatter.ofPattern("G uuuu/MM/dd E")
                                          .withLocale(Locale.JAPANESE)
                                          .withResolverStyle(ResolverStyle.STRICT);
その際、文字列の形式の他にLocaleとResolverStyle（厳密性）を定義できる。
Localeのデフォルト値はシステムによって変化するため、初期化時に設定することが望ましい。
また、ResolverStyle（厳密性）はofPatternメソッドを使う場合、デフォルトでResolverStyle.SMARTが設定されるが、本ガイドラインでは予期せぬ挙動が起こらないよう、厳密に日付を解釈するResolverStyle.STRICTの設定を推奨している。（ISOパターンのフォーマッタを利用する場合はResolverStyle.STRICTが設定されている)

なお、Date and Time API では書式yyyyは暦に対する年を表すため、暦によって解釈が異なる(西暦なら2015と解釈されるが、和暦なら0027と解釈される）。
西暦を表したい場合は、yyyy形式に変えてuuuu形式を利用することを推奨する。
定義されている書式一覧はDateTimeFormatterを参照されたい。

以下に例を示す。
DateTimeFormatter formatter1 = DateTimeFormatter.BASIC_ISO_DATE;

DateTimeFormatter formatter2 = DateTimeFormatter.ofPattern("G uuuu/MM/dd E")
                                          .withLocale(Locale.JAPANESE)
                                          .withResolverStyle(ResolverStyle.STRICT);

LocalDate localDate1 = LocalDate.of(2015, 12, 25);

// "2015-12-25"
System.out.println(localDate1.toString());
// "20151225"
System.out.println(formatter1.format(localDate1));
// "西暦 2015/12/25 金"
System.out.println(formatter2.format(localDate1));

また、これらの文字列をThymeleafの画面上に表示したい場合、
ThymeleafではDate and Time APIをサポートしたダイアレクト（Java8 Time Dialect）を標準機能として提供している。
詳細は、 Thymeleafのダイアレクト を参照されたい。

Controllerクラス

@Controller
public class HomeController {

    @RequestMapping(value = "/", method = {RequestMethod.GET, RequestMethod.POST})
    public String home(Model model, Locale locale) {

        DateTimeFormatter dateFormatter = DateTimeFormatter.ofPattern("uuuu/MM/dd")
                                          .withLocale(locale)
                                          .withResolverStyle(ResolverStyle.STRICT);

        LocalDate localDate1 = LocalDate.now();

        model.addAttribute("currentDate", localDate1.toString());
        model.addAttribute("formattedCurrentDateString", dateFormatter.format(localDate1));

      // omitted

    }
}

ThymeleafのテンプレートHTML

<p th:text="|currentDate = ${currentDate}|"></p>
<p th:text="|formattedCurrentDateString = ${formattedCurrentDateString}|"></p>

Note

Java SE 11ではJava SE 8と日付の文字列表現が異なる場合がある。 Java SE 8と同様に表現するにはデフォルトで使用されるロケール・データの変更を参照されたい。


7.3.2.3.5. 文字列からのパース

文字列への変換と同様に、java.time.fomat.DateTimeFormatterを用いることで、様々な日付文字列をDate and Time APIのクラスへ変換することが出来る。
以下に例を示す。
DateTimeFormatter formatter1 = DateTimeFormatter.ofPattern("uuuu/MM/dd")
                                           .withLocale(Locale.JAPANESE)
                                           .withResolverStyle(ResolverStyle.STRICT);

DateTimeFormatter formatter2 = DateTimeFormatter.ofPattern("HH:mm:ss")
                                           .withLocale(Locale.JAPANESE)
                                           .withResolverStyle(ResolverStyle.STRICT);

LocalDate localDate = LocalDate.parse("2015/12/25", formatter1);
LocalTime localTime = LocalTime.parse("14:09:20", formatter2);

7.3.2.4. 日付操作

Date and Time APIでは、日時の計算や比較などを容易に行うことが出来る。
以下に例を示す。

7.3.2.4.1. 日時の計算

日時の計算をするためにplusメソッドとminusメソッドが提供されている。

  1. 時間の計算を行う場合の例。

LocalTime localTime =  LocalTime.of(20, 30, 50);
LocalTime plusHoursTime = localTime.plusHours(2);
LocalTime plusMinutesTime = localTime.plusMinutes(10);
LocalTime minusSecondsTime = localTime.minusSeconds(15);

  1. 日付の計算を行う場合の例。

LocalDate localDate =  LocalDate.of(2015, 12, 25);
LocalDate plusYearsDate = localDate.plusYears(10);
LocalDate minusMonthsTime = localDate.minusMonths(1);
LocalDate plusDaysTime = localDate.plusDays(3);

7.3.2.4.2. 日時の比較

Date and Time APIでは、過去・未来・同時などの時系列の比較が行える。
以下に例を示す。

  1. 時間の比較を行う場合の例。

LocalTime morning =  LocalTime.of(7, 30, 00);
LocalTime daytime =  LocalTime.of(12, 00, 00);
LocalTime evening =  LocalTime.of(17, 30, 00);

daytime.isBefore(morning); // false
morning.isAfter(evening); // true
evening.equals(LocalTime.of(17, 30, 00)); // true

daytime.isBefore(daytime); // false
morning.isAfter(morning); // false

  1. 日付の比較を行う場合の例。

LocalDate may =  LocalDate.of(2015, 6, 1);
LocalDate june =  LocalDate.of(2015, 7, 1);
LocalDate july =  LocalDate.of(2015, 8, 1);

may.isBefore(june); // true
june.isAfter(july); // false
july.equals(may); // false

may.isBefore(may); // false
june.isAfter(june); // false

なお、Date and Time APIの標準機能では期間を取得するAPI(JodaTimeのIntervalに相当するAPI)は存在しない。

7.3.2.4.3. 日時の判定

以下に日時の判定の例を示す。

  1. 妥当な日時文字列かを判定したい場合、java.time.format.DateTimeParseExceptionの発生有無で判定できる。

String strDateTime = "aabbcc";
DateTimeFormatter timeFormatter  = DateTimeFormatter.ofPattern("HHmmss")
                              .withLocale(Locale.JAPANESE)
                              .withResolverStyle(ResolverStyle.STRICT);;

DateTimeFormatter dateFormatter  = DateTimeFormatter.ofPattern("uuMMdd")
                              .withLocale(Locale.JAPANESE)
                              .withResolverStyle(ResolverStyle.STRICT);;

try {
    // DateTimeParseException
    LocalTime localTime = LocalTime.parse(strDateTime, timeFormatter);
} catch (DateTimeParseException e) {
    System.out.println("Invalid time string !!");
}

try {
    // DateTimeParseException
    LocalDate localDate = LocalDate.parse(strDateTime, dateFormatter);
} catch (DateTimeParseException e) {
    System.out.println("Invalid date string !!");
}

  1. うるう年かを判定したい場合、java.time.LocalDateのisLeapYearメソッドで判定できる。

LocalDate date1 = LocalDate.of(2012, 1, 1);
LocalDate date2 = LocalDate.of(2015, 1, 1);

date1.isLeapYear(); // true
date2.isLeapYear(); // false

7.3.2.4.4. 年月日等の個別取得

年、月などをそれぞれ取得したい場合は、getメソッドを利用する。
以下に日付に関する情報を取得する例を示す。
LocalDate localDate = LocalDate.of(2015, 2, 3);
LocalTime localTime = LocalTime.of(2, 30, 22, 123456789);

int year = localDate.getYear(); // (1)
int month = localDate.getMonthValue(); // (2)
int dayOfMonth = localDate.getDayOfMonth(); // (3)
int dayOfYear = localDate.getDayOfYear(); // (4)
DayOfWeek week = localDate.getDayOfWeek(); // (5)
int weekValue = week.getValue(); // (5)
int hour = localTime.getHour(); // (6)
int minute = localTime.getMinute(); // (7)
int second = localTime.getSecond(); // (8)
int nano = localTime.getNano(); // (9)

項番

説明
(1)
年を取得する。本例では、2015が返却される。
(2)
月を取得する。本例では、2が返却される。

Note

java.util.Calendarの仕様とは異なり、java.time.Monthは”1“始まりである。
(3)
月初からの日数を取得する。本例では、3が返却される。
(4)
元日からの日数を取得する。本例では、34が返却される。
(5)
曜日を取得する。本例では、TUESDAY(getValueでは2)が返却される。
返却される値と曜日の対応は、[1:MONDAY、2:TUESDAY、3:WEDNESDAY、4:THURSDAY、5:FRIDAY、6:SATURDAY、7:SUNDAY]となる。
(6)
時を取得する。本例では、2が返却される。
(7)
分を取得する。本例では、30が返却される。
(8)
秒を取得する。本例では、22が返却される。
(9)
ナノ秒を取得する。本例では、123456789が返却される。

7.3.2.5. 和暦（JapaneseDate）

Date and Time APIではjava.time.chrono.JapaneseDateという、和暦を扱うクラスが提供されている。

7.3.2.5.1. 和暦の取得

java.time.LocalDateと同様に、nowメソッド、ofメソッドで取得できる。
また、java.time.chrono.JapaneseEraクラスを使うことで、和暦を指定した取得も行うことが出来る。
以下に例を示す。
JapaneseDate japaneseDate1 = JapaneseDate.now();
JapaneseDate japaneseDate2 = JapaneseDate.of(2015, 12, 25);
JapaneseDate japaneseDate3 = JapaneseDate.of(JapaneseEra.HEISEI, 27, 12, 25);

Note

java.time.chrono.JapaneseDateは、グレゴリオ暦が導入された明治6年(西暦1873年)より前は利用できない。

// DateTimeException
JapaneseDate japaneseDate = JapaneseDate.of(1500, 1, 1);

実行結果

java.time.DateTimeException: JapaneseDate before Meiji 6 is not supported

7.3.2.5.2. 文字列へのフォーマット

java.time.fomat.DateTimeFormatterを用いることで、和暦日付へ変換することが出来る。利用の際には、DateTimeFormatter#withChronologyメソッドで暦をjava.time.chrono.JapaneseChronologyに設定する。
和暦日付でも様々なフォーマットを扱うことが出来るため、0埋めや空白埋めなど要件に応じた出力が行える。
以下に空白埋めで和暦を表示する例を示す。
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("Gppy年ppM月ppd日")
                                 .withLocale(Locale.JAPANESE)
                                 .withResolverStyle(ResolverStyle.STRICT)
                                 .withChronology(JapaneseChronology.INSTANCE);

JapaneseDate japaneseDate = JapaneseDate.of(1992, 1, 1);

// "平成 4年 1月 1日"
System.out.println(formatter.format(japaneseDate));

7.3.2.5.3. 文字列からのパース

java.time.fomat.DateTimeFormatterを用いることで、和暦文字列からjava.time.chrono.JapaneseDateへ変換することが出来る。
以下に例を示す。
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("Gy年MM月dd日")
                                .withLocale(Locale.JAPANESE)
                                .withResolverStyle(ResolverStyle.STRICT)
                                .withChronology(JapaneseChronology.INSTANCE);

JapaneseDate japaneseDate1 = JapaneseDate.from(formatter.parse("平成27年12月25日"));
JapaneseDate japaneseDate2 = JapaneseDate.from(formatter.parse("明治6年01月01日"));

7.3.2.5.4. 西暦・和暦の変換

fromメソッドを使うことでjava.time.LocalDateからの変換を容易に行える。
LocalDate localDate = LocalDate.of(2015, 12, 25);
JapaneseDate jpDate = JapaneseDate.from(localDate);

7.3.2.6. JSP Tag Library

JSTLの fmt:formatDate タグは、java.util.Dateと、java.util.TimeZoneオブジェクトを扱う。
JSR-310 Date And Timeのオブジェクトを扱うためには、Java 8 java.time JSP tagsを使用する。
機能面でJSTLとほぼ同じであるため、JSTLの知識がある場合は、JSR-310 Date And TimeのJSPタグライブラリを容易に使える。

7.3.2.6.1. 設定方法

タブライブラリを利用するには、以下のtaglib定義が必要である。

<%@ taglib uri="http://sargue.net/jsptags/time" prefix="javatime" %>

7.3.2.6.2. javatime:formateタグ

javatime:formatタグとは、LocalDate、LocalTime、LocalDateTimeオブジェクトをフォーマットするタグである。

<% pageContext.setAttribute("now", java.time.LocalDateTime.now()); %>

<span>Using pattern="uuuuMMdd" to format the current system date</span><br/>
<javatime:format value="${now}" pattern="yyyyMMdd" />
<br/>
<span>Using style="SM" to format the current system date</span><br/>
<javatime:format value="${now}" style="SM" />

出力結果

  • jpロケールの場合

/DateAndTime

  • enロケールの場合

/DateAndTime

javatime:formatタグの属性一覧は、以下の通りである。

属性情報

No.

Attributes

Description
value
Temporalインスタンスを設定する。
var
時刻情報を持つ変数名
scope
時刻情報を持つ変数名のスコープ
locale
ロケール情報
style
フォーマットするためのスタイル情報（2桁。日付部分と時刻部分それぞれのスタイルを設定する。
入力可能な値は S=Short, M=Medium, L=Long, F=Full, -=None）

Note

style属性を指定して日付と時刻部分を表示する場合、ブラウザのlocaleによって表示内容が異なる。
pattern
フォーマットするためのパターン（uuuuMMddなど）。
入力可能なパターンは、DateTimeFormatterのjavadocを参照されたい。
dateTimeZone
タイムゾーン

ほかのタグについては、Java 8 java.time JSP tagsを参照されたい。


7.3.2.7. Thymeleafのダイアレクト

ThymeleafではDate and Time APIをサポートしたダイアレクト（Java8 Time Dialect）を標準機能として提供している。

Java8 Time Dialectでは#temporalsを用意している。
#temporalsを利用することで、テンプレートHTMLでDate and Time APIのオブジェクトの文字列フォーマットなどが可能となる。

Note

Java8 Time Dialectは、Thymeleafで公式にサポートされている。

Java8 Time Dialectに関する情報は、thymeleaf-extras-java8timeを参照されたい。

Tip

Thymeleaf 3.0 以前のバージョンを使用する場合はthymeleaf-extras-java8timeを依存関係に追加する必要がある。


7.3.2.7.1. Viewの実装

Java8 Time Dialectを使用してViewの実装を行うには、#temporalsを使用する。
#temporalsでは用途に応じて様々なメソッドを用意している。ここでは、Date and Time APIオブジェクトのフォーマットを行うformatメソッドについて説明する。

formatメソッドは以下のようなシグネチャをもつ。同様にフォーマットを行うメソッドとして、formatISOメソッドについても以下の一覧に示す。

項番

メソッドシグネチャ

説明
format(Temporal)
Temporalを指定してフォーマットする。
format(Temporal, フォーマット文字列)
Temporal、フォーマット文字列を指定してフォーマットする。
format(Temporal, ロケール)
Temporal、ロケールを指定してフォーマットする。
format(Temporal, フォーマット文字列, ロケール)
Temporal、フォーマット文字列、ロケールを指定してフォーマットする。
formatISO(Temporal)
Temporalを指定して ISO8601形式にフォーマットする。
formatメソッドはjava.time.temporal.Temporal型(LocalDateTime、LocalDate、LocalTimeなど）のオブジェクトを入力値として、フォーマット文字列とロケールを与えて文字列にフォーマットする。
フォーマットとロケールは省略することができ、それぞれデフォルト値は以下のようになる。

  • フォーマット文字列： uuuu/MM/dd形式

  • ロケール： システムのデフォルトロケール

Note

formatメソッドのデフォルトのフォーマット文字列は上記のとおり、uuuu/MM/dd形式となる。

Date and Time APIのオブジェクトを、toStringメソッドで文字列に変換した場合(uuuu-MM-dd形式)と異なる形式でフォーマットされることに留意されたい。


Temporal、フォーマット文字列、ロケールを指定する場合の実装例を以下に示す。

  • Controllerクラス

    model.addAttribute("currentDateTime", LocalDateTime.now()); // (1)
model.addAttribute("locale", Locale.ENGLISH); // (2)

  • テンプレートHTML

    <p th:text="|currentDateTime = ${#temporals.format(currentDateTime, 'G uuuu/MM/dd E', locale)}.|"></p> <!--/* (3) /*-->

  • 出力結果例(html)

    <p>currentDate =  AD 2015/12/25 Fri.</p> <!-- (4) -->

    項番

    説明
    (1)
    ModelオブジェクトにLocalDateTimeオブジェクトを追加する。
    ここでは、現在日時を指定している。
    (2)
    ModelオブジェクトにLocaleオブジェクトを追加する。
    ここでは、言語のロケールとして英語を指定している。
    (3)
    LocalDateTimeオブジェクトを指定したフォーマット文字列およびロケールでフォーマットする。
    ここでは、フォーマット文字列をG uuuu/MM/dd E形式で指定している。

    formatメソッドではフォーマッタとして、java.time.format.DateTimeFormatterを利用している。
    そのため、フォーマットのパターンの指定は、ofPatternメソッドを利用する場合と同一である。
    (4)
    現在の日付が2015年12月25日の場合、ロケールが英語のため、AD 2015/12/25 Friと表示される。

7.3.2.7.2. #temporalsのメソッド

先述のとおり、#temporalsでは用途に応じて様々なメソッドを用意している。
以下に、#temporalsが持つメソッドの一覧を示す。
#temporalsのメソッド一覧

項番

メソッド名

説明

例
format
Temporalを文字列にフォーマットする。
2015年12月25日23時30分59秒の場合、
2015/12/25 23:30:59にフォーマットする。
formatISO
TemporalをISO8601形式で文字列にフォーマットする。
2015年12月25日23時30分59秒345の場合(タイムゾーンは日本)、
2015-12-25T23:30:59.345+0900にフォーマットする。
day
日時情報から日の値を取得する。
12月25日の場合、25を取得する。
month
日時情報から月の値を取得する。
12月25日の場合、12を取得する。
monthName
日時情報から月の名称を取得する。
12月25日の場合、12月を取得する。
monthNameShort
日時情報から月の短縮した名称を取得する。
12月25日の場合、12を取得する。
year
日時情報から年の値を取得する。
2015年の場合、2015を取得する。
dayOfWeek
日時情報から月曜日を起点にした曜日の番号を取得する。
金曜日の場合、5を取得する。
dayOfWeekName
日時情報から曜日の名称を取得する。
金曜日の場合、金曜日を取得する。
dayOfWeekNameShort
日時情報から曜日の短縮した名称を取得する。
金曜日の場合、金を取得する。
hour
日時情報から1日のうちの時の値を取得する。
23時30分59秒の場合、23を取得する。
minute
日時情報から1時間のうちの分の値を取得する。
23時30分59秒の場合、30を取得する。
second
日時情報から1分のうちの秒の値を取得する。
23時30分59秒の場合、59を取得する。
nanosecond
日時情報から1秒のうちのナノ秒の値を取得する。
23時30分59秒345の場合、345を取得する。

Note

上記全てのメソッドには、以下のように配列、リスト、セットに対応したメソッドが存在する。

(例) arrayFormat(...)、listFormat(...)、setFormat(...)など

各メソッドの詳細については、thymeleaf-extras-java8time - Usageを参照されたい。

formatメソッドのシグネチャについては、Viewの実装でも説明している。

Note

上記のメソッド以外に、現在日時の日付オブジェクトや、年・月・日やタイムゾーンを指定して日付オブジェクトを生成するメソッドがある。

これらメソッドのシグネチャの情報については、thymeleaf-extras-java8time - Usageを参照されたい。

ただし、これらのメソッドを利用してViewで日付を生成することは推奨しない。なぜなら、これらのメソッドはシステム日付を取得するため、意図しない日時となり得るためである。

Warning

ロケールとタイムゾーンについて

ロケールとタイムゾーンは同じような意味と勘違いされやすいが、それぞれ異なる意味であるため留意されたい。

ロケールは、国や地域、言語などの表記規則を表す。日時表記で考えた場合、ある日時を日本語や英語で表記することができる。

一方、タイムゾーンは、同じ標準時（国や地域で共通して使う時刻）を使う地域全体を表す。ある日時を基準に、指定した国や地域の日時を表す。国や地域によって時差があるため、異なる日時を取る場合がある。また、ロケールとタイムゾーンを併用することで、日本語表記で他の国の日時を表すことも可能である。