Provides support for dates, times, time zones, durations, intervals, and
partials. This package aims to fully replace the Java
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.
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.
Calendar, the design is
millisecond based with an epoch of 1970-01-01.
This should enable easy conversions.
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 ISO8601 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
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.
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.
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.
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
DurationField instances. If desired, users can write
their own implementations to retrieve an unusual field from the millisecond
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.
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 are like instants, except they do not completely specify a point in
time. The main interface is
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 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.
Interface Summary Interface Description DateTimeUtils.MillisProviderA millisecond provider, allowing control of the system clock. ReadableDateTimeDefines an instant in time that can be queried using datetime fields. ReadableDurationDefines an exact duration of time in milliseconds. ReadableInstantDefines an instant in the datetime continuum. ReadableIntervalReadable interface for an interval of time between two instants. ReadablePartialDefines a partial time that does not support every datetime field, and is thus a local time. ReadablePeriodDefines a time period specified in terms of individual duration fields such as years and days. ReadWritableDateTimeDefines an instant in time that can be queried and modified using datetime fields. ReadWritableInstantDefines an instant in the datetime continuum that can be queried and modified. ReadWritableIntervalWritable interface for an interval. ReadWritablePeriodDefines a duration of time that can be queried and modified using datetime fields.
Class Summary Class Description ChronologyChronology provides access to the individual date time fields for a chronological calendar system. DateMidnight Deprecated.The time of midnight does not exist in some time zones where the daylight saving time forward shift skips the midnight hour. DateMidnight.PropertyDateMidnight.Property binds a DateMidnight to a DateTimeField allowing powerful datetime functionality to be easily accessed. DateTimeDateTime is the standard implementation of an unmodifiable datetime class. DateTime.PropertyDateTime.Property binds a DateTime to a DateTimeField allowing powerful datetime functionality to be easily accessed. DateTimeComparatorDateTimeComparator provides comparators to compare one date with another. DateTimeConstantsDateTimeConstants is a non-instantiable class of constants used in the date time system. DateTimeFieldDefines the calculation engine for date and time fields. DateTimeFieldTypeIdentifies a field, such as year or minuteOfHour, in a chronology-neutral way. DateTimeUtilsDateTimeUtils provide public utility methods for the date-time library. DateTimeZoneDateTimeZone represents a time zone. DaysAn immutable time period representing a number of days. DurationAn immutable duration specifying a length of time in milliseconds. DurationFieldDefines the calculation engine for duration fields. DurationFieldTypeIdentifies a duration field, such as years or minutes, in a chronology-neutral way. HoursAn immutable time period representing a number of hours. InstantInstant is the standard implementation of a fully immutable instant in time. IntervalInterval is the standard implementation of an immutable time interval. JodaTimePermissionJodaTimePermission is used for securing global method calls in the Joda-Time library. LocalDateLocalDate is an immutable datetime class representing a date without a time zone. LocalDate.PropertyLocalDate.Property binds a LocalDate to a DateTimeField allowing powerful datetime functionality to be easily accessed. LocalDateTimeLocalDateTime is an unmodifiable datetime class representing a datetime without a time zone. LocalDateTime.PropertyLocalDateTime.Property binds a LocalDateTime to a DateTimeField allowing powerful datetime functionality to be easily accessed. LocalTimeLocalTime is an immutable time class representing a time without a time zone. LocalTime.PropertyLocalTime.Property binds a LocalTime to a DateTimeField allowing powerful datetime functionality to be easily accessed. MinutesAn immutable time period representing a number of minutes. MonthDayMonthDay is an immutable partial supporting the monthOfYear and dayOfMonth fields. MonthDay.PropertyThe property class for
MonthsAn immutable time period representing a number of months. MutableDateTimeMutableDateTime is the standard implementation of a modifiable datetime class. MutableDateTime.PropertyMutableDateTime.Property binds a MutableDateTime to a DateTimeField allowing powerful datetime functionality to be easily accessed. MutableIntervalMutableInterval is the standard implementation of a mutable time interval. MutablePeriodStandard mutable time period implementation. PartialPartial is an immutable partial datetime supporting any set of datetime fields. Partial.PropertyThe property class for
PeriodAn immutable time period specifying a set of duration field values. PeriodTypeControls a period implementation by specifying which duration fields are to be used. SecondsAn immutable time period representing a number of seconds. TimeOfDay Deprecated.Use LocalTime which has a much better internal implementation and has been available since 1.3 TimeOfDay.Property Deprecated.Use LocalTime which has a much better internal implementation WeeksAn immutable time period representing a number of weeks. YearMonthYearMonth is an immutable partial supporting the year and monthOfYear fields. YearMonth.PropertyThe property class for
YearMonthDay Deprecated.Use LocalDate which has a much better internal implementation and has been available since 1.3 YearMonthDay.Property Deprecated.Use LocalDate which has a much better internal implementation YearsAn immutable time period representing a number of years.
Exception Summary Exception Description IllegalFieldValueExceptionException thrown when attempting to set a field outside its supported range. IllegalInstantExceptionException thrown when attempting to create an instant or date-time that cannot exist.