Brand new Date and Time API

Slide 1

Slide 1 text

Brand new Date and Time API March 21, 2014 HASUNUMA Kenji khasunuma@java.net http://www.coppermine.jp/ Twitter:

Slide 2

Slide 2 text

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". • Speciﬁcation Leads: Stephen Colebourne, Michael Nascimento Santos and Roger Riggs.

Slide 3

Slide 3 text

What is time? “Time” is described by science approaches and deﬁned by International Standard (SI) exactly. Skip

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Deﬁnition of second (Traditional)

Slide 6

Slide 6 text

Deﬁnition of second (Modern)

Slide 7

Slide 7 text

No content

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

PST (Paciﬁc Standard Time) Offset:-08:00 (Summer:-07:00) JST (Japan Standard Time) Offset:+09:00 Skip

Slide 11

Slide 11 text

Time zones (East 1/2) Code Name Oﬀset Summer ECT Europe/Paris +01:00 +02:00 CAT 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)

Slide 12

Slide 12 text

Time zones (East 2/2) Code Name Offset Summer VST 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:00 SST Pacific/Guadalcanal +11:00 (N/A) NST Pacific/Auckland +13:00 +12:00 MIT Pacific/Apia +14:00 +13:00

Slide 13

Slide 13 text

Time zones (West 1/2) Code Name Oﬀset 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

Slide 14

Slide 14 text

Time zones (West 2/2) Code Name Oﬀset 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)

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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.

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

Representation of time (w/Time zone) • Add sufﬁx based on the offset from UTC • UTC: ‘Z’ e.g. 06:30:45Z • Not UTC: +hh:mm or -hh:mm  e.g. 15:30:45+09:00 (JST, Asia/Tokyo)  02:30:45-08:00 (PST, America/Los_Angeles)

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

Deﬁnition 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

Slide 21

Slide 21 text

Deﬁnition 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

Slide 22

Slide 22 text

Deﬁnition 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 year Not Zero - - common year Zero Not Zero - leap year Zero Zero Not Zero common year Zero Zero Zero leap year

Slide 23

Slide 23 text

Deﬁnition of week • a week = 7 days • 1st week of year = a week contents the ﬁrst 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

Slide 24

Slide 24 text

Origin of week

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

Deﬁnition and representation of duration • time amount between two time points • date : nYnMnD e.g. 1Y3M22D • time : nHnMnS e.g. 9H30M45S • date and time : nYnMnDTnHnMnS  e.g. 1Y3M22DT9H30M45S

Slide 27

Slide 27 text

Deﬁnition and representation of period • range between two dates (adopt also two times) • two dates : YYYY-MM-DD/YYYY-MM-DD  e.g. 2013-12-31/2014-03-21 • start date and duration : YYYY-MM-DD/PnYnMnD  e.g. 2013-12-31/P1Y3M22D • end date and duration : PnYnMnD/YYYY-MM-DD  e.g. P1Y3M22D/2013-03-21 • duration : PnYnMnD  e.g. P1Y3M22D

Slide 28

Slide 28 text

JSR 310 Date and Time API Skip

Slide 29

Slide 29 text

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/

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Date and Time conversions

Slide 33

Slide 33 text

Date and Time conversions Oper. 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”

Slide 34

Slide 34 text

Date and Time operators Oper. 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 ﬁeld value. e.g. LocalDate tomorrow = today.plusDays(2); // tomorrow.toString() : “2014-03-23” isLeapYear Verify a date is leap year. e.g. boolean leap = today.isLeapYear(); // leap == false

Slide 35

Slide 35 text

Date and Time formatting Method 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);

Slide 36

Slide 36 text

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/ChronoZonedDateTime instead of LocalDateTime/ZonedDateTime • dates/times that have different chronology can convert by from method each other.

Slide 37

Slide 37 text

Chronology supports Chronology Era ChronoLocalDate IsoChronology IsoEra LocalDate JapaneseChronology JapaneseEra JapaneseDate MinguoChronology MinguoEra MinguoDate ThaiBuddhistChronology ThaiBuddhistEra ThaiBuddhistDate HijrahChronology HijrahEra HĳrahDate

Slide 38

Slide 38 text

Chronology examples LocalDate 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

Slide 39

Slide 39 text

DateTimeFormatter • Provides formats date/time. • Created by ofPattern method (basic way)  e.g. DateTimeFormatter.ofPattern(“yyyy/MM/dd”) • Created by DateTimeFormatterBuilder (full control) • Pre-deﬁned patterns (static ﬁelds) • ISO_LOCAL_DATE // ofPattern(“yyyy-MM-dd”) • ISO_ORDINAL_DATE // ofPattern(“yyyy-ddd”) • ISO_WEEK_DATE // ofPattern(“yyyy-Www”)

Slide 40

Slide 40 text

Chronology and Formatter e.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೔(ۚ)

Slide 41

Slide 41 text

External representation (for Human)

Slide 42

Slide 42 text

Internal representation (for Machine)

Slide 43

Slide 43 text

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.

Slide 44

Slide 44 text

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 deﬁnitions are different from them of ISO 8601.

Slide 45

Slide 45 text

Clock and now method • Provider of the current instant. • There are some clocks, having relation of zones (incl. current zone), ﬁxed 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.ﬁxed(instant, ZoneId.systemDefault);

Slide 46

Slide 46 text

Examples More examples: https://github.com/btnrouge/threetensamples Skip

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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]

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

Brand new Date and Time API March 21, 2014 HASUNUMA Kenji khasunuma@java.net http://www.coppermine.jp/ Twitter: @khasunuma