Partial

A partial in Joda-Time is a partial date and time representation. All implementations represent local dates and times, and do not reference a time zone. As such, they only partially represent a date or time in the datetime continuum.

The main implementations changed in version 1.3. This was to address implementation issues with the original design. The previous classes - TimeofDay and YearMonthDay - are now effectively deprecated. The new implementations are LocalDate, LocalTime and LocalDateTime.

It is not possible to directly interoperate between a partial and an instant. A partial does not fully specify a single point in the datetime continuum, but instead may match multiple points. For example, a LocalTime occurs one per day on the datetime continuum.

A partial can be converted to a full instant by specifying the missing values. At a minimum the time zone must be specified. It may be necessary to specify other missing fields. For example, to convert a LocalDate to a DateTime requires filling in the time fields and the time zone.

In terms of datetime maths, you could write: 

      partial  +  missing fields  +  time zone  =  instant

Date representations

Two classes represent a date in Joda-Time - DateMidnight and LocalDate. These have different meanings. DateMidnight is a fully specified instant, with a time zone. It is defined as the milliseond instant at exactly mignight (00:00) at the start of a day. LocalDate defines a day using the year, monthOfYear and dayOfMonth fields and no time zone. It can be thought of as a local date that covers the whole of the day from 00:00 to 23:59.

Using Partials in Joda-Time

Within Joda-Time a partial is represented by the ReadablePartial interface. There are six implementations of the interface provided:

  • LocalDate - An immutable implementation that represents a date without a time or time zone.
  • LocalTime - An immutable implementation that represents a time without a date or time zone.
  • LocalDateTime - An immutable implementation that represents a datetime without a time zone.
  • YearMonth - An immutable implementation that represents a year and month, useful for credit card expiry dates.
  • MonthDay - An immutable implementation that represents a month and day, useful for birthdays without years.
  • Partial - An immutable implementation that can store any combination of datetime fields. For example, using this class you could create a YearMonth or DayOfWeekDayOfMonth partial.
  • YearMonthDay - Effectively deprecated - only supports the year, monthOfYear and dayOfMonth fields.
  • TimeOfDay - Effectively deprecated - only supports the hour, minute, second and millisecond fields.

The code can be used in various ways: 

// setup objects
LocalDate date = new LocalDate(2004, 12, 25);
LocalTime time = new LocalTime(12, 20);

int year = date.getYear();  // returns 2004
int hour = time.getHour();  // returns 12
String monthStr = date.month().getAsText();  // returns 'December'
Conversion to and from instants is easy: 
LocalDate date = new LocalDate(2004, 12, 25);
LocalTime time = new LocalTime(12, 20);

// merge, resulting in 2004-25-12T12:20 (default time zone)
DateTime dt = date.toDateTime(time);

// extract the date fields from someDT
DateTime someDT = ...
LocalDate date = new LocalDate(someDT);

Note that the interface ReadablePartial should not be used like the collections API. The interface only contains the core subset of the operations. Instead, you should refer directly to the implementation classes in your APIs.

Nulls

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