Java日付時刻API

Javaの日付時刻APIについて。

概要

JDK1.8で新しい日付時刻API（Date and Time API）（java.timeパッケージ）が導入された。

これまで日付時刻に使っていたjava.util.Date・java.util.Calendarやjava.text.SimpleDateFormatとは全くの別物。
新APIでは従来のDateやCalendarは一切出てこない。

日付・時刻クラス

日付や時刻等の「ある時点」を表すクラスは、java.time.temporal.Temporal（TemporalAccessor）インターフェースのサブクラスになっている。

日付（年月日）を表すクラスだけでなく、年・年月・月・月日を表すクラスまで別々に用意されている。
また、日付（年月日）と日時（年月日時分秒）の他に、時刻（時分秒）を表すクラスも個別に存在する。

日時を表すクラスには、Local・Offset・Zonedの3種類が存在する。

Local

タイムゾーンを持たない日時。例えば「1時」と言った場合、日本の1時なのかアメリカの1時なのかは不明。

Offset

UTC（グリニッジ）からのオフセット（差分）を持つ日時。日本の場合は「+09:00」。

Zoned

タイムゾーン（「日本時間」とかの情報）を持つ日時。日本の場合は「Asia/Tokyo」。

Zonedには夏時間の考慮が入っているようだ。
したがって、日本時間を扱う場合はOffsetでもZonedでも大差ないと思うが、日時を保持したい場合は基本的にはZonedを使えばよいと思う。
※とりあえず何を使えばよいか→dmikurubeさんのタイムゾーン呪いの書 [2018-02-06]

import java.time.*;

ほとんどの日付時刻クラス同士は、変換用のメソッドを用いて変換できる。

直接の変換メソッドが無い場合でも、fromメソッドを使えば（必要な情報が存在している場合は）変換できる。
fromメソッドはどんな日付時刻クラスも引数に指定できる（引数の型がTemporalAccessorインターフェースになっている）が、対応していない変換の場合は例外が発生するので 、コンパイル時にチェックされるto系やat系のメソッドを使う方がいいだろう。

		OffsetTime otime = OffsetTime.from(zdt);

日付・時刻の使用例

import java.time.*;
import java.time.temporal.*;

タイムゾーン

タイムゾーンはjava.time.ZoneIdで扱う。
（従来はjava.util.TimeZoneを使っていた）

他に、UTCからのオフセット（「+09:00」みたいなやつ）を扱うZoneOffsetがある。
ZoneOffsetはZoneIdのサブクラスになっている。
ZoneIdもZoneOffsetも不変オブジェクトであり、スレッドセーフである。

OffsetDateTimeやOffsetTimeは内部でZoneOffsetを保持している。
ZonedDateTimeは内部でZoneOffsetとZoneIdの2つを保持している。

import java.time.*;

タイムゾーンの変更方法

ZonedDateTimeでUTC（GMT・標準時）からJST（日本時間）へ変換するには以下のようにする。[2017-01-19]

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

	static final DateTimeFormatter DATETIME_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

		String s = "2017-01-19 23:45:01.234";
		LocalDateTime localDate = LocalDateTime.parse(s, DATETIME_FORMATTER);
		System.out.println("ldt=" + localDate);

		ZonedDateTime utcDate = ZonedDateTime.of(localDate, ZoneId.of("UTC"));
		System.out.println("utc=" + utcDate);

		// 日付時刻の値を変えずにタイムゾーンIDだけ変更する
		ZonedDateTime jstDate1 = utcDate.withZoneSameLocal(ZoneId.of("Asia/Tokyo"));
		System.out.println("jst=" + jstDate1);

		// 同じ日時を表す別タイムゾーン
		ZonedDateTime jstDate2 = utcDate.withZoneSameInstant(ZoneId.of("Asia/Tokyo"));
		System.out.println("jst=" + jstDate2);

		String d = jstDate2.format(DATETIME_FORMATTER);
		System.out.println("str=" + d);

↓実行結果

ldt=2017-01-19T23:45:01.234
utc=2017-01-19T23:45:01.234Z[UTC]
jst=2017-01-19T23:45:01.234+09:00[Asia/Tokyo]
jst=2017-01-20T08:45:01.234+09:00[Asia/Tokyo]
str=2017-01-20 08:45:01.234

Clock

java.time.Clockは、現在日時へアクセスする為のクラス。[2014-07-21]

日付時刻クラスで現在日付・現在時刻を取得するnowメソッドに、Clockを渡すことが出来る。
普段はデフォルトのClockを使っておき、テスト用に特定日時のClockを渡す、といった使い方が出来る。

例

テスト対象クラス：

import java.time.Clock;
import java.time.YearMonth;

public class ClockExample {

	private static Clock DEFAULT_CLOCK = Clock.systemDefaultZone();

	public String getNowMonthName() {
		return getNowMonthName(DEFAULT_CLOCK);
	}

	String getNowMonthName(Clock clock) {
		YearMonth ym = YearMonth.now(clock);

		int month = ym.getMonthValue();
		if (month % 3 == 0) {
			return "Fizz";
		} else if (month % 5 == 0) {
			return "Buzz";
		} else {
			return ym.getMonth().name();
		}
	}
}

テストクラス：

import static org.hamcrest.CoreMatchers.*;
import static org.junit.Assert.*;

import java.time.Clock;
import java.time.Instant;
import java.time.ZoneId;

import org.junit.Test;

public class ClockExampleTest {

	@Test
	public void testGetNowMonthName() {
		ClockExample example = new ClockExample();

		Clock clock1 = Clock.fixed(Instant.parse("2014-01-01T00:00:00Z"), ZoneId.systemDefault());
		assertThat(example.getNowMonthName(clock1), is("JANUARY"));

		Clock clock3 = Clock.fixed(Instant.parse("2014-03-01T00:00:00Z"), ZoneId.systemDefault());
		assertThat(example.getNowMonthName(clock3), is("Fizz"));

		Clock clock5 = Clock.fixed(Instant.parse("2014-05-01T00:00:00Z"), ZoneId.systemDefault());
		assertThat(example.getNowMonthName(clock5), is("Buzz"));
	}
}

Clockの生成

import java.time.*;

Clockを指定したnowメソッドを呼び出す度（ZonedDateTime.now(clock)とか）に、Clockから“呼び出し時点の現在日時”を取得して新しい日付時刻オブジェクトが作られる。
ただし、fixedメソッドによって作られたClockの場合は、時間は進まない。何度nowメソッドを呼び出しても同じ日時が返る。

リンク

• Java8リリース前
  • cero-tさんの続・今日から始めるJava8 - JSR-310 Date and Time API (2013-02-13)
  • きしださんのJava8日付時刻APIの使いづらさと凄さ (2013-09-17)
  • HASUNUMA Kenjiさんの日本人のためのDate and Time API Tips (2013-12-04)
  • マイナビニュースの大刷新リリース Java 8の新機能 新たな日付処理のためのAPI (2014-03-11)
  • ありえるえりあ井上さんのJava8の日付および時刻処理(Date/Time API(JSR-310))の紹介と利用指針 (2014-03-15)
• Java8リリース（2014/3/18）後
  • JJUGイベント 祝☆Java 8 Launch (2014-03-21)
    • HASUNUMA Kenjiさんの『Brand new Date and Time API』講演・スライド …日付・時刻の基礎について超詳しい！
    • togetter
  • dmikurubeさんのタイムゾーン呪いの書 (2018-02-06)