Instant

The most frequently used concept in Joda-Time is that of the instant. An Instant is defined as an instant 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.

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. More powerful access to the field can be obtained via its property. 

DateTime dt = new DateTime();  // current time
int month = dt.getMonth();     // gets the current month
int month = dt.month().get();  // alternative way to get value
String monthStr = dt.month().getAsText();  // gets the month name

To deal with local times (no time zone), or with date only or time only concepts, you should use the partial classes.

Using Instants in Joda-Time

Within Joda-Time an instant is represented by the ReadableInstant interface. There are four implementations of the interface provided:

  • Instant - A simple immutable implementation which is restricted to the UTC time zone and is intended for time zone and calendar neutral data transfer
  • DateTime - The most commonly used class in the library, and an immutable representation of a date and time with calendar and time zone
  • DateMidnight - Similar to DateTime and also immutable but with the time component forced to be midnight (at the start of a day)
  • MutableDateTime - A mutable representation of date and time with calendar and time zone
We recommend the immutable implementations for general usage.

The code can be used in various ways: 

// setup date object for midday on Christmas 2004 (ISO year 2004)
DateTime dt = new DateTime(2004, 12, 25, 12, 0, 0, 0);
// get the year, 2004
int year = dt.getYear();
// get the day of week index 1 (Monday) to 7 (Sunday)
int dow = dt.getDayOfWeek();
// get the text, such as 'Tuesday'
String dowStr = dt.dayOfWeek().getAsText();
Compared to GregorianCalendar Joda-Time classes use 1-12 for months, and are immutable in the standard implementations. It is also easy to convert to and from the JDK classes. 
// construct DateTime from JDK Date
Date jdkDate = new Date();
DateTime dt = new DateTime(jdkDate);

// construct Calendar from DateTime (could also construct a Date)
GregorianCalendar cal = dt.toGregorianCalendar();

Note that the interface ReadableInstant should not be used like the collections API. The interface only contains the core subset of the operations of DateTime. You should use the interface only when you feel the need to be flexible about future changes to the object passed into a method. You might also want to consider the ReadableDateTime interface which extends ReadableInstant to provide additional methods.

Nulls

Joda-Time defines a null instant as the current time. Thus, when a method is defined as taking a ReadableInstant, passing null in will be the same as passing in an instant set to the current time.