Introduction to Date and Time API 4

Introduction to
Date and Time API IV
HASUNUMA Kenji
k.hasunuma@coppermine.jp

Twitter: @khasunuma
April 22, 2016

Definition of second (Traditional)

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

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

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

Duration
• Time amount between time points

• date : nYnMnD e.g. 1Y3M22D

• time : nHnMnS e.g. 9H30M45S

• date and time : nYnMnDTnHnMnS 
e.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 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
7 Sunday

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

Factory methods
Oper. Description
of-
Create from fields.

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

"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 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) 
.atOﬀset(ZoneOﬀset.ofHours(9))
to-
Truncate fields.

e.g. LocalDateTime.of(2015, 7, 11, 13, 30, 45) 
.toLocalDate()

Obtain/Modify methods
Oper. 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 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

Arithmetric methods
Oper. 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 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

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

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)

DateTimeFormatter
1. 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

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 clock

LocalDateTime.now(clock);

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

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.

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

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.

OﬀsetTime
LocalDate
Year
LocalDateTime OﬀsetDateTime
ZonedDateTime
LocalTime
YearMonth
Temporal Objects

firstDayOfMonth
lastDayOfMonth
next(MONDAY)

TemporalAdjuster
• Adjusts/Modifies temporal objects.

• "Strategy design pattern"; 
separates a temporal object and an
algorithm.

• TemporalAdjusters class provides
some useful adjusters.

Usage
LocalDate today = LocalDate.now();
TemporalAdjuster adjuster =
TemporalAdjusters.lastDayOfMonth();
// lastDay: 2015-03-31
LocalDate lastDay =
today.with(adjuster);

TemporalAdjusters
Standard set of adjusters:

• finding the first/last day of the month

• finding the first/last day of the year

• finding the next/previous day-of-week

and more...

The beginning as code
LocalDate today = LocalDate.now();
// 2015-03-01
today.with(firstDayOfMonth());
// 2015-03-31
today.with(lastDayOfMonth());
// 2015-03-09
today.with(next(MONDAY));

Chronology Support
• JDK 8 supports for ISO 8601 and
some local chronology; 
Japanese Era, Minguo Era, Thai
Buddhist Era and Hijrah Era

• User defined chronologies are also
supported 
-> Chronology Framework

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

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

• diﬀerent chronology can convert by
from method each other

Chronological Date
Chronology Era ChronoLocalDate
IsoChronology IsoEra LocalDate
JapaneseChronology JapaneseEra JapaneseDate
MinguoChronology MinguoEra MinguoDate
ThaiBuddhistChronology ThaiBuddhistEra ThaiBuddhistDate
HijrahChronology HijrahEra HijrahDate

Chronology Example
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

Japanese Date Format
• JIS X 0301 defines Japanese date
format as 'NYY.MM.DD' (N: Era)

• Use such a DateTimeFormatter if it is
based on JIS X 0301;

DateTimeFormatter 
.pattern("GGGGGyy.MM.dd")

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/Oﬀset/Zoned

• Set priority to the classes

• Trial and error!

Introduction to Date and Time API IV
HASUNUMA Kenji
k.hasunuma@coppermine.jp

Twitter: @khasunuma

Introduction to Date and Time API 4

Recommended

More Related Content

What's hot (6)

Similar to Introduction to Date and Time API 4 (20)

More from Kenji HASUNUMA (15)

Recently uploaded (20)

Introduction to Date and Time API 4