|PREV NEXT||FRAMES NO FRAMES|
This Javadoc is for an alpha release of the ThreeTen project.
|java.util||Amended OpenJDK classes that integrate JSR-310 with the existing date and time APIs.|
|javax.time||Provides classes to manage the continuous time-scale including a wrapper for the system clock.|
|javax.time.calendar||Provides classes to manage the human time-scale including date, time, date-time and time-zone representations.|
|javax.time.calendar.format||Provides classes to print and parse dates and times.|
|javax.time.calendar.zone||Provides classes to implement time-zones and their rules.|
|javax.time.i18n||Provides classes representing dates and times in alternate calendar systems.|
This Javadoc is for an alpha release of the ThreeTen project. The JSR-310 specification will be derived over time from the ThreeTen project. Since the ThreeTen project is incomplete, the JSR-310 specification is also incomplete.
ThreeTen defines a new Date and Time API for Java. This is a relatively large API, but each class follows a common design language, especially in method prefixes. Once the prefixes are understood, the API is relatively simple to comprehend.
The key task is to choose the correct class for your needs. There is a high-level and a low-level API - this guide will focus on the high-level. Simply follow this guide to choose the best class:
Instant. This is useful for logging and persistence of a point in time and has in the past been associated with storing the result from
ZonedDateTime. This is useful if you want to perform accurate calculations of dates and times taking into account the time-zone, such as 'Europe/Paris'.
OffsetDate. This stores a date like '2010-12-03+01:00'.
OffsetTime. This stores a date like '11:30+01:00'.
OffsetDateTime. This stores a date like '2010-12-03T11:30+01:00'.
LocalDate. This stores a date like '2010-12-03' and could be used to store a birthday.
LocalTime. This stores a date like '11:30' and could be used to store an opening or closing time.
LocalDateTime. This stores a date like '2010-12-03T11:30'.
YearMonth. This stores a year and month, such as '2010-12' and could be used for a credit card expiry.
MonthDay. This stores a month and day-of-month, such as '--12-03' and could be used to store an annual event like a birthday without storing the year.
Year. This stores a single year in isolation, such as '2010'.
MonthOfYear. This stores a single month-of-year in isolation, such as 'DECEMBER'.
DayOfWeek. This stores a single day-of-week in isolation, such as 'TUESDAY'.
All these classes are always valid, immutable and thread-safe.
They are all based on the ISO calendar system with a fixed 86400 second day.
This is the de facto world calendar following the proleptic Gregorian rules.
i18n package contains other calendar systems.
The time-zone support is extensive. Information may be provided by multiple vendors, each of which may produce multiple versions of their data. The information may be updated while the system is running. Any update will not invalidate objects that have already been created.
Support is provided for printing and parsing all manner of dates and times. This support can be accessed via constants, a pattern or a builder.
The set of supported date-time fields can be extended by applications using the low-level API. This allows a new field, such as hour-of-fortnight to be created if desired.
Where the 86400 second day definition is insufficient, classes are provided to cover the UTC (with leap-seconds) and TAI time-scales. It is expected that most applications will be content with ignoring leap-seconds.
Beyond dates and times, the API also allows the storage of period and durations of time.
A duration is a simple measure of time along the time-line in nanoseconds.
A period expressed an amount of time in units meaningful to humans, such as years or hours.
Duration class is used to store a duration, while the
Period class is the key class for storing a period.
The API has two layers - the high-level API for use by applications, and the low-level API for use by frameworks. This separation proved to be the best way to handle complexity. Where possible, applications should stick with using the high-level API.
The high-level API avoids the use of null.
NullPointerException on input and do not return null.
However, check methods starting with 'is' will normally tolerate null input.
The low-level API makes frequent use of null return values as an indication of not found, or similar meaning.
The API is designed to be type-safe where reasonable in the main high-level API. Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications. Further classes handle other combinations - year, year-month and month-day in a type-safe manner.
In a language like Java, the use of many different types tends to cause API bloat.
This is handled here through the use of common method naming patterns throughout the API.
The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'.
LocalDate for an example of each of these methods.
Following type-safety to its logical conclusion would result in more classes, especially for time -
hour-minute, hour-minute-second and hour-minute-second-nanosecond.
While logically pure, this was not possible in practice, as the additional classes would have
excessively complicated the API. Notably, there would be additional combinations at the offset
and date-time levels, such as offset-date-hour-minute.
To avoid this explosion of types,
LocalTime is used for all precisions of time.
By contrast, some additional classes were used for dates, such as
This proved necessary, as the API for year-month is significantly different to that for a date.
Similarly, type-safety would require a separate class for each field in date-time.
This would have created a class for hour-of-day, minute-of-hour, day-of-year, and many more.
This approach was tried, but was excessively complicated in the Java language, lacking usability.
Therefore two classes,
the full range of fields without dedicated types.
A similar problem occurs with periods.
There is a case for a separate class for each period unit, such as a type for years and a type
for minutes. However, this yields a lot of classes and a problem of type conversion.
As such, a standard set of fields was chosen for
PeriodFields handling the more unusual cases.
Multiple calendar systems is an awkward addition to the design challenges. The approach taken is to keep calendar systems out of the main classes to limit complexity. This is based on the principal that most users want the standard ISO calendar system. In addition, those wanting a historically accurate Gregorian-Julian calendar system need to think carefully about the cutover date between the two systems, which varied by location.
A further design limitation was the desire to allow date-time fields to be defined by applications
that would be integrated into those defined by the core.
DateTimeField approach achieves this, but at the cost of some complexity.
All API methods should document whether they accept null or not.
If a method does not accept null, and null is passed in, then a
NullPointerException will be thrown.
NullPointerException is not explicitly documented in each method.
|PREV NEXT||FRAMES NO FRAMES|