This document provides an introduction to Java's Date and Time API. It discusses key classes like LocalDate, LocalDateTime, and ZonedDateTime that represent dates, times, and timestamps. It also covers formatting and parsing dates and times using DateTimeFormatter, and manipulating dates and times using factory and conversion methods. The document concludes that the API provides a powerful way to perform date and time calculations while modeling the ISO 8601 standard.
9. 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)
10. 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
11. 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)
12. 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
13. Date (Short)
• year-month:
YYYY-MM e.g. 2015-07
• year:
YYYY e.g. 2015
• month-day:
--MM-DD e.g. --07-11
14. Date and Time
• Concat date and time using 'T'
• If it needs, add offset (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
15. Duration
• Time amount between time points
• date : nYnMnD e.g. 1Y3M22D
• time : nHnMnS e.g. 9H30M45S
• date and time : nYnMnDTnHnMnS
e.g. 1Y3M22DT9H30M45S
16. 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)
17. 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
19. 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
20. 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
21. 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")
25. 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)
27. 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)
29. 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
30. 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)
31. 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
32. 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
35. 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"
37. 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
38. 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.
39. 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);
41. 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).
42. 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.
44. ZoneId.of(String zoneId)
1. Fixed offsets
e.g. "+09:00", "Z"
-> instance of ZoneOffset
2. Geographical regions
e.g. "Asia/Tokyo"
-> instance of ZoneRegion
46. 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.
48. 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.*)
49. 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!
50. Introduction to Date and Time API III
HASUNUMA Kenji
k.hasunuma@coppermine.jp
Twitter: @khasunuma