Introduction to Date and Time API 3

Slide 1

Slide 1 text

Introduction to Date and Time API III HASUNUMA Kenji k.hasunuma@coppermine.jp Twitter: @khasunuma July 11, 2015 #kanjava

Slide 2

Slide 2 text

Time?

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

Deﬁnition of second (Traditional)

Slide 5

Slide 5 text

Deﬁnition of second (Modern)

Slide 6

Slide 6 text

time zones and offsets +09:00 -08:00

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

ISO 8601

Slide 9

Slide 9 text

What's ISO 8601? • International Standard • Using Gregorian calendar • Base of JIS X 0301, RFC 3339, etc. • Incompatible with Unix time  (java.util.Date/Calendar are based on Unix time)

Slide 10

Slide 10 text

Time (w/o Time Zone) • hh:mm:ss e.g. 14:30:15 • hh:mm e.g. 14:30 • hh e.g. 14 • hh:mm:ss.s e.g. 14:30:15.250

Slide 11

Slide 11 text

Time (w/Time Zone) • Add suﬃx - oﬀset from UTC (±hh:mm) • hh:mm:ss±hh:mm • e.g. 14:30:45+09:00 (Asia/Tokyo) • e.g. 21:30:45-08:00 (America/Los_Angeles) • e.g. 05:30:45Z (UTC)

Slide 12

Slide 12 text

Date • calendar date:   YYYY-MM-DD e.g. 2015-07-11 • ordinal date:   YYYY-DDD e.g. 2015-192 • week date:   YYYY-Www-D e.g. 2015-W29-6

Slide 13

Slide 13 text

Date (Short) • year-month:   YYYY-MM e.g. 2015-07 • year:   YYYY e.g. 2015 • month-day:   --MM-DD e.g. --07-11

Slide 14

Slide 14 text

Date and Time • Concat date and time using 'T' • If it needs, add oﬀset (Time Zone) • YYYY-MM-DDThh:mm:ss  e.g. 2015-07-11T14:45:30 • YYYY-MM-DDThh:mm:ss±hh:mm  e.g. 2015-07-10T21:45:30-08:00

Slide 15

Slide 15 text

Duration • Time amount between time points • date : nYnMnD e.g. 1Y3M22D • time : nHnMnS e.g. 9H30M45S • date and time : nYnMnDTnHnMnS  e.g. 1Y3M22DT9H30M45S

Slide 16

Slide 16 text

Period • Range between dates/times • YYYY-MM-DD/YYYY-MM-DD (start/end) • YYYY-MM-DD/PnYnMnD (start/duration) • PnYnMnD/YYYY-MM-DD (duration/end) • PnYnMnD (duration)

Slide 17

Slide 17 text

Deﬁnition of week • a week = 7 days • 1st week contains   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 18

Slide 18 text

Date and Time API Essentials

Slide 19

Slide 19 text

Packages Package Description Use java.time Basic classes usual java.time.format Date and Time Formatter partial java.time.chrono Chronology supports partial java.time.temporal Low-level API rare java.time.zone Low-level API rare

Slide 20

Slide 20 text

Date and Time classes Class Field T/Z ISO 8601 LocalDate Date N/A YYYY-MM-DD LocalDateTime Date/Time N/A YYYY-MM-DDThh:mm:ss LocalTime Time N/A hh:mm:ss OffsetDateTime Date/Time offset YYYY-MM-DDThh:mm:ss±hh:mm OffsetTime Time offset hh:mm:ss±hh:mm ZonedDateTime Date/Time zone id N/A

Slide 21

Slide 21 text

Factory methods Oper. Description of- Create from ﬁelds. e.g. LocalDate.of(2015, 7, 11) now Create from a clock. e.g. LocalDate.now() from Create from other Temporal objects. e.g. LocalDate.from(LocalDateTime.now()) parse Create from String. (may use a formatter) e.g. LocalDate.parse("2015-07-11")

Slide 22

Slide 22 text

"of" method (examples) LocalDate.of(2015, 7, 11) LocalDateTime.of(2015, 7, 11, 13, 30, 45, 250) LocalTime.of(13, 30, 45, 250) OffsetDateTime.of(2015, 7, 11, 13, 30, 45, 250,   ZoneOffset.ofHours(9)) OffsetTime.of(13, 30, 45, 250, ZoneOffset.ofHours(9)) ZonedDateTime.of(2015, 7, 11, 13, 30, 45, 250,   ZoneId.of("Asia/Tokyo"))

Slide 23

Slide 23 text

Conversion methods Oper. Description at- Expand with fields. e.g. LocalDate.of(2015, 7, 11).atTime(13, 30) e.g. LocalDateTime.of(2015, 7, 11, 13, 30, 45)  .atOffset(ZoneOffset.ofHours(9)) to- Truncate fields. e.g. LocalDateTime.of(2015, 7, 11, 13, 30, 45)  .toLocalDate()

Slide 24

Slide 24 text

Date and Time conversions

Slide 25

Slide 25 text

Obtain/Modify methods Oper. Description get- Obtain the value of a ﬁeld. e.g. LocalDate.now().getYear() e.g. LocalDate.now().get(YEAR) with- Modify the value of a ﬁeld (returns a copy). e.g. LocalDate.now().withYear(2016) e.g. LocalDate.now().with(2016, YEAR)

Slide 26

Slide 26 text

Obtain/Modify methods ChronoField Obtain Modify YEAR getYear withYear MONTH_OF_YEAR getMonthValue withMonth DAY_OF_MONTH getDayOfMonth withDayOfMonth DAY_OF_WEEK getDayOfWeek N/A HOUR_OF_DAY getHour withHour MINUTE_OF_HOUR getMinute withMinute SECOND_OD_MINUTE getSecond withSecond NANO_OF_SECOND getNano withNano

Slide 27

Slide 27 text

Arithmetric methods Oper. Description plus- Add a ﬁeld value. (returns a copy) e.g. LocalDate.now().plusDays(7) e.g. LocalDate.now().plus(7, DAYS) minus- subtract a ﬁeld value. (returns a copy) e.g. LocalDate.now().minusDays(7) e.g. LocalDate.now().minus(7, DAYS)

Slide 28

Slide 28 text

Arithmetric methods ChronoUnit Add Subtract YEARS plusYears minusYears MONTHS plusMonths minusMonths DAYS plusDays minusDays WEEKS plusWeeks minusWeeks HOURS plusHours minusHours MINUTES plusMinutes minusMinutes SECONDS plusSeconds minusSeconds NANOS plusNanos minusNanos

Slide 29

Slide 29 text

Compare methods Oper. Description isBefore e.g. today.isBefore(yesterday) ; false e.g. today.isBefore(today) ; false e.g. today.isBefore(tomorrow) ; true isEqual e.g. today.isEqual(yesterday) ; false e.g. today.isEqual(today) ; true e.g. today.isEqual(tomorrow) ; false isAfter e.g. today.isAfter(yesterday) ; true e.g. today.isAfter(today) ; false e.g. today.isAfter(tomorrow) ; false

Slide 30

Slide 30 text

Format/Parse methods Method Description toString() Format using default formatter (Instance method) format(DateTimeFormatter f) Format using custom formatter (Instance method) parse(String s) Parse using default formatter (Factory method) parse(String s, DateTimeFormatter f) Parse using custom formatter (Factory method)

Slide 31

Slide 31 text

DateTimeFormatter 1. Created by ofPattern factory (usually)  e.g. ofPettern("uuuu/MM/dd") 2. Select from pre-deﬁned patterns: • ISO_LOCAL_DATE • ISO_OFFSET_TIME • ISO_ZONED_DATE_TIME 3. Created by DateTimeFomatterBuilder

Slide 32

Slide 32 text

ResolverStyle • One of formatter option (enum) • LENIENT, SMART (default), STRICT • Modiﬁng method: withResolverStyle • If it is STRICT mode, Pattern 'y' must be used with 'G'  e.g. NO: yyyy/MM/dd OK: Gyyyy/MM/dd

Slide 33

Slide 33 text

Advanced

Slide 34

Slide 34 text

External representation Representation for Human

Slide 35

Slide 35 text

Duration and Period • Representation of temporal amount correspond with "period" (ISO 8601). • Period is the date part of "period",   i.e. formatted as "P1Y2M3D" • Duration is the time part of "period", i.e. formatted as "PT15H30M45D"

Slide 36

Slide 36 text

Internal representation Representation for Machine

Slide 37

Slide 37 text

Instant • Representation of a time-point • The precision is a nano second • The epoch is 1970-01-01T00:00:00Z • The only interface to java.util.Date

Slide 38

Slide 38 text

Clock • Provider of the current instant. • Zone relative, ﬁxed and custom. • By default, it uses the clock relative current zone. • now method (LocalDate, et al.) creates a temporal instance from a clock.

Slide 39

Slide 39 text

Fixed Clock • Clock always provides same instant. • It's very useful for application testing. Clock clock = Clock.ﬁxed(instant,   ZoneId.systemDefault); ! // Using ﬁxed clock LocalDateTime.now(clock);

Slide 40

Slide 40 text

ZoneId and ZoneOﬀset

Slide 41

Slide 41 text

ZoneId is ... • ID/tag of a time zone. • The representation of time zone is ZoneRules. • There is the system default value. • Abstract class; derived to ZoneOﬀset and ZoneRegion (implicit).

Slide 42

Slide 42 text

ZoneOffset is ... • ID/tag of a time zone for fixed offsets. • Contains the offset from UTC. • Used for OffsetDateTime/OffsetTime. • Used for ZonedDateTime (as ZoneId). • Defines transitions of ZoneRules.

Slide 43

Slide 43 text

Class diagram

Slide 44

Slide 44 text

ZoneId.of(String zoneId) 1. Fixed oﬀsets  e.g. "+09:00", "Z"  -> instance of ZoneOﬀset 2. Geographical regions  e.g. "Asia/Tokyo"  -> instance of ZoneRegion

Slide 45

Slide 45 text

Create ZoneId (examples) • ZoneId.systemDefault() • ZoneId.of("Asia/Tokyo") • ZoneId.of("JST", ZoneId.SHORT_IDS) • ZoneId.of("+09:00") • ZoneId.from(ZonedDateTime.now())

Slide 46

Slide 46 text

OffsetDateTime vs. ZonedDateTime • OffsetDateTime is based on ISO 8601 but ZonedDateTime is not. • ZonedDateTime is adapt to daylight savings easily. OffsetDateTime is not. • Zones may be changed because of region or country convenience. But offsets are never.

Slide 47

Slide 47 text

Conclusion

Slide 48

Slide 48 text

What's Date and Time API? • Modeling of ISO 8601 • Many classes, but ease of use • Powerful Date/Time calculations  (See also TemporalAdjuster) • Many extention points  (See also java.time.chrono.*)

Slide 49

Slide 49 text

How to study? • Learn ISO 8601 (JIS X 0301) • Master to use LocalDate • Know why exists Local/Oﬀset/Zoned • Set priority to the classes • Trial and error!

Slide 50

Slide 50 text

Introduction to Date and Time API III HASUNUMA Kenji k.hasunuma@coppermine.jp Twitter: @khasunuma