org.joda.time

Provides support for dates, times, time zones, durations, intervals, and partials. This package aims to fully replace the Java Date, Calendar, and TimeZone classes. This implementation covers both the Gregorian/Julian calendar system and the ISO8601 standard. Additional calendar systems and extensions can be created as well.

The ISO8601 standard is the international standard for dates, times, durations, and intervals. It defines text representations, the first day of the week as Monday, and the first week in a year as having a Thursday in it. 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, and is thus the preferred format.

Interfaces

The main API concepts are defined by interfaces:

• ReadableInstant - an instant in time
• ReadableDateTime - an instant in time with field accessors such as dayOfWeek
• ReadablePartial - a definition for local times that are not defined to the millisecond, such as the time of day
• ReadableDuration - a duration defined in milliseconds
• ReadablePeriod - a time period defined in fields such as hours and minutes
• ReadableInterval - a period of time between two instants

• ReadWritableInstant - an instant that can be modified
• ReadWritableDateTime - a datetime that can be modified
• ReadWritablePeriod - a time period that can be modified
• ReadWritableInterval - an interval that can be modified

These define the public interface to dates, times, periods, intervals and durations. As with java.util.Date and Calendar, the design is millisecond based with an epoch of 1970-01-01. This should enable easy conversions.

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. The class follows the definition of the millisecond instant fully, thus it references the ISO-8601 calendar system and UTC time zone. 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 ReadableDateTime interface, providing convenient methods to access the fields of the datetime. Conversion methods allow integration with the Java Date and Calendar classes.

Like Instant, DateTime is immutable, and it can be used safely in a multi-threaded environment. In order to be fully immutable, key clases are declared as final. Abstract superclasses are provided should you need to define your own implementations.

The concrete implementations of the ReadWritable... interfaces are named the same as their immutable counterparts, but with a "Mutable" prefix. For example, MutableDateTime implements ReadWritableDateTime, making datetime editing easy. Note that it is possible to use the immutable DateTime for modifying datetimes, however each modification method returns a new instance of DateTime.

Interface usage

The interfaces in Joda-Time are not designed to operate in the same way as those in the Java Collections Framework (List/Map/Set etc). The Joda-Time interfaces represent a core subset of the functionality available via the actual classes. Thus, much of the work of an application will probably use methods on the class, not on the interface. Your application must determine whether it should define dates in terms of the interfaces, or in terms of the classes.

The interfaces provide simple methods to access an instance of the immutable class, which is implemented either via typecast or object creation. Thus, if you hold a reference to a ReadableInstant, and you call the method toDateTime(), the same instance will be returned (typecast) if it already was a DateTime.

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 an implementation of DateTimeField. Likewise, duration fields are calculated by specialized DurationField instances. If desired, users can write their own implementations to retrieve an unusual field from the millisecond value.

The datetime and duration fields that together represent a calendar system are grouped into a Chronology. The chronology represents all the information to convert from a millisecond value to human understandable fields in a specific calendar system. Chronologies are provided for ISO, Gregorian/Julian (GJ), Buddhist, Coptic and Ethiopic. More implementations are sought from the community.

The chronology and field classes are singletons. This design results in a low overhead on the date and time classes. The 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.

When reviewing the library for the first time, it is easy to mistake the number of classes with complexity. The library is in fact clearly divided between user packages and implementation packages in the javadoc. Most users will should not need to be concerned with the back-end implementation.

Partials

Partials are like instants, except they do not completely specify a point in time. The main interface is ReadablePartial.

The main implementations are:

• LocalTime - A class storing a local time without a date
• LocalDate - A class storing a local date without a time
• LocalDateTime - A class storing a local datetime
• Partial - A class storing any combination of datetime fields, such as dayOfMonth and dayOfWeek

All partial implementations represent a local time, in other words without a time zone. Thus, to convert a partial to an instant (which does contain a time zone) requires adding a zone.

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 via the builder classes.

Various chronologies are supported by subclasses including ISO and GregorianJulian.

It is important to emphasise that this class represents the time of midnight on any given day. Note that midnight is defined as 00:00, which is at the very start of a day.

This class does not represent a day, but the millisecond instant at midnight. If you need a class that represents the whole day, then an Interval or a LocalDate may be more suitable.

This class uses a Chronology internally.

DateTime is the most widely used implementation of ReadableInstant .

This design is extensible so, if you wish, you can extract a different field from the milliseconds.

A time zone is a system of rules to convert time from one geographic location to another.

Days is an immutable period that can only store days. It does not store years, months or hours for example.

This design is extensible so, if you wish, you can extract a different field from the millisecond duration.

Hours is an immutable period that can only store hours. It does not store years, months or minutes for example.

Instant is an implementation of ReadableInstant . As with all instants, it represents an exact point on the time-line, but limited to the precision of milliseconds.

LocalDateTime implements the ReadablePartial interface. To do this, certain methods focus on key fields Year, MonthOfYear, DayOfYear and MillisOfDay. However, all fields may in fact be queried.

Internally, LocalDateTime uses a single millisecond-based value to represent the local datetime.

Minutes is an immutable period that can only store minutes. It does not store years, months or hours for example.

Months is an immutable period that can only store months. It does not store years, days or hours for example.

This class uses a Chronology internally.

A time period is divided into a number of fields, such as hours and seconds. Which fields are supported is defined by the PeriodType class. The default is the standard period type, which supports years, months, weeks, days, hours, minutes, seconds and millis.

When this time period is added to an instant, the effect is of adding each field in turn. As a result, this takes into account daylight savings time. Adding a time period of 1 day to the day before daylight savings starts will only add 23 hours rather than 24 to ensure that the time remains the same. If this is not the behaviour you want, then see Duration .

The definition of a period also affects the equals method.

A time period is divided into a number of fields, such as hours and seconds. Which fields are supported is defined by the PeriodType class. The default is the standard period type, which supports years, months, weeks, days, hours, minutes, seconds and millis.

When this time period is added to an instant, the effect is of adding each field in turn. As a result, this takes into account daylight savings time. Adding a time period of 1 day to the day before daylight savings starts will only add 23 hours rather than 24 to ensure that the time remains the same. If this is not the behaviour you want, then see Duration .

The definition of a period also affects the equals method.

The implementation of this interface may be mutable or immutable.

A ReadablePartial supports a subset of those fields on the chronology. It cannot be compared to a ReadableInstant, as it does not fully specify an instant in time.

The implementation of this interface may be mutable or immutable.

Seconds is an immutable period that can only store seconds. It does not store years, months or hours for example.

NOTE: This class only supports the four fields listed above.

Weeks is an immutable period that can only store weeks. It does not store years, months or hours for example.

NOTE: This class only supports the three fields listed above.

Years is an immutable period that can only store years. It does not store years, days or hours for example.