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.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はそれぞれ容易に変換が可能である。

以下に例を示す。

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));

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));

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もそれぞれ容易に変換が可能である。
以下に例を示す。

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));

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"));

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に変換することが可能である。

以下に例を示す。

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の各クラスの相互運用性を参照されたい。

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等のクラスと相互変換が可能である。

以下に例を示す。

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

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

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

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

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

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

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

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

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

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

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では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メソッドが提供されている。

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

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

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

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では、過去・未来・同時などの時系列の比較が行える。

以下に例を示す。

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

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

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

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. 日時の判定 ¶

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

妥当な日時文字列かを判定したい場合、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 !!");
}

うるう年かを判定したい場合、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. 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 を参照されたい。

7.3.2.6.1. 設定方法 ¶

Java8 Time Dialectを使用するためには、以下の2点の設定を行う。

なお、いずれもブランクプロジェクトには設定済みであり、新たに設定を加える必要はない。

thymeleaf-extras-java8time の依存関係の設定
Java8 Time Dialectを使用するためのBean定義

pom.xmlの定義

[artifactID]-webプロジェクトのpom.xml
<dependencies>
  
  
  <dependency>
    <groupId>org.thymeleaf.extras</groupId>
    <artifactId>thymeleaf-extras-java8time</artifactId>
  </dependency>
</dependencies>
Note

上記設定例は、依存ライブラリのバージョンを親プロジェクトである terasoluna-gfw-parent で管理する前提であるため、pom.xmlでのバージョンの指定は不要である。上記の依存ライブラリはterasoluna-gfw-parentが依存しているSpring Bootで管理されている。

spring-mvc.xmlの定義

<bean id="templateEngine" class="org.thymeleaf.spring6.SpringTemplateEngine">
    
    <property name="additionalDialects">
        <set>
            
            <bean class="org.thymeleaf.extras.java8time.dialect.Java8TimeDialect"/> 
        </set>
    </property>
</bean>
項番説明

(1)

thymeleaf-extras-java8time のdependencyを定義する。

(2)

thymeleaf-extras-java8time のバージョンを定義する。

指定するバージョンは、 Macchinetta Server Framework (1.x)のスタックの利用するOSSのバージョンを参照されたい。

(3)

thymeleaf-extras-java8time のdependencyを追加することで、Java8 Time Dialectが利用可能となる。

(4)

additionalDialects に、Java8TimeDialect を定義することで、テンプレートHTML内で、#temporals が利用可能となる。

7.3.2.6.2. 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> 
項番説明

(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.6.3. #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

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

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

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

Table Of Contents

Previous topic

Next topic

This Page

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

7.3.1. Overview ¶

7.3.2. How to use ¶

7.3.2.1. 日時取得 ¶

7.3.2.1.1. 現在日時で取得 ¶

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

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

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

7.3.2.2. 期間 ¶

7.3.2.2.1. 期間の取得 ¶

7.3.2.3. 型変換 ¶

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

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

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

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

7.3.2.3.5. 文字列からのパース ¶

7.3.2.4. 日付操作 ¶

7.3.2.4.1. 日時の計算 ¶

7.3.2.4.2. 日時の比較 ¶

7.3.2.4.3. 日時の判定 ¶

7.3.2.4.4. 年月日等の個別取得 ¶

7.3.2.5. 和暦（JapaneseDate）¶

7.3.2.5.1. 和暦の取得 ¶

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

7.3.2.5.3. 文字列からのパース ¶

7.3.2.5.4. 西暦・和暦の変換 ¶

7.3.2.6. Thymeleafのダイアレクト ¶

7.3.2.6.1. 設定方法 ¶

7.3.2.6.2. Viewの実装 ¶

7.3.2.6.3. #temporalsのメソッド ¶

クラス名	説明
`java.time.OffsetDateTime`	定量値（時差のみ）を持つため、各地域の時間の概念に変化がある場合も、システムに変化が起こらない。
`java.time.ZonedDateTime`	時差に加えて地域の概念があるため、各地域の時間の概念に変化があった場合、システムに変化が起こる。（政策としてサマータイム導入される場合など）

項番	説明
(1)	`thymeleaf-extras-java8time` のdependencyを定義する。
(2)	`thymeleaf-extras-java8time` のバージョンを定義する。指定するバージョンは、 Macchinetta Server Framework (1.x)のスタックの利用するOSSのバージョンを参照されたい。
(3)	`thymeleaf-extras-java8time` のdependencyを追加することで、Java8 Time Dialectが利用可能となる。
(4)	`additionalDialects` に、`Java8TimeDialect` を定義することで、テンプレートHTML内で、`#temporals` が利用可能となる。

項番	メソッドシグネチャ	説明
	format(Temporal)	`Temporal` を指定してフォーマットする。
	format(Temporal, フォーマット文字列)	`Temporal` 、フォーマット文字列を指定してフォーマットする。
	format(Temporal, ロケール)	`Temporal` 、ロケールを指定してフォーマットする。
	format(Temporal, フォーマット文字列, ロケール)	`Temporal` 、フォーマット文字列、ロケールを指定してフォーマットする。
	formatISO(Temporal)	`Temporal` を指定して ISO8601形式にフォーマットする。

項番	説明
(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` と表示される。