This document provides an overview of JSR-310, a Java date and time library introduced in Java 8. It discusses limitations of the existing Date and Calendar classes and why Joda Time is not ideal. JSR-310 addresses these issues by providing immutable classes for instants, dates, times and durations with improved naming and design. It also supports time zone handling, parsing/formatting and testing through interface abstractions and pluggable clock implementations.

1. A JSR-310 DATE
BEYOND JODA TIME

2. IN THIS PRESENTATION
• What is JSR-310?
• What’s wrong with Date, Calendar and
DateFormat?
• Why not JODA Time?
• JSR-310 Overview

3. • What does it mean?
• What does it have?
WHAT IS
JSR-310?

4. WHAT DOES JSR-310 MEANS?
• A Java Specification Request included on Java 8

5. WHAT DOES JSR-310 MEANS?
• A Java Specification Request included on Java 8
• A library to handle dates and times

6. WHAT DOES JSR-310 MEANS?
• A Java Specification Request included on Java 8
• A library to handle dates and times
• A set of packages:
•
•
•
•
•
java.time.*
java.time.chrono.*
java.time.format.*
java.time.temporal.*
java.time.zone.*

7. WHAT DOES JSR-310 HAVE?
•
•
•
•
•
•
Instants (timestamps)
Date and Time
Partial Date and Time
Parser and Formatter
Time zones
Different chronologies (calendars)

8. WHAT’S
WRONG
WITH THE
EXISTING
CLASSES?
• Bad Naming
• Historical Issues
• Design Problems
• Deficiencies

9. BAD NAMING
• Horrible naming decisions

10. BAD NAMING
• Horrible naming decisions
• Date is not a date, it is an instant in time (a timestamp)

11. BAD NAMING
• Horrible naming decisions
• Date is not a date, it is an instant in time (a timestamp)
• Date is not a time
• The time field manipulation methods are deprecated

12. BAD NAMING
• Horrible naming decisions
• Date is not a date, it is an instant in time (a timestamp)
• Date is not a time
• The time field manipulation methods are deprecated
• Calendar is not a calendar, it is a date and time

13. HISTORICAL ISSUES
• Date has no support for I18N or L10N

14. HISTORICAL ISSUES
• Date has no support for I18N or L10N
• So Sun added IBM-donated (through Taligent) code
• Calendar
• TimeZone
• SimpleDateFormat

15. HISTORICAL ISSUES
• Date has no support for I18N or L10N
• So Sun added IBM-donated (through Taligent) code
• Calendar
• TimeZone
• SimpleDateFormat
• Which don’t even play well together
• SimpleDateFormat can’t be used to convert from or to
Calendar

16. HISTORICAL ISSUES
• Date has no support for I18N or L10N
• So Sun added IBM-donated (through Taligent) code
• Calendar
• TimeZone
• SimpleDateFormat
• Which don’t even play well together
• SimpleDateFormat can’t be used to convert from or to
Calendar
• And still kept months 0-based
• (but at least made years 0-based instead of 1900-based)

17. DESIGN PROBLEMS
• They are mutable!

18. DESIGN PROBLEMS
• They are mutable!
• On core, excluding tests, SimpleDateTime is:
• instantiated in 225 places
• a field in 77 places
• usually synchronized (if correct)
• a local variable in 103 places
• Which could be replaced with a dozen immutable
static constants

19. DESIGN PROBLEMS
• They are mutable!
• On core, excluding tests, SimpleDateTime is:
• instantiated in 225 places
• a field in 77 places
• usually synchronized (if correct)
• a local variable in 103 places
• Which could be replaced with a dozen immutable
static constants
• Calendar stores redundant representations, and
recomputes lazily depending on the method being
called

20. DEFICIENCIES
• They are limited
• My alarm clock rings at 6:30 AM

21. DEFICIENCIES
• They are limited
• My alarm clock rings at 6:30 AM (time without date or tz)
• I was born March 23, 1971

22. DEFICIENCIES
• They are limited
• My alarm clock rings at 6:30 AM (time without date or tz)
• I was born March 23, 1971(date without time)
• My birthday is March 23

23. DEFICIENCIES
• They are limited
•
•
•
•
My alarm clock rings at 6:30 AM (time without date or tz)
I was born March 23, 1971(date without time)
My birthday is March 23 (date without year)
This presentation is one hour long

24. DEFICIENCIES
• They are limited
•
•
•
•
•
My alarm clock rings at 6:30 AM (time without date or tz)
I was born March 23, 1971(date without time)
My birthday is March 23 (date without year)
This presentation is one hour long (a duration)
A year has twelve months

25. DEFICIENCIES
• They are limited
•
•
•
•
•
My alarm clock rings at 6:30 AM (time without date or tz)
I was born March 23, 1971(date without time)
My birthday is March 23 (date without year)
This presentation is one hour long (a duration)
A year has twelve months (a period)

26. WHY NOT
JODA TIME?
• Why JODA Time?
• Too Flexible
• Bad Internal
Representation
• Null-happy
• JODA Time & JSR310

27. WHY JODA TIME?
• JODA Time addresses all these issues:
•
•
•
•
It is composed of immutable classes
It handles Instants, Date&Time, Partials, and Durations
It is flexible
It is well designed

28. TOO FLEXIBLE
• Every class is prepared to handle the most obscure
calendar systems (pluggable chronology)
• But code usually assumes Gregorian Calendar
• (have you ever written code that handles 13 months?)
• int month = dateTime.getMonthOfDay();
• It lacks type safety

29. BAD INTERNAL REPRESENTATION
• Represents dates as instants
• But a date&time may correspond to more than one
instant
• Overlap hour when daylight savings end
• As well as not have any instant that corresponds to
it at all
• Gap hour when daylight starts
• Has to perform complex computations for simple
operations

30. NULL-HAPPY
• Accepts nulls as valid values on most of its methods
• Leads to subtle bugs

31. JODA TIME AND JSR-310
• JODA Time is Not Broken
• But the lessons learned led to a new time library
design
• JSR-310 is inspired by JODA Time, but simpler and
more robust

32. JSR-310
OVERVIEW
• Basic classes
• Now
• Clocks and Testing
• Parsing and Printing
• Fields and Units
• Java 7 Backport

33. BASIC INTERFACES
Interface
•
•
•
•
•
•
•
TemporalAccessor
Temporal
TemporalField
TemporalAmount
TemporalUnit
TemporalQuery
TemporalAdjuster
Purpose
•
•
•
•
•
•
•
Readable date&time
Modifiable date&time
Date&time component
Amount of time
Unit of amount of time
Queries date&time
Modifies date&time

34. TEMPORALACCESSOR

35. TEMPORAL

36. TEMPORALFIELD

37. TEMPORALAMOUNT

38. TEMPORALUNIT

39. TEMPORALQUERY

40. TEMPORALADJUSTER

41. BASIC CLASSES
Class
•
•
•
•
Instant
Clock
LocalDateTime
OffsetDateTime
• ZonedDateTime
• Duration
• Period
Purpose
Moment in time
Instant Factory
Arbitrary Date and Time
Date & Time with UTC
offset
• Date & Time with TZ
• Difference between
instants
• Duration in time units
•
•
•
•

42. INSTANT
• A point in time
• Time since 1970-01-01 00:00:00 UTC
•
•
•
•
•
•
Useful for timestamps
Nanosecond resolution
Temporal, TemporalAccessor, TemporalAdjuster
Before/After
To/From seconds, milliseconds
Creates OffsetDateTime & ZonedDateTime

43. LOCALDATETIME
• A time in years, months, days, hours, minutes and
seconds
• No timezone
• Does not have an instant associated with it
ISO-8601 Calendar System, not Gregorian
Temporal, TemporalAccessor, TemporalAdjuster
Before/After
Manipulate with
years, months, weeks, days, hours, minutes, seconds
and nanos
• Creates OffsetDateTime & ZonedDateTime
•
•
•
•

44. ZONEDDATETIME/OFFSETDATETIME
• A date and time associated with either a particular
time zone, or a particular time zone offset
• OffsetDateTime always have an associated instant
• ZonedDateTime have gaps and overlaps
• One can get a ZDT that returns either the earlier or the later
time in an overlap
• Temporal, TemporalAccessor
• Before/After

45. DURATION & PERIOD
•
•
•
•
Represent amounts of time
Duration is an amount of nanoseconds
Period is an amount of years, months and days
Can be computed in absolute terms
• Duration.ofMinutes(10)
• Can be computed from dates and instants
• Period.between(LocalDate.now(), birthDay)
• Can be added of subtracted from instants, dates
and times

46. PARTIAL DATES AND TIMES
•
•
•
•
•
•
•
LocalDate
LocalTime
DayOfWeek
Month
MonthDay
YearMonth
Year

47. WHAT TIME IS IT NOW?
• Instant.now()
• default timezone
• Instant.now(ZoneId zone)
• time at a specific time zone
• Instant.now(Clock clock)
• time as generated by a specific clock
•
•
•
•
LocalTime.now()
MonthDay.now(clock)
ZonedDateTime(zone)
etc

48. CLOCK AND TESTING
• Clocks can be injected
• Clocks can be created with various properties
• Static clocks
• Mocked clocks
• Low-precision clocks (whole seconds, whole minutes, etc)
• Clocks can be created with specific time zones
• Clock.system(Zone.of(“America/Los_Angeles”))
• Makes code handling date and time testable
• Makes tests independent of timezone

49. PRINTING & PARSING
•
•
•
•
•
DateTimeFormatter replaces SimpleDateFormat
Immutable, so reusable and thread-safe
Many pre-defined styles
DateTimeFormatterBuilder
All instant, date and time classes use it the same
way:
• Instant t = Instant.parse(input, dateTimeFormatter);
• String ts = ZonedDateTime.format(dateTimeFormatter);
• Duration, Period and other classes have fixed
formats:
• Duration d = Duration.parse(repr);

50. JSR-310 BACKPORT TO JAVA 7
• Fork of the original implementation of JSR310, under the BSD license, before it got added to
JDK 8
• Presently equivalent to milestone 7 of JDK 1.8
• When JDK 1.8 comes out, a new release of the
backport will be made
• Presently diverging from JDK 1.8
• org.threeten, threetenbp, 8.1
• package org.threeten.bp instead of java.time

51. BENEFITS OF ADOPTING THE
BACKPORT
•
•
•
•
Much superior to existing Java classes
Closer to Java 8 than JODA, and less prone to bugs
Easy transition to Java 8
Superior testability

52. TRIVIAL EXAMPLE

53. COMPLEX EXAMPLE 1

54. COMPLEX EXAMPLE 2