Introduction to Date and Time API 2 (2013-11-09)

1. Introduction to
Date and Time API II
HASUNUMA Kenji
GlassFish Community
khasunuma@java.net
Twitter: @khasunuma
November 9, 2013
#ccc_r21

2. Time?

10. Representation of
Date/Time

11. java.util.Date
ANSI/ISO Cのtime_tと機能的に同等
現在は日付・時刻の表現のみに徹する
※java.sql.Date等のサブクラス
java.util.Calendar
Javaの国際化対応(JDK 1.1)で導入
日付・時刻の作成・編集に用いる
※GregorianCalendar等のサブクラス
java.time.*
(JSR 310)
JDK8~、Date/Calendar代替が当初の目標
日付・時刻を総合的に扱うフレームワーク
※規模はJDK8の新APIでも最大級
※その他、XML DOM APIのXMLGregorianCalendarがある

12. java.util.Dateの課題
• フィールド操作が面倒
• 年フィールド+1900が実際の年
• 月が0から始まる (1月→0…12月→11)
• フィールドの直接操作が非推奨 (Calendarを使う)
• 日付部と時刻部が混在している
• 日付演算が貧弱、フォーマット機能も使い勝手に難
• JDK 1.1以降、一部例外を除きメンテナンスなし

13. java.util.Calendarの課題
• フィールド操作が面倒 (Dateよりは改善)
• 月が0から始まる →定数でお茶を濁す
• フィールド操作の使い勝手がイマイチ
• 日付演算が貧弱 … それでもDateよりは多少マシ
• 日付・時刻型として認識されないことも多い
例: DateFormat → Dateとの相互変換を利用

14. java.util.Calendarの改善
JDK8よりCalendar.Builderを導入
→メソッドチェーン(1行)で日付・時刻を表せる
// 2013年11月9日を表すCalendar (since JDK8)
Calendar calendar = new Calendar.Builder()
.setDate(2013, NOVEMBER, 9)
.setField(HOUR_OF_DAY, 9)
.build();

15. JSR 310
Date and Time API

16. JSR 310 : Date and Time API
•Date、Calendar、DateFormat等を置き
換えることが目的
•ISO 8601形式の日付・時刻表現
•ImmutableかつスレッドセーフなAPI
•設計思想はJoda-Timeに酷似

17. java.util.Date JSR 310
オブジェクト Mutable Immutable
精度 ミリ秒 ナノ秒
フィールド操作 Calendar経由 直接サポート
タイムゾーン サポート サポート
toString戻り値 Unix形式 ISO 8601形式
日付と時刻の分離 不可 可能
日付演算 比較のみ 様々な日付演算
関連クラス数 数個 たくさん

18. JSR 310のメリット
•月:1∼12 (Date, Calendarは0∼11)
•toStringでISO 8601形式を返す
•日付と時刻を分離することができる
•多様な日付演算機能を持つ
•スレッドセーフである

19. JSR 310のデメリット
•JDK8 APIの中でも最大規模(=複雑)
•既存APIとの相互運用性はガン無視
• Dateとの相互変換は比較的最近に実現
•今後の展開が不明瞭
• JPAやJAXBへの展開は検討中?
• 少なくともJavaFX 8には間に合わず

20. 参考: ISO 8601形式
• 日付: yyyy-MM-dd
• 2013-11-09
• 時刻: hh:mm:ss.SSSZ
• 04:05:00.000Z
• 日時: yyyy-MM-dd’T’HH:mm:ss.SSSZ
• 2013-11-09T04:05:00.000Z

21. JSR 310 Essentials

22. マシン向けの表現(内部表現)
• Instant
• Duration
• Clock
人間向けの表現(外部表現)
• DateTime
• Period
• Chronology

23. マシン向けの表現(内部表現)

24. 人間向けの表現(外部表現)

25. DateTime : 日付・時刻
• TemporalAccessor等の実装
• 現在日時または任意の日時から生成
• DateTimeの演算(plus/minus)および他
のDateTimeからの変換をサポート
• Instantに対応する人間向け表現

26. 主なDateTimeの実装
• LocalDate, LocalTime, LocalDateTime
• OffsetTime, OffsetDateTime
• ZonedDateTime
• 不足情報の追加または余剰情報の切り
捨てにより相互に変換可

27. Date Time DateTime
Local
年/月/日
!
時差情報なし
!
時/分/秒/未満
時差情報なし
年/月/日
時/分/秒/未満
時差情報なし
Offset N/A
!
時/分/秒/未満
UTCからの時差
年/月/日
時/分/秒/未満
UTCからの時差
Zoned N/A N/A
年/月/日
時/分/秒/未満
タイムゾーン

28. OffsetDateTime vs. ZonedDateTime
• OffsetDateTime - UTCからの時差のみ考慮
• ZonedDateTime - タイムゾーンを考慮
※タイムゾーン UTCからの時差
タイムゾーンは以下も考慮している:
• 夏時間(米国や西欧で多く導入)
• 時差の改訂(ごく稀に発生)

29. Chronology : 暦 (インタフェース)
Chronology
暦そのものを表し、各種変換
メソッドを提供
ChronoLocalDate 暦の情報を含むLocalDate
ChronoLocalDateTime
<D extends ChronoLocalDate>
ChronoLocalDateに
時刻を付加
ChronoZonedDateTime
<D extends ChronoLocalDate>
ChronoLocalDateに
時刻とタイムゾーンを付加
Era
暦の紀元(開始年)を表す
※和暦は開始・終了年月日

30. Chronologyの実装クラス
IsoChronology/-Era
LocalDate
ISO 8601(標準)
JapaneseChronology/-Era
JapaneseDate
和暦(日本)
ThaiBuddistChronology/-Era
ThaiBuddistDate
仏暦(タイ)
MinguoChronology/-Era
MinguoDate
民国紀元(台湾)
HijirahChronology/-Era
HijirahDate
イスラム暦

31. 日付・時刻演算
• DateTime、Period、Instant、Durationはそれ自身が
加算・減算・比較・判定・変換メソッドを持つ
• OpenJDK合流以前と比較して機能は大幅に削減さ
れたものの、依然としてDate/Calendarより強力
• 昨年同時期と比較して、Chronologyの使い勝手は向
上した模様 (インタフェースのdefaultメソッド乱用という悪しき前例を作ったが…)
• Immutableのため、演算結果がもとのオブジェクト
に影響しないのも大きなメリット

32. 日付・時刻の構成要素
Year
「年」を表すクラス
※加減算・判定・各種変換メソッド
Month
「月」を表す列挙型、月末日付も保持
※加減算・各種変換メソッド
YearMonth
「年月」を表すクラス
※加減算・判定・各種判定メソッド
MonthDay
「月日」を表すクラス
※「年」を加えればLocalDateへ
DayOfWeek
「曜日」を表す列挙型
※DateTimeからの曜日取得も可

33. JSR 310のフォーマット機能
• LocalDate等のtoStringメソッドは、ISO 8601形式
でフォーマットしたものを返す
• 標準以外のフォーマット→DateTimeFormatter
※DateTimeFormatterには使用頻度の高いフォーマットが定義済み
• フォーマットを新しく作成する場合は、
DateTimeFomatterBuilderの使用を推奨
※国内ではyyyy/MM/dd形式が普及しているため、欧米と比較して
DateTimeFormatterBuilderの使用頻度は高いと思われる
• java.text.DateFormatはJSR 310では使用できない
※逆にDateTimeFormatterはjava.text.DateFormatに変換可能

34. Interoperability

35. JSR 310 Date/Calendar変換
重要 : JSR 310はDate/Calendarとの直接変換を
サポートしない
• DateはInstantを介してJSR 310と相互変換が可能
具体的にはDate.from() / Date.toInstant()を用いる
• CalendarはCalendar.toInstant()でInstantに変換可能、
ただしその逆はできない
• Instant.toEpochMilli() / Instant.ofEpochMilli() で
Instantをlong値に変換する方法もあり

36. ThreeTen backport
• JSR 310からJDK8依存の部分を取り除き、JDK7で
利用可能にした、JSR 310ライクなライブラリ
(パッケージ名はjava.timeではなくorg.threeten.bp)
• Java SE 8リリース前にJSR 310を予習するための
教材として最適
• Apache License 2.0のOSSとして配布
https://github.com/ThreeTen/threetenbp

37. Examples

38. // 今日の日付を取得→date
LocalDate date = LocalDate.now();

39. // 2013年11月9日→date
LocalDate date =
LocalDate.of(2013, 11, 9);

40. // 今日の日付→d1
// 3日後の日付→d2
LocalDate d1 = LocalDate.now();
LocalDate d2 = d1.plusDays(3);

41. // 今日の日付→date
// 今日の13時40分→dateTime
LocalDate date = LocalDate.now();
LocalDateTime dateTime =
date.atTime(13, 40);

42. // 今日の日時→dateTime
// 今日の日付→date
LocalDateTime dateTime =
LocalDateTime.now();
LocalDate date =
LocalDate.from(dateTime);

43. // date: 1992年10月8日 (うるう年)
// → leap = true
LocalDate date =
LocalDate.of(1992, 10, 8);
boolean leap = date.isLeapYear();

44. // 今日の日付→date
// dateを標準出力へ
LocalDate date = LocalDate.now();
System.out.println(date.toString());
2013-11-09
出力結果

45. // 今日の日付(和暦)→jdate
// ThreeTen Backportでも結果自体は同じ
JapaneseDate jdate =
JapaneseDate.now();
System.out.println(jdate.toString);
H25-11-09
出力結果

46. 応用 : JSR 310をJAXBに対応させてみる
public class LocalDateXmlAdapter extends!
XmlAdapter<XMLGregorianCalendar, LocalDate> {!
!
@Override!
public LocalDate unmarshal(XMLGregorianCalendar value) throws Exception {!
int timezone = value.getTimezone();!
ZoneOffset offset = ZoneOffset.ofTotalSeconds(timezone * 60);!
return OffsetDateTime.of(value.getYear(), value.getMonth(),!
value.getDay(), 0, 0, 0, 0, offset).toLocalDate();!
}!
!
@Override!
public XMLGregorianCalendar marshal(LocalDate value) throws Exception {!
ZoneOffset offset = OffsetDateTime.now().getOffset();!
int timezone = offset.getTotalSeconds() / 60;!
return DatatypeFactory.newInstance().newXMLGregorianCalendarDate(!
value.getYear(), value.getMonthValue(), value.getDayOfMonth(),!
timezone);!
}!
!
}

47. Conclusion

48. JSR 310とは何なのか?
•JSR 310はjava.util.Dateの欠点をすべて
解決しようとする野心的試み
•過去との互換性を断ち切ることで、日
付・時刻APIの理想を追求した
•正直やり過ぎ感も否めないが、既存API
の問題点の多くを解決した点は評価

49. Date/Calendarの今後は?
• JSR 310が浸透するまで、当分の間はそ
の位置づけに変化はないはず。
• Calendar.Builderは延命措置だが、短期
的には効果大。
• 日付の操作ではJSR 310に遠く及ばな
いため、長期的にはフェードアウト?

50. JDK8時代の日付・時刻表現
• お好きなAPIをどうぞ。
• Date/CalendarとJSR 310の相互変換につい
ては早いうちに準備するのがベター。
• 当初からJSR 310の使える箇所は、業務ロ
ジックの日付処理、JAXBおよびそれに依存
するJAX-RS/JAX-WS。

51. Introduction to Date and Time API II
HASUNUMA Kenji
khasunuma@java.net
Twitter: @khasunuma