Joda-Time & JSR 310
– Problems, Concepts and Approaches
Justin Lin
caterpillar@openhome.cc
http://openhome.cc

Agenda
• Date and Calendar Problems
• Time ABC
• Joda-Time
• JSR310
2 / 66

3 / 66

What's wrong?
• I am 818 years old?
Rounding off error
4 / 66

Fixed
• I am 38 years old.
There's a long type. All other
operands are promoted.
5 / 66

• Taiwan Java Developer Day is 1913/9/2?
What's wrong?
Deprecated
6 / 66

• Taiwan Java Developer Day is 2013/9/2?
What's wrong?
This calendar field
begins from 0.
7 / 66

• Taiwan Java Developer Day is 2013/8/2.
Fixed
Use the constant
variable of Calendar.
8 / 66

• Days between two calendars is zero?
What's wrong?
The Calendar instance is
mutable and state-reserved.
9 / 66
0

Fixed
clone() the instance , or
create a new instance.
10 / 66

The Date instance is not a date
• It represents a specific instant in time, with
millisecond precision.
– For example, 1375430498832 milliseconds after
"the epoch", namely January 1, 1970, 00:00:00
UTC.
11 / 66

• Prior to JDK 1.1, It allowed the interpretation
of dates as year, month, day, hour, minute,
and second values. But…wired values…
– A year y is represented by the integer y - 1900.
– A month, hour, minutes and second begin from 0.
– A day of month begins from 1.
12 / 66

• All those methods about the interpretation of
dates are deprecated after JDK 1.1.
• The setTime method is not deprecated. The
Date instance is mutable.
• Converting between a specific instant in time
manually is error-prone. The Calendar class
provides methods for that. But …
The Date instance is not a specific instant
13 / 66

• A set of calendar fields such as YEAR, MONTH,
DAY_OF_MONTH, HOUR, and so on.
– A month, hour, minute and second begin from 0.
– Remember to use Calendar.JANUARY.
• The Calendar instance is mutable. Methods
such as add, set and roll changes the state
of the instance.
Using Calendar can be painful and tedious
14 / 66

15 / 66

Time the time
• Greenwich Mean Time（GMT）
– Originally referred to the mean solar time at the Royal
Observatory in Greenwich, London.
– Noon Greenwich Mean Time is the moment when the
sun reaches its highest point in the sky.
– GMT is sometimes used loosely and arguably as a
synonym for UTC.
• Universal Time（UT）
– Observe stars as they crossed a meridian.
– In 1935, the term Universal Time was recommended as
a more precise term than Greenwich Mean Time.
– GMT is the same as UT before 1972.
16 / 66

• International Atomic Time（TAI）
– The SI（ International System of Units） second was
defined in terms of the caesium atom in 1967.
– Synchronised with Universal Time at the beginning of
1958.
• Coordinated Universal Time（UTC）
– Based on TAI. Introduced on at the beginning 1972.
– With leap seconds added at irregular intervals to
compensate for the slowing of Earth's rotation.
– Since 30 June 2012 when the last leap second was
added, TAI has been exactly 35 seconds ahead of UTC.
17 / 66

• Unix time
– A system for describing instants in time.
– Defined as the number of seconds that have
elapsed since 00:00:00 UTC on 1 January 1970,
not counting leap seconds.
• The epoch（date）
– An instant in time chosen as the origin of a
particular era.
– The Unix epoch is the time 00:00:00 UTC on 1
January 1970.
18 / 66

Chronologies
• Julian calendar
– A reform of the Roman calendar introduced by Julius
Caesar in 46 BC, took effect in 45 BC, and widely used
from about 4CE to 1582CE.
– Defines a leap year as once every four years.
• Gregorian calendar
– A reform of the Julian calendar.
– The last day of the Julian calendar was Thursday, 4
October 1582.
– Friday, 15 October 1582 was the first day of the
Gregorian calendar.
19 / 66

• Gregorian calendar (continued)
– Britain and the British Empire (including the
eastern part of what is now the United States)
adopted the Gregorian calendar in 1752.
20 / 66

• Gregorian calendar (continued)
– The concrete subclass GregorianCalendar of
Calendar is a hybrid calendar that supports
both the Julian and Gregorian calendar systems.
– setGregorianChange sets the Gregorian
Calendar change date. Default is October 15, 1582
(Gregorian).
21 / 66
Fri Oct 15 1582
Thu Oct 4 1582

• The ISO8601 standard
– An international standard covering the exchange of
date and time-related data.
– Provide an unambiguous and well-defined method
of representing dates and times.
• yyyy-mm-ddTHH:MM:SS.SSS
• yyyy-dddTHH:MM:SS.SSS
• yyyy-Www-dTHH:MM:SS.SSS
• ...
22 / 66

• The ISO8601 standard (continued)
– When representing dates and times, the Gregorian
and ISO8601 differ slightly.
– In ISO8601, "19" refer to the century from 1900 to
1999 inclusive.
– In Gregorian, the 19th century is 1801 to 1900
inclusive.
From: https://en.wikipedia.org/wiki/ISO_8601
23 / 66

Time Zones
• A region that has a uniform standard time for
legal, commercial, social, and political purposes.
• Most of the time zones on land are offset from
UTC (UTC−12 to UTC+12)
– A time change of one hour is required for each
change of longitude by 15°.
– The UTC time zone is sometimes denoted by Z.
24 / 66

• Some countries, such as China and India, use a
single time zone.
https://upload.wikimedia.org/wikipedia/commons/a/ad/Standard_time_zones_of_the_world.png
25 / 66

• Some higher latitude countries use daylight
saving time (summer time) for part of the
year, typically by changing clocks by an hour.
• Taiwan DST were from 1945 to 1961 and 1974
to 1975.
26 / 66

• JDK time zone data is updated when the JDK is
updated.
• Timezone Updater Tool (aka TZUpdater)
– http://www.oracle.com/technetwork/java/javase/
downloads/tzupdater-download-513681.html
27 / 66

Joda-Time

Joda-Time
• Created in 2002.
• Released as v1.0 in 2005.
• Released as v2.0 In 2011.
• Currently v2.2.
Stephen Colebourne
29 / 66

Key concepts
• Instant
– Defined as an instant in the datetime continuum specified
as a number of milliseconds from 1970-01-01T00:00Z.
• The ReadableInstant defines an instant in the
datetime continuum.
– Instant
– DateTime
– DateMidnight
– MutableDateTime
30 / 66
Immutable

• Instant (continued)
– The millisecond instant can be converted to any
date time field using a Chronology.
Instant
Time-line
31 / 66

• Partial
– A partial date and time representation.
– May 26 could apply to any year. 13:06 p.m. could apply
to any day of any year.
• The ReadablePartial interface defines a
partial time.
– LocalDate、LocalTime、LocalDateTime
– YearMonth、MonthDay
– Partial
– YearMonthDay
– TimeOfDay
32 / 66

• Partial (continued)
Instant
Time-line
= Partial + missing fields + time zone
33 / 66

• Interval
– An interval of time between two instants.
• Interval is defined by the ReadableInterval
interface.
– Interval
– MutableInterval
34 / 66

• Interval (continued)
Start instant End instant
Interval
35 / 66

• Duration
– Represents a duration of time measured in
milliseconds.
• Duration is represented by the
ReadableDuration interface.
– Duration
instant + Duration = instant
36 / 66

• Period
– Represents the same concept as Duration, but in
"human" terms such as years, months, and weeks.
• Period is represented by the
ReadablePeriod interface.
– Period
– MutablePeriod
– Years、Months、Weeks、Days
– Hours、Minutes、Seconds
37 / 66

• Period (continued)
instant + Period = instant
38 / 66

• Chronology
– A chronology is a pluggable calendar system.
• The Chronology class provides access to the
individual date time fields.
– ISO8601 (Default) - ISOChronology
– Gregorian - GregorianChronology
– GregorianJulian – GJChronology
– Julian - JulianChronology
– Buddhist - BuddhistChronology
– Coptic - CopticChronology
– Ethiopic - EthiopicChronology
– Islamic - IslamicChronology
GregorainCalendar
replacement
39 / 66

• Chronology (continued)
40 / 66

• Time Zone
– Joda-Time also compiles the time zone data into
our jar file.
– You can update the raw data and recompile the jar
at any time.
– http://joda-time.sourceforge.net/tz_update.html
• Available Time Zones
– http://joda-time.sourceforge.net/timezones.html
41 / 66

Beef
• What do you need?
• Period between two Instants or Partials.
42 / 66

• What do you need?
• Most of the time, we need Partial.
43 / 66

• What do you need?
• Period.
44 / 66

• Adding 5 days, 6 months, and 3 weeks to a date
and printing the formatted result.
• Using Joda-Time.
45 / 66

46 / 66
JS R 31
0

Joda-Time as JSR-310?
• Why JSR-310 isn't Joda-Time
– http://blog.joda.org/2009/11/why-jsr-310-isn-
joda-time_4941.html
• Joda-Time has design flaws
– Human/Machine timelines
– Pluggable chronology
– Nulls
– Internal implementation
Stephen Colebourne
47 / 66

Machine/Human timelines
• Machines have one view - a single, ever
increasing number.
• Humans have a totally different view of time.
– Calendar systems.
– Years, months, days, hours, minutes and seconds.
– Time zones
– ...
• In Joda-Time, the DateTime class (human view of an
instant in time) are implementations of
ReadableInstant. This is wrong.
48 / 66

JSR 310
• The java.time package.
• The distinction between computer-related
times and human-related times have been
made more apparent.
49 / 66

Computer-related times
• Instant
– Represents a fixed point in time as an offset from
the standard Java epoch (1st Jan 1970). The
instant is stored to nanosecond resolution.
– Defines its own time-scale, the Java Time-Scale.
– http://download.java.net/jdk8/docs/api/java/time
/Instant.html
50 / 66

Human-related times
• Without a time-zone in the ISO-8601
– LocalDateTime
– LocalDate
– LocalTime
• Years, months, days
– Year, such as 2007.
– YearMonth, such as 2007-12.
– MonthDay, such as 12-03.
51 / 66

An amount of time
• A time-based amount of time.
– Duration, such as '34.5 seconds'.
–Uses nanosecond resolution with a
maximum value of the seconds that can be
held in a long.
• A date-based amount of time
– Period, such as '2 years, 3 months and 4 days'.
52 / 66

Joda-Time vs JSR310
• Joda-Time
• JSR310
53 / 66

• Joda-Time
• JSR310
54 / 66

• Joda-Time
• Using JSR310.
55 / 66

• OffsetDateTime adds to the instant the
offset from UTC in ISO-8601.
• ZonedDateTime adds full time-zone rules
56 / 66

Framework-level API
• The java.time.temporal package.
• TemporalAccessor
– Defines read-only access to a temporal object,
such as a date, time, offset or some combination
of these.
• Temporal extends TemporalAccessor.
– The base interface type for date, time and offset
objects that are complete enough to be
manipulated using plus, minus and with.
57 / 66

• Temporal implementations.
– Instant
– LocalDate、LocalDateTime、LocalTime
– OffsetDateTime、OffsetTime
– Year、YearMonth
– ZonedDateTime
• MonthDay implements TemporalAccessor
rather than Temporal. Why?
– http://download.java.net/jdk8/docs/api/java/time/M
onthDay.html
58 / 66

• plus and minus of Temporal
– plus(TemporalAmount amount)
– plus(long amountToAdd, TemporalUnit unit)
– minus(TemporalAmount amount)
– minus(long amountToSubtract, TemporalUnit unit)
• TemporalAmount defines an amount of
time, such as "6 hours", "8 days" or "2 years
and 3 months".
– Duration
– Period
59 / 66

• TemporalUnit defines a unit of date-time,
such as Days or Hours.
60 / 66

• with of Temporal
– with(TemporalField field, long newValue)
– with(TemporalAdjuster adjuster)
• TemporalField defines a field of date-time, such
as month-of-year or hour-of-minute.
• Use TemporalAdjuster for more complex
alterations
61 / 66

Chronology?
• What is the range of values returned by this
method in Joda-Time?
• The answer is not 1 to 12, but could be 1 to 13!
– The Coptic chronology has 13 months in a year,
and thus can return a range of 1 to 13.
• Most users of the API never check to see if the
chronology is the standard ISO chronology.
62 / 66

• A better solution would be to keep the date/time
classes restricted to a single calendar system.
• Those date and time classes located in the
java.time package are in the ISO-8601 calendar
system.
• Check the java.time.chrono package if you
need other chronologies.
– JapaneseChronology
– ThaiBuddhistChronology
– …
63 / 66

Summery
• Using Date, Calendar and existing date-
related APIs can be error-prone, painful and
tedious.
• The complexities of accurate timekeeping are
beyond your imagine.
• What do you need? Computer-related times
or human-related times?
• Need to manipulate dates and times? Using
Joda-Time or JSR310 to make it easy!
64 / 66

• Other libraries for handling dates and times
– Date4j, Simple Alternative To java.util.Date.
– Arrow, Better dates and times for Python.
– Moment.js, A JavaScript date library for parsing,
validating, manipulating, and formatting dates.
– Noda-Time, A port of Joda-Time to .NET
65 / 66

References
• Joda-Time
– http://joda-time.sourceforge.net/
• Joda-Time - You can't escape time. Why not make it easy?
– http://www.ibm.com/developerworks/java/library/j-
jodatime/index.html
• JSR 310 Date and Time API for Java
– http://www.infoq.com/news/2010/03/jsr-310
• Why JSR-310 isn't Joda-Time
– http://blog.joda.org/2009/11/why-jsr-310-isn-joda-
time_4941.html
• JDK8 Javadoc
– http://download.java.net/jdk8/docs/api/index.html
66 / 66