Joda Time and a Brief History of the World Daniel Hinojosa @dhinojosa Joda Time and a Brief History of the World

Preamble

Epoch (reference date) Serves as a reference point from which time is measured. Most of the world uses Anno Domini calendar era (the civil calendar era used internationally and in many countries) Traditionally-reckoned Incarnation of Jesus. Many other current and historical calendar eras exist, each with its own epoch.

Asian Epochs Japan: From the accession of the current emperor. China: Followed same with emperor until 1912. Since 1912: Republican era was established still used in Taiwan Common Era: People's republic of China starts in 1949. India: The Saka Era. Vernal Equinox since year 78. North Korea: Starts 1912: but because Kim Il-Sung was born on that date. Thailand: Founding of Bangkok in 1782, but in 1941 uses 543BC started Thai Solar Calendar.

Religious Epochs Israel - Hebrew Calendar dates from "Creation" (Anno Mundi) / March 18, 3952 BC In case you are wondering Earth Day is on Spring Equinox Islam - Anno Hegiræ - The year of the Hijra (the Migration of Mohammed to Medina in 622 Bikram Samwat Calendar established by Indian emperor Vikramaditya. It is a popularly used calendar in India and the official calendar of Bangladesh and Nepal.

Already it's complex

Computer System Epochs Matlab, Turbo DB, tdbengine – January 1, 0 Symbian, .NET, RXX, Rata Die – January 1, 1 NTFS, COBOL, Win32/64 – January 1, 1601 MS SQL Server – January 1, 1753 Microsoft Excel, Lotus 1-2-3 - January 0, 1900. Common LISP, CICS, Network Time Protocol – January 1, 1900 LabView, Mac OS <= 9.0, Palm – January 1, 1904 And More...

Perhaps a Standard 0 = January 1, 1970 Midnight GMT. Unix Time Unix, Linux, Ruby, Mac OS X, Java, JavaScript, C, PHP

GMT Greenwich Mean Time Mean solar time at the Royal Observatory in Greenwich, London. Britain had been the world's time keeper since Victorian Age. It is commonly used in practice to refer to UTC (not accurate) Side Note: GMT used in winter, British Summer Time in summer

UTC? Coordinated Universal Time Backronym: "Universal Time, Coordinated" Time Standard based on International Atomic Time (TAI) Not based on solar calculations UTC replaced GMT as the basis for the main reference time scale or civil time in various regions on 1 January 1972. .

ISO 8601 Representation of dates and times is an international standard covering the exchange of date and time-related data. Avoid misinterpretation of numeric representations of dates and times. Standardized method of communicating time- based information across time zones by attaching an offset to Coordinated Universal Time (UTC)

How ISO 8601 is Done Date: 2010-07-07 Separate Date and Time in UTC:  2010-07-07 07:01Z Combined Date and Time in UTC: 2010-07-07T07:01Z Combined Date and Time in MDT: 2010-07- 07T07:38:51.716-06:00 Date With Week Number: 2010-W27-3 Ordinal Date: 2010-188 Duration: P3Y6M4DT12H30M5S Intervals: 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z 2007-03-01T13:00:00Z/P1Y2M10DT2H30M P1Y2M10DT2H30M/2008-05-11T15:30:00Z P1Y2M10DT2H30M

Modern Calendering/Chronology

Julian Reform of the Roman calendar Was introduced by Julius Caesar in 46 BC Remained in use into the 20th century in some countries as a civil calendar The Roman Catholic Church and Protestant churches have replaced the Julian calendar with the Gregorian calendar. Orthodox Church (with the exception of Estonia and Finland) still use for calculating the dates of moveable feasts.

Gregorian Accepted As Civil Calendar Worldwide Introduced by Pope Gregory XIII Julian calendar system assumes time between vernal equinoxes is 365.25 days, when in fact it is about 11 minutes less. Signed 24 February 1582.

Other In-Use Calendars Buddhist - One era (the current era), and has a year offset by 543 from the current Gregorian year. Coptic - Based on that used in ancient Egypt. a.k.a. Alexandrian Calendar In use today by the Coptic Orthodox Church and by farmers tracking the seasons in Egypt.

Other In-Use Calendars Ethiopic – Similar to Coptic in use in Ethiopia Gregorian-Julian - Switch from one to the other occurs at a configurable date. The default date is 1582-10-15, as defined by Pope Gregory XIII. Islamic - Lunar calendar used in many Muslim countries. Anno Hegiræ

Dates, Times, Calendars are Tough

The Problem with Java

java.util.Date No support for Locale No calendar support Just a wrapper for # of milliseconds since epoch Deprecated Intended to reflect coordinated universal time (UTC), it may not do so exactly, depending on the host environment of the Java Virtual Machine. A year y is represented by the integer y - 1900.

java.util.Calendar Based on Gregorian Calendar A month is represented by an integer from 0 to 11; 0 is January, 1 is February, and so forth; thus 11 is December. Mutable, You can change the object created without other references knowing about it. Awkward methods Uses static methods Calendar.getInstance() Other Calendars are awkward to extend.

Joda Time

Joda Time Straight-forward instantiation and methods ISO 8601 Based, not Gregorian Calendar Has support for other calendar systems if you need it (Julian, Gregorian-Julian, Coptic, Buddhist) Includes classes for date times, dates without times, times without dates, intervals and time periods. Advanced formatting Well documented and well tested Immutable! Months are 1 based JSR-310

Starting off import org.joda.time.DateTime; DateTime dateTime = new DateTime(); DateTime dt = new DateTime            ("2011-07-13T23:39:45.618-06:00");

Instant Moment in the DateTime continuum specified as a number of milliseconds from 1970-01-01T00:00Z Represented by the ReadableInstant interface Instant, DateTime, MutableDateTime and DateTimeMidnight

Interval Interval of time from one instant to another instant. Both instants are fully specified instants in the DateTime continuum, complete with time zone. Start instant is inclusive but the end instant is exclusive Interval and MutableInterval

Interval Example DateTime saleStart = new DateTime (2011, 11, 26, 5, 30, 0, 0); DateMidnight saleEnd = new DateMidnight(2011, 12, 25); Interval interval = new Interval(saleStart, saleEnd); interval.contains(new DateTime()); //false interval.contains(new DateTime (2011, 12, 12, 20, 12, 44, 332)); //true interval.toDuration().getStandardSeconds(); //Woohoo! 2485800 sec. sale! Wait what? interval.toPeriod(PeriodType.days()).getDays()); //28 day sale!

Duration Duration of time measured in milliseconds Usually obtained from Interval Start to Finish instant + duration = instant

Duration Example DateTime saleStart = new DateTime (2011, 11, 26, 5, 30, 0, 0); DateMidnight saleEnd = new DateMidnight(2011, 12, 25); Interval interval = new Interval(saleStart, saleEnd); interval.contains(new DateTime()); //false interval.contains(new DateTime (2011, 12, 12, 20, 12, 44, 332)); //true interval.toDuration().getStandardSeconds(); //Woohoo! 2485800 sec. sale! Wait what? interval.toPeriod(PeriodType.days()).getDays()); //28 day sale!

Period instant + period = instant Period of time defined in terms of fields, for example, 3 years 5 months 2 days and 7 hours Differs from a duration in that it is inexact in terms of milliseconds Periods are useful for human interaction “How many weeks will it take?”

Period Side Effects Given 1 month period, if you add this period to the 1st February (ISO) then you will get the 1st March. Given 1 month period to the 1st March you will get the 1st April

More Period Side Effects Adding 1 day at the daylight savings boundary. If you use a period to do the addition then either 23 or 25 hours will be added as appropriate. If you had created a duration equal to 24 hours, then you would end up with the wrong result (maybe) Period, Mutable Period

Period Example DateTime saleStart = new DateTime (2011, 11, 26, 5, 30, 0, 0); DateMidnight saleEnd = new DateMidnight(2011, 12, 25); Interval interval = new Interval(saleStart, saleEnd); interval.contains(new DateTime()); //false interval.contains(new DateTime (2011, 12, 12, 20, 12, 44, 332)); //true interval.toDuration().getStandardSeconds(); //Woohoo! 2485800 sec. sale! Wait what? interval.toPeriod(PeriodType.days()).getDays()); //28 day sale!

Partial partial + missing fields + time zone = instant Partial representation of date / time A partial does not fully specify a single point in the datetime continuum Essentially an date or time object to be defined later. LocalDate, LocalTime, LocalDateTime, YearMonth, MonthDay, Partial

Partial Example LocalDate localDate = new LocalDate(2011, 10, 11); //LocalDate is not time zone or time specific localDate.minusDays(10).dayOfWeek().getAsText(); //Saturday LocalTime lunch = new LocalTime(11, 30); //Local Time is not time zone or date specific DateTime lunchTime = localDate.toDateTime (lunch,DateTimeZone.forID("US/Mountain")); //Bring it together 2011-10-11T11:30:00.000-06:00

Chronology Representation of Calendars Default is ISO Chronology Pluggable Chronology coptic = CopticChronology.getInstance();

Time Zones DateTimeZone zone = DateTimeZone.forID("Europe/London"); DateTimeZone zoneUTC = DateTimeZone.UTC; DateTimeZone zoneUTC =    DateTimeZone.forOffsetHours(hours); Based on public TZ Database @ http://www.twinsun.com/tz/tz-link.htm

Packaging The public packages are the root package (under org.joda.time) and the format package The private packages are the base, chrono, convert, field and tz packages.

JDK interoperability

java.util.Date // from JodaTime to JDK DateTime dt = new DateTime(); Date jdkDate = dt.toDate(); // from JDKTime to Joda dt = new DateTime(jdkDate);

java.util.Calendar // from Joda to JDK DateTime dt = new DateTime(); Calendar jdkCal =    dt.toCalendar(Locale.CHINESE); // from JDK to Joda dt = new DateTime(jdkCal);

java.util.GregorianCalendar // from Joda to JDK DateTime dt = new DateTime(); GregorianCalendar jdkGCal =      dt.toGregorianCalendar(); // from JDK to Joda dt = new DateTime(jdkGCal);

Date and Field Separation DateTimeField is separate from DateTime to query information. Done through DateTime.Property DateTime.Property has then other methods to do get better information

Date and Field Example Given: DateTime dateTime = new DateTime(2011, 7, 12, 20, 0, 0, 0); DateTime.Property dayOfWeekProperty =     dateTime.dayOfWeek(); dayOfWeekProperty.getAsShortText();        //returns "Mon", "Tue", etc. dayOfWeekProperty.getAsText();        // returns "Monday",        // "Tuesday", etc.

Date and Field Separation (Cont.) dayOfWeekProperty.getAsText (Locale.FRENCH); // returns "Lundi", etc. dayOfWeekProperty.get(); // Integer Representation Other metadata on the minimum and maximum text size, leap status, related durations.

“Modifying” DateTimes Given: DateTime dateTime = new DateTime(2011, 7, 12, 20, 0, 0, 0); DateTime result =     dt.dayOfWeek().addToCopy(3); // 2011-07-15 20:00:00.000 DateTime result = dateTime.plusDays(3) // 2011-07-15 20:00:00.000 Each provides a copy

Mutable DateTime MutableDateTime mdt = dt.toMutableDateTime(); (Intended for creation purposes) MutableDateTime mdt =     dt.toMutableDateTime();       // perform various calculations on mdt   DateTime result =     mdt.toDateTime(); //lock it up!

Time Zones // get current moment in default time zone DateTime dt = new DateTime(); //2011-07-13T13:23:33.230-06:00 // translate to Eastern time DateTime dtEastern = dt.withZone (DateTimeZone.forID("US/Eastern")); //2011-07-13T15:23:33.230-04:00 DateTime dtEastern = dt.withZoneRetainFields (DateTimeZone.forID("US/Eastern")); //2011-07-13T13:23:33.230-04:00

DateTimeFormatter Used to format the DateTime Instant DateTimeFormatter fmt =    DateTimeFormat.forPattern("yyyyMMdd"); DateTimeFormatter frenchFmt =    fmt.withLocale(Locale.FRENCH); DateTimeFormatter dateTimeFormatter = ISODateTimeFormat. dateHourMinuteSecond();

Direct Format via toString() DateTime dt = new DateTime(); String a = dt.toString(); String b = dt.toString("dd:MM:yy"); String c = dt.toString ("EEE", Locale.FRENCH); DateTimeFormatter fmt = ...; String d = dt.toString(fmt);

What's Possible dateTime.plusDays(20). plusMonths(2).dayOfWeek(). withMaximumValue().plusHours(4). toString ("E MM/dd/yyyy HH:mm:ss.SSS"); Immutability = Automatic Memento

Joda-Time Language Libraries Scala-Time https://github.com/jorgeortiz85/scala-time DateTime.nextMonth < DateTime.now + 2.months Clj-Time https://github.com/getwoven/clj-time (hour (date-time 1986 10 14 22))

Testing with JodaTime // always return the same time // when querying current time DateTimeUtils.setCurrentMillisFixed(millis) ; // offset the real time DateTimeUtils.setCurrentMillisOffset (millis); // reset it back DateTimeUtilssetCurrentMillisSystem()

Time Pro Tips Have a Continuous Integration Server in another time zone Store Date/Time in Unix Time UTC, Make it your standard Think of Time Zones as presentation specific Different computers have different times due to temperature, incorrectness, adjustment, gravity, and more. Use Joda Time

Thank You