Introduction to Date and Time API III

HASUNUMA Kenji k.hasunuma@coppermine.jp

Twitter: @khasunuma

July 11, 2015#kanjava

Time?

Definition of second (Traditional)

Definition of second (Modern)

time zones and offsets

+09:00-08:00

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

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

ISO 8601

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)

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

Time (w/Time Zone)• Add suffix - offset 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)

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

Date (Short)

• year-month: YYYY-MM e.g. 2015-07

• year: YYYY e.g. 2015

• month-day: --MM-DD e.g. --07-11

Date and Time• Concat date and time using 'T'

• If it needs, add offset (Time Zone)

• YYYY-MM-DDThh:mm:sse.g. 2015-07-11T14:45:30

• YYYY-MM-DDThh:mm:ss±hh:mm e.g. 2015-07-10T21:45:30-08:00

Duration

• Time amount between time points

• date : nYnMnD e.g. 1Y3M22D

• time : nHnMnS e.g. 9H30M45S

• date and time : nYnMnDTnHnMnSe.g. 1Y3M22DT9H30M45S

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)

Definition of week

• a week = 7 days

• 1st week contains the first Thursday of the year.

• a year contents 52 or 53 weeks.

1 Monday2 Tuesday3 Wednesday4 Thursday5 Friday6 Saturday7 Sunday

Date and Time API Essentials

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

Date and Time classesClass 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

Factory methodsOper. Description

of-Create from fields.e.g. LocalDate.of(2015, 7, 11)

nowCreate from a clock.e.g. LocalDate.now()

fromCreate from other Temporal objects.e.g. LocalDate.from(LocalDateTime.now())

parseCreate from String. (may use a formatter)e.g. LocalDate.parse("2015-07-11")

"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"))

Conversion methodsOper. 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()

Date and Time conversions

Obtain/Modify methodsOper. Description

get-Obtain the value of a field.e.g. LocalDate.now().getYear()e.g. LocalDate.now().get(YEAR)

with-Modify the value of a field (returns a copy).e.g. LocalDate.now().withYear(2016)e.g. LocalDate.now().with(2016, YEAR)

Obtain/Modify methodsChronoField 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

Arithmetric methodsOper. Description

plus-Add a field value. (returns a copy)e.g. LocalDate.now().plusDays(7)e.g. LocalDate.now().plus(7, DAYS)

minus-subtract a field value. (returns a copy)e.g. LocalDate.now().minusDays(7)e.g. LocalDate.now().minus(7, DAYS)

Arithmetric methodsChronoUnit 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

Compare methodsOper. Description

isBeforee.g. today.isBefore(yesterday) ; falsee.g. today.isBefore(today) ; falsee.g. today.isBefore(tomorrow) ; true

isEquale.g. today.isEqual(yesterday) ; falsee.g. today.isEqual(today) ; truee.g. today.isEqual(tomorrow) ; false

isAftere.g. today.isAfter(yesterday) ; truee.g. today.isAfter(today) ; falsee.g. today.isAfter(tomorrow) ; false

Format/Parse methodsMethod 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)

DateTimeFormatter1. Created by ofPattern factory (usually)

e.g. ofPettern("uuuu/MM/dd")

2. Select from pre-defined patterns:• ISO_LOCAL_DATE• ISO_OFFSET_TIME• ISO_ZONED_DATE_TIME

3. Created by DateTimeFomatterBuilder

ResolverStyle• One of formatter option (enum)

• LENIENT, SMART (default), STRICT

• Modifing method: withResolverStyle

• If it is STRICT mode, Pattern 'y' must be used with 'G'e.g. NO: yyyy/MM/dd OK: Gyyyy/MM/dd

Advanced

External representation

Representation for Human

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"

Internal representation

Representation for Machine

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

Clock• Provider of the current instant.

• Zone relative, fixed and custom.

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

• now method (LocalDate, et al.) creates a temporal instance from a clock.

Fixed Clock• Clock always provides same instant.

• It's very useful for application testing.

Clock clock = Clock.fixed(instant, ZoneId.systemDefault);!// Using fixed clockLocalDateTime.now(clock);

ZoneId and ZoneOffset

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 ZoneOffset and ZoneRegion (implicit).

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.

Class diagram

ZoneId.of(String zoneId)

1. Fixed offsetse.g. "+09:00", "Z"-> instance of ZoneOffset

2. Geographical regionse.g. "Asia/Tokyo"-> instance of ZoneRegion

Create ZoneId (examples)• ZoneId.systemDefault()

• ZoneId.of("Asia/Tokyo")

• ZoneId.of("JST", ZoneId.SHORT_IDS)

• ZoneId.of("+09:00")

• ZoneId.from(ZonedDateTime.now())

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.

Conclusion

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.*)

How to study?• Learn ISO 8601 (JIS X 0301)

• Master to use LocalDate

• Know why exists Local/Offset/Zoned

• Set priority to the classes

• Trial and error!

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