1 /*
2 * Copyright (c) 1996, 2019, 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
23 * questions.
24 */
25
26 /*
27 * (C) Copyright Taligent, Inc. 1996-1998 - All Rights Reserved
28 * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved
29 *
30 * The original version of this source code and documentation is copyrighted
31 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
32 * materials are provided under terms of a License Agreement between Taligent
33 * and Sun. This technology is protected by multiple US and International
34 * patents. This notice and attribution to Taligent may not be removed.
35 * Taligent is a registered trademark of Taligent, Inc.
36 *
37 */
38
39 package java.util;
40
41 import java.io.IOException;
42 import java.io.ObjectInputStream;
43 import java.io.ObjectOutputStream;
44 import java.io.OptionalDataException;
45 import java.io.Serializable;
46 import java.security.AccessControlContext;
47 import java.security.AccessController;
48 import java.security.PermissionCollection;
49 import java.security.PrivilegedActionException;
50 import java.security.PrivilegedExceptionAction;
51 import java.security.ProtectionDomain;
52 import java.text.DateFormat;
53 import java.text.DateFormatSymbols;
54 import java.time.Instant;
55 import java.util.concurrent.ConcurrentHashMap;
56 import java.util.concurrent.ConcurrentMap;
57 import sun.util.BuddhistCalendar;
58 import sun.util.calendar.ZoneInfo;
59 import sun.util.locale.provider.CalendarDataUtility;
60 import sun.util.locale.provider.LocaleProviderAdapter;
61 import sun.util.locale.provider.TimeZoneNameUtility;
62 import sun.util.spi.CalendarProvider;
63
64 /**
65 * The <code>Calendar</code> class is an abstract class that provides methods
66 * for converting between a specific instant in time and a set of {@link
67 * #fields calendar fields} such as <code>YEAR</code>, <code>MONTH</code>,
68 * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, and so on, and for
69 * manipulating the calendar fields, such as getting the date of the next
70 * week. An instant in time can be represented by a millisecond value that is
71 * an offset from the <a id="Epoch"><em>Epoch</em></a>, January 1, 1970
72 * 00:00:00.000 GMT (Gregorian).
73 *
74 * <p>The class also provides additional fields and methods for
75 * implementing a concrete calendar system outside the package. Those
76 * fields and methods are defined as <code>protected</code>.
77 *
78 * <p>
79 * Like other locale-sensitive classes, <code>Calendar</code> provides a
80 * class method, <code>getInstance</code>, for getting a generally useful
81 * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
82 * returns a <code>Calendar</code> object whose
83 * calendar fields have been initialized with the current date and time:
84 * <blockquote>
85 * <pre>
86 * Calendar rightNow = Calendar.getInstance();
87 * </pre>
88 * </blockquote>
89 *
90 * <p>A <code>Calendar</code> object can produce all the calendar field values
91 * needed to implement the date-time formatting for a particular language and
92 * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
93 * <code>Calendar</code> defines the range of values returned by
94 * certain calendar fields, as well as their meaning. For example,
95 * the first month of the calendar system has value <code>MONTH ==
96 * JANUARY</code> for all calendars. Other values are defined by the
97 * concrete subclass, such as <code>ERA</code>. See individual field
98 * documentation and subclass documentation for details.
99 *
100 * <h2>Getting and Setting Calendar Field Values</h2>
101 *
102 * <p>The calendar field values can be set by calling the <code>set</code>
103 * methods. Any field values set in a <code>Calendar</code> will not be
104 * interpreted until it needs to calculate its time value (milliseconds from
105 * the Epoch) or values of the calendar fields. Calling the
106 * <code>get</code>, <code>getTimeInMillis</code>, <code>getTime</code>,
107 * <code>add</code> and <code>roll</code> involves such calculation.
108 *
109 * <h3>Leniency</h3>
110 *
111 * <p><code>Calendar</code> has two modes for interpreting the calendar
112 * fields, <em>lenient</em> and <em>non-lenient</em>. When a
113 * <code>Calendar</code> is in lenient mode, it accepts a wider range of
114 * calendar field values than it produces. When a <code>Calendar</code>
115 * recomputes calendar field values for return by <code>get()</code>, all of
116 * the calendar fields are normalized. For example, a lenient
117 * <code>GregorianCalendar</code> interprets <code>MONTH == JANUARY</code>,
118 * <code>DAY_OF_MONTH == 32</code> as February 1.
119
120 * <p>When a <code>Calendar</code> is in non-lenient mode, it throws an
121 * exception if there is any inconsistency in its calendar fields. For
122 * example, a <code>GregorianCalendar</code> always produces
123 * <code>DAY_OF_MONTH</code> values between 1 and the length of the month. A
124 * non-lenient <code>GregorianCalendar</code> throws an exception upon
125 * calculating its time or calendar field values if any out-of-range field
126 * value has been set.
127 *
128 * <h3><a id="first_week">First Week</a></h3>
129 *
130 * <code>Calendar</code> defines a locale-specific seven day week using two
131 * parameters: the first day of the week and the minimal days in first week
132 * (from 1 to 7). These numbers are taken from the locale resource data or the
133 * locale itself when a {@code Calendar} is constructed. If the designated
134 * locale contains "fw" and/or "rg" <a href="./Locale.html#def_locale_extension">
135 * Unicode extensions</a>, the first day of the week will be obtained according to
136 * those extensions. If both "fw" and "rg" are specified, the value from the "fw"
137 * extension supersedes the implicit one from the "rg" extension.
138 * They may also be specified explicitly through the methods for setting their
139 * values.
140 *
141 * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
142 * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
143 * first week of the month or year as a reference point. The first week of a
144 * month or year is defined as the earliest seven day period beginning on
145 * <code>getFirstDayOfWeek()</code> and containing at least
146 * <code>getMinimalDaysInFirstWeek()</code> days of that month or year. Weeks
147 * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
148 * it. Note that the normalized numbering returned by <code>get()</code> may be
149 * different. For example, a specific <code>Calendar</code> subclass may
150 * designate the week before week 1 of a year as week <code><i>n</i></code> of
151 * the previous year.
152 *
153 * <h3>Calendar Fields Resolution</h3>
154 *
155 * When computing a date and time from the calendar fields, there
156 * may be insufficient information for the computation (such as only
157 * year and month with no day of month), or there may be inconsistent
158 * information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,
159 * 1996 is actually a Monday). <code>Calendar</code> will resolve
160 * calendar field values to determine the date and time in the
161 * following way.
162 *
163 * <p><a id="resolution">If there is any conflict in calendar field values,
164 * <code>Calendar</code> gives priorities to calendar fields that have been set
165 * more recently.</a> The following are the default combinations of the
166 * calendar fields. The most recent combination, as determined by the
167 * most recently set single field, will be used.
168 *
169 * <p><a id="date_resolution">For the date fields</a>:
170 * <blockquote>
171 * <pre>
172 * YEAR + MONTH + DAY_OF_MONTH
173 * YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
174 * YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
175 * YEAR + DAY_OF_YEAR
176 * YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
177 * </pre></blockquote>
178 *
179 * <a id="time_resolution">For the time of day fields</a>:
180 * <blockquote>
181 * <pre>
182 * HOUR_OF_DAY
183 * AM_PM + HOUR
184 * </pre></blockquote>
185 *
186 * <p>If there are any calendar fields whose values haven't been set in the selected
187 * field combination, <code>Calendar</code> uses their default values. The default
188 * value of each field may vary by concrete calendar systems. For example, in
189 * <code>GregorianCalendar</code>, the default of a field is the same as that
190 * of the start of the Epoch: i.e., <code>YEAR = 1970</code>, <code>MONTH =
191 * JANUARY</code>, <code>DAY_OF_MONTH = 1</code>, etc.
192 *
193 * <p>
194 * <strong>Note:</strong> There are certain possible ambiguities in
195 * interpretation of certain singular times, which are resolved in the
196 * following ways:
197 * <ol>
198 * <li> 23:59 is the last minute of the day and 00:00 is the first
199 * minute of the next day. Thus, 23:59 on Dec 31, 1999 < 00:00 on
200 * Jan 1, 2000 < 00:01 on Jan 1, 2000.
201 *
202 * <li> Although historically not precise, midnight also belongs to "am",
203 * and noon belongs to "pm", so on the same day,
204 * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
205 * </ol>
206 *
207 * <p>
208 * The date or time format strings are not part of the definition of a
209 * calendar, as those must be modifiable or overridable by the user at
210 * runtime. Use {@link DateFormat}
211 * to format dates.
212 *
213 * <h3>Field Manipulation</h3>
214 *
215 * The calendar fields can be changed using three methods:
216 * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.
217 *
218 * <p><strong><code>set(f, value)</code></strong> changes calendar field
219 * <code>f</code> to <code>value</code>. In addition, it sets an
220 * internal member variable to indicate that calendar field <code>f</code> has
221 * been changed. Although calendar field <code>f</code> is changed immediately,
222 * the calendar's time value in milliseconds is not recomputed until the next call to
223 * <code>get()</code>, <code>getTime()</code>, <code>getTimeInMillis()</code>,
224 * <code>add()</code>, or <code>roll()</code> is made. Thus, multiple calls to
225 * <code>set()</code> do not trigger multiple, unnecessary
226 * computations. As a result of changing a calendar field using
227 * <code>set()</code>, other calendar fields may also change, depending on the
228 * calendar field, the calendar field value, and the calendar system. In addition,
229 * <code>get(f)</code> will not necessarily return <code>value</code> set by
230 * the call to the <code>set</code> method
231 * after the calendar fields have been recomputed. The specifics are determined by
232 * the concrete calendar class.</p>
233 *
234 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
235 * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
236 * Calendar.SEPTEMBER)</code> sets the date to September 31,
237 * 1999. This is a temporary internal representation that resolves to
238 * October 1, 1999 if <code>getTime()</code>is then called. However, a
239 * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
240 * <code>getTime()</code> sets the date to September 30, 1999, since
241 * no recomputation occurs after <code>set()</code> itself.</p>
242 *
243 * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
244 * to field <code>f</code>. This is equivalent to calling <code>set(f,
245 * get(f) + delta)</code> with two adjustments:</p>
246 *
247 * <blockquote>
248 * <p><strong>Add rule 1</strong>. The value of field <code>f</code>
249 * after the call minus the value of field <code>f</code> before the
250 * call is <code>delta</code>, modulo any overflow that has occurred in
251 * field <code>f</code>. Overflow occurs when a field value exceeds its
252 * range and, as a result, the next larger field is incremented or
253 * decremented and the field value is adjusted back into its range.</p>
254 *
255 * <p><strong>Add rule 2</strong>. If a smaller field is expected to be
256 * invariant, but it is impossible for it to be equal to its
257 * prior value because of changes in its minimum or maximum after field
258 * <code>f</code> is changed or other constraints, such as time zone
259 * offset changes, then its value is adjusted to be as close
260 * as possible to its expected value. A smaller field represents a
261 * smaller unit of time. <code>HOUR</code> is a smaller field than
262 * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
263 * that are not expected to be invariant. The calendar system
264 * determines what fields are expected to be invariant.</p>
265 * </blockquote>
266 *
267 * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
268 * an immediate recomputation of the calendar's milliseconds and all
269 * fields.</p>
270 *
271 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
272 * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
273 * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
274 * 1</strong> sets the <code>MONTH</code> field to September, since
275 * adding 13 months to August gives September of the next year. Since
276 * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
277 * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
278 * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
279 * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
280 * rule 2, since it is expected to change when the month changes in a
281 * <code>GregorianCalendar</code>.</p>
282 *
283 * <p><strong><code>roll(f, delta)</code></strong> adds
284 * <code>delta</code> to field <code>f</code> without changing larger
285 * fields. This is equivalent to calling <code>add(f, delta)</code> with
286 * the following adjustment:</p>
287 *
288 * <blockquote>
289 * <p><strong>Roll rule</strong>. Larger fields are unchanged after the
290 * call. A larger field represents a larger unit of
291 * time. <code>DAY_OF_MONTH</code> is a larger field than
292 * <code>HOUR</code>.</p>
293 * </blockquote>
294 *
295 * <p><em>Example</em>: See {@link java.util.GregorianCalendar#roll(int, int)}.
296 *
297 * <p><strong>Usage model</strong>. To motivate the behavior of
298 * <code>add()</code> and <code>roll()</code>, consider a user interface
299 * component with increment and decrement buttons for the month, day, and
300 * year, and an underlying <code>GregorianCalendar</code>. If the
301 * interface reads January 31, 1999 and the user presses the month
302 * increment button, what should it read? If the underlying
303 * implementation uses <code>set()</code>, it might read March 3, 1999. A
304 * better result would be February 28, 1999. Furthermore, if the user
305 * presses the month increment button again, it should read March 31,
306 * 1999, not March 28, 1999. By saving the original date and using either
307 * <code>add()</code> or <code>roll()</code>, depending on whether larger
308 * fields should be affected, the user interface can behave as most users
309 * will intuitively expect.</p>
310 *
311 * @see java.lang.System#currentTimeMillis()
312 * @see Date
313 * @see GregorianCalendar
314 * @see TimeZone
315 * @see java.text.DateFormat
316 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
317 * @since 1.1
318 */
319 public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
320
321 // Data flow in Calendar
322 // ---------------------
323
324 // The current time is represented in two ways by Calendar: as UTC
325 // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
326 // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the
327 // millis from the fields, and vice versa. The data needed to do this
328 // conversion is encapsulated by a TimeZone object owned by the Calendar.
329 // The data provided by the TimeZone object may also be overridden if the
330 // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
331 // keeps track of what information was most recently set by the caller, and
332 // uses that to compute any other information as needed.
333
334 // If the user sets the fields using set(), the data flow is as follows.
335 // This is implemented by the Calendar subclass's computeTime() method.
336 // During this process, certain fields may be ignored. The disambiguation
337 // algorithm for resolving which fields to pay attention to is described
338 // in the class documentation.
339
340 // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
341 // |
342 // | Using Calendar-specific algorithm
343 // V
344 // local standard millis
345 // |
346 // | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
347 // V
348 // UTC millis (in time data member)
349
350 // If the user sets the UTC millis using setTime() or setTimeInMillis(),
351 // the data flow is as follows. This is implemented by the Calendar
352 // subclass's computeFields() method.
353
354 // UTC millis (in time data member)
355 // |
356 // | Using TimeZone getOffset()
357 // V
358 // local standard millis
359 // |
360 // | Using Calendar-specific algorithm
361 // V
362 // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
363
364 // In general, a round trip from fields, through local and UTC millis, and
365 // back out to fields is made when necessary. This is implemented by the
366 // complete() method. Resolving a partial set of fields into a UTC millis
367 // value allows all remaining fields to be generated from that value. If
368 // the Calendar is lenient, the fields are also renormalized to standard
369 // ranges when they are regenerated.
370
371 /**
372 * Field number for <code>get</code> and <code>set</code> indicating the
373 * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
374 * value; see subclass documentation.
375 *
376 * @see GregorianCalendar#AD
377 * @see GregorianCalendar#BC
378 */
379 public static final int ERA = 0;
380
381 /**
382 * Field number for <code>get</code> and <code>set</code> indicating the
383 * year. This is a calendar-specific value; see subclass documentation.
384 */
385 public static final int YEAR = 1;
386
387 /**
388 * Field number for <code>get</code> and <code>set</code> indicating the
389 * month. This is a calendar-specific value. The first month of
390 * the year in the Gregorian and Julian calendars is
391 * <code>JANUARY</code> which is 0; the last depends on the number
392 * of months in a year.
393 *
394 * @see #JANUARY
395 * @see #FEBRUARY
396 * @see #MARCH
397 * @see #APRIL
398 * @see #MAY
399 * @see #JUNE
400 * @see #JULY
401 * @see #AUGUST
402 * @see #SEPTEMBER
403 * @see #OCTOBER
404 * @see #NOVEMBER
405 * @see #DECEMBER
406 * @see #UNDECIMBER
407 */
408 public static final int MONTH = 2;
409
410 /**
411 * Field number for <code>get</code> and <code>set</code> indicating the
412 * week number within the current year. The first week of the year, as
413 * defined by <code>getFirstDayOfWeek()</code> and
414 * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
415 * the value of <code>WEEK_OF_YEAR</code> for days before the first week of
416 * the year.
417 *
418 * @see #getFirstDayOfWeek
419 * @see #getMinimalDaysInFirstWeek
420 */
421 public static final int WEEK_OF_YEAR = 3;
422
423 /**
424 * Field number for <code>get</code> and <code>set</code> indicating the
425 * week number within the current month. The first week of the month, as
426 * defined by <code>getFirstDayOfWeek()</code> and
427 * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
428 * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
429 * the month.
430 *
431 * @see #getFirstDayOfWeek
432 * @see #getMinimalDaysInFirstWeek
433 */
434 public static final int WEEK_OF_MONTH = 4;
435
436 /**
437 * Field number for <code>get</code> and <code>set</code> indicating the
438 * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
439 * The first day of the month has value 1.
440 *
441 * @see #DAY_OF_MONTH
442 */
443 public static final int DATE = 5;
444
445 /**
446 * Field number for <code>get</code> and <code>set</code> indicating the
447 * day of the month. This is a synonym for <code>DATE</code>.
448 * The first day of the month has value 1.
449 *
450 * @see #DATE
451 */
452 public static final int DAY_OF_MONTH = 5;
453
454 /**
455 * Field number for <code>get</code> and <code>set</code> indicating the day
456 * number within the current year. The first day of the year has value 1.
457 */
458 public static final int DAY_OF_YEAR = 6;
459
460 /**
461 * Field number for <code>get</code> and <code>set</code> indicating the day
462 * of the week. This field takes values <code>SUNDAY</code>,
463 * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
464 * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
465 *
466 * @see #SUNDAY
467 * @see #MONDAY
468 * @see #TUESDAY
469 * @see #WEDNESDAY
470 * @see #THURSDAY
471 * @see #FRIDAY
472 * @see #SATURDAY
473 */
474 public static final int DAY_OF_WEEK = 7;
475
476 /**
477 * Field number for <code>get</code> and <code>set</code> indicating the
478 * ordinal number of the day of the week within the current month. Together
479 * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
480 * within a month. Unlike <code>WEEK_OF_MONTH</code> and
481 * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
482 * <code>getFirstDayOfWeek()</code> or
483 * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
484 * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
485 * 1</code>; <code>8</code> through <code>14</code> correspond to
486 * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
487 * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
488 * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
489 * end of the month, so the last Sunday of a month is specified as
490 * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
491 * negative values count backward they will usually be aligned differently
492 * within the month than positive values. For example, if a month has 31
493 * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
494 * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
495 *
496 * @see #DAY_OF_WEEK
497 * @see #WEEK_OF_MONTH
498 */
499 public static final int DAY_OF_WEEK_IN_MONTH = 8;
500
501 /**
502 * Field number for <code>get</code> and <code>set</code> indicating
503 * whether the <code>HOUR</code> is before or after noon.
504 * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
505 *
506 * @see #AM
507 * @see #PM
508 * @see #HOUR
509 */
510 public static final int AM_PM = 9;
511
512 /**
513 * Field number for <code>get</code> and <code>set</code> indicating the
514 * hour of the morning or afternoon. <code>HOUR</code> is used for the
515 * 12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12.
516 * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
517 *
518 * @see #AM_PM
519 * @see #HOUR_OF_DAY
520 */
521 public static final int HOUR = 10;
522
523 /**
524 * Field number for <code>get</code> and <code>set</code> indicating the
525 * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
526 * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
527 *
528 * @see #HOUR
529 */
530 public static final int HOUR_OF_DAY = 11;
531
532 /**
533 * Field number for <code>get</code> and <code>set</code> indicating the
534 * minute within the hour.
535 * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
536 */
537 public static final int MINUTE = 12;
538
539 /**
540 * Field number for <code>get</code> and <code>set</code> indicating the
541 * second within the minute.
542 * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
543 */
544 public static final int SECOND = 13;
545
546 /**
547 * Field number for <code>get</code> and <code>set</code> indicating the
548 * millisecond within the second.
549 * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
550 */
551 public static final int MILLISECOND = 14;
552
553 /**
554 * Field number for <code>get</code> and <code>set</code>
555 * indicating the raw offset from GMT in milliseconds.
556 * <p>
557 * This field reflects the correct GMT offset value of the time
558 * zone of this <code>Calendar</code> if the
559 * <code>TimeZone</code> implementation subclass supports
560 * historical GMT offset changes.
561 */
562 public static final int ZONE_OFFSET = 15;
563
564 /**
565 * Field number for <code>get</code> and <code>set</code> indicating the
566 * daylight saving offset in milliseconds.
567 * <p>
568 * This field reflects the correct daylight saving offset value of
569 * the time zone of this <code>Calendar</code> if the
570 * <code>TimeZone</code> implementation subclass supports
571 * historical Daylight Saving Time schedule changes.
572 */
573 public static final int DST_OFFSET = 16;
574
575 /**
576 * The number of distinct fields recognized by <code>get</code> and <code>set</code>.
577 * Field numbers range from <code>0..FIELD_COUNT-1</code>.
578 */
579 public static final int FIELD_COUNT = 17;
580
581 /**
582 * Value of the {@link #DAY_OF_WEEK} field indicating
583 * Sunday.
584 */
585 public static final int SUNDAY = 1;
586
587 /**
588 * Value of the {@link #DAY_OF_WEEK} field indicating
589 * Monday.
590 */
591 public static final int MONDAY = 2;
592
593 /**
594 * Value of the {@link #DAY_OF_WEEK} field indicating
595 * Tuesday.
596 */
597 public static final int TUESDAY = 3;
598
599 /**
600 * Value of the {@link #DAY_OF_WEEK} field indicating
601 * Wednesday.
602 */
603 public static final int WEDNESDAY = 4;
604
605 /**
606 * Value of the {@link #DAY_OF_WEEK} field indicating
607 * Thursday.
608 */
609 public static final int THURSDAY = 5;
610
611 /**
612 * Value of the {@link #DAY_OF_WEEK} field indicating
613 * Friday.
614 */
615 public static final int FRIDAY = 6;
616
617 /**
618 * Value of the {@link #DAY_OF_WEEK} field indicating
619 * Saturday.
620 */
621 public static final int SATURDAY = 7;
622
623 /**
624 * Value of the {@link #MONTH} field indicating the
625 * first month of the year in the Gregorian and Julian calendars.
626 */
627 public static final int JANUARY = 0;
628
629 /**
630 * Value of the {@link #MONTH} field indicating the
631 * second month of the year in the Gregorian and Julian calendars.
632 */
633 public static final int FEBRUARY = 1;
634
635 /**
636 * Value of the {@link #MONTH} field indicating the
637 * third month of the year in the Gregorian and Julian calendars.
638 */
639 public static final int MARCH = 2;
640
641 /**
642 * Value of the {@link #MONTH} field indicating the
643 * fourth month of the year in the Gregorian and Julian calendars.
644 */
645 public static final int APRIL = 3;
646
647 /**
648 * Value of the {@link #MONTH} field indicating the
649 * fifth month of the year in the Gregorian and Julian calendars.
650 */
651 public static final int MAY = 4;
652
653 /**
654 * Value of the {@link #MONTH} field indicating the
655 * sixth month of the year in the Gregorian and Julian calendars.
656 */
657 public static final int JUNE = 5;
658
659 /**
660 * Value of the {@link #MONTH} field indicating the
661 * seventh month of the year in the Gregorian and Julian calendars.
662 */
663 public static final int JULY = 6;
664
665 /**
666 * Value of the {@link #MONTH} field indicating the
667 * eighth month of the year in the Gregorian and Julian calendars.
668 */
669 public static final int AUGUST = 7;
670
671 /**
672 * Value of the {@link #MONTH} field indicating the
673 * ninth month of the year in the Gregorian and Julian calendars.
674 */
675 public static final int SEPTEMBER = 8;
676
677 /**
678 * Value of the {@link #MONTH} field indicating the
679 * tenth month of the year in the Gregorian and Julian calendars.
680 */
681 public static final int OCTOBER = 9;
682
683 /**
684 * Value of the {@link #MONTH} field indicating the
685 * eleventh month of the year in the Gregorian and Julian calendars.
686 */
687 public static final int NOVEMBER = 10;
688
689 /**
690 * Value of the {@link #MONTH} field indicating the
691 * twelfth month of the year in the Gregorian and Julian calendars.
692 */
693 public static final int DECEMBER = 11;
694
695 /**
696 * Value of the {@link #MONTH} field indicating the
697 * thirteenth month of the year. Although <code>GregorianCalendar</code>
698 * does not use this value, lunar calendars do.
699 */
700 public static final int UNDECIMBER = 12;
701
702 /**
703 * Value of the {@link #AM_PM} field indicating the
704 * period of the day from midnight to just before noon.
705 */
706 public static final int AM = 0;
707
708 /**
709 * Value of the {@link #AM_PM} field indicating the
710 * period of the day from noon to just before midnight.
711 */
712 public static final int PM = 1;
713
714 /**
715 * A style specifier for {@link #getDisplayNames(int, int, Locale)
716 * getDisplayNames} indicating names in all styles, such as
717 * "January" and "Jan".
718 *
719 * @see #SHORT_FORMAT
720 * @see #LONG_FORMAT
721 * @see #SHORT_STANDALONE
722 * @see #LONG_STANDALONE
723 * @see #SHORT
724 * @see #LONG
725 * @since 1.6
726 */
727 public static final int ALL_STYLES = 0;
728
729 static final int STANDALONE_MASK = 0x8000;
730
731 /**
732 * A style specifier for {@link #getDisplayName(int, int, Locale)
733 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
734 * getDisplayNames} equivalent to {@link #SHORT_FORMAT}.
735 *
736 * @see #SHORT_STANDALONE
737 * @see #LONG
738 * @since 1.6
739 */
740 public static final int SHORT = 1;
741
742 /**
743 * A style specifier for {@link #getDisplayName(int, int, Locale)
744 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
745 * getDisplayNames} equivalent to {@link #LONG_FORMAT}.
746 *
747 * @see #LONG_STANDALONE
748 * @see #SHORT
749 * @since 1.6
750 */
751 public static final int LONG = 2;
752
753 /**
754 * A style specifier for {@link #getDisplayName(int, int, Locale)
755 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
756 * getDisplayNames} indicating a narrow name used for format. Narrow names
757 * are typically single character strings, such as "M" for Monday.
758 *
759 * @see #NARROW_STANDALONE
760 * @see #SHORT_FORMAT
761 * @see #LONG_FORMAT
762 * @since 1.8
763 */
764 public static final int NARROW_FORMAT = 4;
765
766 /**
767 * A style specifier for {@link #getDisplayName(int, int, Locale)
768 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
769 * getDisplayNames} indicating a narrow name independently. Narrow names
770 * are typically single character strings, such as "M" for Monday.
771 *
772 * @see #NARROW_FORMAT
773 * @see #SHORT_STANDALONE
774 * @see #LONG_STANDALONE
775 * @since 1.8
776 */
777 public static final int NARROW_STANDALONE = NARROW_FORMAT | STANDALONE_MASK;
778
779 /**
780 * A style specifier for {@link #getDisplayName(int, int, Locale)
781 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
782 * getDisplayNames} indicating a short name used for format.
783 *
784 * @see #SHORT_STANDALONE
785 * @see #LONG_FORMAT
786 * @see #LONG_STANDALONE
787 * @since 1.8
788 */
789 public static final int SHORT_FORMAT = 1;
790
791 /**
792 * A style specifier for {@link #getDisplayName(int, int, Locale)
793 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
794 * getDisplayNames} indicating a long name used for format.
795 *
796 * @see #LONG_STANDALONE
797 * @see #SHORT_FORMAT
798 * @see #SHORT_STANDALONE
799 * @since 1.8
800 */
801 public static final int LONG_FORMAT = 2;
802
803 /**
804 * A style specifier for {@link #getDisplayName(int, int, Locale)
805 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
806 * getDisplayNames} indicating a short name used independently,
807 * such as a month abbreviation as calendar headers.
808 *
809 * @see #SHORT_FORMAT
810 * @see #LONG_FORMAT
811 * @see #LONG_STANDALONE
812 * @since 1.8
813 */
814 public static final int SHORT_STANDALONE = SHORT | STANDALONE_MASK;
815
816 /**
817 * A style specifier for {@link #getDisplayName(int, int, Locale)
818 * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
819 * getDisplayNames} indicating a long name used independently,
820 * such as a month name as calendar headers.
821 *
822 * @see #LONG_FORMAT
823 * @see #SHORT_FORMAT
824 * @see #SHORT_STANDALONE
825 * @since 1.8
826 */
827 public static final int LONG_STANDALONE = LONG | STANDALONE_MASK;
828
829 // Internal notes:
830 // Calendar contains two kinds of time representations: current "time" in
831 // milliseconds, and a set of calendar "fields" representing the current time.
832 // The two representations are usually in sync, but can get out of sync
833 // as follows.
834 // 1. Initially, no fields are set, and the time is invalid.
835 // 2. If the time is set, all fields are computed and in sync.
836 // 3. If a single field is set, the time is invalid.
837 // Recomputation of the time and fields happens when the object needs
838 // to return a result to the user, or use a result for a computation.
839
840 /**
841 * The calendar field values for the currently set time for this calendar.
842 * This is an array of <code>FIELD_COUNT</code> integers, with index values
843 * <code>ERA</code> through <code>DST_OFFSET</code>.
844 * @serial
845 */
846 @SuppressWarnings("ProtectedField")
847 protected int fields[];
848
849 /**
850 * The flags which tell if a specified calendar field for the calendar is set.
851 * A new object has no fields set. After the first call to a method
852 * which generates the fields, they all remain set after that.
853 * This is an array of <code>FIELD_COUNT</code> booleans, with index values
854 * <code>ERA</code> through <code>DST_OFFSET</code>.
855 * @serial
856 */
857 @SuppressWarnings("ProtectedField")
858 protected boolean isSet[];
859
860 /**
861 * Pseudo-time-stamps which specify when each field was set. There
862 * are two special values, UNSET and COMPUTED. Values from
863 * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.
864 */
865 private transient int stamp[];
866
867 /**
868 * The currently set time for this calendar, expressed in milliseconds after
869 * January 1, 1970, 0:00:00 GMT.
870 * @see #isTimeSet
871 * @serial
872 */
873 @SuppressWarnings("ProtectedField")
874 protected long time;
875
876 /**
877 * True if then the value of <code>time</code> is valid.
878 * The time is made invalid by a change to an item of <code>field[]</code>.
879 * @see #time
880 * @serial
881 */
882 @SuppressWarnings("ProtectedField")
883 protected boolean isTimeSet;
884
885 /**
886 * True if <code>fields[]</code> are in sync with the currently set time.
887 * If false, then the next attempt to get the value of a field will
888 * force a recomputation of all fields from the current value of
889 * <code>time</code>.
890 * @serial
891 */
892 @SuppressWarnings("ProtectedField")
893 protected boolean areFieldsSet;
894
895 /**
896 * True if all fields have been set.
897 * @serial
898 */
899 transient boolean areAllFieldsSet;
900
901 /**
902 * <code>True</code> if this calendar allows out-of-range field values during computation
903 * of <code>time</code> from <code>fields[]</code>.
904 * @see #setLenient
905 * @see #isLenient
906 * @serial
907 */
908 private boolean lenient = true;
909
910 /**
911 * The <code>TimeZone</code> used by this calendar. <code>Calendar</code>
912 * uses the time zone data to translate between locale and GMT time.
913 * @serial
914 */
915 private TimeZone zone;
916
917 /**
918 * <code>True</code> if zone references to a shared TimeZone object.
919 */
920 private transient boolean sharedZone = false;
921
922 /**
923 * The first day of the week, with possible values <code>SUNDAY</code>,
924 * <code>MONDAY</code>, etc. This is a locale-dependent value.
925 * @serial
926 */
927 private int firstDayOfWeek;
928
929 /**
930 * The number of days required for the first week in a month or year,
931 * with possible values from 1 to 7. This is a locale-dependent value.
932 * @serial
933 */
934 private int minimalDaysInFirstWeek;
935
936 /**
937 * Cache to hold the firstDayOfWeek and minimalDaysInFirstWeek
938 * of a Locale.
939 */
940 private static final ConcurrentMap<Locale, int[]> cachedLocaleData
941 = new ConcurrentHashMap<>(3);
942
943 // Special values of stamp[]
944 /**
945 * The corresponding fields[] has no value.
946 */
947 private static final int UNSET = 0;
948
949 /**
950 * The value of the corresponding fields[] has been calculated internally.
951 */
952 private static final int COMPUTED = 1;
953
954 /**
955 * The value of the corresponding fields[] has been set externally. Stamp
956 * values which are greater than 1 represents the (pseudo) time when the
957 * corresponding fields[] value was set.
958 */
959 private static final int MINIMUM_USER_STAMP = 2;
960
961 /**
962 * The mask value that represents all of the fields.
963 */
964 static final int ALL_FIELDS = (1 << FIELD_COUNT) - 1;
965
966 /**
967 * The next available value for <code>stamp[]</code>, an internal array.
968 * This actually should not be written out to the stream, and will probably
969 * be removed from the stream in the near future. In the meantime,
970 * a value of <code>MINIMUM_USER_STAMP</code> should be used.
971 * @serial
972 */
973 private int nextStamp = MINIMUM_USER_STAMP;
974
975 // the internal serial version which says which version was written
976 // - 0 (default) for version up to JDK 1.1.5
977 // - 1 for version from JDK 1.1.6, which writes a correct 'time' value
978 // as well as compatible values for other fields. This is a
979 // transitional format.
980 // - 2 (not implemented yet) a future version, in which fields[],
981 // areFieldsSet, and isTimeSet become transient, and isSet[] is
982 // removed. In JDK 1.1.6 we write a format compatible with version 2.
983 static final int currentSerialVersion = 1;
984
985 /**
986 * The version of the serialized data on the stream. Possible values:
987 * <dl>
988 * <dt><b>0</b> or not present on stream</dt>
989 * <dd>
990 * JDK 1.1.5 or earlier.
991 * </dd>
992 * <dt><b>1</b></dt>
993 * <dd>
994 * JDK 1.1.6 or later. Writes a correct 'time' value
995 * as well as compatible values for other fields. This is a
996 * transitional format.
997 * </dd>
998 * </dl>
999 * When streaming out this class, the most recent format
1000 * and the highest allowable <code>serialVersionOnStream</code>
1001 * is written.
1002 * @serial
1003 * @since 1.1.6
1004 */
1005 private int serialVersionOnStream = currentSerialVersion;
1006
1007 // Proclaim serialization compatibility with JDK 1.1
1008 @java.io.Serial
1009 static final long serialVersionUID = -1807547505821590642L;
1010
1011 // Mask values for calendar fields
1012 @SuppressWarnings("PointlessBitwiseExpression")
1013 static final int ERA_MASK = (1 << ERA);
1014 static final int YEAR_MASK = (1 << YEAR);
1015 static final int MONTH_MASK = (1 << MONTH);
1016 static final int WEEK_OF_YEAR_MASK = (1 << WEEK_OF_YEAR);
1017 static final int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
1018 static final int DAY_OF_MONTH_MASK = (1 << DAY_OF_MONTH);
1019 static final int DATE_MASK = DAY_OF_MONTH_MASK;
1020 static final int DAY_OF_YEAR_MASK = (1 << DAY_OF_YEAR);
1021 static final int DAY_OF_WEEK_MASK = (1 << DAY_OF_WEEK);
1022 static final int DAY_OF_WEEK_IN_MONTH_MASK = (1 << DAY_OF_WEEK_IN_MONTH);
1023 static final int AM_PM_MASK = (1 << AM_PM);
1024 static final int HOUR_MASK = (1 << HOUR);
1025 static final int HOUR_OF_DAY_MASK = (1 << HOUR_OF_DAY);
1026 static final int MINUTE_MASK = (1 << MINUTE);
1027 static final int SECOND_MASK = (1 << SECOND);
1028 static final int MILLISECOND_MASK = (1 << MILLISECOND);
1029 static final int ZONE_OFFSET_MASK = (1 << ZONE_OFFSET);
1030 static final int DST_OFFSET_MASK = (1 << DST_OFFSET);
1031
1032 /**
1033 * {@code Calendar.Builder} is used for creating a {@code Calendar} from
1034 * various date-time parameters.
1035 *
1036 * <p>There are two ways to set a {@code Calendar} to a date-time value. One
1037 * is to set the instant parameter to a millisecond offset from the <a
1038 * href="Calendar.html#Epoch">Epoch</a>. The other is to set individual
1039 * field parameters, such as {@link Calendar#YEAR YEAR}, to their desired
1040 * values. These two ways can't be mixed. Trying to set both the instant and
1041 * individual fields will cause an {@link IllegalStateException} to be
1042 * thrown. However, it is permitted to override previous values of the
1043 * instant or field parameters.
1044 *
1045 * <p>If no enough field parameters are given for determining date and/or
1046 * time, calendar specific default values are used when building a
1047 * {@code Calendar}. For example, if the {@link Calendar#YEAR YEAR} value
1048 * isn't given for the Gregorian calendar, 1970 will be used. If there are
1049 * any conflicts among field parameters, the <a
1050 * href="Calendar.html#resolution"> resolution rules</a> are applied.
1051 * Therefore, the order of field setting matters.
1052 *
1053 * <p>In addition to the date-time parameters,
1054 * the {@linkplain #setLocale(Locale) locale},
1055 * {@linkplain #setTimeZone(TimeZone) time zone},
1056 * {@linkplain #setWeekDefinition(int, int) week definition}, and
1057 * {@linkplain #setLenient(boolean) leniency mode} parameters can be set.
1058 *
1059 * <p><b>Examples</b>
1060 * <p>The following are sample usages. Sample code assumes that the
1061 * {@code Calendar} constants are statically imported.
1062 *
1063 * <p>The following code produces a {@code Calendar} with date 2012-12-31
1064 * (Gregorian) because Monday is the first day of a week with the <a
1065 * href="GregorianCalendar.html#iso8601_compatible_setting"> ISO 8601
1066 * compatible week parameters</a>.
1067 * <pre>
1068 * Calendar cal = new Calendar.Builder().setCalendarType("iso8601")
1069 * .setWeekDate(2013, 1, MONDAY).build();</pre>
1070 * <p>The following code produces a Japanese {@code Calendar} with date
1071 * 1989-01-08 (Gregorian), assuming that the default {@link Calendar#ERA ERA}
1072 * is <em>Heisei</em> that started on that day.
1073 * <pre>
1074 * Calendar cal = new Calendar.Builder().setCalendarType("japanese")
1075 * .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();</pre>
1076 *
1077 * @since 1.8
1078 * @see Calendar#getInstance(TimeZone, Locale)
1079 * @see Calendar#fields
1080 */
1081 public static class Builder {
1082 private static final int NFIELDS = FIELD_COUNT + 1; // +1 for WEEK_YEAR
1083 private static final int WEEK_YEAR = FIELD_COUNT;
1084
1085 private long instant;
1086 // Calendar.stamp[] (lower half) and Calendar.fields[] (upper half) combined
1087 private int[] fields;
1088 // Pseudo timestamp starting from MINIMUM_USER_STAMP.
1089 // (COMPUTED is used to indicate that the instant has been set.)
1090 private int nextStamp;
1091 // maxFieldIndex keeps the max index of fields which have been set.
1092 // (WEEK_YEAR is never included.)
1093 private int maxFieldIndex;
1094 private String type;
1095 private TimeZone zone;
1096 private boolean lenient = true;
1097 private Locale locale;
1098 private int firstDayOfWeek, minimalDaysInFirstWeek;
1099
1100 /**
1101 * Constructs a {@code Calendar.Builder}.
1102 */
1103 public Builder() {
1104 }
1105
1106 /**
1107 * Sets the instant parameter to the given {@code instant} value that is
1108 * a millisecond offset from <a href="Calendar.html#Epoch">the
1109 * Epoch</a>.
1110 *
1111 * @param instant a millisecond offset from the Epoch
1112 * @return this {@code Calendar.Builder}
1113 * @throws IllegalStateException if any of the field parameters have
1114 * already been set
1115 * @see Calendar#setTime(Date)
1116 * @see Calendar#setTimeInMillis(long)
1117 * @see Calendar#time
1118 */
1119 public Builder setInstant(long instant) {
1120 if (fields != null) {
1121 throw new IllegalStateException();
1122 }
1123 this.instant = instant;
1124 nextStamp = COMPUTED;
1125 return this;
1126 }
1127
1128 /**
1129 * Sets the instant parameter to the {@code instant} value given by a
1130 * {@link Date}. This method is equivalent to a call to
1131 * {@link #setInstant(long) setInstant(instant.getTime())}.
1132 *
1133 * @param instant a {@code Date} representing a millisecond offset from
1134 * the Epoch
1135 * @return this {@code Calendar.Builder}
1136 * @throws NullPointerException if {@code instant} is {@code null}
1137 * @throws IllegalStateException if any of the field parameters have
1138 * already been set
1139 * @see Calendar#setTime(Date)
1140 * @see Calendar#setTimeInMillis(long)
1141 * @see Calendar#time
1142 */
1143 public Builder setInstant(Date instant) {
1144 return setInstant(instant.getTime()); // NPE if instant == null
1145 }
1146
1147 /**
1148 * Sets the {@code field} parameter to the given {@code value}.
1149 * {@code field} is an index to the {@link Calendar#fields}, such as
1150 * {@link Calendar#DAY_OF_MONTH DAY_OF_MONTH}. Field value validation is
1151 * not performed in this method. Any out of range values are either
1152 * normalized in lenient mode or detected as an invalid value in
1153 * non-lenient mode when building a {@code Calendar}.
1154 *
1155 * @param field an index to the {@code Calendar} fields
1156 * @param value the field value
1157 * @return this {@code Calendar.Builder}
1158 * @throws IllegalArgumentException if {@code field} is invalid
1159 * @throws IllegalStateException if the instant value has already been set,
1160 * or if fields have been set too many
1161 * (approximately {@link Integer#MAX_VALUE}) times.
1162 * @see Calendar#set(int, int)
1163 */
1164 public Builder set(int field, int value) {
1165 // Note: WEEK_YEAR can't be set with this method.
1166 if (field < 0 || field >= FIELD_COUNT) {
1167 throw new IllegalArgumentException("field is invalid");
1168 }
1169 if (isInstantSet()) {
1170 throw new IllegalStateException("instant has been set");
1171 }
1172 allocateFields();
1173 internalSet(field, value);
1174 return this;
1175 }
1176
1177 /**
1178 * Sets field parameters to their values given by
1179 * {@code fieldValuePairs} that are pairs of a field and its value.
1180 * For example,
1181 * <pre>
1182 * setFields(Calendar.YEAR, 2013,
1183 * Calendar.MONTH, Calendar.DECEMBER,
1184 * Calendar.DAY_OF_MONTH, 23);</pre>
1185 * is equivalent to the sequence of the following
1186 * {@link #set(int, int) set} calls:
1187 * <pre>
1188 * set(Calendar.YEAR, 2013)
1189 * .set(Calendar.MONTH, Calendar.DECEMBER)
1190 * .set(Calendar.DAY_OF_MONTH, 23);</pre>
1191 *
1192 * @param fieldValuePairs field-value pairs
1193 * @return this {@code Calendar.Builder}
1194 * @throws NullPointerException if {@code fieldValuePairs} is {@code null}
1195 * @throws IllegalArgumentException if any of fields are invalid,
1196 * or if {@code fieldValuePairs.length} is an odd number.
1197 * @throws IllegalStateException if the instant value has been set,
1198 * or if fields have been set too many (approximately
1199 * {@link Integer#MAX_VALUE}) times.
1200 */
1201 public Builder setFields(int... fieldValuePairs) {
1202 int len = fieldValuePairs.length;
1203 if ((len % 2) != 0) {
1204 throw new IllegalArgumentException();
1205 }
1206 if (isInstantSet()) {
1207 throw new IllegalStateException("instant has been set");
1208 }
1209 if ((nextStamp + len / 2) < 0) {
1210 throw new IllegalStateException("stamp counter overflow");
1211 }
1212 allocateFields();
1213 for (int i = 0; i < len; ) {
1214 int field = fieldValuePairs[i++];
1215 // Note: WEEK_YEAR can't be set with this method.
1216 if (field < 0 || field >= FIELD_COUNT) {
1217 throw new IllegalArgumentException("field is invalid");
1218 }
1219 internalSet(field, fieldValuePairs[i++]);
1220 }
1221 return this;
1222 }
1223
1224 /**
1225 * Sets the date field parameters to the values given by {@code year},
1226 * {@code month}, and {@code dayOfMonth}. This method is equivalent to
1227 * a call to:
1228 * <pre>
1229 * setFields(Calendar.YEAR, year,
1230 * Calendar.MONTH, month,
1231 * Calendar.DAY_OF_MONTH, dayOfMonth);</pre>
1232 *
1233 * @param year the {@link Calendar#YEAR YEAR} value
1234 * @param month the {@link Calendar#MONTH MONTH} value
1235 * (the month numbering is <em>0-based</em>).
1236 * @param dayOfMonth the {@link Calendar#DAY_OF_MONTH DAY_OF_MONTH} value
1237 * @return this {@code Calendar.Builder}
1238 */
1239 public Builder setDate(int year, int month, int dayOfMonth) {
1240 return setFields(YEAR, year, MONTH, month, DAY_OF_MONTH, dayOfMonth);
1241 }
1242
1243 /**
1244 * Sets the time of day field parameters to the values given by
1245 * {@code hourOfDay}, {@code minute}, and {@code second}. This method is
1246 * equivalent to a call to:
1247 * <pre>
1248 * setTimeOfDay(hourOfDay, minute, second, 0);</pre>
1249 *
1250 * @param hourOfDay the {@link Calendar#HOUR_OF_DAY HOUR_OF_DAY} value
1251 * (24-hour clock)
1252 * @param minute the {@link Calendar#MINUTE MINUTE} value
1253 * @param second the {@link Calendar#SECOND SECOND} value
1254 * @return this {@code Calendar.Builder}
1255 */
1256 public Builder setTimeOfDay(int hourOfDay, int minute, int second) {
1257 return setTimeOfDay(hourOfDay, minute, second, 0);
1258 }
1259
1260 /**
1261 * Sets the time of day field parameters to the values given by
1262 * {@code hourOfDay}, {@code minute}, {@code second}, and
1263 * {@code millis}. This method is equivalent to a call to:
1264 * <pre>
1265 * setFields(Calendar.HOUR_OF_DAY, hourOfDay,
1266 * Calendar.MINUTE, minute,
1267 * Calendar.SECOND, second,
1268 * Calendar.MILLISECOND, millis);</pre>
1269 *
1270 * @param hourOfDay the {@link Calendar#HOUR_OF_DAY HOUR_OF_DAY} value
1271 * (24-hour clock)
1272 * @param minute the {@link Calendar#MINUTE MINUTE} value
1273 * @param second the {@link Calendar#SECOND SECOND} value
1274 * @param millis the {@link Calendar#MILLISECOND MILLISECOND} value
1275 * @return this {@code Calendar.Builder}
1276 */
1277 public Builder setTimeOfDay(int hourOfDay, int minute, int second, int millis) {
1278 return setFields(HOUR_OF_DAY, hourOfDay, MINUTE, minute,
1279 SECOND, second, MILLISECOND, millis);
1280 }
1281
1282 /**
1283 * Sets the week-based date parameters to the values with the given
1284 * date specifiers - week year, week of year, and day of week.
1285 *
1286 * <p>If the specified calendar doesn't support week dates, the
1287 * {@link #build() build} method will throw an {@link IllegalArgumentException}.
1288 *
1289 * @param weekYear the week year
1290 * @param weekOfYear the week number based on {@code weekYear}
1291 * @param dayOfWeek the day of week value: one of the constants
1292 * for the {@link Calendar#DAY_OF_WEEK DAY_OF_WEEK} field:
1293 * {@link Calendar#SUNDAY SUNDAY}, ..., {@link Calendar#SATURDAY SATURDAY}.
1294 * @return this {@code Calendar.Builder}
1295 * @see Calendar#setWeekDate(int, int, int)
1296 * @see Calendar#isWeekDateSupported()
1297 */
1298 public Builder setWeekDate(int weekYear, int weekOfYear, int dayOfWeek) {
1299 allocateFields();
1300 internalSet(WEEK_YEAR, weekYear);
1301 internalSet(WEEK_OF_YEAR, weekOfYear);
1302 internalSet(DAY_OF_WEEK, dayOfWeek);
1303 return this;
1304 }
1305
1306 /**
1307 * Sets the time zone parameter to the given {@code zone}. If no time
1308 * zone parameter is given to this {@code Calendar.Builder}, the
1309 * {@linkplain TimeZone#getDefault() default
1310 * <code>TimeZone</code>} will be used in the {@link #build() build}
1311 * method.
1312 *
1313 * @param zone the {@link TimeZone}
1314 * @return this {@code Calendar.Builder}
1315 * @throws NullPointerException if {@code zone} is {@code null}
1316 * @see Calendar#setTimeZone(TimeZone)
1317 */
1318 public Builder setTimeZone(TimeZone zone) {
1319 if (zone == null) {
1320 throw new NullPointerException();
1321 }
1322 this.zone = zone;
1323 return this;
1324 }
1325
1326 /**
1327 * Sets the lenient mode parameter to the value given by {@code lenient}.
1328 * If no lenient parameter is given to this {@code Calendar.Builder},
1329 * lenient mode will be used in the {@link #build() build} method.
1330 *
1331 * @param lenient {@code true} for lenient mode;
1332 * {@code false} for non-lenient mode
1333 * @return this {@code Calendar.Builder}
1334 * @see Calendar#setLenient(boolean)
1335 */
1336 public Builder setLenient(boolean lenient) {
1337 this.lenient = lenient;
1338 return this;
1339 }
1340
1341 /**
1342 * Sets the calendar type parameter to the given {@code type}. The
1343 * calendar type given by this method has precedence over any explicit
1344 * or implicit calendar type given by the
1345 * {@linkplain #setLocale(Locale) locale}.
1346 *
1347 * <p>In addition to the available calendar types returned by the
1348 * {@link Calendar#getAvailableCalendarTypes() Calendar.getAvailableCalendarTypes}
1349 * method, {@code "gregorian"} and {@code "iso8601"} as aliases of
1350 * {@code "gregory"} can be used with this method.
1351 *
1352 * @param type the calendar type
1353 * @return this {@code Calendar.Builder}
1354 * @throws NullPointerException if {@code type} is {@code null}
1355 * @throws IllegalArgumentException if {@code type} is unknown
1356 * @throws IllegalStateException if another calendar type has already been set
1357 * @see Calendar#getCalendarType()
1358 * @see Calendar#getAvailableCalendarTypes()
1359 */
1360 public Builder setCalendarType(String type) {
1361 if (type.equals("gregorian")) { // NPE if type == null
1362 type = "gregory";
1363 }
1364 if (!Calendar.getAvailableCalendarTypes().contains(type)
1365 && !type.equals("iso8601")) {
1366 throw new IllegalArgumentException("unknown calendar type: " + type);
1367 }
1368 if (this.type == null) {
1369 this.type = type;
1370 } else {
1371 if (!this.type.equals(type)) {
1372 throw new IllegalStateException("calendar type override");
1373 }
1374 }
1375 return this;
1376 }
1377
1378 /**
1379 * Sets the locale parameter to the given {@code locale}. If no locale
1380 * is given to this {@code Calendar.Builder}, the {@linkplain
1381 * Locale#getDefault(Locale.Category) default <code>Locale</code>}
1382 * for {@link Locale.Category#FORMAT} will be used.
1383 *
1384 * <p>If no calendar type is explicitly given by a call to the
1385 * {@link #setCalendarType(String) setCalendarType} method,
1386 * the {@code Locale} value is used to determine what type of
1387 * {@code Calendar} to be built.
1388 *
1389 * <p>If no week definition parameters are explicitly given by a call to
1390 * the {@link #setWeekDefinition(int,int) setWeekDefinition} method, the
1391 * {@code Locale}'s default values are used.
1392 *
1393 * @param locale the {@link Locale}
1394 * @throws NullPointerException if {@code locale} is {@code null}
1395 * @return this {@code Calendar.Builder}
1396 * @see Calendar#getInstance(Locale)
1397 */
1398 public Builder setLocale(Locale locale) {
1399 if (locale == null) {
1400 throw new NullPointerException();
1401 }
1402 this.locale = locale;
1403 return this;
1404 }
1405
1406 /**
1407 * Sets the week definition parameters to the values given by
1408 * {@code firstDayOfWeek} and {@code minimalDaysInFirstWeek} that are
1409 * used to determine the <a href="Calendar.html#first_week">first
1410 * week</a> of a year. The parameters given by this method have
1411 * precedence over the default values given by the
1412 * {@linkplain #setLocale(Locale) locale}.
1413 *
1414 * @param firstDayOfWeek the first day of a week; one of
1415 * {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
1416 * @param minimalDaysInFirstWeek the minimal number of days in the first
1417 * week (1..7)
1418 * @return this {@code Calendar.Builder}
1419 * @throws IllegalArgumentException if {@code firstDayOfWeek} or
1420 * {@code minimalDaysInFirstWeek} is invalid
1421 * @see Calendar#getFirstDayOfWeek()
1422 * @see Calendar#getMinimalDaysInFirstWeek()
1423 */
1424 public Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek) {
1425 if (!isValidWeekParameter(firstDayOfWeek)
1426 || !isValidWeekParameter(minimalDaysInFirstWeek)) {
1427 throw new IllegalArgumentException();
1428 }
1429 this.firstDayOfWeek = firstDayOfWeek;
1430 this.minimalDaysInFirstWeek = minimalDaysInFirstWeek;
1431 return this;
1432 }
1433
1434 /**
1435 * Returns a {@code Calendar} built from the parameters set by the
1436 * setter methods. The calendar type given by the {@link #setCalendarType(String)
1437 * setCalendarType} method or the {@linkplain #setLocale(Locale) locale} is
1438 * used to determine what {@code Calendar} to be created. If no explicit
1439 * calendar type is given, the locale's default calendar is created.
1440 *
1441 * <p>If the calendar type is {@code "iso8601"}, the
1442 * {@linkplain GregorianCalendar#setGregorianChange(Date) Gregorian change date}
1443 * of a {@link GregorianCalendar} is set to {@code Date(Long.MIN_VALUE)}
1444 * to be the <em>proleptic</em> Gregorian calendar. Its week definition
1445 * parameters are also set to be <a
1446 * href="GregorianCalendar.html#iso8601_compatible_setting">compatible
1447 * with the ISO 8601 standard</a>. Note that the
1448 * {@link GregorianCalendar#getCalendarType() getCalendarType} method of
1449 * a {@code GregorianCalendar} created with {@code "iso8601"} returns
1450 * {@code "gregory"}.
1451 *
1452 * <p>The default values are used for locale and time zone if these
1453 * parameters haven't been given explicitly.
1454 * <p>
1455 * If the locale contains the time zone with "tz"
1456 * <a href="Locale.html#def_locale_extension">Unicode extension</a>,
1457 * and time zone hasn't been given explicitly, time zone in the locale
1458 * is used.
1459 *
1460 * <p>Any out of range field values are either normalized in lenient
1461 * mode or detected as an invalid value in non-lenient mode.
1462 *
1463 * @return a {@code Calendar} built with parameters of this {@code
1464 * Calendar.Builder}
1465 * @throws IllegalArgumentException if the calendar type is unknown, or
1466 * if any invalid field values are given in non-lenient mode, or
1467 * if a week date is given for the calendar type that doesn't
1468 * support week dates.
1469 * @see Calendar#getInstance(TimeZone, Locale)
1470 * @see Locale#getDefault(Locale.Category)
1471 * @see TimeZone#getDefault()
1472 */
1473 public Calendar build() {
1474 if (locale == null) {
1475 locale = Locale.getDefault();
1476 }
1477 if (zone == null) {
1478 zone = defaultTimeZone(locale);
1479 }
1480 Calendar cal;
1481 if (type == null) {
1482 type = locale.getUnicodeLocaleType("ca");
1483 }
1484 if (type == null) {
1485 if (locale.getCountry() == "TH"
1486 && locale.getLanguage() == "th") {
1487 type = "buddhist";
1488 } else {
1489 type = "gregory";
1490 }
1491 }
1492 switch (type) {
1493 case "gregory":
1494 cal = new GregorianCalendar(zone, locale, true);
1495 break;
1496 case "iso8601":
1497 GregorianCalendar gcal = new GregorianCalendar(zone, locale, true);
1498 // make gcal a proleptic Gregorian
1499 gcal.setGregorianChange(new Date(Long.MIN_VALUE));
1500 // and week definition to be compatible with ISO 8601
1501 setWeekDefinition(MONDAY, 4);
1502 cal = gcal;
1503 break;
1504 case "buddhist":
1505 cal = new BuddhistCalendar(zone, locale);
1506 cal.clear();
1507 break;
1508 case "japanese":
1509 cal = new JapaneseImperialCalendar(zone, locale, true);
1510 break;
1511 default:
1512 throw new IllegalArgumentException("unknown calendar type: " + type);
1513 }
1514 cal.setLenient(lenient);
1515 if (firstDayOfWeek != 0) {
1516 cal.setFirstDayOfWeek(firstDayOfWeek);
1517 cal.setMinimalDaysInFirstWeek(minimalDaysInFirstWeek);
1518 }
1519 if (isInstantSet()) {
1520 cal.setTimeInMillis(instant);
1521 cal.complete();
1522 return cal;
1523 }
1524
1525 if (fields != null) {
1526 boolean weekDate = isSet(WEEK_YEAR)
1527 && fields[WEEK_YEAR] > fields[YEAR];
1528 if (weekDate && !cal.isWeekDateSupported()) {
1529 throw new IllegalArgumentException("week date is unsupported by " + type);
1530 }
1531
1532 // Set the fields from the min stamp to the max stamp so that
1533 // the fields resolution works in the Calendar.
1534 for (int stamp = MINIMUM_USER_STAMP; stamp < nextStamp; stamp++) {
1535 for (int index = 0; index <= maxFieldIndex; index++) {
1536 if (fields[index] == stamp) {
1537 cal.set(index, fields[NFIELDS + index]);
1538 break;
1539 }
1540 }
1541 }
1542
1543 if (weekDate) {
1544 int weekOfYear = isSet(WEEK_OF_YEAR) ? fields[NFIELDS + WEEK_OF_YEAR] : 1;
1545 int dayOfWeek = isSet(DAY_OF_WEEK)
1546 ? fields[NFIELDS + DAY_OF_WEEK] : cal.getFirstDayOfWeek();
1547 cal.setWeekDate(fields[NFIELDS + WEEK_YEAR], weekOfYear, dayOfWeek);
1548 }
1549 cal.complete();
1550 }
1551
1552 return cal;
1553 }
1554
1555 private void allocateFields() {
1556 if (fields == null) {
1557 fields = new int[NFIELDS * 2];
1558 nextStamp = MINIMUM_USER_STAMP;
1559 maxFieldIndex = -1;
1560 }
1561 }
1562
1563 private void internalSet(int field, int value) {
1564 fields[field] = nextStamp++;
1565 if (nextStamp < 0) {
1566 throw new IllegalStateException("stamp counter overflow");
1567 }
1568 fields[NFIELDS + field] = value;
1569 if (field > maxFieldIndex && field < WEEK_YEAR) {
1570 maxFieldIndex = field;
1571 }
1572 }
1573
1574 private boolean isInstantSet() {
1575 return nextStamp == COMPUTED;
1576 }
1577
1578 private boolean isSet(int index) {
1579 return fields != null && fields[index] > UNSET;
1580 }
1581
1582 private boolean isValidWeekParameter(int value) {
1583 return value > 0 && value <= 7;
1584 }
1585 }
1586
1587 /**
1588 * Constructs a Calendar with the default time zone
1589 * and the default {@link java.util.Locale.Category#FORMAT FORMAT}
1590 * locale.
1591 * @see TimeZone#getDefault
1592 */
1593 protected Calendar()
1594 {
1595 this(TimeZone.getDefaultRef(), Locale.getDefault(Locale.Category.FORMAT));
1596 sharedZone = true;
1597 }
1598
1599 /**
1600 * Constructs a calendar with the specified time zone and locale.
1601 *
1602 * @param zone the time zone to use
1603 * @param aLocale the locale for the week data
1604 */
1605 protected Calendar(TimeZone zone, Locale aLocale)
1606 {
1607 fields = new int[FIELD_COUNT];
1608 isSet = new boolean[FIELD_COUNT];
1609 stamp = new int[FIELD_COUNT];
1610
1611 this.zone = zone;
1612 setWeekCountData(aLocale);
1613 }
1614
1615 /**
1616 * Gets a calendar using the default time zone and locale. The
1617 * <code>Calendar</code> returned is based on the current time
1618 * in the default time zone with the default
1619 * {@link Locale.Category#FORMAT FORMAT} locale.
1620 * <p>
1621 * If the locale contains the time zone with "tz"
1622 * <a href="Locale.html#def_locale_extension">Unicode extension</a>,
1623 * that time zone is used instead.
1624 *
1625 * @return a Calendar.
1626 */
1627 public static Calendar getInstance()
1628 {
1629 Locale aLocale = Locale.getDefault(Locale.Category.FORMAT);
1630 return createCalendar(defaultTimeZone(aLocale), aLocale);
1631 }
1632
1633 /**
1634 * Gets a calendar using the specified time zone and default locale.
1635 * The <code>Calendar</code> returned is based on the current time
1636 * in the given time zone with the default
1637 * {@link Locale.Category#FORMAT FORMAT} locale.
1638 *
1639 * @param zone the time zone to use
1640 * @return a Calendar.
1641 */
1642 public static Calendar getInstance(TimeZone zone)
1643 {
1644 return createCalendar(zone, Locale.getDefault(Locale.Category.FORMAT));
1645 }
1646
1647 /**
1648 * Gets a calendar using the default time zone and specified locale.
1649 * The <code>Calendar</code> returned is based on the current time
1650 * in the default time zone with the given locale.
1651 * <p>
1652 * If the locale contains the time zone with "tz"
1653 * <a href="Locale.html#def_locale_extension">Unicode extension</a>,
1654 * that time zone is used instead.
1655 *
1656 * @param aLocale the locale for the week data
1657 * @return a Calendar.
1658 */
1659 public static Calendar getInstance(Locale aLocale)
1660 {
1661 return createCalendar(defaultTimeZone(aLocale), aLocale);
1662 }
1663
1664 /**
1665 * Gets a calendar with the specified time zone and locale.
1666 * The <code>Calendar</code> returned is based on the current time
1667 * in the given time zone with the given locale.
1668 *
1669 * @param zone the time zone to use
1670 * @param aLocale the locale for the week data
1671 * @return a Calendar.
1672 */
1673 public static Calendar getInstance(TimeZone zone,
1674 Locale aLocale)
1675 {
1676 return createCalendar(zone, aLocale);
1677 }
1678
1679 private static TimeZone defaultTimeZone(Locale l) {
1680 TimeZone defaultTZ = TimeZone.getDefault();
1681 String shortTZID = l.getUnicodeLocaleType("tz");
1682 return shortTZID != null ?
1683 TimeZoneNameUtility.convertLDMLShortID(shortTZID)
1684 .map(TimeZone::getTimeZone)
1685 .orElse(defaultTZ) :
1686 defaultTZ;
1687 }
1688
1689 private static Calendar createCalendar(TimeZone zone,
1690 Locale aLocale)
1691 {
1692 CalendarProvider provider =
1693 LocaleProviderAdapter.getAdapter(CalendarProvider.class, aLocale)
1694 .getCalendarProvider();
1695 if (provider != null) {
1696 try {
1697 return provider.getInstance(zone, aLocale);
1698 } catch (IllegalArgumentException iae) {
1699 // fall back to the default instantiation
1700 }
1701 }
1702
1703 Calendar cal = null;
1704
1705 if (aLocale.hasExtensions()) {
1706 String caltype = aLocale.getUnicodeLocaleType("ca");
1707 if (caltype != null) {
1708 switch (caltype) {
1709 case "buddhist":
1710 cal = new BuddhistCalendar(zone, aLocale);
1711 break;
1712 case "japanese":
1713 cal = new JapaneseImperialCalendar(zone, aLocale);
1714 break;
1715 case "gregory":
1716 cal = new GregorianCalendar(zone, aLocale);
1717 break;
1718 }
1719 }
1720 }
1721 if (cal == null) {
1722 // If no known calendar type is explicitly specified,
1723 // perform the traditional way to create a Calendar:
1724 // create a BuddhistCalendar for th_TH locale,
1725 // a JapaneseImperialCalendar for ja_JP_JP locale, or
1726 // a GregorianCalendar for any other locales.
1727 // NOTE: The language, country and variant strings are interned.
1728 if (aLocale.getLanguage() == "th" && aLocale.getCountry() == "TH") {
1729 cal = new BuddhistCalendar(zone, aLocale);
1730 } else if (aLocale.getVariant() == "JP" && aLocale.getLanguage() == "ja"
1731 && aLocale.getCountry() == "JP") {
1732 cal = new JapaneseImperialCalendar(zone, aLocale);
1733 } else {
1734 cal = new GregorianCalendar(zone, aLocale);
1735 }
1736 }
1737 return cal;
1738 }
1739
1740 /**
1741 * Returns an array of all locales for which the <code>getInstance</code>
1742 * methods of this class can return localized instances.
1743 * The array returned must contain at least a <code>Locale</code>
1744 * instance equal to {@link java.util.Locale#US Locale.US}.
1745 *
1746 * @return An array of locales for which localized
1747 * <code>Calendar</code> instances are available.
1748 */
1749 public static synchronized Locale[] getAvailableLocales()
1750 {
1751 return DateFormat.getAvailableLocales();
1752 }
1753
1754 /**
1755 * Converts the current calendar field values in {@link #fields fields[]}
1756 * to the millisecond time value
1757 * {@link #time}.
1758 *
1759 * @see #complete()
1760 * @see #computeFields()
1761 */
1762 protected abstract void computeTime();
1763
1764 /**
1765 * Converts the current millisecond time value {@link #time}
1766 * to calendar field values in {@link #fields fields[]}.
1767 * This allows you to sync up the calendar field values with
1768 * a new time that is set for the calendar. The time is <em>not</em>
1769 * recomputed first; to recompute the time, then the fields, call the
1770 * {@link #complete()} method.
1771 *
1772 * @see #computeTime()
1773 */
1774 protected abstract void computeFields();
1775
1776 /**
1777 * Returns a <code>Date</code> object representing this
1778 * <code>Calendar</code>'s time value (millisecond offset from the <a
1779 * href="#Epoch">Epoch</a>").
1780 *
1781 * @return a <code>Date</code> representing the time value.
1782 * @see #setTime(Date)
1783 * @see #getTimeInMillis()
1784 */
1785 public final Date getTime() {
1786 return new Date(getTimeInMillis());
1787 }
1788
1789 /**
1790 * Sets this Calendar's time with the given <code>Date</code>.
1791 * <p>
1792 * Note: Calling <code>setTime()</code> with
1793 * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
1794 * may yield incorrect field values from <code>get()</code>.
1795 *
1796 * @param date the given Date.
1797 * @see #getTime()
1798 * @see #setTimeInMillis(long)
1799 */
1800 public final void setTime(Date date) {
1801 setTimeInMillis(date.getTime());
1802 }
1803
1804 /**
1805 * Returns this Calendar's time value in milliseconds.
1806 *
1807 * @return the current time as UTC milliseconds from the epoch.
1808 * @see #getTime()
1809 * @see #setTimeInMillis(long)
1810 */
1811 public long getTimeInMillis() {
1812 if (!isTimeSet) {
1813 updateTime();
1814 }
1815 return time;
1816 }
1817
1818 /**
1819 * Sets this Calendar's current time from the given long value.
1820 *
1821 * @param millis the new time in UTC milliseconds from the epoch.
1822 * @see #setTime(Date)
1823 * @see #getTimeInMillis()
1824 */
1825 public void setTimeInMillis(long millis) {
1826 // If we don't need to recalculate the calendar field values,
1827 // do nothing.
1828 if (time == millis && isTimeSet && areFieldsSet && areAllFieldsSet
1829 && (zone instanceof ZoneInfo) && !((ZoneInfo)zone).isDirty()) {
1830 return;
1831 }
1832 time = millis;
1833 isTimeSet = true;
1834 areFieldsSet = false;
1835 computeFields();
1836 areAllFieldsSet = areFieldsSet = true;
1837 }
1838
1839 /**
1840 * Returns the value of the given calendar field. In lenient mode,
1841 * all calendar fields are normalized. In non-lenient mode, all
1842 * calendar fields are validated and this method throws an
1843 * exception if any calendar fields have out-of-range values. The
1844 * normalization and validation are handled by the
1845 * {@link #complete()} method, which process is calendar
1846 * system dependent.
1847 *
1848 * @param field the given calendar field.
1849 * @return the value for the given calendar field.
1850 * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
1851 * (<code>field < 0 || field >= FIELD_COUNT</code>).
1852 * @see #set(int,int)
1853 * @see #complete()
1854 */
1855 public int get(int field)
1856 {
1857 complete();
1858 return internalGet(field);
1859 }
1860
1861 /**
1862 * Returns the value of the given calendar field. This method does
1863 * not involve normalization or validation of the field value.
1864 *
1865 * @param field the given calendar field.
1866 * @return the value for the given calendar field.
1867 * @see #get(int)
1868 */
1869 protected final int internalGet(int field)
1870 {
1871 return fields[field];
1872 }
1873
1874 /**
1875 * Sets the value of the given calendar field. This method does
1876 * not affect any setting state of the field in this
1877 * <code>Calendar</code> instance.
1878 *
1879 * @throws IndexOutOfBoundsException if the specified field is out of range
1880 * (<code>field < 0 || field >= FIELD_COUNT</code>).
1881 * @see #areFieldsSet
1882 * @see #isTimeSet
1883 * @see #areAllFieldsSet
1884 * @see #set(int,int)
1885 */
1886 final void internalSet(int field, int value)
1887 {
1888 fields[field] = value;
1889 }
1890
1891 /**
1892 * Sets the given calendar field to the given value. The value is not
1893 * interpreted by this method regardless of the leniency mode.
1894 *
1895 * @param field the given calendar field.
1896 * @param value the value to be set for the given calendar field.
1897 * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
1898 * (<code>field < 0 || field >= FIELD_COUNT</code>).
1899 * in non-lenient mode.
1900 * @see #set(int,int,int)
1901 * @see #set(int,int,int,int,int)
1902 * @see #set(int,int,int,int,int,int)
1903 * @see #get(int)
1904 */
1905 public void set(int field, int value)
1906 {
1907 // If the fields are partially normalized, calculate all the
1908 // fields before changing any fields.
1909 if (areFieldsSet && !areAllFieldsSet) {
1910 computeFields();
1911 }
1912 internalSet(field, value);
1913 isTimeSet = false;
1914 areFieldsSet = false;
1915 isSet[field] = true;
1916 stamp[field] = nextStamp++;
1917 if (nextStamp == Integer.MAX_VALUE) {
1918 adjustStamp();
1919 }
1920 }
1921
1922 /**
1923 * Sets the values for the calendar fields <code>YEAR</code>,
1924 * <code>MONTH</code>, and <code>DAY_OF_MONTH</code>.
1925 * Previous values of other calendar fields are retained. If this is not desired,
1926 * call {@link #clear()} first.
1927 *
1928 * @param year the value used to set the <code>YEAR</code> calendar field.
1929 * @param month the value used to set the <code>MONTH</code> calendar field.
1930 * Month value is 0-based. e.g., 0 for January.
1931 * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1932 * @see #set(int,int)
1933 * @see #set(int,int,int,int,int)
1934 * @see #set(int,int,int,int,int,int)
1935 */
1936 public final void set(int year, int month, int date)
1937 {
1938 set(YEAR, year);
1939 set(MONTH, month);
1940 set(DATE, date);
1941 }
1942
1943 /**
1944 * Sets the values for the calendar fields <code>YEAR</code>,
1945 * <code>MONTH</code>, <code>DAY_OF_MONTH</code>,
1946 * <code>HOUR_OF_DAY</code>, and <code>MINUTE</code>.
1947 * Previous values of other fields are retained. If this is not desired,
1948 * call {@link #clear()} first.
1949 *
1950 * @param year the value used to set the <code>YEAR</code> calendar field.
1951 * @param month the value used to set the <code>MONTH</code> calendar field.
1952 * Month value is 0-based. e.g., 0 for January.
1953 * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1954 * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
1955 * @param minute the value used to set the <code>MINUTE</code> calendar field.
1956 * @see #set(int,int)
1957 * @see #set(int,int,int)
1958 * @see #set(int,int,int,int,int,int)
1959 */
1960 public final void set(int year, int month, int date, int hourOfDay, int minute)
1961 {
1962 set(YEAR, year);
1963 set(MONTH, month);
1964 set(DATE, date);
1965 set(HOUR_OF_DAY, hourOfDay);
1966 set(MINUTE, minute);
1967 }
1968
1969 /**
1970 * Sets the values for the fields <code>YEAR</code>, <code>MONTH</code>,
1971 * <code>DAY_OF_MONTH</code>, <code>HOUR_OF_DAY</code>, <code>MINUTE</code>, and
1972 * <code>SECOND</code>.
1973 * Previous values of other fields are retained. If this is not desired,
1974 * call {@link #clear()} first.
1975 *
1976 * @param year the value used to set the <code>YEAR</code> calendar field.
1977 * @param month the value used to set the <code>MONTH</code> calendar field.
1978 * Month value is 0-based. e.g., 0 for January.
1979 * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1980 * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
1981 * @param minute the value used to set the <code>MINUTE</code> calendar field.
1982 * @param second the value used to set the <code>SECOND</code> calendar field.
1983 * @see #set(int,int)
1984 * @see #set(int,int,int)
1985 * @see #set(int,int,int,int,int)
1986 */
1987 public final void set(int year, int month, int date, int hourOfDay, int minute,
1988 int second)
1989 {
1990 set(YEAR, year);
1991 set(MONTH, month);
1992 set(DATE, date);
1993 set(HOUR_OF_DAY, hourOfDay);
1994 set(MINUTE, minute);
1995 set(SECOND, second);
1996 }
1997
1998 /**
1999 * Sets all the calendar field values and the time value
2000 * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
2001 * this <code>Calendar</code> undefined. This means that {@link
2002 * #isSet(int) isSet()} will return <code>false</code> for all the
2003 * calendar fields, and the date and time calculations will treat
2004 * the fields as if they had never been set. A
2005 * <code>Calendar</code> implementation class may use its specific
2006 * default field values for date/time calculations. For example,
2007 * <code>GregorianCalendar</code> uses 1970 if the
2008 * <code>YEAR</code> field value is undefined.
2009 *
2010 * @see #clear(int)
2011 */
2012 public final void clear()
2013 {
2014 for (int i = 0; i < fields.length; ) {
2015 stamp[i] = fields[i] = 0; // UNSET == 0
2016 isSet[i++] = false;
2017 }
2018 areAllFieldsSet = areFieldsSet = false;
2019 isTimeSet = false;
2020 }
2021
2022 /**
2023 * Sets the given calendar field value and the time value
2024 * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
2025 * this <code>Calendar</code> undefined. This means that {@link
2026 * #isSet(int) isSet(field)} will return <code>false</code>, and
2027 * the date and time calculations will treat the field as if it
2028 * had never been set. A <code>Calendar</code> implementation
2029 * class may use the field's specific default value for date and
2030 * time calculations.
2031 *
2032 * <p>The {@link #HOUR_OF_DAY}, {@link #HOUR} and {@link #AM_PM}
2033 * fields are handled independently and the <a
2034 * href="#time_resolution">the resolution rule for the time of
2035 * day</a> is applied. Clearing one of the fields doesn't reset
2036 * the hour of day value of this <code>Calendar</code>. Use {@link
2037 * #set(int,int) set(Calendar.HOUR_OF_DAY, 0)} to reset the hour
2038 * value.
2039 *
2040 * @param field the calendar field to be cleared.
2041 * @see #clear()
2042 */
2043 public final void clear(int field)
2044 {
2045 fields[field] = 0;
2046 stamp[field] = UNSET;
2047 isSet[field] = false;
2048
2049 areAllFieldsSet = areFieldsSet = false;
2050 isTimeSet = false;
2051 }
2052
2053 /**
2054 * Determines if the given calendar field has a value set,
2055 * including cases that the value has been set by internal fields
2056 * calculations triggered by a <code>get</code> method call.
2057 *
2058 * @param field the calendar field to test
2059 * @return <code>true</code> if the given calendar field has a value set;
2060 * <code>false</code> otherwise.
2061 */
2062 public final boolean isSet(int field)
2063 {
2064 return stamp[field] != UNSET;
2065 }
2066
2067 /**
2068 * Returns the string representation of the calendar
2069 * <code>field</code> value in the given <code>style</code> and
2070 * <code>locale</code>. If no string representation is
2071 * applicable, <code>null</code> is returned. This method calls
2072 * {@link Calendar#get(int) get(field)} to get the calendar
2073 * <code>field</code> value if the string representation is
2074 * applicable to the given calendar <code>field</code>.
2075 *
2076 * <p>For example, if this <code>Calendar</code> is a
2077 * <code>GregorianCalendar</code> and its date is 2005-01-01, then
2078 * the string representation of the {@link #MONTH} field would be
2079 * "January" in the long style in an English locale or "Jan" in
2080 * the short style. However, no string representation would be
2081 * available for the {@link #DAY_OF_MONTH} field, and this method
2082 * would return <code>null</code>.
2083 *
2084 * <p>The default implementation supports the calendar fields for
2085 * which a {@link DateFormatSymbols} has names in the given
2086 * <code>locale</code>.
2087 *
2088 * @param field
2089 * the calendar field for which the string representation
2090 * is returned
2091 * @param style
2092 * the style applied to the string representation; one of {@link
2093 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2094 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2095 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}.
2096 * @param locale
2097 * the locale for the string representation
2098 * (any calendar types specified by {@code locale} are ignored)
2099 * @return the string representation of the given
2100 * {@code field} in the given {@code style}, or
2101 * {@code null} if no string representation is
2102 * applicable.
2103 * @exception IllegalArgumentException
2104 * if {@code field} or {@code style} is invalid,
2105 * or if this {@code Calendar} is non-lenient and any
2106 * of the calendar fields have invalid values
2107 * @exception NullPointerException
2108 * if {@code locale} is null
2109 * @since 1.6
2110 */
2111 public String getDisplayName(int field, int style, Locale locale) {
2112 if (!checkDisplayNameParams(field, style, SHORT, NARROW_FORMAT, locale,
2113 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2114 return null;
2115 }
2116
2117 String calendarType = getCalendarType();
2118 int fieldValue = get(field);
2119 // the standalone/narrow styles and short era are supported only through
2120 // CalendarNameProviders.
2121 if (isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2122 field == ERA && (style & SHORT) == SHORT) {
2123 String val = CalendarDataUtility.retrieveFieldValueName(calendarType,
2124 field, fieldValue,
2125 style, locale);
2126 // Perform fallback here to follow the CLDR rules
2127 if (val == null) {
2128 if (isNarrowFormatStyle(style)) {
2129 val = CalendarDataUtility.retrieveFieldValueName(calendarType,
2130 field, fieldValue,
2131 toStandaloneStyle(style),
2132 locale);
2133 } else if (isStandaloneStyle(style)) {
2134 val = CalendarDataUtility.retrieveFieldValueName(calendarType,
2135 field, fieldValue,
2136 getBaseStyle(style),
2137 locale);
2138 }
2139 }
2140 return val;
2141 }
2142
2143 DateFormatSymbols symbols = DateFormatSymbols.getInstance(locale);
2144 String[] strings = getFieldStrings(field, style, symbols);
2145 if (strings != null) {
2146 if (fieldValue < strings.length) {
2147 return strings[fieldValue];
2148 }
2149 }
2150 return null;
2151 }
2152
2153 /**
2154 * Returns a {@code Map} containing all names of the calendar
2155 * {@code field} in the given {@code style} and
2156 * {@code locale} and their corresponding field values. For
2157 * example, if this {@code Calendar} is a {@link
2158 * GregorianCalendar}, the returned map would contain "Jan" to
2159 * {@link #JANUARY}, "Feb" to {@link #FEBRUARY}, and so on, in the
2160 * {@linkplain #SHORT short} style in an English locale.
2161 *
2162 * <p>Narrow names may not be unique due to use of single characters,
2163 * such as "S" for Sunday and Saturday. In that case narrow names are not
2164 * included in the returned {@code Map}.
2165 *
2166 * <p>The values of other calendar fields may be taken into
2167 * account to determine a set of display names. For example, if
2168 * this {@code Calendar} is a lunisolar calendar system and
2169 * the year value given by the {@link #YEAR} field has a leap
2170 * month, this method would return month names containing the leap
2171 * month name, and month names are mapped to their values specific
2172 * for the year.
2173 *
2174 * <p>The default implementation supports display names contained in
2175 * a {@link DateFormatSymbols}. For example, if {@code field}
2176 * is {@link #MONTH} and {@code style} is {@link
2177 * #ALL_STYLES}, this method returns a {@code Map} containing
2178 * all strings returned by {@link DateFormatSymbols#getShortMonths()}
2179 * and {@link DateFormatSymbols#getMonths()}.
2180 *
2181 * @param field
2182 * the calendar field for which the display names are returned
2183 * @param style
2184 * the style applied to the string representation; one of {@link
2185 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2186 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2187 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}
2188 * @param locale
2189 * the locale for the display names
2190 * @return a {@code Map} containing all display names in
2191 * {@code style} and {@code locale} and their
2192 * field values, or {@code null} if no display names
2193 * are defined for {@code field}
2194 * @exception IllegalArgumentException
2195 * if {@code field} or {@code style} is invalid,
2196 * or if this {@code Calendar} is non-lenient and any
2197 * of the calendar fields have invalid values
2198 * @exception NullPointerException
2199 * if {@code locale} is null
2200 * @since 1.6
2201 */
2202 public Map<String, Integer> getDisplayNames(int field, int style, Locale locale) {
2203 if (!checkDisplayNameParams(field, style, ALL_STYLES, NARROW_FORMAT, locale,
2204 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2205 return null;
2206 }
2207
2208 String calendarType = getCalendarType();
2209 if (style == ALL_STYLES || isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2210 field == ERA && (style & SHORT) == SHORT) {
2211 Map<String, Integer> map;
2212 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field, style, locale);
2213
2214 // Perform fallback here to follow the CLDR rules
2215 if (map == null) {
2216 if (isNarrowFormatStyle(style)) {
2217 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field,
2218 toStandaloneStyle(style), locale);
2219 } else if (style != ALL_STYLES) {
2220 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field,
2221 getBaseStyle(style), locale);
2222 }
2223 }
2224 return map;
2225 }
2226
2227 // SHORT or LONG
2228 return getDisplayNamesImpl(field, style, locale);
2229 }
2230
2231 private Map<String,Integer> getDisplayNamesImpl(int field, int style, Locale locale) {
2232 DateFormatSymbols symbols = DateFormatSymbols.getInstance(locale);
2233 String[] strings = getFieldStrings(field, style, symbols);
2234 if (strings != null) {
2235 Map<String,Integer> names = new HashMap<>();
2236 for (int i = 0; i < strings.length; i++) {
2237 if (strings[i].isEmpty()) {
2238 continue;
2239 }
2240 names.put(strings[i], i);
2241 }
2242 return names;
2243 }
2244 return null;
2245 }
2246
2247 boolean checkDisplayNameParams(int field, int style, int minStyle, int maxStyle,
2248 Locale locale, int fieldMask) {
2249 int baseStyle = getBaseStyle(style); // Ignore the standalone mask
2250 if (field < 0 || field >= fields.length ||
2251 baseStyle < minStyle || baseStyle > maxStyle || baseStyle == 3) {
2252 throw new IllegalArgumentException();
2253 }
2254 if (locale == null) {
2255 throw new NullPointerException();
2256 }
2257 return isFieldSet(fieldMask, field);
2258 }
2259
2260 private String[] getFieldStrings(int field, int style, DateFormatSymbols symbols) {
2261 int baseStyle = getBaseStyle(style); // ignore the standalone mask
2262
2263 // DateFormatSymbols doesn't support any narrow names.
2264 if (baseStyle == NARROW_FORMAT) {
2265 return null;
2266 }
2267
2268 String[] strings = null;
2269 switch (field) {
2270 case ERA:
2271 strings = symbols.getEras();
2272 break;
2273
2274 case MONTH:
2275 strings = (baseStyle == LONG) ? symbols.getMonths() : symbols.getShortMonths();
2276 break;
2277
2278 case DAY_OF_WEEK:
2279 strings = (baseStyle == LONG) ? symbols.getWeekdays() : symbols.getShortWeekdays();
2280 break;
2281
2282 case AM_PM:
2283 strings = symbols.getAmPmStrings();
2284 break;
2285 }
2286 return strings;
2287 }
2288
2289 /**
2290 * Fills in any unset fields in the calendar fields. First, the {@link
2291 * #computeTime()} method is called if the time value (millisecond offset
2292 * from the <a href="#Epoch">Epoch</a>) has not been calculated from
2293 * calendar field values. Then, the {@link #computeFields()} method is
2294 * called to calculate all calendar field values.
2295 */
2296 protected void complete()
2297 {
2298 if (!isTimeSet) {
2299 updateTime();
2300 }
2301 if (!areFieldsSet || !areAllFieldsSet) {
2302 computeFields(); // fills in unset fields
2303 areAllFieldsSet = areFieldsSet = true;
2304 }
2305 }
2306
2307 /**
2308 * Returns whether the value of the specified calendar field has been set
2309 * externally by calling one of the setter methods rather than by the
2310 * internal time calculation.
2311 *
2312 * @return <code>true</code> if the field has been set externally,
2313 * <code>false</code> otherwise.
2314 * @exception IndexOutOfBoundsException if the specified
2315 * <code>field</code> is out of range
2316 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2317 * @see #selectFields()
2318 * @see #setFieldsComputed(int)
2319 */
2320 final boolean isExternallySet(int field) {
2321 return stamp[field] >= MINIMUM_USER_STAMP;
2322 }
2323
2324 /**
2325 * Returns a field mask (bit mask) indicating all calendar fields that
2326 * have the state of externally or internally set.
2327 *
2328 * @return a bit mask indicating set state fields
2329 */
2330 final int getSetStateFields() {
2331 int mask = 0;
2332 for (int i = 0; i < fields.length; i++) {
2333 if (stamp[i] != UNSET) {
2334 mask |= 1 << i;
2335 }
2336 }
2337 return mask;
2338 }
2339
2340 /**
2341 * Sets the state of the specified calendar fields to
2342 * <em>computed</em>. This state means that the specified calendar fields
2343 * have valid values that have been set by internal time calculation
2344 * rather than by calling one of the setter methods.
2345 *
2346 * @param fieldMask the field to be marked as computed.
2347 * @exception IndexOutOfBoundsException if the specified
2348 * <code>field</code> is out of range
2349 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2350 * @see #isExternallySet(int)
2351 * @see #selectFields()
2352 */
2353 final void setFieldsComputed(int fieldMask) {
2354 if (fieldMask == ALL_FIELDS) {
2355 for (int i = 0; i < fields.length; i++) {
2356 stamp[i] = COMPUTED;
2357 isSet[i] = true;
2358 }
2359 areFieldsSet = areAllFieldsSet = true;
2360 } else {
2361 for (int i = 0; i < fields.length; i++) {
2362 if ((fieldMask & 1) == 1) {
2363 stamp[i] = COMPUTED;
2364 isSet[i] = true;
2365 } else {
2366 if (areAllFieldsSet && !isSet[i]) {
2367 areAllFieldsSet = false;
2368 }
2369 }
2370 fieldMask >>>= 1;
2371 }
2372 }
2373 }
2374
2375 /**
2376 * Sets the state of the calendar fields that are <em>not</em> specified
2377 * by <code>fieldMask</code> to <em>unset</em>. If <code>fieldMask</code>
2378 * specifies all the calendar fields, then the state of this
2379 * <code>Calendar</code> becomes that all the calendar fields are in sync
2380 * with the time value (millisecond offset from the Epoch).
2381 *
2382 * @param fieldMask the field mask indicating which calendar fields are in
2383 * sync with the time value.
2384 * @exception IndexOutOfBoundsException if the specified
2385 * <code>field</code> is out of range
2386 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2387 * @see #isExternallySet(int)
2388 * @see #selectFields()
2389 */
2390 final void setFieldsNormalized(int fieldMask) {
2391 if (fieldMask != ALL_FIELDS) {
2392 for (int i = 0; i < fields.length; i++) {
2393 if ((fieldMask & 1) == 0) {
2394 stamp[i] = fields[i] = 0; // UNSET == 0
2395 isSet[i] = false;
2396 }
2397 fieldMask >>= 1;
2398 }
2399 }
2400
2401 // Some or all of the fields are in sync with the
2402 // milliseconds, but the stamp values are not normalized yet.
2403 areFieldsSet = true;
2404 areAllFieldsSet = false;
2405 }
2406
2407 /**
2408 * Returns whether the calendar fields are partially in sync with the time
2409 * value or fully in sync but not stamp values are not normalized yet.
2410 */
2411 final boolean isPartiallyNormalized() {
2412 return areFieldsSet && !areAllFieldsSet;
2413 }
2414
2415 /**
2416 * Returns whether the calendar fields are fully in sync with the time
2417 * value.
2418 */
2419 final boolean isFullyNormalized() {
2420 return areFieldsSet && areAllFieldsSet;
2421 }
2422
2423 /**
2424 * Marks this Calendar as not sync'd.
2425 */
2426 final void setUnnormalized() {
2427 areFieldsSet = areAllFieldsSet = false;
2428 }
2429
2430 /**
2431 * Returns whether the specified <code>field</code> is on in the
2432 * <code>fieldMask</code>.
2433 */
2434 static boolean isFieldSet(int fieldMask, int field) {
2435 return (fieldMask & (1 << field)) != 0;
2436 }
2437
2438 /**
2439 * Returns a field mask indicating which calendar field values
2440 * to be used to calculate the time value. The calendar fields are
2441 * returned as a bit mask, each bit of which corresponds to a field, i.e.,
2442 * the mask value of <code>field</code> is <code>(1 <<
2443 * field)</code>. For example, 0x26 represents the <code>YEAR</code>,
2444 * <code>MONTH</code>, and <code>DAY_OF_MONTH</code> fields (i.e., 0x26 is
2445 * equal to
2446 * <code>(1<<YEAR)|(1<<MONTH)|(1<<DAY_OF_MONTH))</code>.
2447 *
2448 * <p>This method supports the calendar fields resolution as described in
2449 * the class description. If the bit mask for a given field is on and its
2450 * field has not been set (i.e., <code>isSet(field)</code> is
2451 * <code>false</code>), then the default value of the field has to be
2452 * used, which case means that the field has been selected because the
2453 * selected combination involves the field.
2454 *
2455 * @return a bit mask of selected fields
2456 * @see #isExternallySet(int)
2457 */
2458 final int selectFields() {
2459 // This implementation has been taken from the GregorianCalendar class.
2460
2461 // The YEAR field must always be used regardless of its SET
2462 // state because YEAR is a mandatory field to determine the date
2463 // and the default value (EPOCH_YEAR) may change through the
2464 // normalization process.
2465 int fieldMask = YEAR_MASK;
2466
2467 if (stamp[ERA] != UNSET) {
2468 fieldMask |= ERA_MASK;
2469 }
2470 // Find the most recent group of fields specifying the day within
2471 // the year. These may be any of the following combinations:
2472 // MONTH + DAY_OF_MONTH
2473 // MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
2474 // MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
2475 // DAY_OF_YEAR
2476 // WEEK_OF_YEAR + DAY_OF_WEEK
2477 // We look for the most recent of the fields in each group to determine
2478 // the age of the group. For groups involving a week-related field such
2479 // as WEEK_OF_MONTH, DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR, both the
2480 // week-related field and the DAY_OF_WEEK must be set for the group as a
2481 // whole to be considered. (See bug 4153860 - liu 7/24/98.)
2482 int dowStamp = stamp[DAY_OF_WEEK];
2483 int monthStamp = stamp[MONTH];
2484 int domStamp = stamp[DAY_OF_MONTH];
2485 int womStamp = aggregateStamp(stamp[WEEK_OF_MONTH], dowStamp);
2486 int dowimStamp = aggregateStamp(stamp[DAY_OF_WEEK_IN_MONTH], dowStamp);
2487 int doyStamp = stamp[DAY_OF_YEAR];
2488 int woyStamp = aggregateStamp(stamp[WEEK_OF_YEAR], dowStamp);
2489
2490 int bestStamp = domStamp;
2491 if (womStamp > bestStamp) {
2492 bestStamp = womStamp;
2493 }
2494 if (dowimStamp > bestStamp) {
2495 bestStamp = dowimStamp;
2496 }
2497 if (doyStamp > bestStamp) {
2498 bestStamp = doyStamp;
2499 }
2500 if (woyStamp > bestStamp) {
2501 bestStamp = woyStamp;
2502 }
2503
2504 /* No complete combination exists. Look for WEEK_OF_MONTH,
2505 * DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR alone. Treat DAY_OF_WEEK alone
2506 * as DAY_OF_WEEK_IN_MONTH.
2507 */
2508 if (bestStamp == UNSET) {
2509 womStamp = stamp[WEEK_OF_MONTH];
2510 dowimStamp = Math.max(stamp[DAY_OF_WEEK_IN_MONTH], dowStamp);
2511 woyStamp = stamp[WEEK_OF_YEAR];
2512 bestStamp = Math.max(Math.max(womStamp, dowimStamp), woyStamp);
2513
2514 /* Treat MONTH alone or no fields at all as DAY_OF_MONTH. This may
2515 * result in bestStamp = domStamp = UNSET if no fields are set,
2516 * which indicates DAY_OF_MONTH.
2517 */
2518 if (bestStamp == UNSET) {
2519 bestStamp = domStamp = monthStamp;
2520 }
2521 }
2522
2523 if (bestStamp == domStamp ||
2524 (bestStamp == womStamp && stamp[WEEK_OF_MONTH] >= stamp[WEEK_OF_YEAR]) ||
2525 (bestStamp == dowimStamp && stamp[DAY_OF_WEEK_IN_MONTH] >= stamp[WEEK_OF_YEAR])) {
2526 fieldMask |= MONTH_MASK;
2527 if (bestStamp == domStamp) {
2528 fieldMask |= DAY_OF_MONTH_MASK;
2529 } else {
2530 assert (bestStamp == womStamp || bestStamp == dowimStamp);
2531 if (dowStamp != UNSET) {
2532 fieldMask |= DAY_OF_WEEK_MASK;
2533 }
2534 if (womStamp == dowimStamp) {
2535 // When they are equal, give the priority to
2536 // WEEK_OF_MONTH for compatibility.
2537 if (stamp[WEEK_OF_MONTH] >= stamp[DAY_OF_WEEK_IN_MONTH]) {
2538 fieldMask |= WEEK_OF_MONTH_MASK;
2539 } else {
2540 fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
2541 }
2542 } else {
2543 if (bestStamp == womStamp) {
2544 fieldMask |= WEEK_OF_MONTH_MASK;
2545 } else {
2546 assert (bestStamp == dowimStamp);
2547 if (stamp[DAY_OF_WEEK_IN_MONTH] != UNSET) {
2548 fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
2549 }
2550 }
2551 }
2552 }
2553 } else {
2554 assert (bestStamp == doyStamp || bestStamp == woyStamp ||
2555 bestStamp == UNSET);
2556 if (bestStamp == doyStamp) {
2557 fieldMask |= DAY_OF_YEAR_MASK;
2558 } else {
2559 assert (bestStamp == woyStamp);
2560 if (dowStamp != UNSET) {
2561 fieldMask |= DAY_OF_WEEK_MASK;
2562 }
2563 fieldMask |= WEEK_OF_YEAR_MASK;
2564 }
2565 }
2566
2567 // Find the best set of fields specifying the time of day. There
2568 // are only two possibilities here; the HOUR_OF_DAY or the
2569 // AM_PM and the HOUR.
2570 int hourOfDayStamp = stamp[HOUR_OF_DAY];
2571 int hourStamp = aggregateStamp(stamp[HOUR], stamp[AM_PM]);
2572 bestStamp = (hourStamp > hourOfDayStamp) ? hourStamp : hourOfDayStamp;
2573
2574 // if bestStamp is still UNSET, then take HOUR or AM_PM. (See 4846659)
2575 if (bestStamp == UNSET) {
2576 bestStamp = Math.max(stamp[HOUR], stamp[AM_PM]);
2577 }
2578
2579 // Hours
2580 if (bestStamp != UNSET) {
2581 if (bestStamp == hourOfDayStamp) {
2582 fieldMask |= HOUR_OF_DAY_MASK;
2583 } else {
2584 fieldMask |= HOUR_MASK;
2585 if (stamp[AM_PM] != UNSET) {
2586 fieldMask |= AM_PM_MASK;
2587 }
2588 }
2589 }
2590 if (stamp[MINUTE] != UNSET) {
2591 fieldMask |= MINUTE_MASK;
2592 }
2593 if (stamp[SECOND] != UNSET) {
2594 fieldMask |= SECOND_MASK;
2595 }
2596 if (stamp[MILLISECOND] != UNSET) {
2597 fieldMask |= MILLISECOND_MASK;
2598 }
2599 if (stamp[ZONE_OFFSET] >= MINIMUM_USER_STAMP) {
2600 fieldMask |= ZONE_OFFSET_MASK;
2601 }
2602 if (stamp[DST_OFFSET] >= MINIMUM_USER_STAMP) {
2603 fieldMask |= DST_OFFSET_MASK;
2604 }
2605
2606 return fieldMask;
2607 }
2608
2609 int getBaseStyle(int style) {
2610 return style & ~STANDALONE_MASK;
2611 }
2612
2613 private int toStandaloneStyle(int style) {
2614 return style | STANDALONE_MASK;
2615 }
2616
2617 private boolean isStandaloneStyle(int style) {
2618 return (style & STANDALONE_MASK) != 0;
2619 }
2620
2621 private boolean isNarrowStyle(int style) {
2622 return style == NARROW_FORMAT || style == NARROW_STANDALONE;
2623 }
2624
2625 private boolean isNarrowFormatStyle(int style) {
2626 return style == NARROW_FORMAT;
2627 }
2628
2629 /**
2630 * Returns the pseudo-time-stamp for two fields, given their
2631 * individual pseudo-time-stamps. If either of the fields
2632 * is unset, then the aggregate is unset. Otherwise, the
2633 * aggregate is the later of the two stamps.
2634 */
2635 private static int aggregateStamp(int stamp_a, int stamp_b) {
2636 if (stamp_a == UNSET || stamp_b == UNSET) {
2637 return UNSET;
2638 }
2639 return (stamp_a > stamp_b) ? stamp_a : stamp_b;
2640 }
2641
2642 /**
2643 * Returns an unmodifiable {@code Set} containing all calendar types
2644 * supported by {@code Calendar} in the runtime environment. The available
2645 * calendar types can be used for the <a
2646 * href="Locale.html#def_locale_extension">Unicode locale extensions</a>.
2647 * The {@code Set} returned contains at least {@code "gregory"}. The
2648 * calendar types don't include aliases, such as {@code "gregorian"} for
2649 * {@code "gregory"}.
2650 *
2651 * @return an unmodifiable {@code Set} containing all available calendar types
2652 * @since 1.8
2653 * @see #getCalendarType()
2654 * @see Calendar.Builder#setCalendarType(String)
2655 * @see Locale#getUnicodeLocaleType(String)
2656 */
2657 public static Set<String> getAvailableCalendarTypes() {
2658 return AvailableCalendarTypes.SET;
2659 }
2660
2661 private static class AvailableCalendarTypes {
2662 private static final Set<String> SET;
2663 static {
2664 Set<String> set = new HashSet<>(3);
2665 set.add("gregory");
2666 set.add("buddhist");
2667 set.add("japanese");
2668 SET = Collections.unmodifiableSet(set);
2669 }
2670 private AvailableCalendarTypes() {
2671 }
2672 }
2673
2674 /**
2675 * Returns the calendar type of this {@code Calendar}. Calendar types are
2676 * defined by the <em>Unicode Locale Data Markup Language (LDML)</em>
2677 * specification.
2678 *
2679 * <p>The default implementation of this method returns the class name of
2680 * this {@code Calendar} instance. Any subclasses that implement
2681 * LDML-defined calendar systems should override this method to return
2682 * appropriate calendar types.
2683 *
2684 * @return the LDML-defined calendar type or the class name of this
2685 * {@code Calendar} instance
2686 * @since 1.8
2687 * @see <a href="Locale.html#def_extensions">Locale extensions</a>
2688 * @see Locale.Builder#setLocale(Locale)
2689 * @see Locale.Builder#setUnicodeLocaleKeyword(String, String)
2690 */
2691 public String getCalendarType() {
2692 return this.getClass().getName();
2693 }
2694
2695 /**
2696 * Compares this <code>Calendar</code> to the specified
2697 * <code>Object</code>. The result is <code>true</code> if and only if
2698 * the argument is a <code>Calendar</code> object of the same calendar
2699 * system that represents the same time value (millisecond offset from the
2700 * <a href="#Epoch">Epoch</a>) under the same
2701 * <code>Calendar</code> parameters as this object.
2702 *
2703 * <p>The <code>Calendar</code> parameters are the values represented
2704 * by the <code>isLenient</code>, <code>getFirstDayOfWeek</code>,
2705 * <code>getMinimalDaysInFirstWeek</code> and <code>getTimeZone</code>
2706 * methods. If there is any difference in those parameters
2707 * between the two <code>Calendar</code>s, this method returns
2708 * <code>false</code>.
2709 *
2710 * <p>Use the {@link #compareTo(Calendar) compareTo} method to
2711 * compare only the time values.
2712 *
2713 * @param obj the object to compare with.
2714 * @return <code>true</code> if this object is equal to <code>obj</code>;
2715 * <code>false</code> otherwise.
2716 */
2717 @SuppressWarnings("EqualsWhichDoesntCheckParameterClass")
2718 @Override
2719 public boolean equals(Object obj) {
2720 if (this == obj) {
2721 return true;
2722 }
2723 try {
2724 Calendar that = (Calendar)obj;
2725 return compareTo(getMillisOf(that)) == 0 &&
2726 lenient == that.lenient &&
2727 firstDayOfWeek == that.firstDayOfWeek &&
2728 minimalDaysInFirstWeek == that.minimalDaysInFirstWeek &&
2729 zone.equals(that.zone);
2730 } catch (Exception e) {
2731 // Note: GregorianCalendar.computeTime throws
2732 // IllegalArgumentException if the ERA value is invalid
2733 // even it's in lenient mode.
2734 }
2735 return false;
2736 }
2737
2738 /**
2739 * Returns a hash code for this calendar.
2740 *
2741 * @return a hash code value for this object.
2742 * @since 1.2
2743 */
2744 @Override
2745 public int hashCode() {
2746 // 'otheritems' represents the hash code for the previous versions.
2747 int otheritems = (lenient ? 1 : 0)
2748 | (firstDayOfWeek << 1)
2749 | (minimalDaysInFirstWeek << 4)
2750 | (zone.hashCode() << 7);
2751 long t = getMillisOf(this);
2752 return (int) t ^ (int)(t >> 32) ^ otheritems;
2753 }
2754
2755 /**
2756 * Returns whether this <code>Calendar</code> represents a time
2757 * before the time represented by the specified
2758 * <code>Object</code>. This method is equivalent to:
2759 * <pre>{@code
2760 * compareTo(when) < 0
2761 * }</pre>
2762 * if and only if <code>when</code> is a <code>Calendar</code>
2763 * instance. Otherwise, the method returns <code>false</code>.
2764 *
2765 * @param when the <code>Object</code> to be compared
2766 * @return <code>true</code> if the time of this
2767 * <code>Calendar</code> is before the time represented by
2768 * <code>when</code>; <code>false</code> otherwise.
2769 * @see #compareTo(Calendar)
2770 */
2771 public boolean before(Object when) {
2772 return when instanceof Calendar
2773 && compareTo((Calendar)when) < 0;
2774 }
2775
2776 /**
2777 * Returns whether this <code>Calendar</code> represents a time
2778 * after the time represented by the specified
2779 * <code>Object</code>. This method is equivalent to:
2780 * <pre>{@code
2781 * compareTo(when) > 0
2782 * }</pre>
2783 * if and only if <code>when</code> is a <code>Calendar</code>
2784 * instance. Otherwise, the method returns <code>false</code>.
2785 *
2786 * @param when the <code>Object</code> to be compared
2787 * @return <code>true</code> if the time of this <code>Calendar</code> is
2788 * after the time represented by <code>when</code>; <code>false</code>
2789 * otherwise.
2790 * @see #compareTo(Calendar)
2791 */
2792 public boolean after(Object when) {
2793 return when instanceof Calendar
2794 && compareTo((Calendar)when) > 0;
2795 }
2796
2797 /**
2798 * Compares the time values (millisecond offsets from the <a
2799 * href="#Epoch">Epoch</a>) represented by two
2800 * <code>Calendar</code> objects.
2801 *
2802 * @param anotherCalendar the <code>Calendar</code> to be compared.
2803 * @return the value <code>0</code> if the time represented by the argument
2804 * is equal to the time represented by this <code>Calendar</code>; a value
2805 * less than <code>0</code> if the time of this <code>Calendar</code> is
2806 * before the time represented by the argument; and a value greater than
2807 * <code>0</code> if the time of this <code>Calendar</code> is after the
2808 * time represented by the argument.
2809 * @exception NullPointerException if the specified <code>Calendar</code> is
2810 * <code>null</code>.
2811 * @exception IllegalArgumentException if the time value of the
2812 * specified <code>Calendar</code> object can't be obtained due to
2813 * any invalid calendar values.
2814 * @since 1.5
2815 */
2816 @Override
2817 public int compareTo(Calendar anotherCalendar) {
2818 return compareTo(getMillisOf(anotherCalendar));
2819 }
2820
2821 /**
2822 * Adds or subtracts the specified amount of time to the given calendar field,
2823 * based on the calendar's rules. For example, to subtract 5 days from
2824 * the current time of the calendar, you can achieve it by calling:
2825 * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
2826 *
2827 * @param field the calendar field.
2828 * @param amount the amount of date or time to be added to the field.
2829 * @see #roll(int,int)
2830 * @see #set(int,int)
2831 */
2832 public abstract void add(int field, int amount);
2833
2834 /**
2835 * Adds or subtracts (up/down) a single unit of time on the given time
2836 * field without changing larger fields. For example, to roll the current
2837 * date up by one day, you can achieve it by calling:
2838 * <p>roll(Calendar.DATE, true).
2839 * When rolling on the year or Calendar.YEAR field, it will roll the year
2840 * value in the range between 1 and the value returned by calling
2841 * <code>getMaximum(Calendar.YEAR)</code>.
2842 * When rolling on the month or Calendar.MONTH field, other fields like
2843 * date might conflict and, need to be changed. For instance,
2844 * rolling the month on the date 01/31/96 will result in 02/29/96.
2845 * When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
2846 * roll the hour value in the range between 0 and 23, which is zero-based.
2847 *
2848 * @param field the time field.
2849 * @param up indicates if the value of the specified time field is to be
2850 * rolled up or rolled down. Use true if rolling up, false otherwise.
2851 * @see Calendar#add(int,int)
2852 * @see Calendar#set(int,int)
2853 */
2854 public abstract void roll(int field, boolean up);
2855
2856 /**
2857 * Adds the specified (signed) amount to the specified calendar field
2858 * without changing larger fields. A negative amount means to roll
2859 * down.
2860 *
2861 * <p>NOTE: This default implementation on <code>Calendar</code> just repeatedly calls the
2862 * version of {@link #roll(int,boolean) roll()} that rolls by one unit. This may not
2863 * always do the right thing. For example, if the <code>DAY_OF_MONTH</code> field is 31,
2864 * rolling through February will leave it set to 28. The <code>GregorianCalendar</code>
2865 * version of this function takes care of this problem. Other subclasses
2866 * should also provide overrides of this function that do the right thing.
2867 *
2868 * @param field the calendar field.
2869 * @param amount the signed amount to add to the calendar <code>field</code>.
2870 * @since 1.2
2871 * @see #roll(int,boolean)
2872 * @see #add(int,int)
2873 * @see #set(int,int)
2874 */
2875 public void roll(int field, int amount)
2876 {
2877 while (amount > 0) {
2878 roll(field, true);
2879 amount--;
2880 }
2881 while (amount < 0) {
2882 roll(field, false);
2883 amount++;
2884 }
2885 }
2886
2887 /**
2888 * Sets the time zone with the given time zone value.
2889 *
2890 * @param value the given time zone.
2891 */
2892 public void setTimeZone(TimeZone value)
2893 {
2894 zone = value;
2895 sharedZone = false;
2896 /* Recompute the fields from the time using the new zone. This also
2897 * works if isTimeSet is false (after a call to set()). In that case
2898 * the time will be computed from the fields using the new zone, then
2899 * the fields will get recomputed from that. Consider the sequence of
2900 * calls: cal.setTimeZone(EST); cal.set(HOUR, 1); cal.setTimeZone(PST).
2901 * Is cal set to 1 o'clock EST or 1 o'clock PST? Answer: PST. More
2902 * generally, a call to setTimeZone() affects calls to set() BEFORE AND
2903 * AFTER it up to the next call to complete().
2904 */
2905 areAllFieldsSet = areFieldsSet = false;
2906 }
2907
2908 /**
2909 * Gets the time zone.
2910 *
2911 * @return the time zone object associated with this calendar.
2912 */
2913 public TimeZone getTimeZone()
2914 {
2915 // If the TimeZone object is shared by other Calendar instances, then
2916 // create a clone.
2917 if (sharedZone) {
2918 zone = (TimeZone) zone.clone();
2919 sharedZone = false;
2920 }
2921 return zone;
2922 }
2923
2924 /**
2925 * Returns the time zone (without cloning).
2926 */
2927 TimeZone getZone() {
2928 return zone;
2929 }
2930
2931 /**
2932 * Sets the sharedZone flag to <code>shared</code>.
2933 */
2934 void setZoneShared(boolean shared) {
2935 sharedZone = shared;
2936 }
2937
2938 /**
2939 * Specifies whether or not date/time interpretation is to be lenient. With
2940 * lenient interpretation, a date such as "February 942, 1996" will be
2941 * treated as being equivalent to the 941st day after February 1, 1996.
2942 * With strict (non-lenient) interpretation, such dates will cause an exception to be
2943 * thrown. The default is lenient.
2944 *
2945 * @param lenient <code>true</code> if the lenient mode is to be turned
2946 * on; <code>false</code> if it is to be turned off.
2947 * @see #isLenient()
2948 * @see java.text.DateFormat#setLenient
2949 */
2950 public void setLenient(boolean lenient)
2951 {
2952 this.lenient = lenient;
2953 }
2954
2955 /**
2956 * Tells whether date/time interpretation is to be lenient.
2957 *
2958 * @return <code>true</code> if the interpretation mode of this calendar is lenient;
2959 * <code>false</code> otherwise.
2960 * @see #setLenient(boolean)
2961 */
2962 public boolean isLenient()
2963 {
2964 return lenient;
2965 }
2966
2967 /**
2968 * Sets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
2969 * <code>MONDAY</code> in France.
2970 *
2971 * @param value the given first day of the week.
2972 * @see #getFirstDayOfWeek()
2973 * @see #getMinimalDaysInFirstWeek()
2974 */
2975 public void setFirstDayOfWeek(int value)
2976 {
2977 if (firstDayOfWeek == value) {
2978 return;
2979 }
2980 firstDayOfWeek = value;
2981 invalidateWeekFields();
2982 }
2983
2984 /**
2985 * Gets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
2986 * <code>MONDAY</code> in France.
2987 *
2988 * @return the first day of the week.
2989 * @see #setFirstDayOfWeek(int)
2990 * @see #getMinimalDaysInFirstWeek()
2991 */
2992 public int getFirstDayOfWeek()
2993 {
2994 return firstDayOfWeek;
2995 }
2996
2997 /**
2998 * Sets what the minimal days required in the first week of the year are;
2999 * For example, if the first week is defined as one that contains the first
3000 * day of the first month of a year, call this method with value 1. If it
3001 * must be a full week, use value 7.
3002 *
3003 * @param value the given minimal days required in the first week
3004 * of the year.
3005 * @see #getMinimalDaysInFirstWeek()
3006 */
3007 public void setMinimalDaysInFirstWeek(int value)
3008 {
3009 if (minimalDaysInFirstWeek == value) {
3010 return;
3011 }
3012 minimalDaysInFirstWeek = value;
3013 invalidateWeekFields();
3014 }
3015
3016 /**
3017 * Gets what the minimal days required in the first week of the year are;
3018 * e.g., if the first week is defined as one that contains the first day
3019 * of the first month of a year, this method returns 1. If
3020 * the minimal days required must be a full week, this method
3021 * returns 7.
3022 *
3023 * @return the minimal days required in the first week of the year.
3024 * @see #setMinimalDaysInFirstWeek(int)
3025 */
3026 public int getMinimalDaysInFirstWeek()
3027 {
3028 return minimalDaysInFirstWeek;
3029 }
3030
3031 /**
3032 * Returns whether this {@code Calendar} supports week dates.
3033 *
3034 * <p>The default implementation of this method returns {@code false}.
3035 *
3036 * @return {@code true} if this {@code Calendar} supports week dates;
3037 * {@code false} otherwise.
3038 * @see #getWeekYear()
3039 * @see #setWeekDate(int,int,int)
3040 * @see #getWeeksInWeekYear()
3041 * @since 1.7
3042 */
3043 public boolean isWeekDateSupported() {
3044 return false;
3045 }
3046
3047 /**
3048 * Returns the week year represented by this {@code Calendar}. The
3049 * week year is in sync with the week cycle. The {@linkplain
3050 * #getFirstDayOfWeek() first day of the first week} is the first
3051 * day of the week year.
3052 *
3053 * <p>The default implementation of this method throws an
3054 * {@link UnsupportedOperationException}.
3055 *
3056 * @return the week year of this {@code Calendar}
3057 * @exception UnsupportedOperationException
3058 * if any week year numbering isn't supported
3059 * in this {@code Calendar}.
3060 * @see #isWeekDateSupported()
3061 * @see #getFirstDayOfWeek()
3062 * @see #getMinimalDaysInFirstWeek()
3063 * @since 1.7
3064 */
3065 public int getWeekYear() {
3066 throw new UnsupportedOperationException();
3067 }
3068
3069 /**
3070 * Sets the date of this {@code Calendar} with the given date
3071 * specifiers - week year, week of year, and day of week.
3072 *
3073 * <p>Unlike the {@code set} method, all of the calendar fields
3074 * and {@code time} values are calculated upon return.
3075 *
3076 * <p>If {@code weekOfYear} is out of the valid week-of-year range
3077 * in {@code weekYear}, the {@code weekYear} and {@code
3078 * weekOfYear} values are adjusted in lenient mode, or an {@code
3079 * IllegalArgumentException} is thrown in non-lenient mode.
3080 *
3081 * <p>The default implementation of this method throws an
3082 * {@code UnsupportedOperationException}.
3083 *
3084 * @param weekYear the week year
3085 * @param weekOfYear the week number based on {@code weekYear}
3086 * @param dayOfWeek the day of week value: one of the constants
3087 * for the {@link #DAY_OF_WEEK} field: {@link
3088 * #SUNDAY}, ..., {@link #SATURDAY}.
3089 * @exception IllegalArgumentException
3090 * if any of the given date specifiers is invalid
3091 * or any of the calendar fields are inconsistent
3092 * with the given date specifiers in non-lenient mode
3093 * @exception UnsupportedOperationException
3094 * if any week year numbering isn't supported in this
3095 * {@code Calendar}.
3096 * @see #isWeekDateSupported()
3097 * @see #getFirstDayOfWeek()
3098 * @see #getMinimalDaysInFirstWeek()
3099 * @since 1.7
3100 */
3101 public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek) {
3102 throw new UnsupportedOperationException();
3103 }
3104
3105 /**
3106 * Returns the number of weeks in the week year represented by this
3107 * {@code Calendar}.
3108 *
3109 * <p>The default implementation of this method throws an
3110 * {@code UnsupportedOperationException}.
3111 *
3112 * @return the number of weeks in the week year.
3113 * @exception UnsupportedOperationException
3114 * if any week year numbering isn't supported in this
3115 * {@code Calendar}.
3116 * @see #WEEK_OF_YEAR
3117 * @see #isWeekDateSupported()
3118 * @see #getWeekYear()
3119 * @see #getActualMaximum(int)
3120 * @since 1.7
3121 */
3122 public int getWeeksInWeekYear() {
3123 throw new UnsupportedOperationException();
3124 }
3125
3126 /**
3127 * Returns the minimum value for the given calendar field of this
3128 * <code>Calendar</code> instance. The minimum value is defined as
3129 * the smallest value returned by the {@link #get(int) get} method
3130 * for any possible time value. The minimum value depends on
3131 * calendar system specific parameters of the instance.
3132 *
3133 * @param field the calendar field.
3134 * @return the minimum value for the given calendar field.
3135 * @see #getMaximum(int)
3136 * @see #getGreatestMinimum(int)
3137 * @see #getLeastMaximum(int)
3138 * @see #getActualMinimum(int)
3139 * @see #getActualMaximum(int)
3140 */
3141 public abstract int getMinimum(int field);
3142
3143 /**
3144 * Returns the maximum value for the given calendar field of this
3145 * <code>Calendar</code> instance. The maximum value is defined as
3146 * the largest value returned by the {@link #get(int) get} method
3147 * for any possible time value. The maximum value depends on
3148 * calendar system specific parameters of the instance.
3149 *
3150 * @param field the calendar field.
3151 * @return the maximum value for the given calendar field.
3152 * @see #getMinimum(int)
3153 * @see #getGreatestMinimum(int)
3154 * @see #getLeastMaximum(int)
3155 * @see #getActualMinimum(int)
3156 * @see #getActualMaximum(int)
3157 */
3158 public abstract int getMaximum(int field);
3159
3160 /**
3161 * Returns the highest minimum value for the given calendar field
3162 * of this <code>Calendar</code> instance. The highest minimum
3163 * value is defined as the largest value returned by {@link
3164 * #getActualMinimum(int)} for any possible time value. The
3165 * greatest minimum value depends on calendar system specific
3166 * parameters of the instance.
3167 *
3168 * @param field the calendar field.
3169 * @return the highest minimum value for the given calendar field.
3170 * @see #getMinimum(int)
3171 * @see #getMaximum(int)
3172 * @see #getLeastMaximum(int)
3173 * @see #getActualMinimum(int)
3174 * @see #getActualMaximum(int)
3175 */
3176 public abstract int getGreatestMinimum(int field);
3177
3178 /**
3179 * Returns the lowest maximum value for the given calendar field
3180 * of this <code>Calendar</code> instance. The lowest maximum
3181 * value is defined as the smallest value returned by {@link
3182 * #getActualMaximum(int)} for any possible time value. The least
3183 * maximum value depends on calendar system specific parameters of
3184 * the instance. For example, a <code>Calendar</code> for the
3185 * Gregorian calendar system returns 28 for the
3186 * <code>DAY_OF_MONTH</code> field, because the 28th is the last
3187 * day of the shortest month of this calendar, February in a
3188 * common year.
3189 *
3190 * @param field the calendar field.
3191 * @return the lowest maximum value for the given calendar field.
3192 * @see #getMinimum(int)
3193 * @see #getMaximum(int)
3194 * @see #getGreatestMinimum(int)
3195 * @see #getActualMinimum(int)
3196 * @see #getActualMaximum(int)
3197 */
3198 public abstract int getLeastMaximum(int field);
3199
3200 /**
3201 * Returns the minimum value that the specified calendar field
3202 * could have, given the time value of this <code>Calendar</code>.
3203 *
3204 * <p>The default implementation of this method uses an iterative
3205 * algorithm to determine the actual minimum value for the
3206 * calendar field. Subclasses should, if possible, override this
3207 * with a more efficient implementation - in many cases, they can
3208 * simply return <code>getMinimum()</code>.
3209 *
3210 * @param field the calendar field
3211 * @return the minimum of the given calendar field for the time
3212 * value of this <code>Calendar</code>
3213 * @see #getMinimum(int)
3214 * @see #getMaximum(int)
3215 * @see #getGreatestMinimum(int)
3216 * @see #getLeastMaximum(int)
3217 * @see #getActualMaximum(int)
3218 * @since 1.2
3219 */
3220 public int getActualMinimum(int field) {
3221 int fieldValue = getGreatestMinimum(field);
3222 int endValue = getMinimum(field);
3223
3224 // if we know that the minimum value is always the same, just return it
3225 if (fieldValue == endValue) {
3226 return fieldValue;
3227 }
3228
3229 // clone the calendar so we don't mess with the real one, and set it to
3230 // accept anything for the field values
3231 Calendar work = (Calendar)this.clone();
3232 work.setLenient(true);
3233
3234 // now try each value from getLeastMaximum() to getMaximum() one by one until
3235 // we get a value that normalizes to another value. The last value that
3236 // normalizes to itself is the actual minimum for the current date
3237 int result = fieldValue;
3238
3239 do {
3240 work.set(field, fieldValue);
3241 if (work.get(field) != fieldValue) {
3242 break;
3243 } else {
3244 result = fieldValue;
3245 fieldValue--;
3246 }
3247 } while (fieldValue >= endValue);
3248
3249 return result;
3250 }
3251
3252 /**
3253 * Returns the maximum value that the specified calendar field
3254 * could have, given the time value of this
3255 * <code>Calendar</code>. For example, the actual maximum value of
3256 * the <code>MONTH</code> field is 12 in some years, and 13 in
3257 * other years in the Hebrew calendar system.
3258 *
3259 * <p>The default implementation of this method uses an iterative
3260 * algorithm to determine the actual maximum value for the
3261 * calendar field. Subclasses should, if possible, override this
3262 * with a more efficient implementation.
3263 *
3264 * @param field the calendar field
3265 * @return the maximum of the given calendar field for the time
3266 * value of this <code>Calendar</code>
3267 * @see #getMinimum(int)
3268 * @see #getMaximum(int)
3269 * @see #getGreatestMinimum(int)
3270 * @see #getLeastMaximum(int)
3271 * @see #getActualMinimum(int)
3272 * @since 1.2
3273 */
3274 public int getActualMaximum(int field) {
3275 int fieldValue = getLeastMaximum(field);
3276 int endValue = getMaximum(field);
3277
3278 // if we know that the maximum value is always the same, just return it.
3279 if (fieldValue == endValue) {
3280 return fieldValue;
3281 }
3282
3283 // clone the calendar so we don't mess with the real one, and set it to
3284 // accept anything for the field values.
3285 Calendar work = (Calendar)this.clone();
3286 work.setLenient(true);
3287
3288 // if we're counting weeks, set the day of the week to Sunday. We know the
3289 // last week of a month or year will contain the first day of the week.
3290 if (field == WEEK_OF_YEAR || field == WEEK_OF_MONTH) {
3291 work.set(DAY_OF_WEEK, firstDayOfWeek);
3292 }
3293
3294 // now try each value from getLeastMaximum() to getMaximum() one by one until
3295 // we get a value that normalizes to another value. The last value that
3296 // normalizes to itself is the actual maximum for the current date
3297 int result = fieldValue;
3298
3299 do {
3300 work.set(field, fieldValue);
3301 if (work.get(field) != fieldValue) {
3302 break;
3303 } else {
3304 result = fieldValue;
3305 fieldValue++;
3306 }
3307 } while (fieldValue <= endValue);
3308
3309 return result;
3310 }
3311
3312 /**
3313 * Creates and returns a copy of this object.
3314 *
3315 * @return a copy of this object.
3316 */
3317 @Override
3318 public Object clone()
3319 {
3320 try {
3321 Calendar other = (Calendar) super.clone();
3322
3323 other.fields = new int[FIELD_COUNT];
3324 other.isSet = new boolean[FIELD_COUNT];
3325 other.stamp = new int[FIELD_COUNT];
3326 for (int i = 0; i < FIELD_COUNT; i++) {
3327 other.fields[i] = fields[i];
3328 other.stamp[i] = stamp[i];
3329 other.isSet[i] = isSet[i];
3330 }
3331 if (!sharedZone) {
3332 other.zone = (TimeZone) zone.clone();
3333 }
3334 return other;
3335 }
3336 catch (CloneNotSupportedException e) {
3337 // this shouldn't happen, since we are Cloneable
3338 throw new InternalError(e);
3339 }
3340 }
3341
3342 private static final String[] FIELD_NAME = {
3343 "ERA", "YEAR", "MONTH", "WEEK_OF_YEAR", "WEEK_OF_MONTH", "DAY_OF_MONTH",
3344 "DAY_OF_YEAR", "DAY_OF_WEEK", "DAY_OF_WEEK_IN_MONTH", "AM_PM", "HOUR",
3345 "HOUR_OF_DAY", "MINUTE", "SECOND", "MILLISECOND", "ZONE_OFFSET",
3346 "DST_OFFSET"
3347 };
3348
3349 /**
3350 * Returns the name of the specified calendar field.
3351 *
3352 * @param field the calendar field
3353 * @return the calendar field name
3354 * @exception IndexOutOfBoundsException if <code>field</code> is negative,
3355 * equal to or greater than {@code FIELD_COUNT}.
3356 */
3357 static String getFieldName(int field) {
3358 return FIELD_NAME[field];
3359 }
3360
3361 /**
3362 * Return a string representation of this calendar. This method
3363 * is intended to be used only for debugging purposes, and the
3364 * format of the returned string may vary between implementations.
3365 * The returned string may be empty but may not be <code>null</code>.
3366 *
3367 * @return a string representation of this calendar.
3368 */
3369 @Override
3370 public String toString() {
3371 // NOTE: BuddhistCalendar.toString() interprets the string
3372 // produced by this method so that the Gregorian year number
3373 // is substituted by its B.E. year value. It relies on
3374 // "...,YEAR=<year>,..." or "...,YEAR=?,...".
3375 StringBuilder buffer = new StringBuilder(800);
3376 buffer.append(getClass().getName()).append('[');
3377 appendValue(buffer, "time", isTimeSet, time);
3378 buffer.append(",areFieldsSet=").append(areFieldsSet);
3379 buffer.append(",areAllFieldsSet=").append(areAllFieldsSet);
3380 buffer.append(",lenient=").append(lenient);
3381 buffer.append(",zone=").append(zone);
3382 appendValue(buffer, ",firstDayOfWeek", true, (long) firstDayOfWeek);
3383 appendValue(buffer, ",minimalDaysInFirstWeek", true, (long) minimalDaysInFirstWeek);
3384 for (int i = 0; i < FIELD_COUNT; ++i) {
3385 buffer.append(',');
3386 appendValue(buffer, FIELD_NAME[i], isSet(i), (long) fields[i]);
3387 }
3388 buffer.append(']');
3389 return buffer.toString();
3390 }
3391
3392 // =======================privates===============================
3393
3394 private static void appendValue(StringBuilder sb, String item, boolean valid, long value) {
3395 sb.append(item).append('=');
3396 if (valid) {
3397 sb.append(value);
3398 } else {
3399 sb.append('?');
3400 }
3401 }
3402
3403 /**
3404 * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent.
3405 * They are used to figure out the week count for a specific date for
3406 * a given locale. These must be set when a Calendar is constructed.
3407 * @param desiredLocale the given locale.
3408 */
3409 private void setWeekCountData(Locale desiredLocale)
3410 {
3411 /* try to get the Locale data from the cache */
3412 int[] data = cachedLocaleData.get(desiredLocale);
3413 if (data == null) { /* cache miss */
3414 data = new int[2];
3415 data[0] = CalendarDataUtility.retrieveFirstDayOfWeek(desiredLocale);
3416 data[1] = CalendarDataUtility.retrieveMinimalDaysInFirstWeek(desiredLocale);
3417 cachedLocaleData.putIfAbsent(desiredLocale, data);
3418 }
3419 firstDayOfWeek = data[0];
3420 minimalDaysInFirstWeek = data[1];
3421 }
3422
3423 /**
3424 * Recomputes the time and updates the status fields isTimeSet
3425 * and areFieldsSet. Callers should check isTimeSet and only
3426 * call this method if isTimeSet is false.
3427 */
3428 private void updateTime() {
3429 computeTime();
3430 // The areFieldsSet and areAllFieldsSet values are no longer
3431 // controlled here (as of 1.5).
3432 isTimeSet = true;
3433 }
3434
3435 private int compareTo(long t) {
3436 long thisTime = getMillisOf(this);
3437 return (thisTime > t) ? 1 : (thisTime == t) ? 0 : -1;
3438 }
3439
3440 private static long getMillisOf(Calendar calendar) {
3441 if (calendar.isTimeSet) {
3442 return calendar.time;
3443 }
3444 Calendar cal = (Calendar) calendar.clone();
3445 cal.setLenient(true);
3446 return cal.getTimeInMillis();
3447 }
3448
3449 /**
3450 * Adjusts the stamp[] values before nextStamp overflow. nextStamp
3451 * is set to the next stamp value upon the return.
3452 */
3453 private void adjustStamp() {
3454 int max = MINIMUM_USER_STAMP;
3455 int newStamp = MINIMUM_USER_STAMP;
3456
3457 for (;;) {
3458 int min = Integer.MAX_VALUE;
3459 for (int v : stamp) {
3460 if (v >= newStamp && min > v) {
3461 min = v;
3462 }
3463 if (max < v) {
3464 max = v;
3465 }
3466 }
3467 if (max != min && min == Integer.MAX_VALUE) {
3468 break;
3469 }
3470 for (int i = 0; i < stamp.length; i++) {
3471 if (stamp[i] == min) {
3472 stamp[i] = newStamp;
3473 }
3474 }
3475 newStamp++;
3476 if (min == max) {
3477 break;
3478 }
3479 }
3480 nextStamp = newStamp;
3481 }
3482
3483 /**
3484 * Sets the WEEK_OF_MONTH and WEEK_OF_YEAR fields to new values with the
3485 * new parameter value if they have been calculated internally.
3486 */
3487 private void invalidateWeekFields()
3488 {
3489 if (stamp[WEEK_OF_MONTH] != COMPUTED &&
3490 stamp[WEEK_OF_YEAR] != COMPUTED) {
3491 return;
3492 }
3493
3494 // We have to check the new values of these fields after changing
3495 // firstDayOfWeek and/or minimalDaysInFirstWeek. If the field values
3496 // have been changed, then set the new values. (4822110)
3497 Calendar cal = (Calendar) clone();
3498 cal.setLenient(true);
3499 cal.clear(WEEK_OF_MONTH);
3500 cal.clear(WEEK_OF_YEAR);
3501
3502 if (stamp[WEEK_OF_MONTH] == COMPUTED) {
3503 int weekOfMonth = cal.get(WEEK_OF_MONTH);
3504 if (fields[WEEK_OF_MONTH] != weekOfMonth) {
3505 fields[WEEK_OF_MONTH] = weekOfMonth;
3506 }
3507 }
3508
3509 if (stamp[WEEK_OF_YEAR] == COMPUTED) {
3510 int weekOfYear = cal.get(WEEK_OF_YEAR);
3511 if (fields[WEEK_OF_YEAR] != weekOfYear) {
3512 fields[WEEK_OF_YEAR] = weekOfYear;
3513 }
3514 }
3515 }
3516
3517 /**
3518 * Save the state of this object to a stream (i.e., serialize it).
3519 *
3520 * Ideally, <code>Calendar</code> would only write out its state data and
3521 * the current time, and not write any field data out, such as
3522 * <code>fields[]</code>, <code>isTimeSet</code>, <code>areFieldsSet</code>,
3523 * and <code>isSet[]</code>. <code>nextStamp</code> also should not be part
3524 * of the persistent state. Unfortunately, this didn't happen before JDK 1.1
3525 * shipped. To be compatible with JDK 1.1, we will always have to write out
3526 * the field values and state flags. However, <code>nextStamp</code> can be
3527 * removed from the serialization stream; this will probably happen in the
3528 * near future.
3529 */
3530 @java.io.Serial
3531 private synchronized void writeObject(ObjectOutputStream stream)
3532 throws IOException
3533 {
3534 // Try to compute the time correctly, for the future (stream
3535 // version 2) in which we don't write out fields[] or isSet[].
3536 if (!isTimeSet) {
3537 try {
3538 updateTime();
3539 }
3540 catch (IllegalArgumentException e) {}
3541 }
3542
3543 // If this Calendar has a ZoneInfo, save it and set a
3544 // SimpleTimeZone equivalent (as a single DST schedule) for
3545 // backward compatibility.
3546 TimeZone savedZone = null;
3547 if (zone instanceof ZoneInfo) {
3548 SimpleTimeZone stz = ((ZoneInfo)zone).getLastRuleInstance();
3549 if (stz == null) {
3550 stz = new SimpleTimeZone(zone.getRawOffset(), zone.getID());
3551 }
3552 savedZone = zone;
3553 zone = stz;
3554 }
3555
3556 // Write out the 1.1 FCS object.
3557 stream.defaultWriteObject();
3558
3559 // Write out the ZoneInfo object
3560 // 4802409: we write out even if it is null, a temporary workaround
3561 // the real fix for bug 4844924 in corba-iiop
3562 stream.writeObject(savedZone);
3563 if (savedZone != null) {
3564 zone = savedZone;
3565 }
3566 }
3567
3568 private static class CalendarAccessControlContext {
3569 private static final AccessControlContext INSTANCE;
3570 static {
3571 RuntimePermission perm = new RuntimePermission("accessClassInPackage.sun.util.calendar");
3572 PermissionCollection perms = perm.newPermissionCollection();
3573 perms.add(perm);
3574 INSTANCE = new AccessControlContext(new ProtectionDomain[] {
3575 new ProtectionDomain(null, perms)
3576 });
3577 }
3578 private CalendarAccessControlContext() {
3579 }
3580 }
3581
3582 /**
3583 * Reconstitutes this object from a stream (i.e., deserialize it).
3584 */
3585 @java.io.Serial
3586 private void readObject(ObjectInputStream stream)
3587 throws IOException, ClassNotFoundException
3588 {
3589 final ObjectInputStream input = stream;
3590 input.defaultReadObject();
3591
3592 stamp = new int[FIELD_COUNT];
3593
3594 // Starting with version 2 (not implemented yet), we expect that
3595 // fields[], isSet[], isTimeSet, and areFieldsSet may not be
3596 // streamed out anymore. We expect 'time' to be correct.
3597 if (serialVersionOnStream >= 2)
3598 {
3599 isTimeSet = true;
3600 if (fields == null) {
3601 fields = new int[FIELD_COUNT];
3602 }
3603 if (isSet == null) {
3604 isSet = new boolean[FIELD_COUNT];
3605 }
3606 }
3607 else if (serialVersionOnStream >= 0)
3608 {
3609 for (int i=0; i<FIELD_COUNT; ++i) {
3610 stamp[i] = isSet[i] ? COMPUTED : UNSET;
3611 }
3612 }
3613
3614 serialVersionOnStream = currentSerialVersion;
3615
3616 // If there's a ZoneInfo object, use it for zone.
3617 ZoneInfo zi = null;
3618 try {
3619 zi = AccessController.doPrivileged(
3620 new PrivilegedExceptionAction<>() {
3621 @Override
3622 public ZoneInfo run() throws Exception {
3623 return (ZoneInfo) input.readObject();
3624 }
3625 },
3626 CalendarAccessControlContext.INSTANCE);
3627 } catch (PrivilegedActionException pae) {
3628 Exception e = pae.getException();
3629 if (!(e instanceof OptionalDataException)) {
3630 if (e instanceof RuntimeException) {
3631 throw (RuntimeException) e;
3632 } else if (e instanceof IOException) {
3633 throw (IOException) e;
3634 } else if (e instanceof ClassNotFoundException) {
3635 throw (ClassNotFoundException) e;
3636 }
3637 throw new RuntimeException(e);
3638 }
3639 }
3640 if (zi != null) {
3641 zone = zi;
3642 }
3643
3644 // If the deserialized object has a SimpleTimeZone, try to
3645 // replace it with a ZoneInfo equivalent (as of 1.4) in order
3646 // to be compatible with the SimpleTimeZone-based
3647 // implementation as much as possible.
3648 if (zone instanceof SimpleTimeZone) {
3649 String id = zone.getID();
3650 TimeZone tz = TimeZone.getTimeZone(id);
3651 if (tz != null && tz.hasSameRules(zone) && tz.getID().equals(id)) {
3652 zone = tz;
3653 }
3654 }
3655 }
3656
3657 /**
3658 * Converts this object to an {@link Instant}.
3659 * <p>
3660 * The conversion creates an {@code Instant} that represents the
3661 * same point on the time-line as this {@code Calendar}.
3662 *
3663 * @return the instant representing the same point on the time-line
3664 * @since 1.8
3665 */
3666 public final Instant toInstant() {
3667 return Instant.ofEpochMilli(getTimeInMillis());
3668 }
3669 }