Java > Open Source Codes > java > util > GregorianCalendar


1 /*
2  * @(#)GregorianCalendar.java 1.90 06/07/31
3  *
4  * Copyright 2005 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 sun.util.calendar.BaseCalendar;
26 import sun.util.calendar.CalendarDate;
27 import sun.util.calendar.CalendarSystem;
28 import sun.util.calendar.CalendarUtils;
29 import sun.util.calendar.Era;
30 import sun.util.calendar.Gregorian;
31 import sun.util.calendar.JulianCalendar;
32 import sun.util.calendar.ZoneInfo;
33
34 /**
35  * <code>GregorianCalendar</code> is a concrete subclass of
36  * <code>Calendar</code> and provides the standard calendar system
37  * used by most of the world.
38  *
39  * <p> <code>GregorianCalendar</code> is a hybrid calendar that
40  * supports both the Julian and Gregorian calendar systems with the
41  * support of a single discontinuity, which corresponds by default to
42  * the Gregorian date when the Gregorian calendar was instituted
43  * (October 15, 1582 in some countries, later in others). The cutover
44  * date may be changed by the caller by calling {@link
45  * #setGregorianChange(Date) setGregorianChange()}.
46  *
47  * <p>
48  * Historically, in those countries which adopted the Gregorian calendar first,
49  * October 4, 1582 (Julian) was thus followed by October 15, 1582 (Gregorian). This calendar models
50  * this correctly. Before the Gregorian cutover, <code>GregorianCalendar</code>
51  * implements the Julian calendar. The only difference between the Gregorian
52  * and the Julian calendar is the leap year rule. The Julian calendar specifies
53  * leap years every four years, whereas the Gregorian calendar omits century
54  * years which are not divisible by 400.
55  *
56  * <p>
57  * <code>GregorianCalendar</code> implements <em>proleptic</em> Gregorian and
58  * Julian calendars. That is, dates are computed by extrapolating the current
59  * rules indefinitely far backward and forward in time. As a result,
60  * <code>GregorianCalendar</code> may be used for all years to generate
61  * meaningful and consistent results. However, dates obtained using
62  * <code>GregorianCalendar</code> are historically accurate only from March 1, 4
63  * AD onward, when modern Julian calendar rules were adopted. Before this date,
64  * leap year rules were applied irregularly, and before 45 BC the Julian
65  * calendar did not even exist.
66  *
67  * <p>
68  * Prior to the institution of the Gregorian calendar, New Year's Day was
69  * March 25. To avoid confusion, this calendar always uses January 1. A manual
70  * adjustment may be made if desired for dates that are prior to the Gregorian
71  * changeover and which fall between January 1 and March 24.
72  *
73  * <p>Values calculated for the <code>WEEK_OF_YEAR</code> field range from 1 to
74  * 53. Week 1 for a year is the earliest seven day period starting on
75  * <code>getFirstDayOfWeek()</code> that contains at least
76  * <code>getMinimalDaysInFirstWeek()</code> days from that year. It thus
77  * depends on the values of <code>getMinimalDaysInFirstWeek()</code>,
78  * <code>getFirstDayOfWeek()</code>, and the day of the week of January 1.
79  * Weeks between week 1 of one year and week 1 of the following year are
80  * numbered sequentially from 2 to 52 or 53 (as needed).
81
82  * <p>For example, January 1, 1998 was a Thursday. If
83  * <code>getFirstDayOfWeek()</code> is <code>MONDAY</code> and
84  * <code>getMinimalDaysInFirstWeek()</code> is 4 (these are the values
85  * reflecting ISO 8601 and many national standards), then week 1 of 1998 starts
86  * on December 29, 1997, and ends on January 4, 1998. If, however,
87  * <code>getFirstDayOfWeek()</code> is <code>SUNDAY</code>, then week 1 of 1998
88  * starts on January 4, 1998, and ends on January 10, 1998; the first three days
89  * of 1998 then are part of week 53 of 1997.
90  *
91  * <p>Values calculated for the <code>WEEK_OF_MONTH</code> field range from 0
92  * to 6. Week 1 of a month (the days with <code>WEEK_OF_MONTH =
93  * 1</code>) is the earliest set of at least
94  * <code>getMinimalDaysInFirstWeek()</code> contiguous days in that month,
95  * ending on the day before <code>getFirstDayOfWeek()</code>. Unlike
96  * week 1 of a year, week 1 of a month may be shorter than 7 days, need
97  * not start on <code>getFirstDayOfWeek()</code>, and will not include days of
98  * the previous month. Days of a month before week 1 have a
99  * <code>WEEK_OF_MONTH</code> of 0.
100  *
101  * <p>For example, if <code>getFirstDayOfWeek()</code> is <code>SUNDAY</code>
102  * and <code>getMinimalDaysInFirstWeek()</code> is 4, then the first week of
103  * January 1998 is Sunday, January 4 through Saturday, January 10. These days
104  * have a <code>WEEK_OF_MONTH</code> of 1. Thursday, January 1 through
105  * Saturday, January 3 have a <code>WEEK_OF_MONTH</code> of 0. If
106  * <code>getMinimalDaysInFirstWeek()</code> is changed to 3, then January 1
107  * through January 3 have a <code>WEEK_OF_MONTH</code> of 1.
108  *
109  * <p>The <code>clear</code> methods set calendar field(s)
110  * undefined. <code>GregorianCalendar</code> uses the following
111  * default value for each calendar field if its value is undefined.
112  *
113  * <table cellpadding="0" cellspacing="3" border="0"
114  * summary="GregorianCalendar default field values"
115  * style="text-align: left; width: 66%;">
116  * <tbody>
117  * <tr>
118  * <th style="vertical-align: top; background-color: rgb(204, 204, 255);
119  * text-align: center;">Field<br>
120  * </th>
121  * <th style="vertical-align: top; background-color: rgb(204, 204, 255);
122  * text-align: center;">Default Value<br>
123  * </th>
124  * </tr>
125  * <tr>
126  * <td style="vertical-align: middle;">
127  * <code>ERA<br></code>
128  * </td>
129  * <td style="vertical-align: middle;">
130  * <code>AD<br></code>
131  * </td>
132  * </tr>
133  * <tr>
134  * <td style="vertical-align: middle; background-color: rgb(238, 238, 255);">
135  * <code>YEAR<br></code>
136  * </td>
137  * <td style="vertical-align: middle; background-color: rgb(238, 238, 255);">
138  * <code>1970<br></code>
139  * </td>
140  * </tr>
141  * <tr>
142  * <td style="vertical-align: middle;">
143  * <code>MONTH<br></code>
144  * </td>
145  * <td style="vertical-align: middle;">
146  * <code>JANUARY<br></code>
147  * </td>
148  * </tr>
149  * <tr>
150  * <td style="vertical-align: top; background-color: rgb(238, 238, 255);">
151  * <code>DAY_OF_MONTH<br></code>
152  * </td>
153  * <td style="vertical-align: top; background-color: rgb(238, 238, 255);">
154  * <code>1<br></code>
155  * </td>
156  * </tr>
157  * <tr>
158  * <td style="vertical-align: middle;">
159  * <code>DAY_OF_WEEK<br></code>
160  * </td>
161  * <td style="vertical-align: middle;">
162  * <code>the first day of week<br></code>
163  * </td>
164  * </tr>
165  * <tr>
166  * <td style="vertical-align: top; background-color: rgb(238, 238, 255);">
167  * <code>WEEK_OF_MONTH<br></code>
168  * </td>
169  * <td style="vertical-align: top; background-color: rgb(238, 238, 255);">
170  * <code>0<br></code>
171  * </td>
172  * </tr>
173  * <tr>
174  * <td style="vertical-align: top;">
175  * <code>DAY_OF_WEEK_IN_MONTH<br></code>
176  * </td>
177  * <td style="vertical-align: top;">
178  * <code>1<br></code>
179  * </td>
180  * </tr>
181  * <tr>
182  * <td style="vertical-align: middle; background-color: rgb(238, 238, 255);">
183  * <code>AM_PM<br></code>
184  * </td>
185  * <td style="vertical-align: middle; background-color: rgb(238, 238, 255);">
186  * <code>AM<br></code>
187  * </td>
188  * </tr>
189  * <tr>
190  * <td style="vertical-align: middle;">
191  * <code>HOUR, HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND<br></code>
192  * </td>
193  * <td style="vertical-align: middle;">
194  * <code>0<br></code>
195  * </td>
196  * </tr>
197  * </tbody>
198  * </table>
199  * <br>Default values are not applicable for the fields not listed above.
200  *
201  * <p>
202  * <strong>Example:</strong>
203  * <blockquote>
204  * <pre>
205  * // get the supported ids for GMT-08:00 (Pacific Standard Time)
206  * String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
207  * // if no ids were returned, something is wrong. get out.
208  * if (ids.length == 0)
209  * System.exit(0);
210  *
211  * // begin output
212  * System.out.println("Current Time");
213  *
214  * // create a Pacific Standard Time time zone
215  * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
216  *
217  * // set up rules for daylight savings time
218  * pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
219  * pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
220  *
221  * // create a GregorianCalendar with the Pacific Daylight time zone
222  * // and the current date and time
223  * Calendar calendar = new GregorianCalendar(pdt);
224  * Date trialTime = new Date();
225  * calendar.setTime(trialTime);
226  *
227  * // print out a bunch of interesting things
228  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
229  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
230  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
231  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
232  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
233  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
234  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
235  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
236  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
237  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
238  * + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
239  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
240  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
241  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
242  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
243  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
244  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
245  * System.out.println("ZONE_OFFSET: "
246  * + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
247  * System.out.println("DST_OFFSET: "
248  * + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
249
250  * System.out.println("Current Time, with hour reset to 3");
251  * calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
252  * calendar.set(Calendar.HOUR, 3);
253  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
254  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
255  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
256  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
257  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
258  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
259  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
260  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
261  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
262  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
263  * + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
264  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
265  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
266  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
267  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
268  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
269  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
270  * System.out.println("ZONE_OFFSET: "
271  * + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
272  * System.out.println("DST_OFFSET: "
273  * + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
274  * </pre>
275  * </blockquote>
276  *
277  * @see TimeZone
278  * @version 1.90
279  * @author David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu
280  * @since JDK1.1
281  */
282 public class GregorianCalendar extends Calendar {
283     /*
284      * Implementation Notes
285      *
286      * The epoch is the number of days or milliseconds from some defined
287      * starting point. The epoch for java.util.Date is used here; that is,
288      * milliseconds from January 1, 1970 (Gregorian), midnight UTC. Other
289      * epochs which are used are January 1, year 1 (Gregorian), which is day 1
290      * of the Gregorian calendar, and December 30, year 0 (Gregorian), which is
291      * day 1 of the Julian calendar.
292      *
293      * We implement the proleptic Julian and Gregorian calendars. This means we
294      * implement the modern definition of the calendar even though the
295      * historical usage differs. For example, if the Gregorian change is set
296      * to new Date(Long.MIN_VALUE), we have a pure Gregorian calendar which
297      * labels dates preceding the invention of the Gregorian calendar in 1582 as
298      * if the calendar existed then.
299      *
300      * Likewise, with the Julian calendar, we assume a consistent
301      * 4-year leap year rule, even though the historical pattern of
302      * leap years is irregular, being every 3 years from 45 BCE
303      * through 9 BCE, then every 4 years from 8 CE onwards, with no
304      * leap years in-between. Thus date computations and functions
305      * such as isLeapYear() are not intended to be historically
306      * accurate.
307      */
308
309 //////////////////
310 // Class Variables
311 //////////////////
312
313     /**
314      * Value of the <code>ERA</code> field indicating
315      * the period before the common era (before Christ), also known as BCE.
316      * The sequence of years at the transition from <code>BC</code> to <code>AD</code> is
317      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
318      *
319      * @see #ERA
320      */
321     public static final int BC = 0;
322
323     /**
324      * Value of the {@link #ERA} field indicating
325      * the period before the common era, the same value as {@link #BC}.
326      *
327      * @see #CE
328      */
329     static final int BCE = 0;
330
331     /**
332      * Value of the <code>ERA</code> field indicating
333      * the common era (Anno Domini), also known as CE.
334      * The sequence of years at the transition from <code>BC</code> to <code>AD</code> is
335      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
336      *
337      * @see #ERA
338      */
339     public static final int AD = 1;
340
341     /**
342      * Value of the {@link #ERA} field indicating
343      * the common era, the same value as {@link #AD}.
344      *
345      * @see #BCE
346      */
347     static final int CE = 1;
348
349     private static final int EPOCH_OFFSET = 719163; // Fixed date of January 1, 1970 (Gregorian)
350 private static final int EPOCH_YEAR = 1970;
351
352     static final int MONTH_LENGTH[]
353         = {31,28,31,30,31,30,31,31,30,31,30,31}; // 0-based
354 static final int LEAP_MONTH_LENGTH[]
355         = {31,29,31,30,31,30,31,31,30,31,30,31}; // 0-based
356
357     // Useful millisecond constants. Although ONE_DAY and ONE_WEEK can fit
358 // into ints, they must be longs in order to prevent arithmetic overflow
359 // when performing (bug 4173516).
360 private static final int ONE_SECOND = 1000;
361     private static final int ONE_MINUTE = 60*ONE_SECOND;
362     private static final int ONE_HOUR = 60*ONE_MINUTE;
363     private static final long ONE_DAY = 24*ONE_HOUR;
364     private static final long ONE_WEEK = 7*ONE_DAY;
365
366     /*
367      * <pre>
368      * Greatest Least
369      * Field name Minimum Minimum Maximum Maximum
370      * ---------- ------- ------- ------- -------
371      * ERA 0 0 1 1
372      * YEAR 1 1 292269054 292278994
373      * MONTH 0 0 11 11
374      * WEEK_OF_YEAR 1 1 52* 53
375      * WEEK_OF_MONTH 0 0 4* 6
376      * DAY_OF_MONTH 1 1 28* 31
377      * DAY_OF_YEAR 1 1 365* 366
378      * DAY_OF_WEEK 1 1 7 7
379      * DAY_OF_WEEK_IN_MONTH -1 -1 4* 6
380      * AM_PM 0 0 1 1
381      * HOUR 0 0 11 11
382      * HOUR_OF_DAY 0 0 23 23
383      * MINUTE 0 0 59 59
384      * SECOND 0 0 59 59
385      * MILLISECOND 0 0 999 999
386      * ZONE_OFFSET -13:00 -13:00 14:00 14:00
387      * DST_OFFSET 0:00 0:00 0:20 2:00
388      * </pre>
389      * *: depends on the Gregorian change date
390      */
391     static final int MIN_VALUES[] = {
392         BCE, // ERA
393 1, // YEAR
394 JANUARY, // MONTH
395 1, // WEEK_OF_YEAR
396 0, // WEEK_OF_MONTH
397 1, // DAY_OF_MONTH
398 1, // DAY_OF_YEAR
399 SUNDAY, // DAY_OF_WEEK
400 1, // DAY_OF_WEEK_IN_MONTH
401 AM, // AM_PM
402 0, // HOUR
403 0, // HOUR_OF_DAY
404 0, // MINUTE
405 0, // SECOND
406 0, // MILLISECOND
407 -13*ONE_HOUR, // ZONE_OFFSET (UNIX compatibility)
408 0 // DST_OFFSET
409 };
410     static final int LEAST_MAX_VALUES[] = {
411         CE, // ERA
412 292269054, // YEAR
413 DECEMBER, // MONTH
414 52, // WEEK_OF_YEAR
415 4, // WEEK_OF_MONTH
416 28, // DAY_OF_MONTH
417 365, // DAY_OF_YEAR
418 SATURDAY, // DAY_OF_WEEK
419 4, // DAY_OF_WEEK_IN
420 PM, // AM_PM
421 11, // HOUR
422 23, // HOUR_OF_DAY
423 59, // MINUTE
424 59, // SECOND
425 999, // MILLISECOND
426 14*ONE_HOUR, // ZONE_OFFSET
427 20*ONE_MINUTE // DST_OFFSET (historical least maximum)
428 };
429     static final int MAX_VALUES[] = {
430         CE, // ERA
431 292278994, // YEAR
432 DECEMBER, // MONTH
433 53, // WEEK_OF_YEAR
434 6, // WEEK_OF_MONTH
435 31, // DAY_OF_MONTH
436 366, // DAY_OF_YEAR
437 SATURDAY, // DAY_OF_WEEK
438 6, // DAY_OF_WEEK_IN
439 PM, // AM_PM
440 11, // HOUR
441 23, // HOUR_OF_DAY
442 59, // MINUTE
443 59, // SECOND
444 999, // MILLISECOND
445 14*ONE_HOUR, // ZONE_OFFSET
446 2*ONE_HOUR // DST_OFFSET (double summer time)
447 };
448
449     // Proclaim serialization compatibility with JDK 1.1
450 static final long serialVersionUID = -8125100834729963327L;
451
452     // Reference to the sun.util.calendar.Gregorian instance (singleton).
453 private static final Gregorian gcal =
454                 CalendarSystem.getGregorianCalendar();
455
456     // Reference to the JulianCalendar instance (singleton), set as needed. See
457 // getJulianCalendarSystem().
458 private static JulianCalendar jcal;
459
460     // JulianCalendar eras. See getJulianCalendarSystem().
461 private static Era[] jeras;
462
463     // The default value of gregorianCutover.
464 static final long DEFAULT_GREGORIAN_CUTOVER = -12219292800000L;
465
466 /////////////////////
467 // Instance Variables
468 /////////////////////
469
470     /**
471      * The point at which the Gregorian calendar rules are used, measured in
472      * milliseconds from the standard epoch. Default is October 15, 1582
473      * (Gregorian) 00:00:00 UTC or -12219292800000L. For this value, October 4,
474      * 1582 (Julian) is followed by October 15, 1582 (Gregorian). This
475      * corresponds to Julian day number 2299161.
476      * @serial
477      */
478     private long gregorianCutover = DEFAULT_GREGORIAN_CUTOVER;
479
480     /**
481      * The fixed date of the gregorianCutover.
482      */
483     private transient long gregorianCutoverDate =
484         (((DEFAULT_GREGORIAN_CUTOVER + 1)/ONE_DAY) - 1) + EPOCH_OFFSET; // == 577736
485
486     /**
487      * The normalized year of the gregorianCutover in Gregorian, with
488      * 0 representing 1 BCE, -1 representing 2 BCE, etc.
489      */
490     private transient int gregorianCutoverYear = 1582;
491
492     /**
493      * The normalized year of the gregorianCutover in Julian, with 0
494      * representing 1 BCE, -1 representing 2 BCE, etc.
495      */
496     private transient int gregorianCutoverYearJulian = 1582;
497
498     /**
499      * gdate always has a sun.util.calendar.Gregorian.Date instance to
500      * avoid overhead of creating it. The assumption is that most
501      * applications will need only Gregorian calendar calculations.
502      */
503     private transient BaseCalendar.Date gdate;
504
505     /**
506      * Reference to either gdate or a JulianCalendar.Date
507      * instance. After calling complete(), this value is guaranteed to
508      * be set.
509      */
510     private transient BaseCalendar.Date cdate;
511
512     /**
513      * The CalendarSystem used to calculate the date in cdate. After
514      * calling complete(), this value is guaranteed to be set and
515      * consistent with the cdate value.
516      */
517     private transient BaseCalendar calsys;
518
519     /**
520      * Temporary int[2] to get time zone offsets. zoneOffsets[0] gets
521      * the GMT offset value and zoneOffsets[1] gets the DST saving
522      * value.
523      */
524     private transient int[] zoneOffsets;
525
526     /**
527      * Temporary storage for saving original fields[] values in
528      * non-lenient mode.
529      */
530     private transient int[] originalFields;
531
532 ///////////////
533 // Constructors
534 ///////////////
535
536     /**
537      * Constructs a default <code>GregorianCalendar</code> using the current time
538      * in the default time zone with the default locale.
539      */
540     public GregorianCalendar() {
541         this(TimeZone.getDefaultRef(), Locale.getDefault());
542     setZoneShared(true);
543     }
544
545     /**
546      * Constructs a <code>GregorianCalendar</code> based on the current time
547      * in the given time zone with the default locale.
548      *
549      * @param zone the given time zone.
550      */
551     public GregorianCalendar(TimeZone zone) {
552         this(zone, Locale.getDefault());
553     }
554
555     /**
556      * Constructs a <code>GregorianCalendar</code> based on the current time
557      * in the default time zone with the given locale.
558      *
559      * @param aLocale the given locale.
560      */
561     public GregorianCalendar(Locale aLocale) {
562         this(TimeZone.getDefaultRef(), aLocale);
563     setZoneShared(true);
564     }
565
566     /**
567      * Constructs a <code>GregorianCalendar</code> based on the current time
568      * in the given time zone with the given locale.
569      *
570      * @param zone the given time zone.
571      * @param aLocale the given locale.
572      */
573     public GregorianCalendar(TimeZone zone, Locale aLocale) {
574         super(zone, aLocale);
575     gdate = (BaseCalendar.Date) gcal.newCalendarDate(zone);
576         setTimeInMillis(System.currentTimeMillis());
577     }
578
579     /**
580      * Constructs a <code>GregorianCalendar</code> with the given date set
581      * in the default time zone with the default locale.
582      *
583      * @param year the value used to set the <code>YEAR</code> calendar field in the calendar.
584      * @param month the value used to set the <code>MONTH</code> calendar field in the calendar.
585      * Month value is 0-based. e.g., 0 for January.
586      * @param dayOfMonth the value used to set the <code>DAY_OF_MONTH</code> calendar field in the calendar.
587      */
588     public GregorianCalendar(int year, int month, int dayOfMonth) {
589     this(year, month, dayOfMonth, 0, 0, 0, 0);
590     }
591
592     /**
593      * Constructs a <code>GregorianCalendar</code> with the given date
594      * and time set for the default time zone with the default locale.
595      *
596      * @param year the value used to set the <code>YEAR</code> calendar field in the calendar.
597      * @param month the value used to set the <code>MONTH</code> calendar field in the calendar.
598      * Month value is 0-based. e.g., 0 for January.
599      * @param dayOfMonth the value used to set the <code>DAY_OF_MONTH</code> calendar field in the calendar.
600      * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field
601      * in the calendar.
602      * @param minute the value used to set the <code>MINUTE</code> calendar field
603      * in the calendar.
604      */
605     public GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay,
606                              int minute) {
607     this(year, month, dayOfMonth, hourOfDay, minute, 0, 0);
608     }
609
610     /**
611      * Constructs a GregorianCalendar with the given date
612      * and time set for the default time zone with the default locale.
613      *
614      * @param year the value used to set the <code>YEAR</code> calendar field in the calendar.
615      * @param month the value used to set the <code>MONTH</code> calendar field in the calendar.
616      * Month value is 0-based. e.g., 0 for January.
617      * @param dayOfMonth the value used to set the <code>DAY_OF_MONTH</code> calendar field in the calendar.
618      * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field
619      * in the calendar.
620      * @param minute the value used to set the <code>MINUTE</code> calendar field
621      * in the calendar.
622      * @param second the value used to set the <code>SECOND</code> calendar field
623      * in the calendar.
624      */
625     public GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay,
626                              int minute, int second) {
627     this(year, month, dayOfMonth, hourOfDay, minute, second, 0);
628     }
629
630     /**
631      * Constructs a <code>GregorianCalendar</code> with the given date
632      * and time set for the default time zone with the default locale.
633      *
634      * @param year the value used to set the <code>YEAR</code> calendar field in the calendar.
635      * @param month the value used to set the <code>MONTH</code> calendar field in the calendar.
636      * Month value is 0-based. e.g., 0 for January.
637      * @param dayOfMonth the value used to set the <code>DAY_OF_MONTH</code> calendar field in the calendar.
638      * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field
639      * in the calendar.
640      * @param minute the value used to set the <code>MINUTE</code> calendar field
641      * in the calendar.
642      * @param second the value used to set the <code>SECOND</code> calendar field
643      * in the calendar.
644      * @param millis the value used to set the <code>MILLISECOND</code> calendar field
645      */
646     GregorianCalendar(int year, int month, int dayOfMonth,
647               int hourOfDay, int minute, int second, int millis) {
648         super();
649     gdate = (BaseCalendar.Date) gcal.newCalendarDate(getZone());
650         this.set(YEAR, year);
651         this.set(MONTH, month);
652         this.set(DAY_OF_MONTH, dayOfMonth);
653
654     // Set AM_PM and HOUR here to set their stamp values before
655 // setting HOUR_OF_DAY (6178071).
656 if (hourOfDay >= 12 && hourOfDay <= 23) {
657         // If hourOfDay is a valid PM hour, set the correct PM values
658 // so that it won't throw an exception in case it's set to
659 // non-lenient later.
660 this.internalSet(AM_PM, PM);
661         this.internalSet(HOUR, hourOfDay - 12);
662     } else {
663         // The default value for AM_PM is AM.
664 // We don't care any out of range value here for leniency.
665 this.internalSet(HOUR, hourOfDay);
666     }
667     // The stamp values of AM_PM and HOUR must be COMPUTED. (6440854)
668 setFieldsComputed(HOUR_MASK|AM_PM_MASK);
669
670         this.set(HOUR_OF_DAY, hourOfDay);
671         this.set(MINUTE, minute);
672         this.set(SECOND, second);
673     // should be changed to set() when this constructor is made
674 // public.
675 this.internalSet(MILLISECOND, millis);
676     }
677  
678 /////////////////
679 // Public methods
680 /////////////////
681
682     /**
683      * Sets the <code>GregorianCalendar</code> change date. This is the point when the switch
684      * from Julian dates to Gregorian dates occurred. Default is October 15,
685      * 1582 (Gregorian). Previous to this, dates will be in the Julian calendar.
686      * <p>
687      * To obtain a pure Julian calendar, set the change date to
688      * <code>Date(Long.MAX_VALUE)</code>. To obtain a pure Gregorian calendar,
689      * set the change date to <code>Date(Long.MIN_VALUE)</code>.
690      *
691      * @param date the given Gregorian cutover date.
692      */
693     public void setGregorianChange(Date date) {
694     long cutoverTime = date.getTime();
695     if (cutoverTime == gregorianCutover) {
696         return;
697     }
698     // Before changing the cutover date, make sure to have the
699 // time of this calendar.
700 complete();
701     setGregorianChange(cutoverTime);
702     }
703
704     private void setGregorianChange(long cutoverTime) {
705         gregorianCutover = cutoverTime;
706         gregorianCutoverDate = CalendarUtils.floorDivide(cutoverTime, ONE_DAY)
707                 + EPOCH_OFFSET;
708
709     // To provide the "pure" Julian calendar as advertised.
710 // Strictly speaking, the last millisecond should be a
711 // Gregorian date. However, the API doc specifies that setting
712 // the cutover date to Long.MAX_VALUE will make this calendar
713 // a pure Julian calendar. (See 4167995)
714 if (cutoverTime == Long.MAX_VALUE) {
715         gregorianCutoverDate++;
716     }
717
718     BaseCalendar.Date d = getGregorianCutoverDate();
719
720     // Set the cutover year (in the Gregorian year numbering)
721 gregorianCutoverYear = d.getYear();
722
723     BaseCalendar jcal = getJulianCalendarSystem();
724     d = (BaseCalendar.Date) jcal.newCalendarDate(TimeZone.NO_TIMEZONE);
725     jcal.getCalendarDateFromFixedDate(d, gregorianCutoverDate - 1);
726     gregorianCutoverYearJulian = d.getNormalizedYear();
727
728     if (time < gregorianCutover) {
729         // The field values are no longer valid under the new
730 // cutover date.
731 setUnnormalized();
732     }
733     }
734
735     /**
736      * Gets the Gregorian Calendar change date. This is the point when the
737      * switch from Julian dates to Gregorian dates occurred. Default is
738      * October 15, 1582 (Gregorian). Previous to this, dates will be in the Julian
739      * calendar.
740      *
741      * @return the Gregorian cutover date for this <code>GregorianCalendar</code> object.
742      */
743     public final Date getGregorianChange() {
744         return new Date (gregorianCutover);
745     }
746
747     /**
748      * Determines if the given year is a leap year. Returns <code>true</code> if
749      * the given year is a leap year. To specify BC year numbers,
750      * <code>1 - year number</code> must be given. For example, year BC 4 is
751      * specified as -3.
752      *
753      * @param year the given year.
754      * @return <code>true</code> if the given year is a leap year; <code>false</code> otherwise.
755      */
756     public boolean isLeapYear(int year) {
757     if ((year & 3) != 0) {
758         return false;
759     }
760
761         if (year > gregorianCutoverYear) {
762             return (year%100 != 0) || (year%400 == 0); // Gregorian
763 }
764     if (year < gregorianCutoverYearJulian) {
765             return true; // Julian
766 }
767     boolean gregorian;
768     // If the given year is the Gregorian cutover year, we need to
769 // determine which calendar system to be applied to February in the year.
770 if (gregorianCutoverYear == gregorianCutoverYearJulian) {
771         BaseCalendar.Date d = getCalendarDate(gregorianCutoverDate); // Gregorian
772 gregorian = d.getMonth() < BaseCalendar.MARCH;
773     } else {
774         gregorian = year == gregorianCutoverYear;
775     }
776     return gregorian ? (year%100 != 0) || (year%400 == 0) : true;
777     }
778
779     /**
780      * Compares this <code>GregorianCalendar</code> to the specified
781      * <code>Object</code>. The result is <code>true</code> if and
782      * only if the argument is a <code>GregorianCalendar</code> object
783      * that represents the same time value (millisecond offset from
784      * the <a HREF="Calendar.html#Epoch">Epoch</a>) under the same
785      * <code>Calendar</code> parameters and Gregorian change date as
786      * this object.
787      *
788      * @param obj the object to compare with.
789      * @return <code>true</code> if this object is equal to <code>obj</code>;
790      * <code>false</code> otherwise.
791      * @see Calendar#compareTo(Calendar)
792      */
793     public boolean equals(Object obj) {
794         return obj instanceof GregorianCalendar &&
795         super.equals(obj) &&
796             gregorianCutover == ((GregorianCalendar )obj).gregorianCutover;
797     }
798     
799     /**
800      * Generates the hash code for this <code>GregorianCalendar</code> object.
801      */
802     public int hashCode() {
803         return super.hashCode() ^ (int)gregorianCutoverDate;
804     }
805
806     /**
807      * Adds the specified (signed) amount of time to the given calendar field,
808      * based on the calendar's rules.
809      *
810      * <p><em>Add rule 1</em>. The value of <code>field</code>
811      * after the call minus the value of <code>field</code> before the
812      * call is <code>amount</code>, modulo any overflow that has occurred in
813      * <code>field</code>. Overflow occurs when a field value exceeds its
814      * range and, as a result, the next larger field is incremented or
815      * decremented and the field value is adjusted back into its range.</p>
816      *
817      * <p><em>Add rule 2</em>. If a smaller field is expected to be
818      * invariant, but it is impossible for it to be equal to its
819      * prior value because of changes in its minimum or maximum after
820      * <code>field</code> is changed, then its value is adjusted to be as close
821      * as possible to its expected value. A smaller field represents a
822      * smaller unit of time. <code>HOUR</code> is a smaller field than
823      * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
824      * that are not expected to be invariant. The calendar system
825      * determines what fields are expected to be invariant.</p>
826      *
827      * @param field the calendar field.
828      * @param amount the amount of date or time to be added to the field.
829      * @exception IllegalArgumentException if <code>field</code> is
830      * <code>ZONE_OFFSET</code>, <code>DST_OFFSET</code>, or unknown,
831      * or if any calendar fields have out-of-range values in
832      * non-lenient mode.
833      */
834     public void add(int field, int amount) {
835     // If amount == 0, do nothing even the given field is out of
836 // range. This is tested by JCK.
837 if (amount == 0) {
838         return; // Do nothing!
839 }
840
841     if (field < 0 || field >= ZONE_OFFSET) {
842         throw new IllegalArgumentException ();
843     }
844
845     // Sync the time and calendar fields.
846 complete();
847
848         if (field == YEAR) {
849             int year = internalGet(YEAR);
850             if (internalGetEra() == CE) {
851                 year += amount;
852                 if (year > 0) {
853                     set(YEAR, year);
854                 } else { // year <= 0
855 set(YEAR, 1 - year);
856                     // if year == 0, you get 1 BCE.
857 set(ERA, BCE);
858                 }
859             }
860             else { // era == BCE
861 year -= amount;
862                 if (year > 0) {
863                     set(YEAR, year);
864                 } else { // year <= 0
865 set(YEAR, 1 - year);
866                     // if year == 0, you get 1 CE
867 set(ERA, CE);
868                 }
869             }
870             pinDayOfMonth();
871         } else if (field == MONTH) {
872             int month = internalGet(MONTH) + amount;
873         int year = internalGet(YEAR);
874         int y_amount;
875
876         if (month >= 0) {
877                 y_amount = month/12;
878         } else {
879                 y_amount = (month+1)/12 - 1;
880         }
881         if (y_amount != 0) {
882                 if (internalGetEra() == CE) {
883                     year += y_amount;
884                     if (year > 0) {
885                         set(YEAR, year);
886                     } else { // year <= 0
887 set(YEAR, 1 - year);
888                         // if year == 0, you get 1 BCE
889 set(ERA, BCE);
890                     }
891                 }
892                 else { // era == BCE
893 year -= y_amount;
894                     if (year > 0) {
895                         set(YEAR, year);
896                     } else { // year <= 0
897 set(YEAR, 1 - year);
898                         // if year == 0, you get 1 CE
899 set(ERA, CE);
900                     }
901                 }
902             }
903
904             if (month >= 0) {
905                 set(MONTH, (int) (month % 12));
906             } else {
907         // month < 0
908 month %= 12;
909                 if (month < 0) {
910             month += 12;
911         }
912                 set(MONTH, JANUARY + month);
913             }
914             pinDayOfMonth();
915         } else if (field == ERA) {
916             int era = internalGet(ERA) + amount;
917             if (era < 0) {
918         era = 0;
919         }
920             if (era > 1) {
921         era = 1;
922         }
923             set(ERA, era);
924         } else {
925         long delta = amount;
926         long timeOfDay = 0;
927         switch (field) {
928         // Handle the time fields here. Convert the given
929 // amount to milliseconds and call setTimeInMillis.
930 case HOUR:
931             case HOUR_OF_DAY:
932                 delta *= 60 * 60 * 1000; // hours to minutes
933 break;
934
935             case MINUTE:
936                 delta *= 60 * 1000; // minutes to seconds
937 break;
938
939             case SECOND:
940                 delta *= 1000; // seconds to milliseconds
941 break;
942
943             case MILLISECOND:
944                 break;
945
946         // Handle week, day and AM_PM fields which involves
947 // time zone offset change adjustment. Convert the
948 // given amount to the number of days.
949 case WEEK_OF_YEAR:
950             case WEEK_OF_MONTH:
951             case DAY_OF_WEEK_IN_MONTH:
952                 delta *= 7;
953         break;
954
955             case DAY_OF_MONTH: // synonym of DATE
956 case DAY_OF_YEAR:
957             case DAY_OF_WEEK:
958         break;
959
960         case AM_PM:
961         // Convert the amount to the number of days (delta)
962 // and +12 or -12 hours (timeOfDay).
963 delta = amount / 2;
964         timeOfDay = 12 * (amount % 2);
965         break;
966         }
967
968         // The time fields don't require time zone offset change
969 // adjustment.
970 if (field >= HOUR) {
971         setTimeInMillis(time + delta);
972         return;
973         }
974
975         // The rest of the fields (week, day or AM_PM fields)
976 // require time zone offset (both GMT and DST) change
977 // adjustment.
978
979         // Translate the current time to the fixed date and time
980 // of the day.
981 long fd = getCurrentFixedDate();
982         timeOfDay += internalGet(HOUR_OF_DAY);
983         timeOfDay *= 60;
984         timeOfDay += internalGet(MINUTE);
985         timeOfDay *= 60;
986         timeOfDay += internalGet(SECOND);
987         timeOfDay *= 1000;
988         timeOfDay += internalGet(MILLISECOND);
989         if (timeOfDay >= ONE_DAY) {
990         fd++;
991         timeOfDay -= ONE_DAY;
992         } else if (timeOfDay < 0) {
993         fd--;
994         timeOfDay += ONE_DAY;
995         }
996
997         fd += delta; // fd is the expected fixed date after the calculation
998 int zoneOffset = internalGet(ZONE_OFFSET) + internalGet(DST_OFFSET);
999         setTimeInMillis((fd - EPOCH_OFFSET) * ONE_DAY + timeOfDay - zoneOffset);
1000        zoneOffset -= internalGet(ZONE_OFFSET) + internalGet(DST_OFFSET);
1001        // If the time zone offset has changed, then adjust the difference.
1002 if (zoneOffset != 0) {
1003        setTimeInMillis(time + zoneOffset);
1004        long fd2 = getCurrentFixedDate();
1005        // If the adjustment has changed the date, then take
1006 // the previous one.
1007 if (fd2 != fd) {
1008            setTimeInMillis(time - zoneOffset);
1009        }
1010        }
1011    }
1012    }
1013
1014