a jsr-310 date: beyond joda time

B E YO N D J O DA T I M E

A JSR-310 DATE

IN THIS PRESENTATION

• What is JSR-310?• What’s wrong with Date, Calendar and

DateFormat?• Why not JODA Time?• JSR-310 Overview

•What does it mean?•What does it have?WHAT IS

JSR-310?

WHAT DOES JSR-310 MEANS?

• A Java Specification Request included on Java 8

WHAT DOES JSR-310 MEANS?

• A Java Specification Request included on Java 8• A library to handle dates and times

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

WHAT DOES JSR-310 HAVE?

• Instants (timestamps)• Date and Time• Partial Date and Time• Parser and Formatter• Time zones• Different chronologies (calendars)

• Bad Naming•Historical Issues•Design Problems•DeficienciesWHAT’S

WRONG WITH THE EXISTING CLASSES?

BAD NAMING

• Horrible naming decisions

BAD NAMING

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

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

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

HISTORICAL ISSUES

• Date has no support for I18N or L10N

HISTORICAL ISSUES

• Date has no support for I18N or L10N• So Sun added IBM-donated (through Taligent)

code• Calendar• TimeZone• SimpleDateFormat

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

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)

DESIGN PROBLEMS

• They are mutable!

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

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

DEFICIENCIES

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

DEFICIENCIES

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

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

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

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

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)

•Why JODA Time?• Too Flexible• Bad Internal Representation•Null-happy• JODA Time & JSR-310

WHY NOT JODA TIME?

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

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

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

NULL-HAPPY

• Accepts nulls as valid values on most of its methods• Leads to subtle bugs

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

• Basic classes•Now• Clocks and Testing• Parsing and Printing• Fields and Units• Java 7 Backport

JSR-310 OVERVIEW

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

TEMPORALACCESSOR

TEMPORAL

TEMPORALFIELD

TEMPORALAMOUNT

TEMPORALUNIT

TEMPORALQUERY

TEMPORALADJUSTER

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

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

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

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

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

PARTIAL DATES AND TIMES

• LocalDate• LocalTime• DayOfWeek• Month• MonthDay• YearMonth• Year

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

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

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

JSR-310 BACKPORT TO JAVA 7

• Fork of the original implementation of JSR-310, 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

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

TRIVIAL EXAMPLE

COMPLEX EXAMPLE 1

COMPLEX EXAMPLE 2