1 /*
2 * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
73 * </p>
74 * <p>
75 * Each date time instance is composed of fields that are conveniently
76 * made available by the APIs. For lower level access to the fields refer
77 * to the {@code java.time.temporal} package.
78 * Each class includes support for printing and parsing all manner of dates and times.
79 * Refer to the {@code java.time.format} package for customization options.
80 * </p>
81 * <p>
82 * The {@code java.time.chrono} package contains the calendar neutral API
83 * {@link java.time.chrono.ChronoLocalDate ChronoLocalDate},
84 * {@link java.time.chrono.ChronoLocalDateTime ChronoLocalDateTime},
85 * {@link java.time.chrono.ChronoZonedDateTime ChronoZonedDateTime} and
86 * {@link java.time.chrono.Era Era}.
87 * This is intended for use by applications that need to use localized calendars.
88 * It is recommended that applications use the ISO-8601 date and time classes from
89 * this package across system boundaries, such as to the database or across the network.
90 * The calendar neutral API should be reserved for interactions with users.
91 * </p>
92 *
93 * <h3>Dates and Times</h3>
94 * <p>
95 * {@link java.time.Instant} is essentially a numeric timestamp.
96 * The current Instant can be retrieved from a {@link java.time.Clock}.
97 * This is useful for logging and persistence of a point in time
98 * and has in the past been associated with storing the result
99 * from {@link java.lang.System#currentTimeMillis()}.
100 * </p>
101 * <p>
102 * {@link java.time.LocalDate} stores a date without a time.
103 * This stores a date like '2010-12-03' and could be used to store a birthday.
104 * </p>
105 * <p>
106 * {@link java.time.LocalTime} stores a time without a date.
107 * This stores a time like '11:30' and could be used to store an opening or closing time.
108 * </p>
109 * <p>
110 * {@link java.time.LocalDateTime} stores a date and time.
111 * This stores a date-time like '2010-12-03T11:30'.
112 * </p>
113 * <p>
114 * {@link java.time.ZonedDateTime} stores a date and time with a time-zone.
115 * This is useful if you want to perform accurate calculations of
116 * dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.
117 * Where possible, it is recommended to use a simpler class without a time-zone.
118 * The widespread use of time-zones tends to add considerable complexity to an application.
119 * </p>
120 *
121 * <h3>Duration and Period</h3>
122 * <p>
123 * Beyond dates and times, the API also allows the storage of periods and durations of time.
124 * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
125 * A {@link java.time.Period} expresses an amount of time in units meaningful
126 * to humans, such as years or days.
127 * </p>
128 *
129 * <h3>Additional value types</h3>
130 * <p>
131 * {@link java.time.Month} stores a month on its own.
132 * This stores a single month-of-year in isolation, such as 'DECEMBER'.
133 * </p>
134 * <p>
135 * {@link java.time.DayOfWeek} stores a day-of-week on its own.
136 * This stores a single day-of-week in isolation, such as 'TUESDAY'.
137 * </p>
138 * <p>
139 * {@link java.time.Year} stores a year on its own.
140 * This stores a single year in isolation, such as '2010'.
141 * </p>
142 * <p>
143 * {@link java.time.YearMonth} stores a year and month without a day or time.
144 * This stores a year and month, such as '2010-12' and could be used for a credit card expiry.
145 * </p>
146 * <p>
147 * {@link java.time.MonthDay} stores a month and day without a year or time.
148 * This stores a month and day-of-month, such as '--12-03' and
149 * could be used to store an annual event like a birthday without storing the year.
150 * </p>
151 * <p>
152 * {@link java.time.OffsetTime} stores a time and offset from UTC without a date.
153 * This stores a date like '11:30+01:00'.
154 * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'.
155 * </p>
156 * <p>
157 * {@link java.time.OffsetDateTime} stores a date and time and offset from UTC.
158 * This stores a date-time like '2010-12-03T11:30+01:00'.
159 * This is sometimes found in XML messages and other forms of persistence,
160 * but contains less information than a full time-zone.
161 * </p>
162 *
163 * <h3>Package specification</h3>
164 * <p>
165 * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
166 * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
167 * The Javadoc "@param" definition is used to summarise the null-behavior.
168 * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
169 * </p>
170 * <p>
171 * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
172 * or a {@link java.time.DateTimeException}.
173 * </p>
174 *
175 * <h3>Design notes (non normative)</h3>
176 * <p>
177 * The API has been designed to reject null early and to be clear about this behavior.
178 * A key exception is any method that takes an object and returns a boolean, for the purpose
179 * of checking or validating, will generally return false for null.
180 * </p>
181 * <p>
182 * The API is designed to be type-safe where reasonable in the main high-level API.
183 * Thus, there are separate classes for the distinct concepts of date, time and date-time,
184 * plus variants for offset and time-zone.
185 * This can seem like a lot of classes, but most applications can begin with just five date/time types.
186 * <ul>
187 * <li>{@link java.time.Instant} - a timestamp</li>
188 * <li>{@link java.time.LocalDate} - a date without a time, or any reference to an offset or time-zone</li>
189 * <li>{@link java.time.LocalTime} - a time without a date, or any reference to an offset or time-zone</li>
190 * <li>{@link java.time.LocalDateTime} - combines date and time, but still without any offset or time-zone</li>
191 * <li>{@link java.time.ZonedDateTime} - a "full" date-time with time-zone and resolved offset from UTC/Greenwich</li>
192 * </ul>
193 * <p>
194 * {@code Instant} is the closest equivalent class to {@code java.util.Date}.
195 * {@code ZonedDateTime} is the closest equivalent class to {@code java.util.GregorianCalendar}.
|
1 /*
2 * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
73 * </p>
74 * <p>
75 * Each date time instance is composed of fields that are conveniently
76 * made available by the APIs. For lower level access to the fields refer
77 * to the {@code java.time.temporal} package.
78 * Each class includes support for printing and parsing all manner of dates and times.
79 * Refer to the {@code java.time.format} package for customization options.
80 * </p>
81 * <p>
82 * The {@code java.time.chrono} package contains the calendar neutral API
83 * {@link java.time.chrono.ChronoLocalDate ChronoLocalDate},
84 * {@link java.time.chrono.ChronoLocalDateTime ChronoLocalDateTime},
85 * {@link java.time.chrono.ChronoZonedDateTime ChronoZonedDateTime} and
86 * {@link java.time.chrono.Era Era}.
87 * This is intended for use by applications that need to use localized calendars.
88 * It is recommended that applications use the ISO-8601 date and time classes from
89 * this package across system boundaries, such as to the database or across the network.
90 * The calendar neutral API should be reserved for interactions with users.
91 * </p>
92 *
93 * <h2>Dates and Times</h2>
94 * <p>
95 * {@link java.time.Instant} is essentially a numeric timestamp.
96 * The current Instant can be retrieved from a {@link java.time.Clock}.
97 * This is useful for logging and persistence of a point in time
98 * and has in the past been associated with storing the result
99 * from {@link java.lang.System#currentTimeMillis()}.
100 * </p>
101 * <p>
102 * {@link java.time.LocalDate} stores a date without a time.
103 * This stores a date like '2010-12-03' and could be used to store a birthday.
104 * </p>
105 * <p>
106 * {@link java.time.LocalTime} stores a time without a date.
107 * This stores a time like '11:30' and could be used to store an opening or closing time.
108 * </p>
109 * <p>
110 * {@link java.time.LocalDateTime} stores a date and time.
111 * This stores a date-time like '2010-12-03T11:30'.
112 * </p>
113 * <p>
114 * {@link java.time.ZonedDateTime} stores a date and time with a time-zone.
115 * This is useful if you want to perform accurate calculations of
116 * dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.
117 * Where possible, it is recommended to use a simpler class without a time-zone.
118 * The widespread use of time-zones tends to add considerable complexity to an application.
119 * </p>
120 *
121 * <h2>Duration and Period</h2>
122 * <p>
123 * Beyond dates and times, the API also allows the storage of periods and durations of time.
124 * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
125 * A {@link java.time.Period} expresses an amount of time in units meaningful
126 * to humans, such as years or days.
127 * </p>
128 *
129 * <h2>Additional value types</h2>
130 * <p>
131 * {@link java.time.Month} stores a month on its own.
132 * This stores a single month-of-year in isolation, such as 'DECEMBER'.
133 * </p>
134 * <p>
135 * {@link java.time.DayOfWeek} stores a day-of-week on its own.
136 * This stores a single day-of-week in isolation, such as 'TUESDAY'.
137 * </p>
138 * <p>
139 * {@link java.time.Year} stores a year on its own.
140 * This stores a single year in isolation, such as '2010'.
141 * </p>
142 * <p>
143 * {@link java.time.YearMonth} stores a year and month without a day or time.
144 * This stores a year and month, such as '2010-12' and could be used for a credit card expiry.
145 * </p>
146 * <p>
147 * {@link java.time.MonthDay} stores a month and day without a year or time.
148 * This stores a month and day-of-month, such as '--12-03' and
149 * could be used to store an annual event like a birthday without storing the year.
150 * </p>
151 * <p>
152 * {@link java.time.OffsetTime} stores a time and offset from UTC without a date.
153 * This stores a date like '11:30+01:00'.
154 * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'.
155 * </p>
156 * <p>
157 * {@link java.time.OffsetDateTime} stores a date and time and offset from UTC.
158 * This stores a date-time like '2010-12-03T11:30+01:00'.
159 * This is sometimes found in XML messages and other forms of persistence,
160 * but contains less information than a full time-zone.
161 * </p>
162 *
163 * <h2>Package specification</h2>
164 * <p>
165 * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
166 * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
167 * The Javadoc "@param" definition is used to summarise the null-behavior.
168 * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
169 * </p>
170 * <p>
171 * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
172 * or a {@link java.time.DateTimeException}.
173 * </p>
174 *
175 * <h2>Design notes (non normative)</h2>
176 * <p>
177 * The API has been designed to reject null early and to be clear about this behavior.
178 * A key exception is any method that takes an object and returns a boolean, for the purpose
179 * of checking or validating, will generally return false for null.
180 * </p>
181 * <p>
182 * The API is designed to be type-safe where reasonable in the main high-level API.
183 * Thus, there are separate classes for the distinct concepts of date, time and date-time,
184 * plus variants for offset and time-zone.
185 * This can seem like a lot of classes, but most applications can begin with just five date/time types.
186 * <ul>
187 * <li>{@link java.time.Instant} - a timestamp</li>
188 * <li>{@link java.time.LocalDate} - a date without a time, or any reference to an offset or time-zone</li>
189 * <li>{@link java.time.LocalTime} - a time without a date, or any reference to an offset or time-zone</li>
190 * <li>{@link java.time.LocalDateTime} - combines date and time, but still without any offset or time-zone</li>
191 * <li>{@link java.time.ZonedDateTime} - a "full" date-time with time-zone and resolved offset from UTC/Greenwich</li>
192 * </ul>
193 * <p>
194 * {@code Instant} is the closest equivalent class to {@code java.util.Date}.
195 * {@code ZonedDateTime} is the closest equivalent class to {@code java.util.GregorianCalendar}.
|