【Java】Java8からの日時フォーマットクラスの使い方解説

こんにちは、研修を終えたばかりの駆け出しエンジニアの伊藤です。

東京ITカレッジのJava研修で学んだ内容を復習も兼ねて記事にしたいと思います。
今回は、Java8から採用された新APIを使った日時フォーマットについて説明します
この記事では、最低限覚えておいてほしいクラスとして、基本的な操作方法やメソッドを紹介します。

Javaやプログラムについて勉強し始めた方の参考になれば幸いです！
（eclipseを使用して計算を行っています）

関連記事：よく使う日時クラス解説まとめ

　　　　　日時取得の Date/Calendar クラスの基本と使い方を解説

　　　　　Date/Calendarの日時フォーマット/日時比較/日時計算クラス使い方解説

　　　　　Java8からの現在や指定日時取得 9クラスの基本と使い方を解説

　　　　　Java8からの日時計算/日時比較クラスの使い方を解説

　　　　　Java8からの日時フォーマットクラスの使い方解説

　　　　　日付時刻の変換方法（新旧 API 相互変換、Data／Calendar の変換）

　　　　　処理時間/経過時間計測（ミリ秒）に使える2つのメソッドを解説

ISO_8601

Date And Time APIを調べていると、必ず目にしたことがあると思います。
ISO_8601とは、日時を表すフォーマットを定めた国際規格のことです。Date And Time APIは、このISO_8601を基にフォーマット化されています。

基本となるものは、以下の２形式です。

　・拡張形式（DateTimeFormatterのデフォルト）
    　2020-08-02T00:44:46+09:00
　・基本形式
　　  20200802T004446+0900

Date and Time API が文字列表現のデフォルトとして採用しているのは主に拡張形式です。
日付と時刻の間は「T」で連結をする形です。
ISO_8601では、多くの日時フォーマット（省略したもの含め）がありますが、Date And Time APIで対応しているものはその中の一部です。

DateTimeFormatterクラス

文字列の解析や書式を指定する際に、デフォルトのISO_8601の拡張表記とは違う独自の書式を使う場合、java.time.formatパッケージにあるDateTimeFormatterを使うことで、独自のフォーマットで表示することができます。
例えば、デフォルトでは「2020-07-07」になりますが、年月日の区切りを変えたい場合、書式を指定して「2020/07/07」と表記することができます。

主要な日時クラスにはDateTimeFormatterを使って、日時データを指定された書式の文字列に変換したり、文字列を解析して日時データに変換するためのメソッドが用意されています。

　・書式設定用　　format(DateTimeFormatter formatter)
　・文字列解析用　parse(CharSequence text, DateTimeFormatter formatter)

その他に、指定されたパターンを使用してフォーマッタを作成する ofPatternメソッド等もあります。
そして、DateTimeFormatterクラスは旧日時APIのSimpleDateFormatと違いスレッドセーフなところが特徴です。
スレッドセーフになることにより、毎回インスタンス化する必要がないため、処理速度が速くなる利点があります。

また、DateTimeFormatterでは、一部の日時書式パターンが定数として用意されています。

ISO_LOCAL_DATE　　　	    2020-07-07		        年月日を「-」で区切った日付書式（デフォルトでもある）

ISO_OFFSET_DATE　　	    2020-07-07+09:00	    ISO_LOCAL_DATE＋UTCの時差が加わった日付書式

ISO_LOCAL_TIME	　　    09:10:11.100		    時分秒を「:」でミリ秒も表示する時刻書式

ISO_LOCAL_DATE_TIME	    2020-07-07T09:10:11.100 年月日を「-」で区切り、時分秒を「:」でミリ秒も表示し、その２つを「T」で連結した日時書式。

//ISOサンプルコード
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class IsoSample {

	public static void main(String[] args) {
		System.out.println("---取得結果--------------------");
		LocalDateTime localDateTime = LocalDateTime.of(2020,07,07,10,10,10,100);
		DateTimeFormatter formatter = DateTimeFormatter.ISO_LOCAL_DATE;
		String s1 = localDateTime.format(formatter);
		System.out.println("ISO_LOCAL_DATE ： " + s1);
		DateTimeFormatter formatter2 = DateTimeFormatter.ISO_LOCAL_TIME;
		String s2 = localDateTime.format(formatter2);
		System.out.println("ISO_LOCAL_TIME ： " + s2);
	}
}

---取得結果--------------------
ISO_LOCAL_DATE ： 2020-07-07
ISO_LOCAL_TIME ： 10:10:10.0000001

また、パターン文字としては、以下の物があります。

主な日時パターン文字列

年号	 	G	    西暦（AC、BC）
			        年号‐昭和、平成、令和等（JapaneseDateクラスを使用した場合）
		    GGGGG   S、H、R等	

西暦（年） 	uuuu	2020
		    uu	    20

紀元（年） 	yyyy	2020
		    yy	    20

月		    MM	    07
　　　　　 	MMM     Jul
          	MMMM    July

日		    dd	    01

曜日	  	E	    Mon	（ロケールがJapanの場合「月」）
		    EEEE	月曜日	（ロケールがJapanの場合のみ）

時		    H	    0～23時
		    h	    1～12時

分		    m 	    05、10等

秒		    s	    15、20等

ミリ秒	    S	    022、111等
		    SSSS	0044、0031等

オフセット	XXX	    +09:00

主なパターン文字で注意する点が、新APIから導入された年を表す「u」の記号です。
「y」と「u」の違いについては、和暦表示で詳しく解説してあります。

また、従来APIのパターン文字と同じく、大文字小文字では違うものを表すので注意してください。
この他にも多くのパターン文字の書式定数があるので、興味のある方はJavaDocをご参照ください。

formatメソッド

指定した書式で文字列を取得する際に使用します。
formatメソッドには以下の２つがあります。

① DateTimeFormatterクラスのString format(TemporalAccessor temporal)
② LocalDateクラスのString format(DateTimeFormatter formatter)

この２つのメソッドに明確な違いはなく、

②のLocalDateやLocalDateTime の formatメソッドでは、引数に指定したDateTimeFormatterクラス の formatメソッドをそのまま呼び出し（②のメソッドでソースを書いたとしても、引数で①を呼び出し）ています。
基本的にはDateTimeFormatter の formatメソッドを呼び出しますが、LocalDate の formatメソッドでの呼び出し方もできます、というようなことです。

使い分けとしては、プログラムの文脈から考えて使い分けたり、分かりやすい（使いやすい）方を使ったり、といった区分で、絶対の使い分けはありません。「何」を「どうするか」という文章のような形で実装を考えると読みやすいコードが書けると思います。

※ TemporalAccessor temporalでは、パッケージjava.time.temporalを利用して、「年、月、日、時間などの日付/時間の単位」「月、曜日、時などの日付/時間のフィールド」「日付/時間の調整関数」「異なる週の定義」がサポートされています。

LocalDate 変数名1 = LocalDate.of(int, int, int);
DateTimeFormatter 変数名2 = DateTimeFormatter.パターン文字;
String 変数名3 = 変数名1.format(変数名2);

３行目の現在日時を指定した日時パターンの文字列（String）に変換するために使っています。

また、書式を指定しない場合、Date And Time APIのクラスが持つデフォルトの書式（ISO_8601の拡張形式）を使うことになります。

//デフォルトサンプル
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;

public class DefaultSample {

	public static void main(String[] args) {
		System.out.println("---取得結果--------------------");
		LocalDateTime localDateTime = LocalDateTime.of(2020,07,07,10,10,10,100);
		DateTimeFormatter ldtFormatter = DateTimeFormatter.BASIC_ISO_DATE;
		System.out.println("指定日時(デフォルト)    ： " + localDateTime);
		System.out.println("指定日時(①フォーマット) ： " + ldtFormatter.format(localDateTime));
        System.out.println("指定日時(②フォーマット) ： " + localDateTime.format(ldtFormatter));
		OffsetDateTime offsetDateTime = OffsetDateTime.now();
		DateTimeFormatter odtFormatter = DateTimeFormatter.ISO_OFFSET_DATE_TIME;
		System.out.println("現在時刻(デフォルト)    ： " + offsetDateTime);
		System.out.println("現在時刻(①フォーマット) ： " + odtFormatter.format(offsetDateTime));
        System.out.println("現在時刻(②フォーマット) ： " + offsetDateTime.format(odtFormatter));
	}
}

---取得結果--------------------
指定日時(デフォルト) 　 ： 2020-07-07T10:10:10.000000100
指定日時(①フォーマット) ： 20200707
指定日時(②フォーマット) ： 20200707
現在時刻(デフォルト)    ： 2020-08-26T12:26:25.481110+09:00
指定日時(①フォーマット) ： 2020-08-26T12:26:25.48111+09:00
現在時刻(②フォーマット) ： 2020-08-26T12:26:25.48111+09:00

上記サンプルでは、formatメソッドの2つの使い方を両方載せています。取得結果から分かる通り、どちらもまったく同じ結果が出力されています。

関連記事：DateTimeFormatterクラス（JavaDoc‐formatメソッド① DateTimeFormatterクラスのString format(TemporalAccessor temporal)

　　　　　LocalDateクラス（JavaDoc‐formatメソッド② LocalDateクラスのString format(DateTimeFormatter formatter)

ofPatternメソッド

指定されたパターンを使用してフォーマッタを作成することができます。

LocalDate 変数名1 = LocalDate.now();		//LocalDate 変数名1 = LocalDate.of(int, int, int);
DateTimeFormatter 変数名2 = DateTimeFormatter.ofPattern("日時パターン指定");
String 変数名3 = 変数名1.format(変数名2);

日時クラスを宣言し、現在時刻を取得します。
次に、ofPatternメソッドを使って、任意の書式が指定されたDateTimeFormatterインスタンスを取得します。

そして、formatメソッドの引数に書式指定されたDateTimeFormatterを設定して、変数1の現在時刻を指定された書式の文字列に変換しています。
ofPatternメソッドを使ってインスタンスを取得する時、引数に日時パターン指定だけを渡した場合は、実行環境のロケール（国や地域、言語）で出力されます。任意のロケールを指定したい場合は、ofPatternメソッドの第2引数で指定することができます。

DateTimeFormatter 変数名2 = DateTimeFormatter.ofPattern("日時パターン指定", Locale.国や地域);

また、ofPatternメソッドで取得したDateTimeFormatterは、不変オブジェクトであり、スレッドセーフです。
実際のプログラムで見てみましょう。

//ofPatternメソッド　サンプルプログラム
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Locale;

public class FormatSample2 {

	public static void main(String[] args) {

		System.out.println("---取得結果--------------------");
		//LocalDate（タイムゾーンのない日付）
		System.out.println("--LocalDate（タイムゾーンのない日付）--");
		LocalDate localDate = LocalDate.now();
		DateTimeFormatter date1 = DateTimeFormatter.ofPattern("yyyy-MM-dd");
		String stringDate1 = localDate.format(date1);
		System.out.println("現在日付 ： " + stringDate1);
		//LocalDateTime(タイムゾーンのない日時）
		System.out.println("--LocalDateTime(タイムゾーンのない日時）--");
		LocalDateTime localDateTime = LocalDateTime.of(2020,07,07,10,10,10,100);
		DateTimeFormatter date2 = DateTimeFormatter.ofPattern("yyyy年MM月dd日 HH時mm分ss秒SSS");
		String stringDate2 = localDateTime.format(date2);
		System.out.println("指定日時 ： " + stringDate2);
		//OffsetDateTime（オフセット付きの日時）
		System.out.println("--OffsetDateTime（オフセット付きの日時）--");
		ZoneOffset utc = ZoneOffset.UTC;
		OffsetDateTime offsetDateTime = OffsetDateTime.of(2020,07,07,10,10,10,100, utc);
		DateTimeFormatter date3 = DateTimeFormatter.ofPattern("yyyy年MM月dd日 HH:mm:ss.SSSXXX");
		String stringDate3 = offsetDateTime.format(date3);
		System.out.println("現在日時 ： " + stringDate3);
		//ZonedDateTime(タイムゾーン付きの日時）
		System.out.println("--ZonedDateTime(タイムゾーン付きの日時）--");
		ZonedDateTime zonedDateTime = ZonedDateTime.now();
		DateTimeFormatter date4 = DateTimeFormatter.ofPattern("yyyy/MMM/dd EEE HH:mm:ss.SSSXXX VV");
		String stringDate4 = zonedDateTime.format(date4);
		System.out.println("現在日時  　　  　 ： " + stringDate4);
		DateTimeFormatter date41 = DateTimeFormatter.ofPattern("yyyy/MMM/dd EEE HH:mm:ss.SSSXXX VV",Locale.ENGLISH);
		String stringDate41 = zonedDateTime.format(date41);
		System.out.println("指定日時（英語）   ： " + stringDate41);
	}
}

---取得結果--------------------
--LocalDate（タイムゾーンのない日付）--
現在日付 ： 2020-08-18
--LocalDateTime(タイムゾーンのない日時）--
指定日時 ： 2020年07月07日 10時10分10秒000
--OffsetDateTime（オフセット付きの日時）--
現在日時 ： 2020年07月07日 10:10:10.000Z
--ZonedDateTime(タイムゾーン付きの日時）--
現在日時  　　  　 ： 2020/8月/18 火 11:39:25.573+09:00 GMT+09:00
指定日時（英語）   ： 2020/Aug/18 Tue 11:39:25.573+09:00 GMT+09:00

ofPatternメソッドの引数に指定した日時パターンでの表示ができました。

英語の月（MMM）、曜日（EEE）表記を出力したい場合は、Localの設定が必要になります。（サンプルプログラムのZonedDateTime(タイムゾーン付きの日時）設定をしないと 8月月 と言うような出力になるので、どのような出力フォーマットにしたいかをよく考えて使いましょう。

和暦表示するには？

JapaneseDateクラスを使用すると、和暦の表示をすることができます。

//和暦表示サンプル
import java.time.chrono.JapaneseDate;
import java.time.chrono.JapaneseEra;
import java.time.format.DateTimeFormatter;

public class WarekiSample {

	public static void main(String[] args) {
		System.out.println("---取得結果--------------------");
		JapaneseDate dateNow = JapaneseDate.now();
		DateTimeFormatter formatterSeireki = DateTimeFormatter.ofPattern("uuuu年MM月dd日");
		DateTimeFormatter formatterWareki = DateTimeFormatter.ofPattern("Gyy年MM月dd日");
		DateTimeFormatter formatterWarekiG = DateTimeFormatter.ofPattern("GGGGGyy年M月d日");
		String nowSeireki = dateNow.format(formatterSeireki);
		System.out.println("現在日時 ： " + nowSeireki);
		JapaneseDate date1 = JapaneseDate.of(2020, 7, 31);
		String date1WarekiG = date1.format(formatterWarekiG);
		System.out.println("和暦表示 ： " + date1WarekiG);
		String date1Wareki = date1.format(formatterWareki);
		System.out.println("和暦表示 ： " + date1Wareki);
		JapaneseDate date2 = JapaneseDate.of(JapaneseEra.HEISEI, 30, 8, 1);
		String date2WarekiG = date2.format(formatterWarekiG);
		System.out.println("和暦表示 ： " + date2WarekiG);
		String date2Wareki = date2.format(formatterWareki);
		System.out.println("和暦表示 ： " + date2Wareki);
	}
}

---取得結果--------------------
現在日時 ： 2020年08月26日
和暦表示 ： R02年7月31日
和暦表示 ： 令和02年07月31日
和暦表示 ： H30年8月1日
和暦表示 ： 平成30年08月01日

DateTimeAPIではJapaneseDateという和暦を表す専用のクラスが用意されています。

JapaneseDateクラスを使用すると「y」は和暦での年を返すことができます。
和暦サンプルを見ると、「u」と「y」の違いが分かると思います。
和暦年号（平成、令和等）を表す「G」は「y」と一緒に使うと結果表示が分かりやすいです。

また、JapaneseEraクラスでを使って指定できる年号は「MEIJI」「TAISHO」「SHOWA」「HEISEI」だけです。
JapaneseEra.REIWA と記述するとエラーになってしまいます。

「REIWA」は入っていないので、使用する場合は気を付けてください。

parseメソッド

文字列から日時オブジェクトを取得、または文字列の解析をする際に使用します。
parseメソッドには以下の３つがあります。

①

LocalDate 変数名1 = LocalDate.parse("日時文字列");	//日時文字列はデフォルト形式のみ

LocalDate等の日時クラスからparseメソッドを呼び出した場合は、呼び出したLocalDateクラスのインスタンスを取得します。

この場合は、ISO_8601の解説でもしましたが、拡張形式（DateTimeFormatterのデフォルト）で書かないと、（日時を「-」で区切った形での表記であること、"2020-07-07"と"0"省略をしないこと等）コンパイルは通りますが、実行時にエラーになってしまいます。

②

DateTimeFormatter 変数名1 = DateTimeFormatter.ofPattern("日時パターン指定");
LocalDate 変数名1 = LocalDate.parse("日時文字列", 変数名1);  //TemporalAccessor 変数名2 = LocalDate.parse("日時文字列",変数名1);	でも同じ

②ではDateTimeFormatterクラスのofPatternメソッドを使い、日時パターンを指定しています。

この場合は、日時文字列はデフォルトではなく、日時パターン指定した形式に合わせた文字列を書くことができます。
第2引数にパターン指定をした変数を書くことで、"2020/7/7"のような「/」で区切った形の日時文字列も記述、解析することができます。

また、TemporalAccessorのインターフェースからparseメソッドを呼び出すこともできます。しかし、このインターフェースの実装はISO以外の暦体系になっている可能性があるため、意図した日時を表示できなくなる可能性があります。その為、parseメソッドでは「LocalDateクラス等のparse」を使って書くことが一般的となっています。

※formatメソッドでも解説した通り、parseメソッドでも日時インスタンスの取得にはDateTimeFormatterクラスのparseメソッドを呼び出し、文字列から日時クラスに変換を行っています。

その為、上記の①LocalDateを宣言した際も、内部ではDateTimeFormatterクラスのparseメソッドをそのまま呼び出しています。

③

DateTimeFormatter 変数名1 = DateTimeFormatter.ofPattern("日時パターン指定");
TemporalAccessor 変数名2 = 変数名1.parse("日時文字列", TemporalQuery);

DateTimeFormatterクラスのインスタンスから呼び出した場合は、引数に文字列だけ渡すと戻り値はjava.time.format.Parsedクラスのインスタンスが返ってきてしまい、意図していた日時データを表すことができません

（TemporalAccessor 変数名2 =  変数名1.parse("日時文字列"); のように、引数に文字列だけ渡した場合のこと）

その為、

②のように日時クラスのparseメソッドを使って日時に変換するか、

③のように第2引数にTemporalQueryを指定して変換するか、のどちらかで意図したデータとして受け取ることができます。

※TemporalQuery とは、時間的オブジェクトを問い合わせし確かめるために用意されたインタフェースで、時間的オブジェクトから情報を抽出するために使用します。

下記のサンプルでは、TemporalQueryの引数に対してメソッド参照を使って書いています。他には、ラムダ式や匿名クラスを実装した使い方があります。

日時を保証するためのチェックや、存在する日時かの確認等をする場合は、③を使うことで解析をスムーズに行うことができます。
ただし、文字列からの日時オブジェクトの取得では、①と②どちらかを使う方が意図した日時が取得できます。

下記のサンプルプログラムにも、どのクラスのメソッドからの呼び出しなのかが分かるように番号を振ってあるので、上記の解説と合わせて見てください。

//parseメソッドサンプル
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.temporal.TemporalAccessor;

public class ParseSample {

	public static void main(String[] args) {
		System.out.println("---取得結果--------------------");
		System.out.println("---① LocalDate.parse（デフォルト指定文字列）---");
		LocalDate date1 = LocalDate.parse("2020-07-07");	//2020-7-31 ではエラー
		System.out.println("LocalDate : " + date1);
		System.out.println("---② LocalDate.parse（文字列, パターン文字指定）---");
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("uuuu/MM/dd");
		LocalDate date2 = LocalDate.parse("2020/07/07",formatter);
		System.out.println("class : " + date2.getClass());
		System.out.println("LocalDate : " + date2);
		System.out.println("------③ formatter.parse(文字列)------");
		TemporalAccessor temporal = formatter.parse("2020/07/07");
		System.out.println("class : " + temporal.getClass());
		System.out.println("DateTimeFormatter : " + temporal);
		System.out.println("------③ formatter.parse（文字列、TemporalQuery)------");
		temporal = formatter.parse("2020/07/07", LocalDate::from);
		System.out.println("class : " + temporal.getClass());
		System.out.println("LocalDate : " + temporal);
	}
}

---取得結果--------------------
---① LocalDate.parse（デフォルト指定文字列）---
LocalDate : 2020-07-07
---② LocalDate.parse（文字列, パターン文字指定）---
class : class java.time.LocalDate
LocalDate : 2020-07-07
------③ formatter.parse(文字列)------
class : class java.time.format.Parsed
DateTimeFormatter : {},ISO resolved to 2020-07-07
------③ formatter.parse（文字列、TemporalQuery)------
class : class java.time.LocalDate
LocalDate : 2020-07-07

サンプルプログラムの③のコード上での違いは、第2引数を指定したかしていないかだけです。

しかし取得結果を見ると、取得を行っているクラスが違うことが分かると思います。
第2引数にTemporalQueryを指定することで、LocalDateクラスから日時の取得を行っていることが分かります。

他の日時データ取得も行ってみましょう。

//parseメソッドサンプル2
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

public class ParseSample {

	public static void main(String[] args) {
		System.out.println("---取得結果--------------------");
		//LocalDateTime(タイムゾーンのない日時）
		System.out.println("---LocalDateTime--------------");
		DateTimeFormatter ldtformatter = DateTimeFormatter.ofPattern("M月yyyy年d日 HH時mm分ss秒SSS");
		LocalDateTime ldt = LocalDateTime.parse("7月2020年7日 10時10分10秒100", ldtformatter);
		System.out.println("指定日時 ： " + ldt);
		//OffsetDateTime（オフセット付きの日時）
		System.out.println("---OffsetDateTime-------------");
		DateTimeFormatter odtFormatter = DateTimeFormatter.ofPattern("HHmmssSSSXXX ddMMyyyy");
		OffsetDateTime odt = OffsetDateTime.parse("101010100+12:00 07072020", odtFormatter);
		System.out.println("指定日時 ： " + odt);
		//ZonedDateTime(タイムゾーン付きの日時）
		System.out.println("---ZonedDateTime-------------");
		DateTimeFormatter zdtFormatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss.SSSXXX VV");
		ZonedDateTime zdt = ZonedDateTime.parse("2020/07/07 10:10:10.100+09:00 Asia/Tokyo", zdtFormatter);
		System.out.println("指定日時 ： " + zdt);
		//デフォルトでの日時データ変換
		ZonedDateTime time2 = ZonedDateTime.parse("2020-07-31T10:10:10+09:00[GMT+09:00]");
		System.out.println("指定日時 ： " + time2);
	}
}

---取得結果--------------------
---LocalDateTime--------------
指定日時 ： 2020-07-07T10:10:10.100
---OffsetDateTime-------------
指定日時 ： 2020-07-07T10:10:10.100+12:00
---ZonedDateTime-------------
指定日時 ： 2020-07-07T10:10:10.100+09:00[Asia/Tokyo]
指定日時 ： 2020-07-31T10:10:10+09:00[GMT+09:00]

上記サンプルプログラムでは、文字列をわざとあり得ない並びで書いていますが、取得結果ではデフォルト値でしっかりと日時データに変換されています。
また、パターン文字と文字列は同じ記述でなければエラーになるので、気を付けてください。
（"MM月"とパターン文字で指定したのに、文字列では"7月"ではエラー。MM なので 07 に合わせてください）

関連記事：LocalDateクラス（JavaDoc‐parse(CharSequence text)について）

　　　　　DateTimeFormatterクラス（JavaDoc‐ofPattern(String pattern)について）

まとめ

日時フォーマットの方法は分かったでしょうか？

他にも日時比較や日付計算の方法も紹介しているので、併せてご覧ください。

関連記事：よく使う日時クラス解説まとめ