org.joda.time |
org.joda.time package
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
For consistency, the API of each partial class is similar to that of an instant class.
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.
|
Java Source File Name | Type | Comment |
Chronology.java | Class | Chronology provides access to the individual date time fields for a
chronological calendar system.
Various chronologies are supported by subclasses including ISO
and GregorianJulian. |
ClassLoadTest.java | Class | This class displays what the ClassLoader is up to. |
DateMidnight.java | Class | DateMidnight defines a date where the time component is fixed at midnight.
The class uses a time zone, thus midnight is local unless a UTC time zone is used.
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.java | Class | DateTime is the standard implementation of an unmodifiable datetime class.
DateTime is the most widely used implementation of
ReadableInstant . |
DateTimeComparator.java | Class | DateTimeComparator provides comparators to compare one date with another. |
DateTimeConstants.java | Class | DateTimeConstants is a non-instantiable class of constants used in
the date time system. |
DateTimeField.java | Class | Defines the calculation engine for date and time fields.
The interface defines a set of methods that manipulate a millisecond datetime
with regards to a single field, such as monthOfYear or secondOfMinute.
This design is extensible so, if you wish, you can extract a different field from
the milliseconds. |
DateTimeFieldType.java | Class | Identifies a field, such as year or minuteOfHour, in a chronology-neutral way. |
DateTimeUtils.java | Class | DateTimeUtils provide public utility methods for the datetime library. |
DateTimeZone.java | Class | DateTimeZone represents a time zone.
A time zone is a system of rules to convert time from one geographic
location to another. |
Days.java | Class | An immutable time period representing a number of days.
Days is an immutable period that can only store days.
It does not store years, months or hours for example. |
Duration.java | Class | An immutable duration specifying a length of time in milliseconds. |
DurationField.java | Class | Defines the calculation engine for duration fields.
The interface defines a set of methods that manipulate a millisecond duration
with regards to a single field, such as months or seconds.
This design is extensible so, if you wish, you can extract a different field from
the millisecond duration. |
DurationFieldType.java | Class | Identifies a duration field, such as years or minutes, in a chronology-neutral way. |
Hours.java | Class | An immutable time period representing a number of hours.
Hours is an immutable period that can only store hours.
It does not store years, months or minutes for example. |
IllegalFieldValueException.java | Class | Exception thrown when attempting to set a field outside its supported range. |
Instant.java | Class | Instant is the standard implementation of a fully immutable instant in time.
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. |
Interval.java | Class | Interval is the standard implementation of an immutable time interval. |
JodaTimePermission.java | Class | JodaTimePermission is used for securing global method calls in the Joda-Time
library. |
LocalDate.java | Class | LocalDate is an immutable datetime class representing a date
without a time zone. |
LocalDateTime.java | Class | LocalDateTime is an unmodifiable datetime class representing a
datetime without a time zone.
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. |
LocalTime.java | Class | LocalTime is an immutable time class representing a time
without a time zone. |
Minutes.java | Class | An immutable time period representing a number of minutes.
Minutes is an immutable period that can only store minutes.
It does not store years, months or hours for example. |
MockNullZoneChronology.java | Class | Mock class for unit testing. |
MockPartial.java | Class | A basic mock testing class for a PartialInstant that doesn't extend AbstractPartialInstant. |
MockZone.java | Class | |
Months.java | Class | An immutable time period representing a number of months.
Months is an immutable period that can only store months.
It does not store years, days or hours for example. |
MutableDateTime.java | Class | MutableDateTime is the standard implementation of a modifiable datetime class.
It holds the datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z.
This class uses a Chronology internally. |
MutableInterval.java | Class | MutableInterval is the standard implementation of a mutable time interval. |
MutablePeriod.java | Class | Standard mutable time period implementation.
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. |
Partial.java | Class | Partial is an immutable partial datetime supporting any set of datetime fields. |
Period.java | Class | An immutable time period specifying a set of duration field values.
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. |
PeriodType.java | Class | Controls a period implementation by specifying which duration fields are to be used. |
ReadableDateTime.java | Interface | Defines an instant in time that can be queried using datetime fields. |
ReadableDuration.java | Interface | Defines an exact duration of time in milliseconds.
The implementation of this interface may be mutable or immutable. |
ReadableInstant.java | Interface | Defines an instant in the datetime continuum. |
ReadableInterval.java | Interface | Readable interface for an interval of time between two instants. |
ReadablePartial.java | Interface | Defines a partial time that does not support every datetime field, and is
thus a local time.
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. |
ReadablePeriod.java | Interface | Defines a time period specified in terms of individual duration fields
such as years and days.
The implementation of this interface may be mutable or immutable. |
ReadWritableDateTime.java | Interface | Defines an instant in time that can be queried and modified using datetime fields. |
ReadWritableInstant.java | Interface | Defines an instant in the datetime continuum that can be queried and modified. |
ReadWritableInterval.java | Interface | Writable interface for an interval. |
ReadWritablePeriod.java | Interface | Defines a duration of time that can be queried and modified using datetime fields. |
Seconds.java | Class | An immutable time period representing a number of seconds.
Seconds is an immutable period that can only store seconds.
It does not store years, months or hours for example. |
TempTest.java | Class | Test. |
TestAbstractPartial.java | Class | This class is a Junit unit test for YearMonthDay. |
TestAll.java | Class | Entry point for all tests in this package. |
TestAllPackages.java | Class | Entry point for all tests in Joda Time. |
TestBasePartial.java | Class | This class is a Junit unit test for YearMonthDay. |
TestBaseSingleFieldPeriod.java | Class | This class is a Junit unit test for BaseSingleFieldPeriod. |
TestChronology.java | Class | This class is a Junit unit test for Chronology. |
TestDateMidnight_Basics.java | Class | This class is a Junit unit test for DateMidnight. |
TestDateMidnight_Constructors.java | Class | This class is a Junit unit test for DateMidnight. |
TestDateMidnight_Properties.java | Class | This class is a Junit unit test for DateTime. |
TestDateTimeComparator.java | Class | This class is a Junit unit test for the
org.joda.time.DateTimeComparator class. |
TestDateTimeConstants.java | Class | Test case. |
TestDateTimeFieldType.java | Class | This class is a Junit unit test for Chronology. |
TestDateTimeUtils.java | Class | This class is a Junit unit test for Instant. |
TestDateTimeZone.java | Class | This class is a JUnit test for DateTimeZone. |
TestDateTimeZoneCutover.java | Class | This class is a JUnit test for DateTimeZone. |
TestDateTime_Basics.java | Class | This class is a Junit unit test for DateTime. |
TestDateTime_Constructors.java | Class | This class is a Junit unit test for DateTime. |
TestDateTime_Properties.java | Class | This class is a Junit unit test for DateTime. |
TestDays.java | Class | This class is a Junit unit test for Days. |
TestDurationField.java | Class | This class is a Junit unit test for DurationField. |
TestDurationFieldType.java | Class | This class is a Junit unit test for DurationFieldType. |
TestDuration_Basics.java | Class | This class is a Junit unit test for Duration. |
TestDuration_Constructors.java | Class | This class is a JUnit test for Duration. |
TestHours.java | Class | This class is a Junit unit test for Hours. |
TestIllegalFieldValueException.java | Class | Tests IllegalFieldValueException by triggering it from other methods. |
TestInstant_Basics.java | Class | This class is a Junit unit test for Instant. |
TestInstant_Constructors.java | Class | This class is a Junit unit test for Instant. |
TestInterval_Basics.java | Class | This class is a Junit unit test for Instant. |
TestInterval_Constructors.java | Class | This class is a JUnit test for Interval. |
TestLocalDateTime_Basics.java | Class | This class is a Junit unit test for LocalDate. |
TestLocalDateTime_Constructors.java | Class | This class is a Junit unit test for LocalDateTime. |
TestLocalDateTime_Properties.java | Class | This class is a Junit unit test for LocalDateTime. |
TestLocalDate_Basics.java | Class | This class is a Junit unit test for LocalDate. |
TestLocalDate_Constructors.java | Class | This class is a Junit unit test for LocalDate. |
TestLocalDate_Properties.java | Class | This class is a Junit unit test for YearMonthDay. |
TestLocalTime_Basics.java | Class | This class is a Junit unit test for LocalTime. |
TestLocalTime_Constructors.java | Class | This class is a Junit unit test for LocalTime. |
TestLocalTime_Properties.java | Class | This class is a Junit unit test for TimeOfDay. |
TestMinutes.java | Class | This class is a Junit unit test for Minutes. |
TestMonths.java | Class | This class is a Junit unit test for Months. |
TestMutableDateTime_Adds.java | Class | This class is a JUnit test for MutableDateTime. |
TestMutableDateTime_Basics.java | Class | This class is a JUnit test for MutableDateTime. |
TestMutableDateTime_Constructors.java | Class | This class is a Junit unit test for MutableDateTime. |
TestMutableDateTime_Properties.java | Class | This class is a Junit unit test for DateTime. |
TestMutableDateTime_Sets.java | Class | This class is a JUnit test for MutableDateTime. |
TestMutableInterval_Basics.java | Class | This class is a Junit unit test for Instant. |
TestMutableInterval_Constructors.java | Class | This class is a JUnit test for Interval. |
TestMutableInterval_Updates.java | Class | This class is a Junit unit test for Instant. |
TestMutablePeriod_Basics.java | Class | This class is a Junit unit test for MutableDuration. |
TestMutablePeriod_Constructors.java | Class | This class is a JUnit test for MutableDuration. |
TestMutablePeriod_Updates.java | Class | This class is a JUnit test for MutableDuration. |
TestParseISO.java | Class | |
TestPartial_Basics.java | Class | This class is a Junit unit test for Partial. |
TestPartial_Constructors.java | Class | This class is a Junit unit test for Partial. |
TestPartial_Match.java | Class | This class is a Junit unit test for Partial. |
TestPartial_Properties.java | Class | This class is a Junit unit test for Partial. |
TestPeriodType.java | Class | This class is a JUnit test for PeriodType. |
TestPeriod_Basics.java | Class | This class is a Junit unit test for Duration. |
TestPeriod_Constructors.java | Class | This class is a JUnit test for Duration. |
TestSeconds.java | Class | This class is a Junit unit test for Seconds. |
TestSerialization.java | Class | This class is a Junit unit test for serialization. |
TestTimeOfDay_Basics.java | Class | This class is a Junit unit test for TimeOfDay. |
TestTimeOfDay_Constructors.java | Class | This class is a Junit unit test for TimeOfDay. |
TestTimeOfDay_Properties.java | Class | This class is a Junit unit test for TimeOfDay. |
TestWeeks.java | Class | This class is a Junit unit test for Weeks. |
TestYearMonthDay_Basics.java | Class | This class is a Junit unit test for YearMonthDay. |
TestYearMonthDay_Constructors.java | Class | This class is a Junit unit test for YearMonthDay. |
TestYearMonthDay_Properties.java | Class | This class is a Junit unit test for YearMonthDay. |
TestYears.java | Class | This class is a Junit unit test for Years. |
TimeOfDay.java | Class | TimeOfDay is an immutable partial supporting the hour, minute, second
and millisecond fields.
NOTE: This class only supports the four fields listed above. |
Weeks.java | Class | An immutable time period representing a number of weeks.
Weeks is an immutable period that can only store weeks.
It does not store years, months or hours for example. |
YearMonthDay.java | Class | YearMonthDay is an immutable partial supporting the year, monthOfYear
and dayOfMonth fields.
NOTE: This class only supports the three fields listed above. |
Years.java | Class | An immutable time period representing a number of years.
Years is an immutable period that can only store years.
It does not store years, days or hours for example. |