Brand new Date and Time API March 21, 2014

HASUNUMA Kenjikhasunuma@java.net

http://www.coppermine.jp/Twitter: @khasunuma

Preface• JSR 310 is a new and improved date and time API

for Java.

• It is based on ISO 8601 standard.

• The reference implementation is called "ThreeTen".

• Specification Leads: Stephen Colebourne, Michael Nascimento Santos and Roger Riggs.

What is time?“Time” is described by science approaches and defined by International Standard (SI) exactly.

Skip

Definition of second (Traditional)

Definition of second (Modern)

PST (Pacific Standard Time) Offset:-08:00 (Summer:-07:00)

JST (Japan Standard Time) Offset:+09:00

Skip

Time zones (East 1/2)

Code Name Offset SummerECT Europe/Paris +01:00 +02:00CAT Africa/Harare +02:00 (N/A)ART Africa/Cairo +02:00 (N/A)EAT Africa/Addis_Abeba +03:00 (N/A)NET Asia/Yerevan +04:00 (N/A)PLT Asia/Karachi +05:00 (N/A)IST Asia/Koltaka +05:30 (N/A)BST Asia/Dacca +06:00 (N/A)

Time zones (East 2/2)

Code Name Offset SummerVST Asia/Ho_Chi_Minh +07:00 (N/A)CTT Asia/Shanghai +08:00 (N/A)JST Asia/Tokyo +09:00 (N/A)ACT Australia/Darwin +09:30 (N/A)AET Australia/Sydney +11:00 +10:00SST Pacific/Guadalcanal +11:00 (N/A)NST Pacific/Auckland +13:00 +12:00MIT Pacific/Apia +14:00 +13:00

Time zones (West 1/2)

Code Name Offset Summer

BET America/Sao_Paulo -02:00 -03:00

AGT America/Argentina/Buenos_Aires -03:00 (N/A)

CNT America/St_Johns -03:30 -02:30

PRT America/Puerto_Rico -04:00 (N/A)

EST (N/A) -05:00 (N/A)

IET America/Indiana/Indianapolis -05:00 -04:00

Time zones (West 2/2)

Code Name Offset Summer

CST America/Chicago -06:00 -05:00

MST (N/A) -07:00 (N/A)

PNT America/Phoenix -07:00 (N/A)

PST America/Los_Angeles -08:00 -07:00

AST America/Anchorage -09:00 -08:00

HST (N/A) -10:00 (N/A)

ISO 8601Date elements and interchange formats - Information interchange - Representation of dates and times

Skip

What’s ISO 8601?

• International standard for representation of dates and times, using information interchange.

• Based on Gregorian calendar system (1582).

• JIS X 0301 is Japanese translations with remarks about Japanese chronology.

• ISO 8601 and Unix time are incompatible. Unix time is basis of java.util.Date, et al.

Representation of time(w/o Time zone)

• hh:mm:ss e.g. 15:30:45

• hh:mm e.g. 15:30

• hh e.g. 15

• hh:mm:ss.s e.g. 15:30:45.250

Representation of time(w/Time zone)

• Add suffix based on the offset from UTC

• UTC: ‘Z’ e.g. 06:30:45Z

• Not UTC: +hh:mm or -hh:mme.g. 15:30:45+09:00 (JST, Asia/Tokyo) 02:30:45-08:00 (PST, America/Los_Angeles)

Representation of date• date - it consists with year, month, day and week.

• calendar date YYYY-MM-DD e.g. 2014-03-21 • ordinal date YYYY-DDD e.g. 2014-080 • week date YYYY-Www-D e.g. 2014-W12-5

• Short representations: • year-month YYYY-MM e.g. 2014-03 • year YYYY e.g. 2014 • century YY e.g. 20 • month-day --MM-DD e.g. --03-21

Definition of day• a day = 24 hours = 86,400 seconds

• 00:00~24:00 (24:00 is same as next 00:00)

• Exceptions:

• Leap seconds

• Begin and end of summer time

• When the time zone is changed

Definition of month• a month = 28, 29, 30 or 31 days

1 January 01~31 7 July 01~31

2 February 01~28/29 8 August 01~31

3 March 01~31 9 September 01~30

4 April 01~30 10 October 01~31

5 May 01~31 11 November 01~30

6 June 01~30 12 December 01~31

Definition of year• a year = approximation days while the orbital period

of Earth (365.242 19 days), 12 months. • common year = 365 days • leap year = 366 days

• 0000~9999 (0000~1582 is reserved)

mod 4 mod 100 mod 400 yearNot Zero - - common year

Zero Not Zero - leap yearZero Zero Not Zero common yearZero Zero Zero leap year

Definition of week

• a week = 7 days

• 1st week of year = a week contents the first Thursday of the year.

• a year contents 52 or 53 weeks.

1 Monday

2 Tuesday

3 Wednesday

4 Thursday

5 Friday

6 Saturday

7 Sunday

Origin of week

Representation of date and time

• concat date and time by 'T'.

• YYYY-MM-DDThh:mm:ss[Time zone]

• Alt. YYYY-DDDThh:mm:ss[Time Zone]

• e.g. 2014-03-21T06:30 2014-03-21T15:30:45+09:00 2014-079T02:30:45-08:00

Definition and representation of duration

• time amount between two time points

• date : nYnMnD e.g. 1Y3M22D

• time : nHnMnS e.g. 9H30M45S

• date and time : nYnMnDTnHnMnSe.g. 1Y3M22DT9H30M45S

Definition and representation of period

• range between two dates (adopt also two times)

• two dates : YYYY-MM-DD/YYYY-MM-DDe.g. 2013-12-31/2014-03-21

• start date and duration : YYYY-MM-DD/PnYnMnDe.g. 2013-12-31/P1Y3M22D

• end date and duration : PnYnMnD/YYYY-MM-DDe.g. P1Y3M22D/2013-03-21

• duration : PnYnMnDe.g. P1Y3M22D

JSR 310Date and Time API

Skip

JSR 310 : Date and Time API• Since 2007, Reference Implementation: ThreeTen

• Relational projects:

• ThreeTen-Extra: Features dropped from JDK8, i.e. UTC/TAI full support, Coptic chronology, et al.https://github.com/ThreeTen/threeten-extra

• ThreeTen-Backport: JSR 310 like API for JDK7. https://github.com/ThreeTen/threetenbp

• Joda-Time: Provides many hints to JSR 310.http://www.joda.org/joda-time/

Package java.time.*

Package Description Use

java.time Basic classes usually

java.time.format Date and Time Formatter often

java.time.chrono Chronology supports partially

java.time.temporal Low-level API rarely

java.time.zone Low-level API rarely

Date and Time classes

Class Field Time zone ISO 8601 Chrono.

LocalDate Date N/A compatible enable

LocalDateTime Date + Time N/A compatible enable

LocalTime Time N/A compatible N/A

OffsetDateTime Date + Time offset compatible disable

OffsetTime Time offset compatible N/A

ZonedDateTime Date + Time zone id extended enable

Date and Time conversions

Date and Time conversionsOper. Description

of-Create from fields. e.g. LocalDate today = LocalDate.of(2014, 3, 21); // today.toString() : “2014-03-21”

at-Expand with fields. e.g. LocalDateTime current = today.atTime(15:30); // current.toString() : “2014-03-21T15:30:00”

to-Truncate fields. e.g. LocalDate someday = current.toLocalDate(); // someday.toString() : “2014-03-21”

Date and Time operatorsOper. Description

isBefore isEqual isAfter

Compare with other date/time. e.g. LocalDate today = LocalDate.of(2014, 3, 21); boolean b = today.isAfter(LocalDate.of(2014, 3, 19)); // b == true

plus- minus-

Add/subtract field value. e.g. LocalDate tomorrow = today.plusDays(2); // tomorrow.toString() : “2014-03-23”

isLeapYearVerify a date is leap year. e.g. boolean leap = today.isLeapYear(); // leap == false

Date and Time formattingMethod Description

toString()Format using default formatter. e.g. String s = today.toString(); // s : “2014-03-21”

format(DateTimeFormatter f) Format using custom formatter. e.g. String s = today.format(formatter);

parse(String s)Parse using default formatter. e.g. LocalDate d = LocalDate .parse(“2014-03-21”);

parse(String s, DateTimeFormatter f)

Parse using custom formatter. e.g. LocalDate d = LocalDate .parse(“2014-03-21”, formatter);

Chronology

• Date and Time API supports ISO 8601 and some local chronology (e.g., Japanese Era, Minguo Era, Thai Buddhist Era and Hijrah Era).

• ChronoLocalDate and its sub-classes (incl. LocalDate) support chronology.

• ChronoLocalDateTime<D>/ChronoZonedDateTime<D> instead of LocalDateTime/ZonedDateTime

• dates/times that have different chronology can convert by from method each other.

Chronology supports

Chronology Era ChronoLocalDate

IsoChronology IsoEra LocalDate

JapaneseChronology JapaneseEra JapaneseDate

MinguoChronology MinguoEra MinguoDate

ThaiBuddhistChronology ThaiBuddhistEra ThaiBuddhistDate

HijrahChronology HijrahEra HijrahDate

Chronology examplesLocalDate today = LocalDate.of(2014, 3, 21); System.out.println(today); System.out.println(JapaneseDate.from(today)); System.out.println(MinguoDate.from(today)); System.out.println(ThaiBuddhistDate.from(today)); System.out.println(HijrahDate.from(today));

2014-03-21 Japanese Heisei 26-03-21 Minguo ROC 103-03-21 ThaiBuddhist BE 2557-03-21 Hijrah-umalqura AH 1435-05-20

DateTimeFormatter• Provides formats date/time.

• Created by ofPattern method (basic way)e.g. DateTimeFormatter.ofPattern(“yyyy/MM/dd”)

• Created by DateTimeFormatterBuilder (full control)

• Pre-defined patterns (static fields) • ISO_LOCAL_DATE // ofPattern(“yyyy-MM-dd”)

• ISO_ORDINAL_DATE // ofPattern(“yyyy-ddd”)

• ISO_WEEK_DATE // ofPattern(“yyyy-Www”)

Chronology and Formattere.g. JapaneseDate

pattern display example

"YYYY/MM/dd" 2014/03/21

"Y/M/d" 2014/3/21

"GGGGGyy.MM.dd" H26.03.21

"Gy年M月d日(E)" 平成26年3月21日(金)

External representation(for Human)

Internal representation(for Machine)

Instant• Representation of a time-point.

• The precision is a nano second.

• The epoch is 1970-01-01T00:00:00Z

• Convert from/to LocalDateTime, OffsetDateTime or ZonedDateTime.

• Convert from/to java.util.Date, which means that Instant is the only interface to java.util.Date.

Duration and Period• Representations of period (ISO 8601).

• Period (JSR 310) is a period (ISO 8601) between two dates and represents as a date-scale.i.e. format as "P1Y2M3D"

• Duration (JSR 310) is a period (ISO 8601) between any two temporals and represents as a time-scale.i.e. format as "PT15H30M45D"

• Attention: those definitions are different from them of ISO 8601.

Clock and now method• Provider of the current instant.

• There are some clocks, having relation of zones (incl. current zone), fixed clock (for testing) and custom.

• By default, it uses the clock of current zone.

• now method (LocalDate, et al.) creates a temporal instance from a clock. e.g. LocalDate.now(); LocalDate.now(zoneId); LocalDate.now(Clock.fixed(instant, ZoneId.systemDefault);

ExamplesMore examples: https://github.com/btnrouge/threetensamples

Skip

// It is assumed to run at March 21, 2014 LocalDate today = LocalDate.new(); !System.out.println(today);

2014-03-21

LocalDate calendarDate = LocalDate.of(2014, 3, 21); LocalDate ordinalDate = LocalDate.ofYearDays(2014, 80); LocalDateTime localDateTime = LocalDateTime.of(2014, 3, 21, 15, 30); !System.out.println(calendarDate); System.out.println(ordinalDate); System.out.println(localDateTime);

2014-03-21 2014-03-21 2014-03-21T15:30

OffsetDateTime offsetDateTime = OffsetDateTime.of(2014, 3, 21, 15, 30, 45, 0, ZoneOffset.ofHours(9)); ZonedDateTime zonedDateTime = ZonedDateTime.of(2014, 3, 21, 15, 30, 45, 0, ZoneId.of("Asia/Tokyo")); !System.out.println(offsetDateTime); System.out.println(zonedDateTime);

2014-03-21T15:30:45+09:00 2014-03-21T15:30:45+09:00[Asia/Tokyo]

LocalDate localDate = LocalDate.of(2014, 3, 21); LocalDateTime localDateTime0 = localDate.atStartOfDay(); LocalDateTime localDateTime1 = localDate.atTime(15, 30, 45); OffsetDateTime offsetDateTime = localDateTime.atOffset( ZoneOffset.ofHours(9)); !System.out.println(localDateTime0); System.out.println(localDateTime1); System.out.println(offsetDateTime);

2014-03-21T00:00 2014-03-21T15:30:45 2014-03-21T15:30:45+09:00

OffsetDateTime offsetDateTime = OffsetDateTime.of(2014, 3, 21, 15, 30, 45, 0, ZoneOffset.ofHours(9)); LocalDate localDate = offsetDateTime.toLocalDate(); LocalTime localTime = offsetDateTime.toLocalTime(); !System.out.println(offsetDateTime); System.out.println(localDate); System.out.println(localTime);

2014-03-21T15:30:45+09:00 2014-03-21 15:30:45

LocalDate commonYearsDay = LocalDate.of(1990, 12, 19); LocalDate leapYearsDay = LocalDate.of(1992, 10, 8); LocalDate centuryDay = LocalDate.of(2000, 1, 1); !System.out.println( commonYearDay.isLeapYear()); System.out.println( leapYearDay.isLeap()); System.out.println( centuryDay.isLeapYear());

false true false

LocalDate today = LocalDate.of(2014, 3, 21); LocalDate lastWeek = today.minusWeeks(1L); LocalDate dayAfterTomorrow = today.plusDays(2L); Period period = lastWeek.until(dayAfterTomorrow); !System.out.println(yesterday); System.out.println(dayAftereTomorrow); System.out.println(period);

2014-03-20 2014-03-23 P9D

// Convert java.util.Date to LocalDateTime Date date = new Date(); !LocalDateTime localDateTime = LocalDateTime.ofInstant(date.toInstant(), ZoneId.systemDefault());

// Convert LocalDateTime to java.util.Date LocalDateTime localDateTime = LocalDateTime.now(); !Instant instant = localDateTime.atZone( ZoneId.systemDefault()).toInstant(); Date date = Date.from(instant);

Brand new Date and Time API March 21, 2014

HASUNUMA Kenjikhasunuma@java.net

http://www.coppermine.jp/Twitter: @khasunuma