77 * to the {@code java.time.temporal} package. |
77 * to the {@code java.time.temporal} package. |
78 * Each class includes support for printing and parsing all manner of dates and times. |
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. |
79 * Refer to the {@code java.time.format} package for customization options. |
80 * </p> |
80 * </p> |
81 * <p> |
81 * <p> |
82 * The {@code java.time.temporal} package also contains the calendar neutral API |
82 * The {@code java.time.chrono} package contains the calendar neutral API |
83 * {@link java.time.temporal.ChronoLocalDate ChronoLocalDate}, |
83 * {@link java.time.chrono.ChronoLocalDate ChronoLocalDate}, |
84 * {@link java.time.temporal.ChronoLocalDateTime ChronoLocalDateTime}, |
84 * {@link java.time.chrono.ChronoLocalDateTime ChronoLocalDateTime}, |
85 * {@link java.time.temporal.ChronoZonedDateTime ChronoZonedDateTime} and |
85 * {@link java.time.chrono.ChronoZonedDateTime ChronoZonedDateTime} and |
86 * {@link java.time.temporal.Era Era}. |
86 * {@link java.time.chrono.Era Era}. |
87 * This is intended for use by applications that need to use localized calendars. |
87 * This is intended for use by applications that need to use localized calendars. |
88 * It is recommended that applications use the ISO-8601 dates and time classes from |
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. |
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. |
90 * The calendar neutral API should be reserved for interactions with users. |
91 * </p> |
91 * </p> |
92 * |
92 * |
93 * <h3>Dates and Times</h3> |
93 * <h3>Dates and Times</h3> |
133 * <p> |
133 * <p> |
134 * {@link java.time.DayOfWeek} stores a day-of-week on its own. |
134 * {@link java.time.DayOfWeek} stores a day-of-week on its own. |
135 * This stores a single day-of-week in isolation, such as 'TUESDAY'. |
135 * This stores a single day-of-week in isolation, such as 'TUESDAY'. |
136 * </p> |
136 * </p> |
137 * <p> |
137 * <p> |
138 * {@link java.time.temporal.Year} stores a year on its own. |
138 * {@link java.time.Year} stores a year on its own. |
139 * This stores a single year in isolation, such as '2010'. |
139 * This stores a single year in isolation, such as '2010'. |
140 * </p> |
140 * </p> |
141 * <p> |
141 * <p> |
142 * {@link java.time.temporal.YearMonth} stores a year and month without a day or time. |
142 * {@link java.time.YearMonth} stores a year and month without a day or time. |
143 * This stores a year and month, such as '2010-12' and could be used for a credit card expiry. |
143 * This stores a year and month, such as '2010-12' and could be used for a credit card expiry. |
144 * </p> |
144 * </p> |
145 * <p> |
145 * <p> |
146 * {@link java.time.temporal.MonthDay} stores a month and day without a year or time. |
146 * {@link java.time.MonthDay} stores a month and day without a year or time. |
147 * This stores a month and day-of-month, such as '--12-03' and |
147 * This stores a month and day-of-month, such as '--12-03' and |
148 * could be used to store an annual event like a birthday without storing the year. |
148 * could be used to store an annual event like a birthday without storing the year. |
149 * </p> |
149 * </p> |
150 * <p> |
150 * <p> |
151 * {@link java.time.temporal.OffsetTime} stores a time and offset from UTC without a date. |
151 * {@link java.time.OffsetTime} stores a time and offset from UTC without a date. |
152 * This stores a date like '11:30+01:00'. |
152 * This stores a date like '11:30+01:00'. |
153 * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'. |
153 * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'. |
154 * </p> |
154 * </p> |
155 * <p> |
155 * <p> |
156 * {@link java.time.temporal.OffsetDate} stores a date and offset from UTC without a time. |
156 * {@link java.time.OffsetDateTime} stores a date and time and offset from UTC. |
157 * This stores a time like '2010-12-03+01:00'. |
|
158 * </p> |
|
159 * <p> |
|
160 * {@link java.time.temporal.OffsetDateTime} stores a date and time and offset from UTC. |
|
161 * This stores a date-time like '2010-12-03T11:30+01:00'. |
157 * This stores a date-time like '2010-12-03T11:30+01:00'. |
162 * This is sometimes found in XML messages and other forms of persistence, |
158 * This is sometimes found in XML messages and other forms of persistence, |
163 * but contains less information than a full time-zone. |
159 * but contains less information than a full time-zone. |
164 * </p> |
160 * </p> |
165 * |
161 * |
204 * considerable complexity to a calculation. |
200 * considerable complexity to a calculation. |
205 * Many applications can be written only using {@code LocalDate}, {@code LocalTime} and {@code Instant}, |
201 * Many applications can be written only using {@code LocalDate}, {@code LocalTime} and {@code Instant}, |
206 * with the time-zone added at the user interface (UI) layer. |
202 * with the time-zone added at the user interface (UI) layer. |
207 * </p> |
203 * </p> |
208 * <p> |
204 * <p> |
209 * The offset-based date-time types, {@code OffsetDate}, {@code OffsetTime} and {@code OffsetDateTime}, |
205 * The offset-based date-time types {@code OffsetTime} and {@code OffsetDateTime}, |
210 * are intended primarily for use with network protocols and database access. |
206 * are intended primarily for use with network protocols and database access. |
211 * For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but |
207 * For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but |
212 * they can store an offset like '+02:00'. |
208 * they can store an offset like '+02:00'. |
213 * </p> |
209 * </p> |
214 * <p> |
210 * <p> |
259 * The calendar system would be stored separately in the user preferences. |
255 * The calendar system would be stored separately in the user preferences. |
260 * </p> |
256 * </p> |
261 * <p> |
257 * <p> |
262 * There are, however, some limited use cases where users believe they need to store and use |
258 * There are, however, some limited use cases where users believe they need to store and use |
263 * dates in arbitrary calendar systems throughout the application. |
259 * dates in arbitrary calendar systems throughout the application. |
264 * This is supported by {@link java.time.temporal.ChronoLocalDate}, however it is vital to read |
260 * This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read |
265 * all the associated warnings in the Javadoc of that interface before using it. |
261 * all the associated warnings in the Javadoc of that interface before using it. |
266 * In summary, applications that require general interoperation between multiple calendar systems |
262 * In summary, applications that require general interoperation between multiple calendar systems |
267 * typically need to be written in a very different way to those only using the ISO calendar, |
263 * typically need to be written in a very different way to those only using the ISO calendar, |
268 * thus most applications should just use ISO and avoid {@code ChronoLocalDate}. |
264 * thus most applications should just use ISO and avoid {@code ChronoLocalDate}. |
269 * </p> |
265 * </p> |