|
15289
|
1 |
<!--
|
|
|
2 |
/*
|
|
|
3 |
* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
|
4 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
|
5 |
*
|
|
|
6 |
* This code is free software; you can redistribute it and/or modify it
|
|
|
7 |
* under the terms of the GNU General Public License version 2 only, as
|
|
|
8 |
* published by the Free Software Foundation. Oracle designates this
|
|
|
9 |
* particular file as subject to the "Classpath" exception as provided
|
|
|
10 |
* by Oracle in the LICENSE file that accompanied this code.
|
|
|
11 |
*
|
|
|
12 |
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
|
13 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
|
14 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
|
15 |
* version 2 for more details (a copy is included in the LICENSE file that
|
|
|
16 |
* accompanied this code).
|
|
|
17 |
*
|
|
|
18 |
* You should have received a copy of the GNU General Public License version
|
|
|
19 |
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
|
20 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
|
21 |
*
|
|
|
22 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
|
23 |
* or visit www.oracle.com if you need additional information or have any
|
|
|
24 |
* questions.
|
|
|
25 |
*/
|
|
|
26 |
|
|
|
27 |
/*
|
|
|
28 |
* This file is available under and governed by the GNU General Public
|
|
|
29 |
* License version 2 only, as published by the Free Software Foundation.
|
|
|
30 |
* However, the following notice accompanied the original version of this
|
|
|
31 |
* file:
|
|
|
32 |
*
|
|
|
33 |
* Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos
|
|
|
34 |
*
|
|
|
35 |
* All rights reserved.
|
|
|
36 |
*
|
|
|
37 |
* Redistribution and use in source and binary forms, with or without
|
|
|
38 |
* modification, are permitted provided that the following conditions are met:
|
|
|
39 |
*
|
|
|
40 |
* * Redistributions of source code must retain the above copyright notice,
|
|
|
41 |
* this list of conditions and the following disclaimer.
|
|
|
42 |
*
|
|
|
43 |
* * Redistributions in binary form must reproduce the above copyright notice,
|
|
|
44 |
* this list of conditions and the following disclaimer in the documentation
|
|
|
45 |
* and/or other materials provided with the distribution.
|
|
|
46 |
*
|
|
|
47 |
* * Neither the name of JSR-310 nor the names of its contributors
|
|
|
48 |
* may be used to endorse or promote products derived from this software
|
|
|
49 |
* without specific prior written permission.
|
|
|
50 |
*
|
|
|
51 |
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
|
52 |
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
|
53 |
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
|
54 |
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
|
|
|
55 |
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
|
56 |
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
|
57 |
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
|
58 |
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
|
59 |
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
|
60 |
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
|
61 |
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
62 |
*/
|
|
|
63 |
-->
|
|
|
64 |
<body>
|
|
|
65 |
<p>
|
|
|
66 |
A new Date and Time API for Java.
|
|
|
67 |
The design includes a relatively large number of classes and methods,
|
|
|
68 |
however each follows a common design language, especially in method prefixes.
|
|
|
69 |
Once the prefixes are understood, the API is relatively simple to comprehend.
|
|
|
70 |
</p>
|
|
|
71 |
<p>
|
|
|
72 |
The Java Time API is composed of several packages, each with a primary function:
|
|
|
73 |
</p>
|
|
|
74 |
<p>
|
|
|
75 |
{@link java.time} contains the main API based on the ISO-8601 standard.
|
|
|
76 |
The classes defined here represent the principal date-time concepts,
|
|
|
77 |
including instants, durations, dates, times, time-zones and periods.
|
|
|
78 |
They are based on the ISO calendar system, which is the <i>de facto</i> world
|
|
|
79 |
calendar following the proleptic Gregorian rules.
|
|
|
80 |
All the classes are immutable and thread-safe.
|
|
|
81 |
</p>
|
|
|
82 |
<p>
|
|
|
83 |
{@link java.time.temporal} contains the API for accessing the fields and units
|
|
|
84 |
of date-time. Units are measurable, such as years, months and hours.
|
|
|
85 |
For example, the expression "2 hours later" uses the hours unit.
|
|
|
86 |
By contrast, fields are mini-calculations, defining a value.
|
|
|
87 |
For example, month-of-year, day-of-week and hour-of-day are all fields.
|
|
|
88 |
The set of supported units and fields can be extended by applications if desired.
|
|
|
89 |
</p>
|
|
|
90 |
<p>
|
|
|
91 |
{@link java.time.format} contains the API to print and parse fields into date-time
|
|
|
92 |
objects and to customize parsing and printing.
|
|
|
93 |
Formatters can be created in a variety of ways, including constants, patterns,
|
|
|
94 |
localized styles and a builder.
|
|
|
95 |
Formatters are immutable and thread-safe.
|
|
|
96 |
</p>
|
|
|
97 |
<p>
|
|
|
98 |
{@link java.time.zone} contains the API to handle time-zones.
|
|
|
99 |
Detailed information is made available about the rules of each time-zone.
|
|
|
100 |
</p>
|
|
|
101 |
<p>
|
|
15658
|
102 |
{@link java.time.chrono} contains the basic part of the calendar neutral API
|
|
|
103 |
and alternate calendar systems.
|
|
15289
|
104 |
This is intended for use by applications that need to use localized calendars.
|
|
|
105 |
Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars.
|
|
|
106 |
</p>
|
|
|
107 |
<h3>Design notes</h3>
|
|
|
108 |
<p>
|
|
|
109 |
Where possible, the API avoids the use of null.
|
|
|
110 |
All methods define whether they accept or return null in the Javadoc.
|
|
|
111 |
As a general rule, methods do not accept or return null.
|
|
|
112 |
A key exception is any method that takes an object and returns a boolean, for the purpose
|
|
|
113 |
of checking or validating, will generally return false for null.
|
|
|
114 |
</p>
|
|
|
115 |
<p>
|
|
|
116 |
The API is designed to be type-safe where reasonable in the main high-level API.
|
|
|
117 |
Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants
|
|
|
118 |
for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications.
|
|
|
119 |
Further classes handle other combinations - year, year-month and month-day in a type-safe manner.
|
|
|
120 |
</p>
|
|
|
121 |
<p>
|
|
|
122 |
In a language like Java, the use of many different types tends to cause API bloat.
|
|
|
123 |
This is handled here through the use of common method naming patterns throughout the API.
|
|
|
124 |
The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'.
|
|
|
125 |
See {@link java.time.LocalDate} for an example of each of these methods.
|
|
|
126 |
</p>
|
|
|
127 |
<p>
|
|
|
128 |
Following type-safety to its logical conclusion would result in more classes, especially for time -
|
|
|
129 |
hour-minute, hour-minute-second and hour-minute-second-nanosecond.
|
|
|
130 |
While logically pure, this was not possible in practice, as the additional classes would have
|
|
|
131 |
excessively complicated the API. Notably, there would be additional combinations at the offset
|
|
|
132 |
and date-time levels, such as offset-date-hour-minute.
|
|
|
133 |
To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time.
|
|
15658
|
134 |
By contrast, some additional classes were used for dates, such as {@link java.time.YearMonth}.
|
|
15289
|
135 |
This proved necessary, as the API for year-month is significantly different to that for a date, whereas
|
|
|
136 |
an absence of nanoseconds in a time can be approximated by returning zero.
|
|
|
137 |
</p>
|
|
|
138 |
<p>
|
|
|
139 |
Similarly, full type-safety might argue for a separate class for each field in date-time,
|
|
|
140 |
such as a class for HourOfDay and another for DayOfMonth.
|
|
|
141 |
This approach was tried, but was excessively complicated in the Java language, lacking usability.
|
|
|
142 |
A similar problem occurs with periods.
|
|
|
143 |
There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes.
|
|
|
144 |
However, this yields a lot of classes and a problem of type conversion.
|
|
|
145 |
As such, general access to fields and units is not wrapped in a class.
|
|
|
146 |
</p>
|
|
|
147 |
<p>
|
|
|
148 |
Multiple calendar systems is an awkward addition to the design challenges.
|
|
|
149 |
The first principal is that most users want the standard ISO calendar system.
|
|
|
150 |
As such, the main classes are ISO-only. The second principal is that most of those that want a
|
|
|
151 |
non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
|
|
|
152 |
As such, date and time objects should be held as ISO objects in the data model and persistent
|
|
|
153 |
storage, only being converted to and from a local calendar for display.
|
|
|
154 |
The calendar system would be stored separately in the user preferences.
|
|
|
155 |
</p>
|
|
|
156 |
<p>
|
|
|
157 |
There are, however, some limited use cases where users believe they need to store and use
|
|
|
158 |
dates in arbitrary calendar systems throughout the application.
|
|
15658
|
159 |
This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read
|
|
15289
|
160 |
all the associated warnings in the Javadoc of that interface before using it.
|
|
|
161 |
In summary, applications that require general interoperation between multiple calendar systems
|
|
|
162 |
typically need to be written in a very different way to those only using the ISO calendar,
|
|
|
163 |
thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
|
|
|
164 |
</p>
|
|
|
165 |
<p>
|
|
|
166 |
Throughout all of this, a key goal was to allow date-time fields and units to be defined by applications.
|
|
|
167 |
This has been achieved having tried many different designs.
|
|
|
168 |
</p>
|
|
|
169 |
</body>
|