Introduction to Date and Time API 4
0 likes77 views
This document introduces the Java Date and Time API. It discusses key classes like LocalDate, LocalDateTime, OffsetDateTime and ZonedDateTime. It covers concepts like ISO 8601 formatting, factories, conversions between classes, obtaining/modifying fields, arithmetic/comparison methods, formatting/parsing, and time zones. Advanced topics include Instant, Clock, Duration/Period, TemporalAdjuster, and support for non-ISO chronologies. The conclusion emphasizes modeling ISO 8601, powerful date/time calculations, and extension points in the API.
Introduction to Date and Time API 4
- 1. Introduction to Date and Time API IV HASUNUMA Kenji k.hasunuma@coppermine.jp Twitter: @khasunuma April 22, 2016
- 2. Time?
- 4. Definition of second (Traditional)
- 5. Definition of second (Modern)
- 6. time zones and offsets +09:00 -08:00
- 7. PST (Pacific Standard Time) Offset:-08:00 (Summer:-07:00) JST (Japan Standard Time) Offset:+09:00
- 8. ISO 8601
- 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
- 18. Date and Time API Essentials
- 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")
- 22. "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"))
- 23. 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()
- 24. Date and Time conversions
- 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)
- 26. 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
- 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)
- 28. 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
- 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
- 33. Advanced
- 36. 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. Internal representation Representation for Machine
- 38. 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
- 39. 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.
- 40. 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);
- 42. 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).
- 43. 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. Class diagram
- 45. 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. Create ZoneId (examples) • ZoneId.systemDefault() • ZoneId.of("Asia/Tokyo") • ZoneId.of("JST", ZoneId.SHORT_IDS) • ZoneId.of("+09:00") • ZoneId.from(ZonedDateTime.now())
- 47. 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. Temporal Object
- 51. TemporalAdjuster • Adjusts/Modifies temporal objects. • "Strategy design pattern"; separates a temporal object and an algorithm. • TemporalAdjusters class provides some useful adjusters.
- 52. Usage LocalDate today = LocalDate.now(); TemporalAdjuster adjuster = TemporalAdjusters.lastDayOfMonth(); // lastDay: 2015-03-31 LocalDate lastDay = today.with(adjuster);
- 53. 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...
- 54. 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));
- 55. Chronology
- 56. 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
- 57. Chronology Framework • ChronoLocalDate and its sub-classes (incl. LocalDate) support chronology • ChronoLocalDateTime<D> / ChronoZonedDateTime<D> instead of LocalDateTime / ZonedDateTime • different chronology can convert by from method each other
- 58. Chronological Date Chronology Era ChronoLocalDate IsoChronology IsoEra LocalDate JapaneseChronology JapaneseEra JapaneseDate MinguoChronology MinguoEra MinguoDate ThaiBuddhistChronology ThaiBuddhistEra ThaiBuddhistDate HijrahChronology HijrahEra HijrahDate
- 59. 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
- 60. 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")
- 61. Conclusion
- 62. 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.*)
- 63. 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!
- 64. Introduction to Date and Time API IV HASUNUMA Kenji k.hasunuma@coppermine.jp Twitter: @khasunuma