Package org.joda.time

DateTime object creation and manipulation.

See:
Description

Interface Summary

ReadableDateTime	Extends the ReadableInstant interface to support specific datetime fields.
ReadableInstant	Readable interface for an instant in the datetime continuum.
ReadWritableInstant	Writable interface for an instant in the datetime continuum.

Class Summary

AbstractDateTime	AbstractDateTime provides the common behaviour for immutable datetime classes.
AbstractInstant	AbstractInstant provides the common behaviour for immutable time classes.
Chronology	Chronology provides access to the individual date time fields for a chronological calendar system.
DateTime	DateTime is the basic implementation of a datetime class supporting chronologies and time zones.
DateTimeComparator	DateTimeComparator is the standard implementation of the Comparator interface for various Joda and Java objects.
DateTimeConstants	DateTimeConstants is a non-instantiable class of constants used in the date time system.
DateTimeField	DateTimeField is an abstract class which allows the date and time manipulation code to be field based.
DateTimeFieldProperty	DateTimeFieldProperty binds a ReadableInstant to a DateTimeField.
DateTimeZone	DateTimeZone represents a time zone.
Instant	Instant is the standard implementation of a fully immutable instant in time.
MutableDateTime	MutableDateTime is the standard implementation of a modifiable datetime class.
MutableDateTimeFieldProperty	MutableDateTimeFieldProperty binds a ReadWritableInstant to a DateTimeField.

Package org.joda.time Description

DateTime object creation and manipulation.

This package aims to provide a full date and time implementation to replace the Java Date and Calendar classes. The implementation covers both the Gregorian/Julian calendar system and the ISO8601 standard. The design aims to be flexible enough to enable other calendar systems, or extensions to the provided ones, to be created.

The ISO8601 standard is the international standard for dates, times and time periods. It defines a String representation and fixes values for the first day of the week, Monday which has the value 1, and the first week in a year. This standard is being increasingly used in computer interchange and is the agreed format for XML. For most uses, the ISO standard is the same as Gregorian/Julian and is thus the preferred format.

Interfaces

The main API concepts are defined by interfaces:

• ReadableInstant - an instant in time
• ReadWriteableInstant - an instant that can be updated

These define the public interface to dates and times. The design is millisecond based as with java.util.Date and Calendar. This should enable easy conversions.

It is intended that dates are passed into methods using the interface. Methods will utilise the date and if necessary return a specified implementation, preferably Instant. By using the interface to pass time in and Instant to return time you are not hard coding a locale specific calendar system into your API. Within the method you can create an instance of a specific calendar system to work with if required.

Implementations

The basic implementation of the ReadableInstant interface is Instant. This is a simple immutable class that stores the millisecond value and integrates with Java Date and Calendar. If you are dealing with an instant in time but do not know, or do not want to specify, which calendar system it refers to then you should use this class.

The main implementation class for datetimes is the DateTime class. This implements the ReadableInstant interface, but also provides convenient methods to access the fields of the datetime. Conversion methods allow integration with the Java Date and Calendar classes. DateTime has three subclasses at present - ISODateTime, GJDateTime and BuddhistDateTime. These provide the same functionality but with different chronologies.

These subclasses are immutable, so can be used safely in a multi-threaded environment. DateTime itself can be considered to be immutable so long as you only use the methods it or a superclass defines. To be fully immutable DateTime would have to be final, but that prevents subclasses from adding convenient access methods. The chosen design allows the flexibility of convenience, but at the risk of someone writing potentially mutable subclasses. (Note that the millisecond and chronology values are immutable, so the 'danger' posed is small.)

In addition to the datetime classes, there are date and time only classes, DateOnly and TimeOnly. These have similar subclasses to DateTime.

To enable the easy editing of datetimes, there is a single implementation of the ReadWriteableInstant interface, MutableDateTime.

Chronologies and Fields

In order to enable the package to be easily extended, each field of the datetime, such as the month, is calculated by a separate subclass of DateTimeField. If desired, applcations can then write their own implementations to retrieve an unusual field from the millisecond value.

The fields that together represent a calendar system are grouped into a Chonology. The chronology represents all the information to convert from a millisecond value to human understanable fields in a specific calendar system. Chronologies are provided for ISO and Gregorian/Julian (GJ). (ISO is in fact a special case of GJ).

This design results in a low overhead on the date time classes. Java Calendar class performs poorly because it has many internal fields that are constantly kept in sync. This design only calculates fields when required, resulting in lightweight and simple date time classes.

Formatting

Formatting is provided by the format subpackage. Comprehensive support is provided for outputting dates and times in multiple formats. A pattern similar to Java SimpleDateFormat can be used, but a more advanced programmatic technique is available.

General

The package is standalone and has no dependencies other than JDK 1.2. It is licenced under an Apache/BSD style licence.