Java > Open Source Codes > java > util > Calendar


1 /*
2  * @(#)Calendar.java 1.81 04/07/26
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 /*
9  * (C) Copyright Taligent, Inc. 1996-1998 - All Rights Reserved
10  * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved
11  *
12  * The original version of this source code and documentation is copyrighted
13  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
14  * materials are provided under terms of a License Agreement between Taligent
15  * and Sun. This technology is protected by multiple US and International
16  * patents. This notice and attribution to Taligent may not be removed.
17  * Taligent is a registered trademark of Taligent, Inc.
18  *
19  */
20
21 package java.util;
22
23 import java.io.IOException ;
24 import java.io.ObjectInputStream ;
25 import java.io.ObjectOutputStream ;
26 import java.io.Serializable ;
27 import java.security.AccessController ;
28 import java.security.PrivilegedExceptionAction ;
29 import java.text.DateFormat ;
30 import sun.text.resources.LocaleData;
31 import sun.util.BuddhistCalendar;
32 import sun.util.calendar.ZoneInfo;
33
34 /**
35  * The <code>Calendar</code> class is an abstract class that provides methods
36  * for converting between a specific instant in time and a set of {@link
37  * #fields calendar fields} such as <code>YEAR</code>, <code>MONTH</code>,
38  * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, and so on, and for
39  * manipulating the calendar fields, such as getting the date of the next
40  * week. An instant in time can be represented by a millisecond value that is
41  * an offset from the <a name="Epoch"><em>Epoch</em></a>, January 1, 1970
42  * 00:00:00.000 GMT (Gregorian).
43  *
44  * <p>The class also provides additional fields and methods for
45  * implementing a concrete calendar system outside the package. Those
46  * fields and methods are defined as <code>protected</code>.
47  *
48  * <p>
49  * Like other locale-sensitive classes, <code>Calendar</code> provides a
50  * class method, <code>getInstance</code>, for getting a generally useful
51  * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
52  * returns a <code>Calendar</code> object whose
53  * calendar fields have been initialized with the current date and time:
54  * <blockquote>
55  * <pre>
56  * Calendar rightNow = Calendar.getInstance();
57  * </pre>
58  * </blockquote>
59  *
60  * <p>A <code>Calendar</code> object can produce all the calendar field values
61  * needed to implement the date-time formatting for a particular language and
62  * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
63  * <code>Calendar</code> defines the range of values returned by
64  * certain calendar fields, as well as their meaning. For example,
65  * the first month of the calendar system has value <code>MONTH ==
66  * JANUARY</code> for all calendars. Other values are defined by the
67  * concrete subclass, such as <code>ERA</code>. See individual field
68  * documentation and subclass documentation for details.
69  *
70  * <h4>Getting and Setting Calendar Field Values</h4>
71  *
72  * <p>The calendar field values can be set by calling the <code>set</code>
73  * methods. Any field values set in a <code>Calendar</code> will not be
74  * interpreted until it needs to calculate its time value (milliseconds from
75  * the Epoch) or values of the calendar fields. Calling the
76  * <code>get</code>, <code>getTimeInMillis</code>, <code>getTime</code>,
77  * <code>add</code> and <code>roll</code> involves such calculation.
78  *
79  * <h4>Leniency</h4>
80  *
81  * <p><code>Calendar</code> has two modes for interpreting the calendar
82  * fields, <em>lenient</em> and <em>non-lenient</em>. When a
83  * <code>Calendar</code> is in lenient mode, it accepts a wider range of
84  * calendar field values than it produces. When a <code>Calendar</code>
85  * recomputes calendar field values for return by <code>get()</code>, all of
86  * the calendar fields are normalized. For example, a lenient
87  * <code>GregorianCalendar</code> interprets <code>MONTH == JANUARY</code>,
88  * <code>DAY_OF_MONTH == 32</code> as February 1.
89
90  * <p>When a <code>Calendar</code> is in non-lenient mode, it throws an
91  * exception if there is any inconsistency in its calendar fields. For
92  * example, a <code>GregorianCalendar</code> always produces
93  * <code>DAY_OF_MONTH</code> values between 1 and the length of the month. A
94  * non-lenient <code>GregorianCalendar</code> throws an exception upon
95  * calculating its time or calendar field values if any out-of-range field
96  * value has been set.
97  *
98  * <h4>First Week</h4>
99  *
100  * <code>Calendar</code> defines a locale-specific seven day week using two
101  * parameters: the first day of the week and the minimal days in first week
102  * (from 1 to 7). These numbers are taken from the locale resource data when a
103  * <code>Calendar</code> is constructed. They may also be specified explicitly
104  * through the methods for setting their values.
105  *
106  * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
107  * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
108  * first week of the month or year as a reference point. The first week of a
109  * month or year is defined as the earliest seven day period beginning on
110  * <code>getFirstDayOfWeek()</code> and containing at least
111  * <code>getMinimalDaysInFirstWeek()</code> days of that month or year. Weeks
112  * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
113  * it. Note that the normalized numbering returned by <code>get()</code> may be
114  * different. For example, a specific <code>Calendar</code> subclass may
115  * designate the week before week 1 of a year as week <code><i>n</i></code> of
116  * the previous year.
117  *
118  * <h4>Calendar Fields Resolution</h4>
119  *
120  * When computing a date and time from the calendar fields, there
121  * may be insufficient information for the computation (such as only
122  * year and month with no day of month), or there may be inconsistent
123  * information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,
124  * 1996 is actually a Monday). <code>Calendar</code> will resolve
125  * calendar field values to determine the date and time in the
126  * following way.
127  *
128  * <p>If there is any conflict in calendar field values,
129  * <code>Calendar</code> gives priorities to calendar fields that have been set
130  * more recently. The following are the default combinations of the
131  * calendar fields. The most recent combination, as determined by the
132  * most recently set single field, will be used.
133  *
134  * <p><a name="date_resolution">For the date fields</a>:
135  * <blockquote>
136  * <pre>
137  * YEAR + MONTH + DAY_OF_MONTH
138  * YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
139  * YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
140  * YEAR + DAY_OF_YEAR
141  * YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
142  * </pre></blockquote>
143  *
144  * <a name="time_resolution">For the time of day fields</a>:
145  * <blockquote>
146  * <pre>
147  * HOUR_OF_DAY
148  * AM_PM + HOUR
149  * </pre></blockquote>
150  *
151  * <p>If there are any calendar fields whose values haven't been set in the selected
152  * field combination, <code>Calendar</code> uses their default values. The default
153  * value of each field may vary by concrete calendar systems. For example, in
154  * <code>GregorianCalendar</code>, the default of a field is the same as that
155  * of the start of the Epoch: i.e., <code>YEAR = 1970</code>, <code>MONTH =
156  * JANUARY</code>, <code>DAY_OF_MONTH = 1</code>, etc.
157  *
158  * <p>
159  * <strong>Note:</strong> There are certain possible ambiguities in
160  * interpretation of certain singular times, which are resolved in the
161  * following ways:
162  * <ol>
163  * <li> 23:59 is the last minute of the day and 00:00 is the first
164  * minute of the next day. Thus, 23:59 on Dec 31, 1999 &lt; 00:00 on
165  * Jan 1, 2000 &lt; 00:01 on Jan 1, 2000.
166  *
167  * <li> Although historically not precise, midnight also belongs to "am",
168  * and noon belongs to "pm", so on the same day,
169  * 12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
170  * </ol>
171  *
172  * <p>
173  * The date or time format strings are not part of the definition of a
174  * calendar, as those must be modifiable or overridable by the user at
175  * runtime. Use {@link DateFormat}
176  * to format dates.
177  *
178  * <h4>Field Manipulation</h4>
179  *
180  * The calendar fields can be changed using three methods:
181  * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
182  *
183  * <p><strong><code>set(f, value)</code></strong> changes calendar field
184  * <code>f</code> to <code>value</code>. In addition, it sets an
185  * internal member variable to indicate that calendar field <code>f</code> has
186  * been changed. Although calendar field <code>f</code> is changed immediately,
187  * the calendar's time value in milliseconds is not recomputed until the next call to
188  * <code>get()</code>, <code>getTime()</code>, <code>getTimeInMillis()</code>,
189  * <code>add()</code>, or <code>roll()</code> is made. Thus, multiple calls to
190  * <code>set()</code> do not trigger multiple, unnecessary
191  * computations. As a result of changing a calendar field using
192  * <code>set()</code>, other calendar fields may also change, depending on the
193  * calendar field, the calendar field value, and the calendar system. In addition,
194  * <code>get(f)</code> will not necessarily return <code>value</code> set by
195  * the call to the <code>set</code> method
196  * after the calendar fields have been recomputed. The specifics are determined by
197  * the concrete calendar class.</p>
198  *
199  * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
200  * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
201  * Calendar.SEPTEMBER)</code> sets the date to September 31,
202  * 1999. This is a temporary internal representation that resolves to
203  * October 1, 1999 if <code>getTime()</code>is then called. However, a
204  * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
205  * <code>getTime()</code> sets the date to September 30, 1999, since
206  * no recomputation occurs after <code>set()</code> itself.</p>
207  *
208  * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
209  * to field <code>f</code>. This is equivalent to calling <code>set(f,
210  * get(f) + delta)</code> with two adjustments:</p>
211  *
212  * <blockquote>
213  * <p><strong>Add rule 1</strong>. The value of field <code>f</code>
214  * after the call minus the value of field <code>f</code> before the
215  * call is <code>delta</code>, modulo any overflow that has occurred in
216  * field <code>f</code>. Overflow occurs when a field value exceeds its
217  * range and, as a result, the next larger field is incremented or
218  * decremented and the field value is adjusted back into its range.</p>
219  *
220  * <p><strong>Add rule 2</strong>. If a smaller field is expected to be
221  * invariant, but it is impossible for it to be equal to its
222  * prior value because of changes in its minimum or maximum after field
223  * <code>f</code> is changed or other constraints, such as time zone
224  * offset changes, then its value is adjusted to be as close
225  * as possible to its expected value. A smaller field represents a
226  * smaller unit of time. <code>HOUR</code> is a smaller field than
227  * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
228  * that are not expected to be invariant. The calendar system
229  * determines what fields are expected to be invariant.</p>
230  * </blockquote>
231  *
232  * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
233  * an immediate recomputation of the calendar's milliseconds and all
234  * fields.</p>
235  *
236  * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
237  * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
238  * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
239  * 1</strong> sets the <code>MONTH</code> field to September, since
240  * adding 13 months to August gives September of the next year. Since
241  * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
242  * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
243  * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
244  * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
245  * rule 2, since it is expected to change when the month changes in a
246  * <code>GregorianCalendar</code>.</p>
247  *
248  * <p><strong><code>roll(f, delta)</code></strong> adds
249  * <code>delta</code> to field <code>f</code> without changing larger
250  * fields. This is equivalent to calling <code>add(f, delta)</code> with
251  * the following adjustment:</p>
252  *
253  * <blockquote>
254  * <p><strong>Roll rule</strong>. Larger fields are unchanged after the
255  * call. A larger field represents a larger unit of
256  * time. <code>DAY_OF_MONTH</code> is a larger field than
257  * <code>HOUR</code>.</p>
258  * </blockquote>
259  *
260  * <p><em>Example</em>: See {@link java.util.GregorianCalendar#roll(int, int)}.
261  *
262  * <p><strong>Usage model</strong>. To motivate the behavior of
263  * <code>add()</code> and <code>roll()</code>, consider a user interface
264  * component with increment and decrement buttons for the month, day, and
265  * year, and an underlying <code>GregorianCalendar</code>. If the
266  * interface reads January 31, 1999 and the user presses the month
267  * increment button, what should it read? If the underlying
268  * implementation uses <code>set()</code>, it might read March 3, 1999. A
269  * better result would be February 28, 1999. Furthermore, if the user
270  * presses the month increment button again, it should read March 31,
271  * 1999, not March 28, 1999. By saving the original date and using either
272  * <code>add()</code> or <code>roll()</code>, depending on whether larger
273  * fields should be affected, the user interface can behave as most users
274  * will intuitively expect.</p>
275  *
276  * @see java.lang.System#currentTimeMillis()
277  * @see Date
278  * @see GregorianCalendar
279  * @see TimeZone
280  * @see java.text.DateFormat
281  * @version 1.81, 07/26/04
282  * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
283  * @since JDK1.1
284  */
285 public abstract class Calendar implements Serializable , Cloneable , Comparable <Calendar > {
286
287     // Data flow in Calendar
288 // ---------------------
289
290     // The current time is represented in two ways by Calendar: as UTC
291 // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
292 // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the
293 // millis from the fields, and vice versa. The data needed to do this
294 // conversion is encapsulated by a TimeZone object owned by the Calendar.
295 // The data provided by the TimeZone object may also be overridden if the
296 // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
297 // keeps track of what information was most recently set by the caller, and
298 // uses that to compute any other information as needed.
299
300     // If the user sets the fields using set(), the data flow is as follows.
301 // This is implemented by the Calendar subclass's computeTime() method.
302 // During this process, certain fields may be ignored. The disambiguation
303 // algorithm for resolving which fields to pay attention to is described
304 // in the class documentation.
305
306     // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
307 // |
308 // | Using Calendar-specific algorithm
309 // V
310 // local standard millis
311 // |
312 // | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
313 // V
314 // UTC millis (in time data member)
315
316     // If the user sets the UTC millis using setTime() or setTimeInMillis(),
317 // the data flow is as follows. This is implemented by the Calendar
318 // subclass's computeFields() method.
319
320     // UTC millis (in time data member)
321 // |
322 // | Using TimeZone getOffset()
323 // V
324 // local standard millis
325 // |
326 // | Using Calendar-specific algorithm
327 // V
328 // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
329
330     // In general, a round trip from fields, through local and UTC millis, and
331 // back out to fields is made when necessary. This is implemented by the
332 // complete() method. Resolving a partial set of fields into a UTC millis
333 // value allows all remaining fields to be generated from that value. If
334 // the Calendar is lenient, the fields are also renormalized to standard
335 // ranges when they are regenerated.
336
337     /**
338      * Field number for <code>get</code> and <code>set</code> indicating the
339      * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
340      * value; see subclass documentation.
341      *
342      * @see GregorianCalendar#AD
343      * @see GregorianCalendar#BC
344      */
345     public final static int ERA = 0;
346
347     /**
348      * Field number for <code>get</code> and <code>set</code> indicating the
349      * year. This is a calendar-specific value; see subclass documentation.
350      */
351     public final static int YEAR = 1;
352
353     /**
354      * Field number for <code>get</code> and <code>set</code> indicating the
355      * month. This is a calendar-specific value. The first month of the year is
356      * <code>JANUARY</code> which is 0; the last depends on the number of months in a year.
357      *
358      * @see #JANUARY
359      * @see #FEBRUARY
360      * @see #MARCH
361      * @see #APRIL
362      * @see #MAY
363      * @see #JUNE
364      * @see #JULY
365      * @see #AUGUST
366      * @see #SEPTEMBER
367      * @see #OCTOBER
368      * @see #NOVEMBER
369      * @see #DECEMBER
370      * @see #UNDECIMBER
371      */
372     public final static int MONTH = 2;
373
374     /**
375      * Field number for <code>get</code> and <code>set</code> indicating the
376      * week number within the current year. The first week of the year, as
377      * defined by <code>getFirstDayOfWeek()</code> and
378      * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
379      * the value of <code>WEEK_OF_YEAR</code> for days before the first week of
380      * the year.
381      *
382      * @see #getFirstDayOfWeek
383      * @see #getMinimalDaysInFirstWeek
384      */
385     public final static int WEEK_OF_YEAR = 3;
386
387     /**
388      * Field number for <code>get</code> and <code>set</code> indicating the
389      * week number within the current month. The first week of the month, as
390      * defined by <code>getFirstDayOfWeek()</code> and
391      * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
392      * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
393      * the month.
394      *
395      * @see #getFirstDayOfWeek
396      * @see #getMinimalDaysInFirstWeek
397      */
398     public final static int WEEK_OF_MONTH = 4;
399
400     /**
401      * Field number for <code>get</code> and <code>set</code> indicating the
402      * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
403      * The first day of the month has value 1.
404      *
405      * @see #DAY_OF_MONTH
406      */
407     public final static int DATE = 5;
408
409     /**
410      * Field number for <code>get</code> and <code>set</code> indicating the
411      * day of the month. This is a synonym for <code>DATE</code>.
412      * The first day of the month has value 1.
413      *
414      * @see #DATE
415      */
416     public final static int DAY_OF_MONTH = 5;
417
418     /**
419      * Field number for <code>get</code> and <code>set</code> indicating the day
420      * number within the current year. The first day of the year has value 1.
421      */
422     public final static int DAY_OF_YEAR = 6;
423
424     /**
425      * Field number for <code>get</code> and <code>set</code> indicating the day
426      * of the week. This field takes values <code>SUNDAY</code>,
427      * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
428      * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
429      *
430      * @see #SUNDAY
431      * @see #MONDAY
432      * @see #TUESDAY
433      * @see #WEDNESDAY
434      * @see #THURSDAY
435      * @see #FRIDAY
436      * @see #SATURDAY
437      */
438     public final static int DAY_OF_WEEK = 7;
439
440     /**
441      * Field number for <code>get</code> and <code>set</code> indicating the
442      * ordinal number of the day of the week within the current month. Together
443      * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
444      * within a month. Unlike <code>WEEK_OF_MONTH</code> and
445      * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
446      * <code>getFirstDayOfWeek()</code> or
447      * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
448      * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
449      * 1</code>; <code>8</code> through <code>14</code> correspond to
450      * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
451      * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
452      * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
453      * end of the month, so the last Sunday of a month is specified as
454      * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
455      * negative values count backward they will usually be aligned differently
456      * within the month than positive values. For example, if a month has 31
457      * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
458      * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
459      *
460      * @see #DAY_OF_WEEK
461      * @see #WEEK_OF_MONTH
462      */
463     public final static int DAY_OF_WEEK_IN_MONTH = 8;
464
465     /**
466      * Field number for <code>get</code> and <code>set</code> indicating
467      * whether the <code>HOUR</code> is before or after noon.
468      * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
469      *
470      * @see #AM
471      * @see #PM
472      * @see #HOUR
473      */
474     public final static int AM_PM = 9;
475
476     /**
477      * Field number for <code>get</code> and <code>set</code> indicating the
478      * hour of the morning or afternoon. <code>HOUR</code> is used for the
479      * 12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12.
480      * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
481      *
482      * @see #AM_PM
483      * @see #HOUR_OF_DAY
484      */
485     public final static int HOUR = 10;
486
487     /**
488      * Field number for <code>get</code> and <code>set</code> indicating the
489      * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
490      * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
491      *
492      * @see #HOUR
493      */
494     public final static int HOUR_OF_DAY = 11;
495
496     /**
497      * Field number for <code>get</code> and <code>set</code> indicating the
498      * minute within the hour.
499      * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
500      */
501     public final static int MINUTE = 12;
502
503     /**
504      * Field number for <code>get</code> and <code>set</code> indicating the
505      * second within the minute.
506      * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
507      */
508     public final static int SECOND = 13;
509
510     /**
511      * Field number for <code>get</code> and <code>set</code> indicating the
512      * millisecond within the second.
513      * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
514      */
515     public final static int MILLISECOND = 14;
516
517     /**
518      * Field number for <code>get</code> and <code>set</code>
519      * indicating the raw offset from GMT in milliseconds.
520      * <p>
521      * This field reflects the correct GMT offset value of the time
522      * zone of this <code>Calendar</code> if the
523      * <code>TimeZone</code> implementation subclass supports
524      * historical GMT offset changes.
525      */
526     public final static int ZONE_OFFSET = 15;
527
528     /**
529      * Field number for <code>get</code> and <code>set</code> indicating the
530      * daylight savings offset in milliseconds.
531      * <p>
532      * This field reflects the correct daylight saving offset value of
533      * the time zone of this <code>Calendar</code> if the
534      * <code>TimeZone</code> implementation subclass supports
535      * historical Daylight Saving Time schedule changes.
536      */
537     public final static int DST_OFFSET = 16;
538
539     /**
540      * The number of distinct fields recognized by <code>get</code> and <code>set</code>.
541      * Field numbers range from <code>0..FIELD_COUNT-1</code>.
542      */
543     public final static int FIELD_COUNT = 17;
544
545     /**
546      * Value of the {@link #DAY_OF_WEEK} field indicating
547      * Sunday.
548      */
549     public final static int SUNDAY = 1;
550
551     /**
552      * Value of the {@link #DAY_OF_WEEK} field indicating
553      * Monday.
554      */
555     public final static int MONDAY = 2;
556
557     /**
558      * Value of the {@link #DAY_OF_WEEK} field indicating
559      * Tuesday.
560      */
561     public final static int TUESDAY = 3;
562
563     /**
564      * Value of the {@link #DAY_OF_WEEK} field indicating
565      * Wednesday.
566      */
567     public final static int WEDNESDAY = 4;
568
569     /**
570      * Value of the {@link #DAY_OF_WEEK} field indicating
571      * Thursday.
572      */
573     public final static int THURSDAY = 5;
574
575     /**
576      * Value of the {@link #DAY_OF_WEEK} field indicating
577      * Friday.
578      */
579     public final static int FRIDAY = 6;
580
581     /**
582      * Value of the {@link #DAY_OF_WEEK} field indicating
583      * Saturday.
584      */
585     public final static int SATURDAY = 7;
586
587     /**
588      * Value of the {@link #MONTH} field indicating the
589      * first month of the year.
590      */
591     public final static int JANUARY = 0;
592
593     /**
594      * Value of the {@link #MONTH} field indicating the
595      * second month of the year.
596      */
597     public final static int FEBRUARY = 1;
598
599     /**
600      * Value of the {@link #MONTH} field indicating the
601      * third month of the year.
602      */
603     public final static int MARCH = 2;
604
605     /**
606      * Value of the {@link #MONTH} field indicating the
607      * fourth month of the year.
608      */
609     public final static int APRIL = 3;
610
611     /**
612      * Value of the {@link #MONTH} field indicating the
613      * fifth month of the year.
614      */
615     public final static int MAY = 4;
616
617     /**
618      * Value of the {@link #MONTH} field indicating the
619      * sixth month of the year.
620      */
621     public final static int JUNE = 5;
622
623     /**
624      * Value of the {@link #MONTH} field indicating the
625      * seventh month of the year.
626      */
627     public final static int JULY = 6;
628
629     /**
630      * Value of the {@link #MONTH} field indicating the
631      * eighth month of the year.
632      */
633     public final static int AUGUST = 7;
634
635     /**
636      * Value of the {@link #MONTH} field indicating the
637      * ninth month of the year.
638      */
639     public final static int SEPTEMBER = 8;
640
641     /**
642      * Value of the {@link #MONTH} field indicating the
643      * tenth month of the year.
644      */
645     public final static int OCTOBER = 9;
646
647     /**
648      * Value of the {@link #MONTH} field indicating the
649      * eleventh month of the year.
650      */
651     public final static int NOVEMBER = 10;
652
653     /**
654      * Value of the {@link #MONTH} field indicating the
655      * twelfth month of the year.
656      */
657     public final static int DECEMBER = 11;
658
659     /**
660      * Value of the {@link #MONTH} field indicating the
661      * thirteenth month of the year. Although <code>GregorianCalendar</code>
662      * does not use this value, lunar calendars do.
663      */
664     public final static int UNDECIMBER = 12;
665
666     /**
667      * Value of the {@link #AM_PM} field indicating the
668      * period of the day from midnight to just before noon.
669      */
670     public final static int AM = 0;
671
672     /**
673      * Value of the {@link #AM_PM} field indicating the
674      * period of the day from noon to just before midnight.
675      */
676     public final static int PM = 1;
677
678     // Internal notes:
679 // Calendar contains two kinds of time representations: current "time" in
680 // milliseconds, and a set of calendar "fields" representing the current time.
681 // The two representations are usually in sync, but can get out of sync
682 // as follows.
683 // 1. Initially, no fields are set, and the time is invalid.
684 // 2. If the time is set, all fields are computed and in sync.
685 // 3. If a single field is set, the time is invalid.
686 // Recomputation of the time and fields happens when the object needs
687 // to return a result to the user, or use a result for a computation.
688
689     /**
690      * The calendar field values for the currently set time for this calendar.
691      * This is an array of <code>FIELD_COUNT</code> integers, with index values
692      * <code>ERA</code> through <code>DST_OFFSET</code>.
693      * @serial
694      */
695     protected int fields[];
696
697     /**
698      * The flags which tell if a specified calendar field for the calendar is set.
699      * A new object has no fields set. After the first call to a method
700      * which generates the fields, they all remain set after that.
701      * This is an array of <code>FIELD_COUNT</code> booleans, with index values
702      * <code>ERA</code> through <code>DST_OFFSET</code>.
703      * @serial
704      */
705     protected boolean isSet[];
706
707     /**
708      * Pseudo-time-stamps which specify when each field was set. There
709      * are two special values, UNSET and COMPUTED. Values from
710      * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.
711      */
712     transient private int stamp[];
713
714     /**
715      * The currently set time for this calendar, expressed in milliseconds after
716      * January 1, 1970, 0:00:00 GMT.
717      * @see #isTimeSet
718      * @serial
719      */
720     protected long time;
721
722     /**
723      * True if then the value of <code>time</code> is valid.
724      * The time is made invalid by a change to an item of <code>field[]</code>.
725      * @see #time
726      * @serial
727      */
728     protected boolean isTimeSet;
729
730     /**
731      * True if <code>fields[]</code> are in sync with the currently set time.
732      * If false, then the next attempt to get the value of a field will
733      * force a recomputation of all fields from the current value of
734      * <code>time</code>.
735      * @serial
736      */
737     protected boolean areFieldsSet;
738
739     /**
740      * True if all fields have been set.
741      * @serial
742      */
743     transient boolean areAllFieldsSet;
744
745     /**
746      * <code>True</code> if this calendar allows out-of-range field values during computation
747      * of <code>time</code> from <code>fields[]</code>.
748      * @see #setLenient
749      * @see #isLenient
750      * @serial
751      */
752     private boolean lenient = true;
753
754     /**
755      * The <code>TimeZone</code> used by this calendar. <code>Calendar</code>
756      * uses the time zone data to translate between locale and GMT time.
757      * @serial
758      */
759     private TimeZone zone;
760
761     /**
762      * <code>True</code> if zone references to a shared TimeZone object.
763      */
764     transient private boolean sharedZone = false;
765
766     /**
767      * The first day of the week, with possible values <code>SUNDAY</code>,
768      * <code>MONDAY</code>, etc. This is a locale-dependent value.
769      * @serial
770      */
771     private int firstDayOfWeek;
772
773     /**
774      * The number of days required for the first week in a month or year,
775      * with possible values from 1 to 7. This is a locale-dependent value.
776      * @serial
777      */
778     private int minimalDaysInFirstWeek;
779
780     /**
781      * Cache to hold the firstDayOfWeek and minimalDaysInFirstWeek
782      * of a Locale.
783      */
784     private static Hashtable <Locale , int[]> cachedLocaleData = new Hashtable <Locale , int[]>(3);
785
786     // Special values of stamp[]
787 /**
788      * The corresponding fields[] has no value.
789      */
790     private static final int UNSET = 0;
791
792     /**
793      * The value of the corresponding fields[] has been calculated internally.
794      */
795     private static final int COMPUTED = 1;
796
797     /**
798      * The value of the corresponding fields[] has been set externally. Stamp
799      * values which are greater than 1 represents the (pseudo) time when the
800      * corresponding fields[] value was set.
801      */
802     private static final int MINIMUM_USER_STAMP = 2;
803
804     /**
805      * The mask value that represents all of the fields.
806      */
807     static final int ALL_FIELDS = (1 << FIELD_COUNT) - 1;
808
809     /**
810      * The next available value for <code>stamp[]</code>, an internal array.
811      * This actually should not be written out to the stream, and will probably
812      * be removed from the stream in the near future. In the meantime,
813      * a value of <code>MINIMUM_USER_STAMP</code> should be used.
814      * @serial
815      */
816     private int nextStamp = MINIMUM_USER_STAMP;
817
818     // the internal serial version which says which version was written
819 // - 0 (default) for version up to JDK 1.1.5
820 // - 1 for version from JDK 1.1.6, which writes a correct 'time' value
821 // as well as compatible values for other fields. This is a
822 // transitional format.
823 // - 2 (not implemented yet) a future version, in which fields[],
824 // areFieldsSet, and isTimeSet become transient, and isSet[] is
825 // removed. In JDK 1.1.6 we write a format compatible with version 2.
826 static final int currentSerialVersion = 1;
827     
828     /**
829      * The version of the serialized data on the stream. Possible values:
830      * <dl>
831      * <dt><b>0</b> or not present on stream</dt>
832      * <dd>
833      * JDK 1.1.5 or earlier.
834      * </dd>
835      * <dt><b>1</b></dt>
836      * <dd>
837      * JDK 1.1.6 or later. Writes a correct 'time' value
838      * as well as compatible values for other fields. This is a
839      * transitional format.
840      * </dd>
841      * </dl>
842      * When streaming out this class, the most recent format
843      * and the highest allowable <code>serialVersionOnStream</code>
844      * is written.
845      * @serial
846      * @since JDK1.1.6
847      */
848     private int serialVersionOnStream = currentSerialVersion;
849
850     // Proclaim serialization compatibility with JDK 1.1
851 static final long serialVersionUID = -1807547505821590642L;
852
853     // Mask values for calendar fields
854 final static int ERA_MASK = (1 << ERA);
855     final static int YEAR_MASK = (1 << YEAR);
856     final static int MONTH_MASK = (1 << MONTH);
857     final static int WEEK_OF_YEAR_MASK = (1 << WEEK_OF_YEAR);
858     final static int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
859     final static int DAY_OF_MONTH_MASK = (1 << DAY_OF_MONTH);
860     final static int DATE_MASK = DAY_OF_MONTH_MASK;
861     final static int DAY_OF_YEAR_MASK = (1 << DAY_OF_YEAR);
862     final static int DAY_OF_WEEK_MASK = (1 << DAY_OF_WEEK);
863     final static int DAY_OF_WEEK_IN_MONTH_MASK = (1 << DAY_OF_WEEK_IN_MONTH);
864     final static int AM_PM_MASK = (1 << AM_PM);
865     final static int HOUR_MASK = (1 << HOUR);
866     final static int HOUR_OF_DAY_MASK = (1 << HOUR_OF_DAY);
867     final static int MINUTE_MASK = (1 << MINUTE);
868     final static int SECOND_MASK = (1 << SECOND);
869     final static int MILLISECOND_MASK = (1 << MILLISECOND);
870     final static int ZONE_OFFSET_MASK = (1 << ZONE_OFFSET);
871     final static int DST_OFFSET_MASK = (1 << DST_OFFSET);
872
873     /**
874      * Constructs a Calendar with the default time zone
875      * and locale.
876      * @see TimeZone#getDefault
877      */
878     protected Calendar()
879     {
880         this(TimeZone.getDefaultRef(), Locale.getDefault());
881     sharedZone = true;
882     }
883
884     /**
885      * Constructs a calendar with the specified time zone and locale.
886      *
887      * @param zone the time zone to use
888      * @param aLocale the locale for the week data
889      */
890     protected Calendar(TimeZone zone, Locale aLocale)
891     {
892         fields = new int[FIELD_COUNT];
893         isSet = new boolean[FIELD_COUNT];
894         stamp = new int[FIELD_COUNT];
895
896         this.zone = zone;
897         setWeekCountData(aLocale);
898     }
899
900     /**
901      * Gets a calendar using the default time zone and locale. The
902      * <code>Calendar</code> returned is based on the current time
903      * in the default time zone with the default locale.
904      *
905      * @return a Calendar.
906      */
907     public static Calendar getInstance()
908     {
909         Calendar cal = createCalendar(TimeZone.getDefaultRef(), Locale.getDefault());
910     cal.sharedZone = true;
911     return cal;
912     }
913
914     /**
915      * Gets a calendar using the specified time zone and default locale.
916      * The <code>Calendar</code> returned is based on the current time
917      * in the given time zone with the default locale.
918      *
919      * @param zone the time zone to use
920      * @return a Calendar.
921      */
922     public static Calendar getInstance(TimeZone zone)
923     {
924         return createCalendar(zone, Locale.getDefault());
925     }
926
927     /**
928      * Gets a calendar using the default time zone and specified locale.
929      * The <code>Calendar</code> returned is based on the current time
930      * in the default time zone with the given locale.
931      *
932      * @param aLocale the locale for the week data
933      * @return a Calendar.
934      */
935     public static Calendar getInstance(Locale aLocale)
936     {
937         Calendar cal = createCalendar(TimeZone.getDefaultRef(), aLocale);
938     cal.sharedZone = true;
939     return cal;
940     }
941
942     /**
943      * Gets a calendar with the specified time zone and locale.
944      * The <code>Calendar</code> returned is based on the current time
945      * in the given time zone with the given locale.
946      *
947      * @param zone the time zone to use
948      * @param aLocale the locale for the week data
949      * @return a Calendar.
950      */
951     public static Calendar getInstance(TimeZone zone,
952                        Locale aLocale)
953     {
954     return createCalendar(zone, aLocale);
955     }
956
957     private static Calendar createCalendar(TimeZone zone,
958                        Locale aLocale)
959     {
960     // If the specified locale is a Thai locale, returns a BuddhistCalendar
961 // instance.
962 if ("th".equals(aLocale.getLanguage())
963         && ("TH".equals(aLocale.getCountry()))) {
964         return new sun.util.BuddhistCalendar(zone, aLocale);
965     }
966
967     // else create the default calendar
968 return new GregorianCalendar (zone, aLocale);
969     }
970
971     /**
972      * Returns an array of all locales for which the <code>getInstance</code>
973      * methods of this class can return localized instances.
974      * The array returned must contain at least a <code>Locale</code>
975      * instance equal to {@link java.util.Locale#US Locale.US}.
976      *
977      * @return An array of locales for which localized
978      * <code>Calendar</code> instances are available.
979      */
980     public static synchronized Locale [] getAvailableLocales()
981     {
982         return DateFormat.getAvailableLocales();
983     }
984
985     /**
986      * Converts the current calendar field values in {@link #fields fields[]}
987      * to the millisecond time value
988      * {@link #time}.
989      *
990      * @see #complete()
991      * @see #computeFields()
992      */
993     protected abstract void computeTime();
994
995     /**
996      * Converts the current millisecond time value {@link #time}
997      * to calendar field values in {@link #fields fields[]}.
998      * This allows you to sync up the calendar field values with
999      * a new time that is set for the calendar. The time is <em>not</em>
1000     * recomputed first; to recompute the time, then the fields, call the
1001     * {@link #complete()} method.
1002     *
1003     * @see #computeTime()
1004     */
1005    protected abstract void computeFields();
1006
1007    /**
1008     * Returns a <code>Date</code> object representing this
1009     * <code>Calendar</code>'s time value (millisecond offset from the <a
1010     * HREF="#Epoch">Epoch</a>").
1011     *
1012     * @return a <code>Date</code> representing the time value.
1013     * @see #setTime(Date)
1014     * @see #getTimeInMillis()
1015     */
1016    public final Date getTime() {
1017        return new Date (getTimeInMillis());
1018    }
1019
1020    /**
1021     * Sets this Calendar's time with the given <code>Date</code>.
1022     * <p>
1023     * Note: Calling <code>setTime()</code> with
1024     * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
1025     * may yield incorrect field values from <code>get()</code>.
1026     *
1027     * @param date the given Date.
1028     * @see #getTime()
1029     * @see #setTimeInMillis(long)
1030     */
1031    public final void setTime(Date