Introduction

Joda-Time is like an iceberg, 9/10ths of it is invisible to user-code. Many, perhaps most, applications will never need to see what's below the surface. This document provides an introduction to the Joda-Time API for the average user, not for the would-be API developer.

The bulk of the text is devoted to code snippets that display the most common usage scenarios in which the library classes are used. In particular, we cover the usage of the key DateTime, Interval, Duration and Period classes.

We finish with a look at the important topic of formatting and parsing and a few more advanced topics.

• Architecture Overview
  • Instants
    • Fields
    • Properties
  • Intervals
  • Durations
  • Periods
  • Chronology
  • TimeZones
  • Interface usage
  • Package structure
• Working with DateTime
  • Construction
  • JDK Interoperability
  • Querying DateTimes
    • Acessing fields
    • Date fields
    • Time fields
  • Manipulating DateTimes
    • Modifying fields
    • DateTime methods
    • Using a MutableDateTime
  • Changing TimeZone
  • Changing Chronology
• Input and Output
  • Formatters
  • Standard Formatters
  • Custom Formatters
  • Freaky Formatters
• Advanced features
  • Change the Current Time
  • Converters
  • Security

Architecture Overview

The major building blocks of Joda-Time are introduced below. These are the concepts of instant, interval, duration, period, chronology and timezones. We then say a few words about the role of interfaces in the library design, which is a little different than the norm. We end with a few words on package structure. Usage examples for instant are delayed until the following sections of the guide. Examples for interval, duration and period may be found in the appropriate section in the "Key Concepts" part of the documentation.

Instants

The most frequently used concept in Joda-Time is that of the instant. An Instant is defined as a moment in the datetime continuum specified as a number of milliseconds from 1970-01-01T00:00Z. This definition of milliseconds is consistent with that of the JDK in Date or Calendar. Interoperating between the two APIs is thus simple.

Within Joda-Time an instant is represented by the ReadableInstant interface. The main implementation of this interface, and the class that the average API user needs to be most familiar with, is DateTime. DateTime is immutable - and once created the values do not change. Thus, this class can safely be passed around and used in multiple threads without synchronization.

The millisecond instant can be converted to any date time field using a Chronology. To assist with this, methods are provided on DateTime that act as getters for the most common date and time fields.

We discuss the chronology concept a litte further on in this overview.

A companion mutable class to DateTime is MutableDateTime. Objects of this class can be modified and are not thread-safe.

Other implementations of ReadableInstant include Instant and the deprecated DateMidnight.

Intervals

An interval in Joda-Time represents an interval of time from one instant to another instant. Both instants are fully specified instants in the datetime continuum, complete with time zone.

Intervals are implemented as half-open, which is to say that the start instant is inclusive but the end instant is exclusive. The end is always greater than or equal to the start. Both end-points are restricted to having the same chronology and the same time zone.

Two implementations are provided, Interval and MutableInterval, both are specializations of ReadableInterval.

Durations

A duration in Joda-Time represents a duration of time measured in milliseconds. The duration is often obtained from an interval.

Durations are a very simple concept, and the implementation is also simple. They have no chronology or time zone, and consist solely of the millisecond duration.

Durations can be added to an instant, or to either end of an interval to change those objects. In datetime maths you could say:

      instant  +  duration  =  instant

Currently, there is only one implementation of the ReadableDuration interface: Duration.

Periods

A period in Joda-Time represents a period of time defined in terms of fields, for example, 3 years 5 months 2 days and 7 hours. This differs from a duration in that it is inexact in terms of milliseconds. A period can only be resolved to an exact number of milliseconds by specifying the instant (including chronology and time zone) it is relative to.

For example, consider a period of 1 month. If you add this period to the 1st February (ISO) then you will get the 1st March. If you add the same period to the 1st March you will get the 1st April. But the duration added (in milliseconds) in these two cases is very different.

As a second example, consider 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.

Periods are implemented as a set of int fields. The standard set of fields in a period are years, months, weeks, days, hours, minutes, seconds and millis. The PeriodType class allows this set of fields to be restricted, for example to elimate weeks. This is significant when converting a duration or interval to a period, as the calculation needs to know which period fields it should populate.

Methods exist on periods to obtain each field value. Periods are not associated with either a chronology or a time zone.

Periods can be added to an instant, or to either end of an interval to change those objects. In datetime maths you could say:

      instant  +  period  =  instant

There are two implementations of the ReadablePeriod interface, Period and MutablePeriod.

Chronology

The Joda-Time design is based around the Chronology. It is a calculation engine that supports the complex rules for a calendar system. It encapsulates the field objects, which are used on demand to split the absolute time instant into recognisable calendar fields like 'day-of-week'. It is effectively a pluggable calendar system.

The actual calculations of the chronology are split between the Chronology class itself and the field classes - DateTimeField and DurationField. Together, the subclasses of these three classes form the bulk of the code in the library. Most users will never need to use or refer directly to the subclasses. Instead, they will simply obtain the chronology and use it as a singleton, as follows:

Chronology coptic = CopticChronology.getInstance();

Internally, all the chronology, field, etc. classes are maintained as singletons. Thus there is an initial setup cost when using Joda-Time, but after that only the main API instance classes (DateTime, Interval, Period, etc.) have creation and garbage collector costs.

Although the Chronology is key to the design, it is not key to using the API !!

For most applications, the Chronology can be ignored as it will default to the ISOChronology. This is suitable for most uses. You would change it if you need accurate dates before October 15, 1582, or whenever the Julian calendar ceased in the territory you're interested in. You'd also change it if you need a specific calendar like the Coptic calendar illustrated earlier.

TimeZones

The chronology class also supports the time zone functionality. This is applied to the underlying chronology via the decorator design pattern. The DateTimeZone class provides access to the zones primarily through one factory method, as follows:

DateTimeZone zone = DateTimeZone.forID("Europe/London");

In addition to named time zones, Joda-Time also supports fixed time zones. The simplest of these is UTC, which is defined as a constant:

DateTimeZone zoneUTC = DateTimeZone.UTC;

DateTimeZone zoneUTC = DateTimeZone.forOffsetHours(hours);

The time zone implementation is based on data provided by global-tz. A full list of time zone ids can be found here

Joda-Time provides a default time zone which is used in many operations when a time zone is not specified. This is similar in concept to the default time zone of the java.util.TimeZone class. The value can be accessed and updated via static methods:

DateTimeZone defaultZone = DateTimeZone.getDefault();
DateTimeZone.setDefault(myZone);

Interface usage

As you have seen, Joda-Time defines a number of new interfaces which are visible throughout the javadocs. The most important is ReadableInstant which currently has 4 implementations. Other significant interfaces include ReadableInterval and ReadablePeriod. These are currently used as generalizations for a value-only and a mutable class, respectively.

An important point to mention here is that the Joda interfaces are used differently than, for instance, the JDK Collections Framework interfaces. When working with a Collections interface, such as List or Map you will normally hold your variable as a type of List or Map, only referencing the concrete class when you create the object.

    List list = new ArrayList();
    Map map = new HashMap();

    DateTime dt = new DateTime();

For maximum flexibility however, you might choose to declare your method parameters using the Joda-Time interface. A method on the interface can obtain the concrete class for use within the method.

    public void process(ReadableDateTime dateTime) {
        DateTime dt = dateTime.toDateTime();
    }

Package structure

The package structure is designed to separate the methods in the public API from the private API. 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. Most applications should not need to import classes from the private packages.

Working with DateTime

    DateTime dt = new DateTime();

    DateTime dt = new DateTime("2004-12-13T21:39:45.618-08:00");

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

    // from JDK to Joda
    dt = new DateTime(jdkDate);

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

    // from JDK to Joda
    dt = new DateTime(jdkCal);

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

    // from JDK to Joda
    dt = new DateTime(jdkGCal);

Querying DateTimes

The separation of the calculation of calendar fields (DateTimeField) from the representation of the calendar instant (DateTime) makes for a powerful and flexible API. The connection between the two is maintained by the property (DateTime.Property) which provides access to the field.

For instance, the direct way to get the day of week for a particular DateTime, involves calling the method

    int iDoW = dt.getDayOfWeek();

    public static final int MONDAY = 1;
    public static final int TUESDAY = 2;
    public static final int WEDNESDAY = 3;
    public static final int THURSDAY = 4;
    public static final int FRIDAY = 5;
    public static final int SATURDAY = 6;
    public static final int SUNDAY = 7;

    DateTime.Property pDoW = dt.dayOfWeek();

    String strST = pDoW.getAsShortText(); // returns "Mon", "Tue", etc.
    String strT = pDoW.getAsText(); // returns "Monday", "Tuesday", etc.

    String strTF = pDoW.getAsText(Locale.FRENCH); // returns "Lundi", etc.

    iDoW = pDoW.get();

    strT = dt.dayOfWeek().getAsText();
    iDoW = dt.dayOfWeek().get();

    iDoW = dt.getDayOfWeek();

    dt.getEra();
    dt.getYear();
    dt.getWeekyear();
    dt.getCenturyOfEra();
    dt.getYearOfEra();
    dt.getYearOfCentury();
    dt.getMonthOfYear();
    dt.getWeekOfWeekyear();
    dt.getDayOfYear();
    dt.getDayOfMonth();
    dt.getDayOfWeek();

    String month = dt.monthOfYear().getAsText();
    int maxDay = dt.dayOfMonth().getMaximumValue();
    boolean leapYear = dt.yearOfEra().isLeap();

    int hour = dt.getHourOfDay();
    int min = dt.getMinuteOfHour();
    int sec = dt.getSecondOfMinute();

Manipulating DateTimes

DateTime objects have value semantics, and cannot be modified after construction (they are immutable). Therefore, most simple manipulation of a datetime object involves construction of a new datetime as a modified copy of the original.

WARNING: A common mistake to make with immutable classes is to forget to assign the result to a variable. Remember that calling an add or set method on an immtable object has no effect on that object - only the result is updated.

    DateTime result = dt.dayOfWeek().setCopy(DateTimeConstants.MONDAY);

    DateTime result = dt.dayOfWeek().addToCopy(3);

    DateTime result = dt.plusDays(3);

    MutableDateTime mdt = dt.toMutableDateTime();
    // perform various calculations on mdt
    ...
    DateTime result = mdt.toDateTime();

Changing TimeZone

DateTime comes with support for a couple of common timezone calculations. For instance, if you want to get the local time in London at this very moment, you would do the following

    // get current moment in default time zone
    DateTime dt = new DateTime();
    // translate to London local time
    DateTime dtLondon = dt.withZone(DateTimeZone.forID("Europe/London"));

There is also support for the reverse operation, i.e. to get the datetime (absolute millisecond) corresponding to the moment when London has the same local time as exists in the default time zone now. This is done as follows

    // get current moment in default time zone
    DateTime dt = new DateTime();
    // find the moment when London will have / had the same time
    dtLondonSameTime = dt.withZoneRetainFields(DateTimeZone.forID("Europe/London"));

A set of all TimeZone ID strings (such as "Europe/London") may be obtained by calling DateTimeZone.getAvailableIDs(). A full list of available time zones is provided here.

Changing Chronology

The DateTime class also has one method for changing calendars. This allows you to change the calendar for a given moment in time. Thus if you want to get the datetime for the current time, but in the Buddhist Calendar, you would do

    // get current moment in default time zone
    DateTime dt = new DateTime();
    dt.getYear();  // returns 2004
    // change to Buddhist chronology
    DateTime dtBuddhist = dt.withChronology(BuddhistChronology.getInstance());
    dtBuddhist.getYear();  // returns 2547

Input and Output

Reading date time information from external sources which have their own custom format is a frequent requirement for applications that have datetime computations. Writing to a custom format is also a common requirement.

Many custom formats can be represented by date-format strings which specify a sequence of calendar fields along with the representation (numeric, name string, etc) and the field length. For example the pattern "yyyy" would represent a 4 digit year. Other formats are not so easily represented. For example, the pattern "yy" for a two digit year does not uniquely identify the century it belongs to. On output, this will not cause problems, but there is a problem of interpretation on input.

In addition, there are several date/time serialization standards in common use today, in particular the ISO8601. These must also be supported by most datetime applications.

Joda-Time supports these different requirements through a flexible architecture. We will now describe the various elements of this architecture.

    String strInputDateTime;
    // string is populated with a date time string in some fashion
    ...
    DateTime dt = fmt.parseDateTime(strInputDateTime);

    String strOutputDateTime = fmt.print(dt);

    DateTimeFormatter fmt = ISODateTimeFormat.dateTime();

    DateTimeFormatter fmt = DateTimeFormat.forPattern("yyyyMMdd");

    DateTimeFormatter fmt = DateTimeFormat.forPattern("yyyyMMdd");
    DateTimeFormatter frenchFmt = fmt.withLocale(Locale.FRENCH);
    DateTimeFormatter germanFmt = fmt.withLocale(Locale.GERMAN);

    DateTimeFormatter fmt = new DateTimeFormatterBuilder()
            .appendDayOfMonth(2)
            .appendLiteral('-')
            .appendMonthOfYearShortText()
            .appendLiteral('-')
            .appendTwoDigitYear(1956)  // pivot = 1956
            .toFormatter();

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

Advanced features

    // always return the same time when querying current time
    DateTimeUtils.setCurrentMillisFixed(millis);
    // offset the real time
    DateTimeUtils.setCurrentMillisOffset(millis);