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.time.Instant;
  44 import java.time.ZonedDateTime;
  45 import java.time.temporal.ChronoField;
  46 import sun.util.calendar.BaseCalendar;
  47 import sun.util.calendar.CalendarDate;
  48 import sun.util.calendar.CalendarSystem;
  49 import sun.util.calendar.CalendarUtils;
  50 import sun.util.calendar.Era;
  51 import sun.util.calendar.Gregorian;
  52 import sun.util.calendar.JulianCalendar;
  53 import sun.util.calendar.ZoneInfo;
  54 
  55 /**
  56  * {@code GregorianCalendar} is a concrete subclass of
  57  * {@code Calendar} and provides the standard calendar system
  58  * used by most of the world.
  59  *
  60  * <p> {@code GregorianCalendar} is a hybrid calendar that
  61  * supports both the Julian and Gregorian calendar systems with the
  62  * support of a single discontinuity, which corresponds by default to
  63  * the Gregorian date when the Gregorian calendar was instituted
  64  * (October 15, 1582 in some countries, later in others).  The cutover
  65  * date may be changed by the caller by calling {@link
  66  * #setGregorianChange(Date) setGregorianChange()}.
  67  *
  68  * <p>
  69  * Historically, in those countries which adopted the Gregorian calendar first,
  70  * October 4, 1582 (Julian) was thus followed by October 15, 1582 (Gregorian). This calendar models
  71  * this correctly.  Before the Gregorian cutover, {@code GregorianCalendar}
  72  * implements the Julian calendar.  The only difference between the Gregorian
  73  * and the Julian calendar is the leap year rule. The Julian calendar specifies
  74  * leap years every four years, whereas the Gregorian calendar omits century
  75  * years which are not divisible by 400.
  76  *
  77  * <p>
  78  * {@code GregorianCalendar} implements <em>proleptic</em> Gregorian and
  79  * Julian calendars. That is, dates are computed by extrapolating the current
  80  * rules indefinitely far backward and forward in time. As a result,
  81  * {@code GregorianCalendar} may be used for all years to generate
  82  * meaningful and consistent results. However, dates obtained using
  83  * {@code GregorianCalendar} are historically accurate only from March 1, 4
  84  * AD onward, when modern Julian calendar rules were adopted.  Before this date,
  85  * leap year rules were applied irregularly, and before 45 BC the Julian
  86  * calendar did not even exist.
  87  *
  88  * <p>
  89  * Prior to the institution of the Gregorian calendar, New Year's Day was
  90  * March 25. To avoid confusion, this calendar always uses January 1. A manual
  91  * adjustment may be made if desired for dates that are prior to the Gregorian
  92  * changeover and which fall between January 1 and March 24.
  93  *
  94  * <h2><a id="week_and_year">Week Of Year and Week Year</a></h2>
  95  *
  96  * <p>Values calculated for the {@link Calendar#WEEK_OF_YEAR
  97  * WEEK_OF_YEAR} field range from 1 to 53. The first week of a
  98  * calendar year is the earliest seven day period starting on {@link
  99  * Calendar#getFirstDayOfWeek() getFirstDayOfWeek()} that contains at
 100  * least {@link Calendar#getMinimalDaysInFirstWeek()
 101  * getMinimalDaysInFirstWeek()} days from that year. It thus depends
 102  * on the values of {@code getMinimalDaysInFirstWeek()}, {@code
 103  * getFirstDayOfWeek()}, and the day of the week of January 1. Weeks
 104  * between week 1 of one year and week 1 of the following year
 105  * (exclusive) are numbered sequentially from 2 to 52 or 53 (except
 106  * for year(s) involved in the Julian-Gregorian transition).
 107  *
 108  * <p>The {@code getFirstDayOfWeek()} and {@code
 109  * getMinimalDaysInFirstWeek()} values are initialized using
 110  * locale-dependent resources when constructing a {@code
 111  * GregorianCalendar}. <a id="iso8601_compatible_setting">The week
 112  * determination is compatible</a> with the ISO 8601 standard when {@code
 113  * getFirstDayOfWeek()} is {@code MONDAY} and {@code
 114  * getMinimalDaysInFirstWeek()} is 4, which values are used in locales
 115  * where the standard is preferred. These values can explicitly be set by
 116  * calling {@link Calendar#setFirstDayOfWeek(int) setFirstDayOfWeek()} and
 117  * {@link Calendar#setMinimalDaysInFirstWeek(int)
 118  * setMinimalDaysInFirstWeek()}.
 119  *
 120  * <p>A <a id="week_year"><em>week year</em></a> is in sync with a
 121  * {@code WEEK_OF_YEAR} cycle. All weeks between the first and last
 122  * weeks (inclusive) have the same <em>week year</em> value.
 123  * Therefore, the first and last days of a week year may have
 124  * different calendar year values.
 125  *
 126  * <p>For example, January 1, 1998 is a Thursday. If {@code
 127  * getFirstDayOfWeek()} is {@code MONDAY} and {@code
 128  * getMinimalDaysInFirstWeek()} is 4 (ISO 8601 standard compatible
 129  * setting), then week 1 of 1998 starts on December 29, 1997, and ends
 130  * on January 4, 1998. The week year is 1998 for the last three days
 131  * of calendar year 1997. If, however, {@code getFirstDayOfWeek()} is
 132  * {@code SUNDAY}, then week 1 of 1998 starts on January 4, 1998, and
 133  * ends on January 10, 1998; the first three days of 1998 then are
 134  * part of week 53 of 1997 and their week year is 1997.
 135  *
 136  * <h3>Week Of Month</h3>
 137  *
 138  * <p>Values calculated for the {@code WEEK_OF_MONTH} field range from 0
 139  * to 6.  Week 1 of a month (the days with <code>WEEK_OF_MONTH =
 140  * 1</code>) is the earliest set of at least
 141  * {@code getMinimalDaysInFirstWeek()} contiguous days in that month,
 142  * ending on the day before {@code getFirstDayOfWeek()}.  Unlike
 143  * week 1 of a year, week 1 of a month may be shorter than 7 days, need
 144  * not start on {@code getFirstDayOfWeek()}, and will not include days of
 145  * the previous month.  Days of a month before week 1 have a
 146  * {@code WEEK_OF_MONTH} of 0.
 147  *
 148  * <p>For example, if {@code getFirstDayOfWeek()} is {@code SUNDAY}
 149  * and {@code getMinimalDaysInFirstWeek()} is 4, then the first week of
 150  * January 1998 is Sunday, January 4 through Saturday, January 10.  These days
 151  * have a {@code WEEK_OF_MONTH} of 1.  Thursday, January 1 through
 152  * Saturday, January 3 have a {@code WEEK_OF_MONTH} of 0.  If
 153  * {@code getMinimalDaysInFirstWeek()} is changed to 3, then January 1
 154  * through January 3 have a {@code WEEK_OF_MONTH} of 1.
 155  *
 156  * <h3>Default Fields Values</h3>
 157  *
 158  * <p>The {@code clear} method sets calendar field(s)
 159  * undefined. {@code GregorianCalendar} uses the following
 160  * default value for each calendar field if its value is undefined.
 161  *
 162  * <table class="striped" style="text-align: left; width: 66%;">
 163  * <caption style="display:none">GregorianCalendar default field values</caption>
 164  *   <thead>
 165  *     <tr>
 166  *       <th scope="col">
 167  *          Field
 168  *       </th>
 169  *       <th scope="col">
 170             Default Value
 171  *       </th>
 172  *     </tr>
 173  *   </thead>
 174  *   <tbody>
 175  *     <tr>
 176  *       <th scope="row">
 177  *              {@code ERA}
 178  *       </th>
 179  *       <td>
 180  *              {@code AD}
 181  *       </td>
 182  *     </tr>
 183  *     <tr>
 184  *       <th scope="row">
 185  *              {@code YEAR}
 186  *       </th>
 187  *       <td>
 188  *              {@code 1970}
 189  *       </td>
 190  *     </tr>
 191  *     <tr>
 192  *       <th scope="row">
 193  *              {@code MONTH}
 194  *       </th>
 195  *       <td>
 196  *              {@code JANUARY}
 197  *       </td>
 198  *     </tr>
 199  *     <tr>
 200  *       <th scope="row">
 201  *              {@code DAY_OF_MONTH}
 202  *       </th>
 203  *       <td>
 204  *              {@code 1}
 205  *       </td>
 206  *     </tr>
 207  *     <tr>
 208  *       <th scope="row">
 209  *              {@code DAY_OF_WEEK}
 210  *       </th>
 211  *       <td>
 212  *              {@code the first day of week}
 213  *       </td>
 214  *     </tr>
 215  *     <tr>
 216  *       <th scope="row">
 217  *              {@code WEEK_OF_MONTH}
 218  *       </th>
 219  *       <td>
 220  *              {@code 0}
 221  *       </td>
 222  *     </tr>
 223  *     <tr>
 224  *       <th scope="row">
 225  *              {@code DAY_OF_WEEK_IN_MONTH}
 226  *       </th>
 227  *       <td>
 228  *              {@code 1}
 229  *       </td>
 230  *     </tr>
 231  *     <tr>
 232  *       <th scope="row">
 233  *              {@code AM_PM}
 234  *       </th>
 235  *       <td>
 236  *              {@code AM}
 237  *       </td>
 238  *     </tr>
 239  *     <tr>
 240  *       <th scope="row">
 241  *              {@code HOUR, HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND}
 242  *       </th>
 243  *       <td>
 244  *              {@code 0}
 245  *       </td>
 246  *     </tr>
 247  *   </tbody>
 248  * </table>
 249  * <br>Default values are not applicable for the fields not listed above.
 250  *
 251  * <p>
 252  * <strong>Example:</strong>
 253  * <blockquote>
 254  * <pre>
 255  * // get the supported ids for GMT-08:00 (Pacific Standard Time)
 256  * String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
 257  * // if no ids were returned, something is wrong. get out.
 258  * if (ids.length == 0)
 259  *     System.exit(0);
 260  *
 261  *  // begin output
 262  * System.out.println("Current Time");
 263  *
 264  * // create a Pacific Standard Time time zone
 265  * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
 266  *
 267  * // set up rules for Daylight Saving Time
 268  * pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 269  * pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 270  *
 271  * // create a GregorianCalendar with the Pacific Daylight time zone
 272  * // and the current date and time
 273  * Calendar calendar = new GregorianCalendar(pdt);
 274  * Date trialTime = new Date();
 275  * calendar.setTime(trialTime);
 276  *
 277  * // print out a bunch of interesting things
 278  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
 279  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 280  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 281  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 282  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 283  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
 284  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 285  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 286  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 287  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
 288  *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 289  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 290  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 291  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 292  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 293  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 294  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 295  * System.out.println("ZONE_OFFSET: "
 296  *                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
 297  * System.out.println("DST_OFFSET: "
 298  *                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
 299 
 300  * System.out.println("Current Time, with hour reset to 3");
 301  * calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
 302  * calendar.set(Calendar.HOUR, 3);
 303  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
 304  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 305  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 306  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 307  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 308  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
 309  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 310  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 311  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 312  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
 313  *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 314  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 315  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 316  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 317  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 318  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 319  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 320  * System.out.println("ZONE_OFFSET: "
 321  *        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
 322  * System.out.println("DST_OFFSET: "
 323  *        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
 324  * </pre>
 325  * </blockquote>
 326  *
 327  * @see          TimeZone
 328  * @author David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu
 329  * @since 1.1
 330  */
 331 public class GregorianCalendar extends Calendar {
 332     /*
 333      * Implementation Notes
 334      *
 335      * The epoch is the number of days or milliseconds from some defined
 336      * starting point. The epoch for java.util.Date is used here; that is,
 337      * milliseconds from January 1, 1970 (Gregorian), midnight UTC.  Other
 338      * epochs which are used are January 1, year 1 (Gregorian), which is day 1
 339      * of the Gregorian calendar, and December 30, year 0 (Gregorian), which is
 340      * day 1 of the Julian calendar.
 341      *
 342      * We implement the proleptic Julian and Gregorian calendars.  This means we
 343      * implement the modern definition of the calendar even though the
 344      * historical usage differs.  For example, if the Gregorian change is set
 345      * to new Date(Long.MIN_VALUE), we have a pure Gregorian calendar which
 346      * labels dates preceding the invention of the Gregorian calendar in 1582 as
 347      * if the calendar existed then.
 348      *
 349      * Likewise, with the Julian calendar, we assume a consistent
 350      * 4-year leap year rule, even though the historical pattern of
 351      * leap years is irregular, being every 3 years from 45 BCE
 352      * through 9 BCE, then every 4 years from 8 CE onwards, with no
 353      * leap years in-between.  Thus date computations and functions
 354      * such as isLeapYear() are not intended to be historically
 355      * accurate.
 356      */
 357 
 358 //////////////////
 359 // Class Variables
 360 //////////////////
 361 
 362     /**
 363      * Value of the {@code ERA} field indicating
 364      * the period before the common era (before Christ), also known as BCE.
 365      * The sequence of years at the transition from {@code BC} to {@code AD} is
 366      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
 367      *
 368      * @see #ERA
 369      */
 370     public static final int BC = 0;
 371 
 372     /**
 373      * Value of the {@link #ERA} field indicating
 374      * the period before the common era, the same value as {@link #BC}.
 375      *
 376      * @see #CE
 377      */
 378     static final int BCE = 0;
 379 
 380     /**
 381      * Value of the {@code ERA} field indicating
 382      * the common era (Anno Domini), also known as CE.
 383      * The sequence of years at the transition from {@code BC} to {@code AD} is
 384      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
 385      *
 386      * @see #ERA
 387      */
 388     public static final int AD = 1;
 389 
 390     /**
 391      * Value of the {@link #ERA} field indicating
 392      * the common era, the same value as {@link #AD}.
 393      *
 394      * @see #BCE
 395      */
 396     static final int CE = 1;
 397 
 398     private static final int EPOCH_OFFSET   = 719163; // Fixed date of January 1, 1970 (Gregorian)
 399     private static final int EPOCH_YEAR     = 1970;
 400 
 401     static final int MONTH_LENGTH[]
 402         = {31,28,31,30,31,30,31,31,30,31,30,31}; // 0-based
 403     static final int LEAP_MONTH_LENGTH[]
 404         = {31,29,31,30,31,30,31,31,30,31,30,31}; // 0-based
 405 
 406     // Useful millisecond constants.  Although ONE_DAY and ONE_WEEK can fit
 407     // into ints, they must be longs in order to prevent arithmetic overflow
 408     // when performing (bug 4173516).
 409     private static final int  ONE_SECOND = 1000;
 410     private static final int  ONE_MINUTE = 60*ONE_SECOND;
 411     private static final int  ONE_HOUR   = 60*ONE_MINUTE;
 412     private static final long ONE_DAY    = 24*ONE_HOUR;
 413     private static final long ONE_WEEK   = 7*ONE_DAY;
 414 
 415     /*
 416      * <pre>
 417      *                            Greatest       Least
 418      * Field name        Minimum   Minimum     Maximum     Maximum
 419      * ----------        -------   -------     -------     -------
 420      * ERA                     0         0           1           1
 421      * YEAR                    1         1   292269054   292278994
 422      * MONTH                   0         0          11          11
 423      * WEEK_OF_YEAR            1         1          52*         53
 424      * WEEK_OF_MONTH           0         0           4*          6
 425      * DAY_OF_MONTH            1         1          28*         31
 426      * DAY_OF_YEAR             1         1         365*        366
 427      * DAY_OF_WEEK             1         1           7           7
 428      * DAY_OF_WEEK_IN_MONTH    1         1           4*          6
 429      * AM_PM                   0         0           1           1
 430      * HOUR                    0         0          11          11
 431      * HOUR_OF_DAY             0         0          23          23
 432      * MINUTE                  0         0          59          59
 433      * SECOND                  0         0          59          59
 434      * MILLISECOND             0         0         999         999
 435      * ZONE_OFFSET        -13:00    -13:00       14:00       14:00
 436      * DST_OFFSET           0:00      0:00        0:20        2:00
 437      * </pre>
 438      * *: depends on the Gregorian change date
 439      */
 440     static final int MIN_VALUES[] = {
 441         BCE,            // ERA
 442         1,              // YEAR
 443         JANUARY,        // MONTH
 444         1,              // WEEK_OF_YEAR
 445         0,              // WEEK_OF_MONTH
 446         1,              // DAY_OF_MONTH
 447         1,              // DAY_OF_YEAR
 448         SUNDAY,         // DAY_OF_WEEK
 449         1,              // DAY_OF_WEEK_IN_MONTH
 450         AM,             // AM_PM
 451         0,              // HOUR
 452         0,              // HOUR_OF_DAY
 453         0,              // MINUTE
 454         0,              // SECOND
 455         0,              // MILLISECOND
 456         -13*ONE_HOUR,   // ZONE_OFFSET (UNIX compatibility)
 457         0               // DST_OFFSET
 458     };
 459     static final int LEAST_MAX_VALUES[] = {
 460         CE,             // ERA
 461         292269054,      // YEAR
 462         DECEMBER,       // MONTH
 463         52,             // WEEK_OF_YEAR
 464         4,              // WEEK_OF_MONTH
 465         28,             // DAY_OF_MONTH
 466         365,            // DAY_OF_YEAR
 467         SATURDAY,       // DAY_OF_WEEK
 468         4,              // DAY_OF_WEEK_IN
 469         PM,             // AM_PM
 470         11,             // HOUR
 471         23,             // HOUR_OF_DAY
 472         59,             // MINUTE
 473         59,             // SECOND
 474         999,            // MILLISECOND
 475         14*ONE_HOUR,    // ZONE_OFFSET
 476         20*ONE_MINUTE   // DST_OFFSET (historical least maximum)
 477     };
 478     static final int MAX_VALUES[] = {
 479         CE,             // ERA
 480         292278994,      // YEAR
 481         DECEMBER,       // MONTH
 482         53,             // WEEK_OF_YEAR
 483         6,              // WEEK_OF_MONTH
 484         31,             // DAY_OF_MONTH
 485         366,            // DAY_OF_YEAR
 486         SATURDAY,       // DAY_OF_WEEK
 487         6,              // DAY_OF_WEEK_IN
 488         PM,             // AM_PM
 489         11,             // HOUR
 490         23,             // HOUR_OF_DAY
 491         59,             // MINUTE
 492         59,             // SECOND
 493         999,            // MILLISECOND
 494         14*ONE_HOUR,    // ZONE_OFFSET
 495         2*ONE_HOUR      // DST_OFFSET (double summer time)
 496     };
 497 
 498     // Proclaim serialization compatibility with JDK 1.1
 499     @SuppressWarnings("FieldNameHidesFieldInSuperclass")
 500     @java.io.Serial
 501     static final long serialVersionUID = -8125100834729963327L;
 502 
 503     // Reference to the sun.util.calendar.Gregorian instance (singleton).
 504     private static final Gregorian gcal =
 505                                 CalendarSystem.getGregorianCalendar();
 506 
 507     // Reference to the JulianCalendar instance (singleton), set as needed. See
 508     // getJulianCalendarSystem().
 509     private static JulianCalendar jcal;
 510 
 511     // JulianCalendar eras. See getJulianCalendarSystem().
 512     private static Era[] jeras;
 513 
 514     // The default value of gregorianCutover.
 515     static final long DEFAULT_GREGORIAN_CUTOVER = -12219292800000L;
 516 
 517 /////////////////////
 518 // Instance Variables
 519 /////////////////////
 520 
 521     /**
 522      * The point at which the Gregorian calendar rules are used, measured in
 523      * milliseconds from the standard epoch.  Default is October 15, 1582
 524      * (Gregorian) 00:00:00 UTC or -12219292800000L.  For this value, October 4,
 525      * 1582 (Julian) is followed by October 15, 1582 (Gregorian).  This
 526      * corresponds to Julian day number 2299161.
 527      * @serial
 528      */
 529     private long gregorianCutover = DEFAULT_GREGORIAN_CUTOVER;
 530 
 531     /**
 532      * The fixed date of the gregorianCutover.
 533      */
 534     private transient long gregorianCutoverDate =
 535         (((DEFAULT_GREGORIAN_CUTOVER + 1)/ONE_DAY) - 1) + EPOCH_OFFSET; // == 577736
 536 
 537     /**
 538      * The normalized year of the gregorianCutover in Gregorian, with
 539      * 0 representing 1 BCE, -1 representing 2 BCE, etc.
 540      */
 541     private transient int gregorianCutoverYear = 1582;
 542 
 543     /**
 544      * The normalized year of the gregorianCutover in Julian, with 0
 545      * representing 1 BCE, -1 representing 2 BCE, etc.
 546      */
 547     private transient int gregorianCutoverYearJulian = 1582;
 548 
 549     /**
 550      * gdate always has a sun.util.calendar.Gregorian.Date instance to
 551      * avoid overhead of creating it. The assumption is that most
 552      * applications will need only Gregorian calendar calculations.
 553      */
 554     private transient BaseCalendar.Date gdate;
 555 
 556     /**
 557      * Reference to either gdate or a JulianCalendar.Date
 558      * instance. After calling complete(), this value is guaranteed to
 559      * be set.
 560      */
 561     private transient BaseCalendar.Date cdate;
 562 
 563     /**
 564      * The CalendarSystem used to calculate the date in cdate. After
 565      * calling complete(), this value is guaranteed to be set and
 566      * consistent with the cdate value.
 567      */
 568     private transient BaseCalendar calsys;
 569 
 570     /**
 571      * Temporary int[2] to get time zone offsets. zoneOffsets[0] gets
 572      * the GMT offset value and zoneOffsets[1] gets the DST saving
 573      * value.
 574      */
 575     private transient int[] zoneOffsets;
 576 
 577     /**
 578      * Temporary storage for saving original fields[] values in
 579      * non-lenient mode.
 580      */
 581     private transient int[] originalFields;
 582 
 583 ///////////////
 584 // Constructors
 585 ///////////////
 586 
 587     /**
 588      * Constructs a default {@code GregorianCalendar} using the current time
 589      * in the default time zone with the default
 590      * {@link Locale.Category#FORMAT FORMAT} locale.
 591      */
 592     public GregorianCalendar() {
 593         this(TimeZone.getDefaultRef(), Locale.getDefault(Locale.Category.FORMAT));
 594         setZoneShared(true);
 595     }
 596 
 597     /**
 598      * Constructs a {@code GregorianCalendar} based on the current time
 599      * in the given time zone with the default
 600      * {@link Locale.Category#FORMAT FORMAT} locale.
 601      *
 602      * @param zone the given time zone.
 603      */
 604     public GregorianCalendar(TimeZone zone) {
 605         this(zone, Locale.getDefault(Locale.Category.FORMAT));
 606     }
 607 
 608     /**
 609      * Constructs a {@code GregorianCalendar} based on the current time
 610      * in the default time zone with the given locale.
 611      *
 612      * @param aLocale the given locale.
 613      */
 614     public GregorianCalendar(Locale aLocale) {
 615         this(TimeZone.getDefaultRef(), aLocale);
 616         setZoneShared(true);
 617     }
 618 
 619     /**
 620      * Constructs a {@code GregorianCalendar} based on the current time
 621      * in the given time zone with the given locale.
 622      *
 623      * @param zone the given time zone.
 624      * @param aLocale the given locale.
 625      */
 626     public GregorianCalendar(TimeZone zone, Locale aLocale) {
 627         super(zone, aLocale);
 628         gdate = (BaseCalendar.Date) gcal.newCalendarDate(zone);
 629         setTimeInMillis(System.currentTimeMillis());
 630     }
 631 
 632     /**
 633      * Constructs a {@code GregorianCalendar} with the given date set
 634      * in the default time zone with the default locale.
 635      *
 636      * @param year the value used to set the {@code YEAR} calendar field in the calendar.
 637      * @param month the value used to set the {@code MONTH} calendar field in the calendar.
 638      * Month value is 0-based. e.g., 0 for January.
 639      * @param dayOfMonth the value used to set the {@code DAY_OF_MONTH} calendar field in the calendar.
 640      */
 641     public GregorianCalendar(int year, int month, int dayOfMonth) {
 642         this(year, month, dayOfMonth, 0, 0, 0, 0);
 643     }
 644 
 645     /**
 646      * Constructs a {@code GregorianCalendar} with the given date
 647      * and time set for the default time zone with the default locale.
 648      *
 649      * @param year the value used to set the {@code YEAR} calendar field in the calendar.
 650      * @param month the value used to set the {@code MONTH} calendar field in the calendar.
 651      * Month value is 0-based. e.g., 0 for January.
 652      * @param dayOfMonth the value used to set the {@code DAY_OF_MONTH} calendar field in the calendar.
 653      * @param hourOfDay the value used to set the {@code HOUR_OF_DAY} calendar field
 654      * in the calendar.
 655      * @param minute the value used to set the {@code MINUTE} calendar field
 656      * in the calendar.
 657      */
 658     public GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay,
 659                              int minute) {
 660         this(year, month, dayOfMonth, hourOfDay, minute, 0, 0);
 661     }
 662 
 663     /**
 664      * Constructs a GregorianCalendar with the given date
 665      * and time set for the default time zone with the default locale.
 666      *
 667      * @param year the value used to set the {@code YEAR} calendar field in the calendar.
 668      * @param month the value used to set the {@code MONTH} calendar field in the calendar.
 669      * Month value is 0-based. e.g., 0 for January.
 670      * @param dayOfMonth the value used to set the {@code DAY_OF_MONTH} calendar field in the calendar.
 671      * @param hourOfDay the value used to set the {@code HOUR_OF_DAY} calendar field
 672      * in the calendar.
 673      * @param minute the value used to set the {@code MINUTE} calendar field
 674      * in the calendar.
 675      * @param second the value used to set the {@code SECOND} calendar field
 676      * in the calendar.
 677      */
 678     public GregorianCalendar(int year, int month, int dayOfMonth, int hourOfDay,
 679                              int minute, int second) {
 680         this(year, month, dayOfMonth, hourOfDay, minute, second, 0);
 681     }
 682 
 683     /**
 684      * Constructs a {@code GregorianCalendar} with the given date
 685      * and time set for the default time zone with the default locale.
 686      *
 687      * @param year the value used to set the {@code YEAR} calendar field in the calendar.
 688      * @param month the value used to set the {@code MONTH} calendar field in the calendar.
 689      * Month value is 0-based. e.g., 0 for January.
 690      * @param dayOfMonth the value used to set the {@code DAY_OF_MONTH} calendar field in the calendar.
 691      * @param hourOfDay the value used to set the {@code HOUR_OF_DAY} calendar field
 692      * in the calendar.
 693      * @param minute the value used to set the {@code MINUTE} calendar field
 694      * in the calendar.
 695      * @param second the value used to set the {@code SECOND} calendar field
 696      * in the calendar.
 697      * @param millis the value used to set the {@code MILLISECOND} calendar field
 698      */
 699     GregorianCalendar(int year, int month, int dayOfMonth,
 700                       int hourOfDay, int minute, int second, int millis) {
 701         super();
 702         gdate = (BaseCalendar.Date) gcal.newCalendarDate(getZone());
 703         this.set(YEAR, year);
 704         this.set(MONTH, month);
 705         this.set(DAY_OF_MONTH, dayOfMonth);
 706 
 707         // Set AM_PM and HOUR here to set their stamp values before
 708         // setting HOUR_OF_DAY (6178071).
 709         if (hourOfDay >= 12 && hourOfDay <= 23) {
 710             // If hourOfDay is a valid PM hour, set the correct PM values
 711             // so that it won't throw an exception in case it's set to
 712             // non-lenient later.
 713             this.internalSet(AM_PM, PM);
 714             this.internalSet(HOUR, hourOfDay - 12);
 715         } else {
 716             // The default value for AM_PM is AM.
 717             // We don't care any out of range value here for leniency.
 718             this.internalSet(HOUR, hourOfDay);
 719         }
 720         // The stamp values of AM_PM and HOUR must be COMPUTED. (6440854)
 721         setFieldsComputed(HOUR_MASK|AM_PM_MASK);
 722 
 723         this.set(HOUR_OF_DAY, hourOfDay);
 724         this.set(MINUTE, minute);
 725         this.set(SECOND, second);
 726         // should be changed to set() when this constructor is made
 727         // public.
 728         this.internalSet(MILLISECOND, millis);
 729     }
 730 
 731     /**
 732      * Constructs an empty GregorianCalendar.
 733      *
 734      * @param zone    the given time zone
 735      * @param aLocale the given locale
 736      * @param flag    the flag requesting an empty instance
 737      */
 738     GregorianCalendar(TimeZone zone, Locale locale, boolean flag) {
 739         super(zone, locale);
 740         gdate = (BaseCalendar.Date) gcal.newCalendarDate(getZone());
 741     }
 742 
 743 /////////////////
 744 // Public methods
 745 /////////////////
 746 
 747     /**
 748      * Sets the {@code GregorianCalendar} change date. This is the point when the switch
 749      * from Julian dates to Gregorian dates occurred. Default is October 15,
 750      * 1582 (Gregorian). Previous to this, dates will be in the Julian calendar.
 751      * <p>
 752      * To obtain a pure Julian calendar, set the change date to
 753      * {@code Date(Long.MAX_VALUE)}.  To obtain a pure Gregorian calendar,
 754      * set the change date to {@code Date(Long.MIN_VALUE)}.
 755      *
 756      * @param date the given Gregorian cutover date.
 757      */
 758     public void setGregorianChange(Date date) {
 759         long cutoverTime = date.getTime();
 760         if (cutoverTime == gregorianCutover) {
 761             return;
 762         }
 763         // Before changing the cutover date, make sure to have the
 764         // time of this calendar.
 765         complete();
 766         setGregorianChange(cutoverTime);
 767     }
 768 
 769     private void setGregorianChange(long cutoverTime) {
 770         gregorianCutover = cutoverTime;
 771         gregorianCutoverDate = CalendarUtils.floorDivide(cutoverTime, ONE_DAY)
 772                                 + EPOCH_OFFSET;
 773 
 774         // To provide the "pure" Julian calendar as advertised.
 775         // Strictly speaking, the last millisecond should be a
 776         // Gregorian date. However, the API doc specifies that setting
 777         // the cutover date to Long.MAX_VALUE will make this calendar
 778         // a pure Julian calendar. (See 4167995)
 779         if (cutoverTime == Long.MAX_VALUE) {
 780             gregorianCutoverDate++;
 781         }
 782 
 783         BaseCalendar.Date d = getGregorianCutoverDate();
 784 
 785         // Set the cutover year (in the Gregorian year numbering)
 786         gregorianCutoverYear = d.getYear();
 787 
 788         BaseCalendar julianCal = getJulianCalendarSystem();
 789         d = (BaseCalendar.Date) julianCal.newCalendarDate(TimeZone.NO_TIMEZONE);
 790         julianCal.getCalendarDateFromFixedDate(d, gregorianCutoverDate - 1);
 791         gregorianCutoverYearJulian = d.getNormalizedYear();
 792 
 793         if (time < gregorianCutover) {
 794             // The field values are no longer valid under the new
 795             // cutover date.
 796             setUnnormalized();
 797         }
 798     }
 799 
 800     /**
 801      * Gets the Gregorian Calendar change date.  This is the point when the
 802      * switch from Julian dates to Gregorian dates occurred. Default is
 803      * October 15, 1582 (Gregorian). Previous to this, dates will be in the Julian
 804      * calendar.
 805      *
 806      * @return the Gregorian cutover date for this {@code GregorianCalendar} object.
 807      */
 808     public final Date getGregorianChange() {
 809         return new Date(gregorianCutover);
 810     }
 811 
 812     /**
 813      * Determines if the given year is a leap year. Returns {@code true} if
 814      * the given year is a leap year. To specify BC year numbers,
 815      * {@code 1 - year number} must be given. For example, year BC 4 is
 816      * specified as -3.
 817      *
 818      * @param year the given year.
 819      * @return {@code true} if the given year is a leap year; {@code false} otherwise.
 820      */
 821     public boolean isLeapYear(int year) {
 822         if ((year & 3) != 0) {
 823             return false;
 824         }
 825 
 826         if (year > gregorianCutoverYear) {
 827             return (year%100 != 0) || (year%400 == 0); // Gregorian
 828         }
 829         if (year < gregorianCutoverYearJulian) {
 830             return true; // Julian
 831         }
 832         boolean gregorian;
 833         // If the given year is the Gregorian cutover year, we need to
 834         // determine which calendar system to be applied to February in the year.
 835         if (gregorianCutoverYear == gregorianCutoverYearJulian) {
 836             BaseCalendar.Date d = getCalendarDate(gregorianCutoverDate); // Gregorian
 837             gregorian = d.getMonth() < BaseCalendar.MARCH;
 838         } else {
 839             gregorian = year == gregorianCutoverYear;
 840         }
 841         return gregorian ? (year%100 != 0) || (year%400 == 0) : true;
 842     }
 843 
 844     /**
 845      * Returns {@code "gregory"} as the calendar type.
 846      *
 847      * @return {@code "gregory"}
 848      * @since 1.8
 849      */
 850     @Override
 851     public String getCalendarType() {
 852         return "gregory";
 853     }
 854 
 855     /**
 856      * Compares this {@code GregorianCalendar} to the specified
 857      * {@code Object}. The result is {@code true} if and
 858      * only if the argument is a {@code GregorianCalendar} object
 859      * that represents the same time value (millisecond offset from
 860      * the <a href="Calendar.html#Epoch">Epoch</a>) under the same
 861      * {@code Calendar} parameters and Gregorian change date as
 862      * this object.
 863      *
 864      * @param obj the object to compare with.
 865      * @return {@code true} if this object is equal to {@code obj};
 866      * {@code false} otherwise.
 867      * @see Calendar#compareTo(Calendar)
 868      */
 869     @Override
 870     public boolean equals(Object obj) {
 871         return obj instanceof GregorianCalendar &&
 872             super.equals(obj) &&
 873             gregorianCutover == ((GregorianCalendar)obj).gregorianCutover;
 874     }
 875 
 876     /**
 877      * Generates the hash code for this {@code GregorianCalendar} object.
 878      */
 879     @Override
 880     public int hashCode() {
 881         return super.hashCode() ^ (int)gregorianCutoverDate;
 882     }
 883 
 884     /**
 885      * Adds the specified (signed) amount of time to the given calendar field,
 886      * based on the calendar's rules.
 887      *
 888      * <p><em>Add rule 1</em>. The value of {@code field}
 889      * after the call minus the value of {@code field} before the
 890      * call is {@code amount}, modulo any overflow that has occurred in
 891      * {@code field}. Overflow occurs when a field value exceeds its
 892      * range and, as a result, the next larger field is incremented or
 893      * decremented and the field value is adjusted back into its range.</p>
 894      *
 895      * <p><em>Add rule 2</em>. If a smaller field is expected to be
 896      * invariant, but it is impossible for it to be equal to its
 897      * prior value because of changes in its minimum or maximum after
 898      * {@code field} is changed, then its value is adjusted to be as close
 899      * as possible to its expected value. A smaller field represents a
 900      * smaller unit of time. {@code HOUR} is a smaller field than
 901      * {@code DAY_OF_MONTH}. No adjustment is made to smaller fields
 902      * that are not expected to be invariant. The calendar system
 903      * determines what fields are expected to be invariant.</p>
 904      *
 905      * @param field the calendar field.
 906      * @param amount the amount of date or time to be added to the field.
 907      * @throws    IllegalArgumentException if {@code field} is
 908      * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown,
 909      * or if any calendar fields have out-of-range values in
 910      * non-lenient mode.
 911      */
 912     @Override
 913     public void add(int field, int amount) {
 914         // If amount == 0, do nothing even the given field is out of
 915         // range. This is tested by JCK.
 916         if (amount == 0) {
 917             return;   // Do nothing!
 918         }
 919 
 920         if (field < 0 || field >= ZONE_OFFSET) {
 921             throw new IllegalArgumentException();
 922         }
 923 
 924         // Sync the time and calendar fields.
 925         complete();
 926 
 927         if (field == YEAR) {
 928             int year = internalGet(YEAR);
 929             if (internalGetEra() == CE) {
 930                 year += amount;
 931                 if (year > 0) {
 932                     set(YEAR, year);
 933                 } else { // year <= 0
 934                     set(YEAR, 1 - year);
 935                     // if year == 0, you get 1 BCE.
 936                     set(ERA, BCE);
 937                 }
 938             }
 939             else { // era == BCE
 940                 year -= amount;
 941                 if (year > 0) {
 942                     set(YEAR, year);
 943                 } else { // year <= 0
 944                     set(YEAR, 1 - year);
 945                     // if year == 0, you get 1 CE
 946                     set(ERA, CE);
 947                 }
 948             }
 949             pinDayOfMonth();
 950         } else if (field == MONTH) {
 951             int month = internalGet(MONTH) + amount;
 952             int year = internalGet(YEAR);
 953             int y_amount;
 954 
 955             if (month >= 0) {
 956                 y_amount = month/12;
 957             } else {
 958                 y_amount = (month+1)/12 - 1;
 959             }
 960             if (y_amount != 0) {
 961                 if (internalGetEra() == CE) {
 962                     year += y_amount;
 963                     if (year > 0) {
 964                         set(YEAR, year);
 965                     } else { // year <= 0
 966                         set(YEAR, 1 - year);
 967                         // if year == 0, you get 1 BCE
 968                         set(ERA, BCE);
 969                     }
 970                 }
 971                 else { // era == BCE
 972                     year -= y_amount;
 973                     if (year > 0) {
 974                         set(YEAR, year);
 975                     } else { // year <= 0
 976                         set(YEAR, 1 - year);
 977                         // if year == 0, you get 1 CE
 978                         set(ERA, CE);
 979                     }
 980                 }
 981             }
 982 
 983             if (month >= 0) {
 984                 set(MONTH,  month % 12);
 985             } else {
 986                 // month < 0
 987                 month %= 12;
 988                 if (month < 0) {
 989                     month += 12;
 990                 }
 991                 set(MONTH, JANUARY + month);
 992             }
 993             pinDayOfMonth();
 994         } else if (field == ERA) {
 995             int era = internalGet(ERA) + amount;
 996             if (era < 0) {
 997                 era = 0;
 998             }
 999             if (era > 1) {
1000                 era = 1;
1001             }
1002             set(ERA, era);
1003         } else {
1004             long delta = amount;
1005             long timeOfDay = 0;
1006             switch (field) {
1007             // Handle the time fields here. Convert the given
1008             // amount to milliseconds and call setTimeInMillis.
1009             case HOUR:
1010             case HOUR_OF_DAY:
1011                 delta *= 60 * 60 * 1000;        // hours to minutes
1012                 break;
1013 
1014             case MINUTE:
1015                 delta *= 60 * 1000;             // minutes to seconds
1016                 break;
1017 
1018             case SECOND:
1019                 delta *= 1000;                  // seconds to milliseconds
1020                 break;
1021 
1022             case MILLISECOND:
1023                 break;
1024 
1025             // Handle week, day and AM_PM fields which involves
1026             // time zone offset change adjustment. Convert the
1027             // given amount to the number of days.
1028             case WEEK_OF_YEAR:
1029             case WEEK_OF_MONTH:
1030             case DAY_OF_WEEK_IN_MONTH:
1031                 delta *= 7;
1032                 break;
1033 
1034             case DAY_OF_MONTH: // synonym of DATE
1035             case DAY_OF_YEAR:
1036             case DAY_OF_WEEK:
1037                 break;
1038 
1039             case AM_PM:
1040                 // Convert the amount to the number of days (delta)
1041                 // and +12 or -12 hours (timeOfDay).
1042                 delta = amount / 2;
1043                 timeOfDay = 12 * (amount % 2);
1044                 break;
1045             }
1046 
1047             // The time fields don't require time zone offset change
1048             // adjustment.
1049             if (field >= HOUR) {
1050                 setTimeInMillis(time + delta);
1051                 return;
1052             }
1053 
1054             // The rest of the fields (week, day or AM_PM fields)
1055             // require time zone offset (both GMT and DST) change
1056             // adjustment.
1057 
1058             // Translate the current time to the fixed date and time
1059             // of the day.
1060             long fd = getCurrentFixedDate();
1061             timeOfDay += internalGet(HOUR_OF_DAY);
1062             timeOfDay *= 60;
1063             timeOfDay += internalGet(MINUTE);
1064             timeOfDay *= 60;
1065             timeOfDay += internalGet(SECOND);
1066             timeOfDay *= 1000;
1067             timeOfDay += internalGet(MILLISECOND);
1068             if (timeOfDay >= ONE_DAY) {
1069                 fd++;
1070                 timeOfDay -= ONE_DAY;
1071             } else if (timeOfDay < 0) {
1072                 fd--;
1073                 timeOfDay += ONE_DAY;
1074             }
1075 
1076             fd += delta; // fd is the expected fixed date after the calculation
1077             int zoneOffset = internalGet(ZONE_OFFSET) + internalGet(DST_OFFSET);
1078             setTimeInMillis((fd - EPOCH_OFFSET) * ONE_DAY + timeOfDay - zoneOffset);
1079             zoneOffset -= internalGet(ZONE_OFFSET) + internalGet(DST_OFFSET);
1080             // If the time zone offset has changed, then adjust the difference.
1081             if (zoneOffset != 0) {
1082                 setTimeInMillis(time + zoneOffset);
1083                 long fd2 = getCurrentFixedDate();
1084                 // If the adjustment has changed the date, then take
1085                 // the previous one.
1086                 if (fd2 != fd) {
1087                     setTimeInMillis(time - zoneOffset);
1088                 }
1089             }
1090         }
1091     }
1092 
1093     /**
1094      * Adds or subtracts (up/down) a single unit of time on the given time
1095      * field without changing larger fields.
1096      * <p>
1097      * <em>Example</em>: Consider a {@code GregorianCalendar}
1098      * originally set to December 31, 1999. Calling {@link #roll(int,boolean) roll(Calendar.MONTH, true)}
1099      * sets the calendar to January 31, 1999.  The {@code YEAR} field is unchanged
1100      * because it is a larger field than {@code MONTH}.</p>
1101      *
1102      * @param up indicates if the value of the specified calendar field is to be
1103      * rolled up or rolled down. Use {@code true} if rolling up, {@code false} otherwise.
1104      * @throws    IllegalArgumentException if {@code field} is
1105      * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown,
1106      * or if any calendar fields have out-of-range values in
1107      * non-lenient mode.
1108      * @see #add(int,int)
1109      * @see #set(int,int)
1110      */
1111     @Override
1112     public void roll(int field, boolean up) {
1113         roll(field, up ? +1 : -1);
1114     }
1115 
1116     /**
1117      * Adds a signed amount to the specified calendar field without changing larger fields.
1118      * A negative roll amount means to subtract from field without changing
1119      * larger fields. If the specified amount is 0, this method performs nothing.
1120      *
1121      * <p>This method calls {@link #complete()} before adding the
1122      * amount so that all the calendar fields are normalized. If there
1123      * is any calendar field having an out-of-range value in non-lenient mode, then an
1124      * {@code IllegalArgumentException} is thrown.
1125      *
1126      * <p>
1127      * <em>Example</em>: Consider a {@code GregorianCalendar}
1128      * originally set to August 31, 1999. Calling <code>roll(Calendar.MONTH,
1129      * 8)</code> sets the calendar to April 30, <strong>1999</strong>. Using a
1130      * {@code GregorianCalendar}, the {@code DAY_OF_MONTH} field cannot
1131      * be 31 in the month April. {@code DAY_OF_MONTH} is set to the closest possible
1132      * value, 30. The {@code YEAR} field maintains the value of 1999 because it
1133      * is a larger field than {@code MONTH}.
1134      * <p>
1135      * <em>Example</em>: Consider a {@code GregorianCalendar}
1136      * originally set to Sunday June 6, 1999. Calling
1137      * {@code roll(Calendar.WEEK_OF_MONTH, -1)} sets the calendar to
1138      * Tuesday June 1, 1999, whereas calling
1139      * {@code add(Calendar.WEEK_OF_MONTH, -1)} sets the calendar to
1140      * Sunday May 30, 1999. This is because the roll rule imposes an
1141      * additional constraint: The {@code MONTH} must not change when the
1142      * {@code WEEK_OF_MONTH} is rolled. Taken together with add rule 1,
1143      * the resultant date must be between Tuesday June 1 and Saturday June
1144      * 5. According to add rule 2, the {@code DAY_OF_WEEK}, an invariant
1145      * when changing the {@code WEEK_OF_MONTH}, is set to Tuesday, the
1146      * closest possible value to Sunday (where Sunday is the first day of the
1147      * week).</p>
1148      *
1149      * @param field the calendar field.
1150      * @param amount the signed amount to add to {@code field}.
1151      * @throws    IllegalArgumentException if {@code field} is
1152      * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown,
1153      * or if any calendar fields have out-of-range values in
1154      * non-lenient mode.
1155      * @see #roll(int,boolean)
1156      * @see #add(int,int)
1157      * @see #set(int,int)
1158      * @since 1.2
1159      */
1160     @Override
1161     public void roll(int field, int amount) {
1162         // If amount == 0, do nothing even the given field is out of
1163         // range. This is tested by JCK.
1164         if (amount == 0) {
1165             return;
1166         }
1167 
1168         if (field < 0 || field >= ZONE_OFFSET) {
1169             throw new IllegalArgumentException();
1170         }
1171 
1172         // Sync the time and calendar fields.
1173         complete();
1174 
1175         int min = getMinimum(field);
1176         int max = getMaximum(field);
1177 
1178         switch (field) {
1179         case AM_PM:
1180         case ERA:
1181         case YEAR:
1182         case MINUTE:
1183         case SECOND:
1184         case MILLISECOND:
1185             // These fields are handled simply, since they have fixed minima
1186             // and maxima.  The field DAY_OF_MONTH is almost as simple.  Other
1187             // fields are complicated, since the range within they must roll
1188             // varies depending on the date.
1189             break;
1190 
1191         case HOUR:
1192         case HOUR_OF_DAY:
1193             {
1194                 int rolledValue = getRolledValue(internalGet(field), amount, min, max);
1195                 int hourOfDay = rolledValue;
1196                 if (field == HOUR && internalGet(AM_PM) == PM) {
1197                     hourOfDay += 12;
1198                 }
1199 
1200                 // Create the current date/time value to perform wall-clock-based
1201                 // roll.
1202                 CalendarDate d = calsys.getCalendarDate(time, getZone());
1203                 d.setHours(hourOfDay);
1204                 time = calsys.getTime(d);
1205 
1206                 // If we stay on the same wall-clock time, try the next or previous hour.
1207                 if (internalGet(HOUR_OF_DAY) == d.getHours()) {
1208                     hourOfDay = getRolledValue(rolledValue, amount > 0 ? +1 : -1, min, max);
1209                     if (field == HOUR && internalGet(AM_PM) == PM) {
1210                         hourOfDay += 12;
1211                     }
1212                     d.setHours(hourOfDay);
1213                     time = calsys.getTime(d);
1214                 }
1215                 // Get the new hourOfDay value which might have changed due to a DST transition.
1216                 hourOfDay = d.getHours();
1217                 // Update the hour related fields
1218                 internalSet(HOUR_OF_DAY, hourOfDay);
1219                 internalSet(AM_PM, hourOfDay / 12);
1220                 internalSet(HOUR, hourOfDay % 12);
1221 
1222                 // Time zone offset and/or daylight saving might have changed.
1223                 int zoneOffset = d.getZoneOffset();
1224                 int saving = d.getDaylightSaving();
1225                 internalSet(ZONE_OFFSET, zoneOffset - saving);
1226                 internalSet(DST_OFFSET, saving);
1227                 return;
1228             }
1229 
1230         case MONTH:
1231             // Rolling the month involves both pinning the final value to [0, 11]
1232             // and adjusting the DAY_OF_MONTH if necessary.  We only adjust the
1233             // DAY_OF_MONTH if, after updating the MONTH field, it is illegal.
1234             // E.g., <jan31>.roll(MONTH, 1) -> <feb28> or <feb29>.
1235             {
1236                 if (!isCutoverYear(cdate.getNormalizedYear())) {
1237                     int mon = (internalGet(MONTH) + amount) % 12;
1238                     if (mon < 0) {
1239                         mon += 12;
1240                     }
1241                     set(MONTH, mon);
1242 
1243                     // Keep the day of month in the range.  We don't want to spill over
1244                     // into the next month; e.g., we don't want jan31 + 1 mo -> feb31 ->
1245                     // mar3.
1246                     int monthLen = monthLength(mon);
1247                     if (internalGet(DAY_OF_MONTH) > monthLen) {
1248                         set(DAY_OF_MONTH, monthLen);
1249                     }
1250                 } else {
1251                     // We need to take care of different lengths in
1252                     // year and month due to the cutover.
1253                     int yearLength = getActualMaximum(MONTH) + 1;
1254                     int mon = (internalGet(MONTH) + amount) % yearLength;
1255                     if (mon < 0) {
1256                         mon += yearLength;
1257                     }
1258                     set(MONTH, mon);
1259                     int monthLen = getActualMaximum(DAY_OF_MONTH);
1260                     if (internalGet(DAY_OF_MONTH) > monthLen) {
1261                         set(DAY_OF_MONTH, monthLen);
1262                     }
1263                 }
1264                 return;
1265             }
1266 
1267         case WEEK_OF_YEAR:
1268             {
1269                 int y = cdate.getNormalizedYear();
1270                 max = getActualMaximum(WEEK_OF_YEAR);
1271                 set(DAY_OF_WEEK, internalGet(DAY_OF_WEEK));
1272                 int woy = internalGet(WEEK_OF_YEAR);
1273                 int value = woy + amount;
1274                 if (!isCutoverYear(y)) {
1275                     int weekYear = getWeekYear();
1276                     if (weekYear == y) {
1277                         // If the new value is in between min and max
1278                         // (exclusive), then we can use the value.
1279                         if (value > min && value < max) {
1280                             set(WEEK_OF_YEAR, value);
1281                             return;
1282                         }
1283                         long fd = getCurrentFixedDate();
1284                         // Make sure that the min week has the current DAY_OF_WEEK
1285                         // in the calendar year
1286                         long day1 = fd - (7 * (woy - min));
1287                         if (calsys.getYearFromFixedDate(day1) != y) {
1288                             min++;
1289                         }
1290 
1291                         // Make sure the same thing for the max week
1292                         fd += 7 * (max - internalGet(WEEK_OF_YEAR));
1293                         if (calsys.getYearFromFixedDate(fd) != y) {
1294                             max--;
1295                         }
1296                     } else {
1297                         // When WEEK_OF_YEAR and YEAR are out of sync,
1298                         // adjust woy and amount to stay in the calendar year.
1299                         if (weekYear > y) {
1300                             if (amount < 0) {
1301                                 amount++;
1302                             }
1303                             woy = max;
1304                         } else {
1305                             if (amount > 0) {
1306                                 amount -= woy - max;
1307                             }
1308                             woy = min;
1309                         }
1310                     }
1311                     set(field, getRolledValue(woy, amount, min, max));
1312                     return;
1313                 }
1314 
1315                 // Handle cutover here.
1316                 long fd = getCurrentFixedDate();
1317                 BaseCalendar cal;
1318                 if (gregorianCutoverYear == gregorianCutoverYearJulian) {
1319                     cal = getCutoverCalendarSystem();
1320                 } else if (y == gregorianCutoverYear) {
1321                     cal = gcal;
1322                 } else {
1323                     cal = getJulianCalendarSystem();
1324                 }
1325                 long day1 = fd - (7 * (woy - min));
1326                 // Make sure that the min week has the current DAY_OF_WEEK
1327                 if (cal.getYearFromFixedDate(day1) != y) {
1328                     min++;
1329                 }
1330 
1331                 // Make sure the same thing for the max week
1332                 fd += 7 * (max - woy);
1333                 cal = (fd >= gregorianCutoverDate) ? gcal : getJulianCalendarSystem();
1334                 if (cal.getYearFromFixedDate(fd) != y) {
1335                     max--;
1336                 }
1337                 // value: the new WEEK_OF_YEAR which must be converted
1338                 // to month and day of month.
1339                 value = getRolledValue(woy, amount, min, max) - 1;
1340                 BaseCalendar.Date d = getCalendarDate(day1 + value * 7);
1341                 set(MONTH, d.getMonth() - 1);
1342                 set(DAY_OF_MONTH, d.getDayOfMonth());
1343                 return;
1344             }
1345 
1346         case WEEK_OF_MONTH:
1347             {
1348                 boolean isCutoverYear = isCutoverYear(cdate.getNormalizedYear());
1349                 // dow: relative day of week from first day of week
1350                 int dow = internalGet(DAY_OF_WEEK) - getFirstDayOfWeek();
1351                 if (dow < 0) {
1352                     dow += 7;
1353                 }
1354 
1355                 long fd = getCurrentFixedDate();
1356                 long month1;     // fixed date of the first day (usually 1) of the month
1357                 int monthLength; // actual month length
1358                 if (isCutoverYear) {
1359                     month1 = getFixedDateMonth1(cdate, fd);
1360                     monthLength = actualMonthLength();
1361                 } else {
1362                     month1 = fd - internalGet(DAY_OF_MONTH) + 1;
1363                     monthLength = calsys.getMonthLength(cdate);
1364                 }
1365 
1366                 // the first day of week of the month.
1367                 long monthDay1st = BaseCalendar.getDayOfWeekDateOnOrBefore(month1 + 6,
1368                                                                            getFirstDayOfWeek());
1369                 // if the week has enough days to form a week, the
1370                 // week starts from the previous month.
1371                 if ((int)(monthDay1st - month1) >= getMinimalDaysInFirstWeek()) {
1372                     monthDay1st -= 7;
1373                 }
1374                 max = getActualMaximum(field);
1375 
1376                 // value: the new WEEK_OF_MONTH value
1377                 int value = getRolledValue(internalGet(field), amount, 1, max) - 1;
1378 
1379                 // nfd: fixed date of the rolled date
1380                 long nfd = monthDay1st + value * 7 + dow;
1381 
1382                 // Unlike WEEK_OF_YEAR, we need to change day of week if the
1383                 // nfd is out of the month.
1384                 if (nfd < month1) {
1385                     nfd = month1;
1386                 } else if (nfd >= (month1 + monthLength)) {
1387                     nfd = month1 + monthLength - 1;
1388                 }
1389                 int dayOfMonth;
1390                 if (isCutoverYear) {
1391                     // If we are in the cutover year, convert nfd to
1392                     // its calendar date and use dayOfMonth.
1393                     BaseCalendar.Date d = getCalendarDate(nfd);
1394                     dayOfMonth = d.getDayOfMonth();
1395                 } else {
1396                     dayOfMonth = (int)(nfd - month1) + 1;
1397                 }
1398                 set(DAY_OF_MONTH, dayOfMonth);
1399                 return;
1400             }
1401 
1402         case DAY_OF_MONTH:
1403             {
1404                 if (!isCutoverYear(cdate.getNormalizedYear())) {
1405                     max = calsys.getMonthLength(cdate);
1406                     break;
1407                 }
1408 
1409                 // Cutover year handling
1410                 long fd = getCurrentFixedDate();
1411                 long month1 = getFixedDateMonth1(cdate, fd);
1412                 // It may not be a regular month. Convert the date and range to
1413                 // the relative values, perform the roll, and
1414                 // convert the result back to the rolled date.
1415                 int value = getRolledValue((int)(fd - month1), amount, 0, actualMonthLength() - 1);
1416                 BaseCalendar.Date d = getCalendarDate(month1 + value);
1417                 assert d.getMonth()-1 == internalGet(MONTH);
1418                 set(DAY_OF_MONTH, d.getDayOfMonth());
1419                 return;
1420             }
1421 
1422         case DAY_OF_YEAR:
1423             {
1424                 max = getActualMaximum(field);
1425                 if (!isCutoverYear(cdate.getNormalizedYear())) {
1426                     break;
1427                 }
1428 
1429                 // Handle cutover here.
1430                 long fd = getCurrentFixedDate();
1431                 long jan1 = fd - internalGet(DAY_OF_YEAR) + 1;
1432                 int value = getRolledValue((int)(fd - jan1) + 1, amount, min, max);
1433                 BaseCalendar.Date d = getCalendarDate(jan1 + value - 1);
1434                 set(MONTH, d.getMonth() - 1);
1435                 set(DAY_OF_MONTH, d.getDayOfMonth());
1436                 return;
1437             }
1438 
1439         case DAY_OF_WEEK:
1440             {
1441                 if (!isCutoverYear(cdate.getNormalizedYear())) {
1442                     // If the week of year is in the same year, we can
1443                     // just change DAY_OF_WEEK.
1444                     int weekOfYear = internalGet(WEEK_OF_YEAR);
1445                     if (weekOfYear > 1 && weekOfYear < 52) {
1446                         set(WEEK_OF_YEAR, weekOfYear); // update stamp[WEEK_OF_YEAR]
1447                         max = SATURDAY;
1448                         break;
1449                     }
1450                 }
1451 
1452                 // We need to handle it in a different way around year
1453                 // boundaries and in the cutover year. Note that
1454                 // changing era and year values violates the roll
1455                 // rule: not changing larger calendar fields...
1456                 amount %= 7;
1457                 if (amount == 0) {
1458                     return;
1459                 }
1460                 long fd = getCurrentFixedDate();
1461                 long dowFirst = BaseCalendar.getDayOfWeekDateOnOrBefore(fd, getFirstDayOfWeek());
1462                 fd += amount;
1463                 if (fd < dowFirst) {
1464                     fd += 7;
1465                 } else if (fd >= dowFirst + 7) {
1466                     fd -= 7;
1467                 }
1468                 BaseCalendar.Date d = getCalendarDate(fd);
1469                 set(ERA, (d.getNormalizedYear() <= 0 ? BCE : CE));
1470                 set(d.getYear(), d.getMonth() - 1, d.getDayOfMonth());
1471                 return;
1472             }
1473 
1474         case DAY_OF_WEEK_IN_MONTH:
1475             {
1476                 min = 1; // after normalized, min should be 1.
1477                 if (!isCutoverYear(cdate.getNormalizedYear())) {
1478                     int dom = internalGet(DAY_OF_MONTH);
1479                     int monthLength = calsys.getMonthLength(cdate);
1480                     int lastDays = monthLength % 7;
1481                     max = monthLength / 7;
1482                     int x = (dom - 1) % 7;
1483                     if (x < lastDays) {
1484                         max++;
1485                     }
1486                     set(DAY_OF_WEEK, internalGet(DAY_OF_WEEK));
1487                     break;
1488                 }
1489 
1490                 // Cutover year handling
1491                 long fd = getCurrentFixedDate();
1492                 long month1 = getFixedDateMonth1(cdate, fd);
1493                 int monthLength = actualMonthLength();
1494                 int lastDays = monthLength % 7;
1495                 max = monthLength / 7;
1496                 int x = (int)(fd - month1) % 7;
1497                 if (x < lastDays) {
1498                     max++;
1499                 }
1500                 int value = getRolledValue(internalGet(field), amount, min, max) - 1;
1501                 fd = month1 + value * 7 + x;
1502                 BaseCalendar cal = (fd >= gregorianCutoverDate) ? gcal : getJulianCalendarSystem();
1503                 BaseCalendar.Date d = (BaseCalendar.Date) cal.newCalendarDate(TimeZone.NO_TIMEZONE);
1504                 cal.getCalendarDateFromFixedDate(d, fd);
1505                 set(DAY_OF_MONTH, d.getDayOfMonth());
1506                 return;
1507             }
1508         }
1509 
1510         set(field, getRolledValue(internalGet(field), amount, min, max));
1511     }
1512 
1513     /**
1514      * Returns the minimum value for the given calendar field of this
1515      * {@code GregorianCalendar} instance. The minimum value is
1516      * defined as the smallest value returned by the {@link
1517      * Calendar#get(int) get} method for any possible time value,
1518      * taking into consideration the current values of the
1519      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1520      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1521      * {@link #getGregorianChange() getGregorianChange} and
1522      * {@link Calendar#getTimeZone() getTimeZone} methods.
1523      *
1524      * @param field the calendar field.
1525      * @return the minimum value for the given calendar field.
1526      * @see #getMaximum(int)
1527      * @see #getGreatestMinimum(int)
1528      * @see #getLeastMaximum(int)
1529      * @see #getActualMinimum(int)
1530      * @see #getActualMaximum(int)
1531      */
1532     @Override
1533     public int getMinimum(int field) {
1534         return MIN_VALUES[field];
1535     }
1536 
1537     /**
1538      * Returns the maximum value for the given calendar field of this
1539      * {@code GregorianCalendar} instance. The maximum value is
1540      * defined as the largest value returned by the {@link
1541      * Calendar#get(int) get} method for any possible time value,
1542      * taking into consideration the current values of the
1543      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1544      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1545      * {@link #getGregorianChange() getGregorianChange} and
1546      * {@link Calendar#getTimeZone() getTimeZone} methods.
1547      *
1548      * @param field the calendar field.
1549      * @return the maximum value for the given calendar field.
1550      * @see #getMinimum(int)
1551      * @see #getGreatestMinimum(int)
1552      * @see #getLeastMaximum(int)
1553      * @see #getActualMinimum(int)
1554      * @see #getActualMaximum(int)
1555      */
1556     @Override
1557     public int getMaximum(int field) {
1558         switch (field) {
1559         case MONTH:
1560         case DAY_OF_MONTH:
1561         case DAY_OF_YEAR:
1562         case WEEK_OF_YEAR:
1563         case WEEK_OF_MONTH:
1564         case DAY_OF_WEEK_IN_MONTH:
1565         case YEAR:
1566             {
1567                 // On or after Gregorian 200-3-1, Julian and Gregorian
1568                 // calendar dates are the same or Gregorian dates are
1569                 // larger (i.e., there is a "gap") after 300-3-1.
1570                 if (gregorianCutoverYear > 200) {
1571                     break;
1572                 }
1573                 // There might be "overlapping" dates.
1574                 GregorianCalendar gc = (GregorianCalendar) clone();
1575                 gc.setLenient(true);
1576                 gc.setTimeInMillis(gregorianCutover);
1577                 int v1 = gc.getActualMaximum(field);
1578                 gc.setTimeInMillis(gregorianCutover-1);
1579                 int v2 = gc.getActualMaximum(field);
1580                 return Math.max(MAX_VALUES[field], Math.max(v1, v2));
1581             }
1582         }
1583         return MAX_VALUES[field];
1584     }
1585 
1586     /**
1587      * Returns the highest minimum value for the given calendar field
1588      * of this {@code GregorianCalendar} instance. The highest
1589      * minimum value is defined as the largest value returned by
1590      * {@link #getActualMinimum(int)} for any possible time value,
1591      * taking into consideration the current values of the
1592      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1593      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1594      * {@link #getGregorianChange() getGregorianChange} and
1595      * {@link Calendar#getTimeZone() getTimeZone} methods.
1596      *
1597      * @param field the calendar field.
1598      * @return the highest minimum value for the given calendar field.
1599      * @see #getMinimum(int)
1600      * @see #getMaximum(int)
1601      * @see #getLeastMaximum(int)
1602      * @see #getActualMinimum(int)
1603      * @see #getActualMaximum(int)
1604      */
1605     @Override
1606     public int getGreatestMinimum(int field) {
1607         if (field == DAY_OF_MONTH) {
1608             BaseCalendar.Date d = getGregorianCutoverDate();
1609             long mon1 = getFixedDateMonth1(d, gregorianCutoverDate);
1610             d = getCalendarDate(mon1);
1611             return Math.max(MIN_VALUES[field], d.getDayOfMonth());
1612         }
1613         return MIN_VALUES[field];
1614     }
1615 
1616     /**
1617      * Returns the lowest maximum value for the given calendar field
1618      * of this {@code GregorianCalendar} instance. The lowest
1619      * maximum value is defined as the smallest value returned by
1620      * {@link #getActualMaximum(int)} for any possible time value,
1621      * taking into consideration the current values of the
1622      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1623      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1624      * {@link #getGregorianChange() getGregorianChange} and
1625      * {@link Calendar#getTimeZone() getTimeZone} methods.
1626      *
1627      * @param field the calendar field
1628      * @return the lowest maximum value for the given calendar field.
1629      * @see #getMinimum(int)
1630      * @see #getMaximum(int)
1631      * @see #getGreatestMinimum(int)
1632      * @see #getActualMinimum(int)
1633      * @see #getActualMaximum(int)
1634      */
1635     @Override
1636     public int getLeastMaximum(int field) {
1637         switch (field) {
1638         case MONTH:
1639         case DAY_OF_MONTH:
1640         case DAY_OF_YEAR:
1641         case WEEK_OF_YEAR:
1642         case WEEK_OF_MONTH:
1643         case DAY_OF_WEEK_IN_MONTH:
1644         case YEAR:
1645             {
1646                 GregorianCalendar gc = (GregorianCalendar) clone();
1647                 gc.setLenient(true);
1648                 gc.setTimeInMillis(gregorianCutover);
1649                 int v1 = gc.getActualMaximum(field);
1650                 gc.setTimeInMillis(gregorianCutover-1);
1651                 int v2 = gc.getActualMaximum(field);
1652                 return Math.min(LEAST_MAX_VALUES[field], Math.min(v1, v2));
1653             }
1654         }
1655         return LEAST_MAX_VALUES[field];
1656     }
1657 
1658     /**
1659      * Returns the minimum value that this calendar field could have,
1660      * taking into consideration the given time value and the current
1661      * values of the
1662      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1663      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1664      * {@link #getGregorianChange() getGregorianChange} and
1665      * {@link Calendar#getTimeZone() getTimeZone} methods.
1666      *
1667      * <p>For example, if the Gregorian change date is January 10,
1668      * 1970 and the date of this {@code GregorianCalendar} is
1669      * January 20, 1970, the actual minimum value of the
1670      * {@code DAY_OF_MONTH} field is 10 because the previous date
1671      * of January 10, 1970 is December 27, 1996 (in the Julian
1672      * calendar). Therefore, December 28, 1969 to January 9, 1970
1673      * don't exist.
1674      *
1675      * @param field the calendar field
1676      * @return the minimum of the given field for the time value of
1677      * this {@code GregorianCalendar}
1678      * @see #getMinimum(int)
1679      * @see #getMaximum(int)
1680      * @see #getGreatestMinimum(int)
1681      * @see #getLeastMaximum(int)
1682      * @see #getActualMaximum(int)
1683      * @since 1.2
1684      */
1685     @Override
1686     public int getActualMinimum(int field) {
1687         if (field == DAY_OF_MONTH) {
1688             GregorianCalendar gc = getNormalizedCalendar();
1689             int year = gc.cdate.getNormalizedYear();
1690             if (year == gregorianCutoverYear || year == gregorianCutoverYearJulian) {
1691                 long month1 = getFixedDateMonth1(gc.cdate, gc.calsys.getFixedDate(gc.cdate));
1692                 BaseCalendar.Date d = getCalendarDate(month1);
1693                 return d.getDayOfMonth();
1694             }
1695         }
1696         return getMinimum(field);
1697     }
1698 
1699     /**
1700      * Returns the maximum value that this calendar field could have,
1701      * taking into consideration the given time value and the current
1702      * values of the
1703      * {@link Calendar#getFirstDayOfWeek() getFirstDayOfWeek},
1704      * {@link Calendar#getMinimalDaysInFirstWeek() getMinimalDaysInFirstWeek},
1705      * {@link #getGregorianChange() getGregorianChange} and
1706      * {@link Calendar#getTimeZone() getTimeZone} methods.
1707      * For example, if the date of this instance is February 1, 2004,
1708      * the actual maximum value of the {@code DAY_OF_MONTH} field
1709      * is 29 because 2004 is a leap year, and if the date of this
1710      * instance is February 1, 2005, it's 28.
1711      *
1712      * <p>This method calculates the maximum value of {@link
1713      * Calendar#WEEK_OF_YEAR WEEK_OF_YEAR} based on the {@link
1714      * Calendar#YEAR YEAR} (calendar year) value, not the <a
1715      * href="#week_year">week year</a>. Call {@link
1716      * #getWeeksInWeekYear()} to get the maximum value of {@code
1717      * WEEK_OF_YEAR} in the week year of this {@code GregorianCalendar}.
1718      *
1719      * @param field the calendar field
1720      * @return the maximum of the given field for the time value of
1721      * this {@code GregorianCalendar}
1722      * @see #getMinimum(int)
1723      * @see #getMaximum(int)
1724      * @see #getGreatestMinimum(int)
1725      * @see #getLeastMaximum(int)
1726      * @see #getActualMinimum(int)
1727      * @since 1.2
1728      */
1729     @Override
1730     public int getActualMaximum(int field) {
1731         final int fieldsForFixedMax = ERA_MASK|DAY_OF_WEEK_MASK|HOUR_MASK|AM_PM_MASK|
1732             HOUR_OF_DAY_MASK|MINUTE_MASK|SECOND_MASK|MILLISECOND_MASK|
1733             ZONE_OFFSET_MASK|DST_OFFSET_MASK;
1734         if ((fieldsForFixedMax & (1<<field)) != 0) {
1735             return getMaximum(field);
1736         }
1737 
1738         GregorianCalendar gc = getNormalizedCalendar();
1739         BaseCalendar.Date date = gc.cdate;
1740         BaseCalendar cal = gc.calsys;
1741         int normalizedYear = date.getNormalizedYear();
1742 
1743         int value = -1;
1744         switch (field) {
1745         case MONTH:
1746             {
1747                 if (!gc.isCutoverYear(normalizedYear)) {
1748                     value = DECEMBER;
1749                     break;
1750                 }
1751 
1752                 // January 1 of the next year may or may not exist.
1753                 long nextJan1;
1754                 do {
1755                     nextJan1 = gcal.getFixedDate(++normalizedYear, BaseCalendar.JANUARY, 1, null);
1756                 } while (nextJan1 < gregorianCutoverDate);
1757                 BaseCalendar.Date d = (BaseCalendar.Date) date.clone();
1758                 cal.getCalendarDateFromFixedDate(d, nextJan1 - 1);
1759                 value = d.getMonth() - 1;
1760             }
1761             break;
1762 
1763         case DAY_OF_MONTH:
1764             {
1765                 value = cal.getMonthLength(date);
1766                 if (!gc.isCutoverYear(normalizedYear) || date.getDayOfMonth() == value) {
1767                     break;
1768                 }
1769 
1770                 // Handle cutover year.
1771                 long fd = gc.getCurrentFixedDate();
1772                 if (fd >= gregorianCutoverDate) {
1773                     break;
1774                 }
1775                 int monthLength = gc.actualMonthLength();
1776                 long monthEnd = gc.getFixedDateMonth1(gc.cdate, fd) + monthLength - 1;
1777                 // Convert the fixed date to its calendar date.
1778                 BaseCalendar.Date d = gc.getCalendarDate(monthEnd);
1779                 value = d.getDayOfMonth();
1780             }
1781             break;
1782 
1783         case DAY_OF_YEAR:
1784             {
1785                 if (!gc.isCutoverYear(normalizedYear)) {
1786                     value = cal.getYearLength(date);
1787                     break;
1788                 }
1789 
1790                 // Handle cutover year.
1791                 long jan1;
1792                 if (gregorianCutoverYear == gregorianCutoverYearJulian) {
1793                     BaseCalendar cocal = gc.getCutoverCalendarSystem();
1794                     jan1 = cocal.getFixedDate(normalizedYear, 1, 1, null);
1795                 } else if (normalizedYear == gregorianCutoverYearJulian) {
1796                     jan1 = cal.getFixedDate(normalizedYear, 1, 1, null);
1797                 } else {
1798                     jan1 = gregorianCutoverDate;
1799                 }
1800                 // January 1 of the next year may or may not exist.
1801                 long nextJan1 = gcal.getFixedDate(++normalizedYear, 1, 1, null);
1802                 if (nextJan1 < gregorianCutoverDate) {
1803                     nextJan1 = gregorianCutoverDate;
1804                 }
1805                 assert jan1 <= cal.getFixedDate(date.getNormalizedYear(), date.getMonth(),
1806                                                 date.getDayOfMonth(), date);
1807                 assert nextJan1 >= cal.getFixedDate(date.getNormalizedYear(), date.getMonth(),
1808                                                 date.getDayOfMonth(), date);
1809                 value = (int)(nextJan1 - jan1);
1810             }
1811             break;
1812 
1813         case WEEK_OF_YEAR:
1814             {
1815                 if (!gc.isCutoverYear(normalizedYear)) {
1816                     // Get the day of week of January 1 of the year
1817                     CalendarDate d = cal.newCalendarDate(TimeZone.NO_TIMEZONE);
1818                     d.setDate(date.getYear(), BaseCalendar.JANUARY, 1);
1819                     int dayOfWeek = cal.getDayOfWeek(d);
1820                     // Normalize the day of week with the firstDayOfWeek value
1821                     dayOfWeek -= getFirstDayOfWeek();
1822                     if (dayOfWeek < 0) {
1823                         dayOfWeek += 7;
1824                     }
1825                     value = 52;
1826                     int magic = dayOfWeek + getMinimalDaysInFirstWeek() - 1;
1827                     if ((magic == 6) ||
1828                         (date.isLeapYear() && (magic == 5 || magic == 12))) {
1829                         value++;
1830                     }
1831                     break;
1832                 }
1833 
1834                 if (gc == this) {
1835                     gc = (GregorianCalendar) gc.clone();
1836                 }
1837                 int maxDayOfYear = getActualMaximum(DAY_OF_YEAR);
1838                 gc.set(DAY_OF_YEAR, maxDayOfYear);
1839                 value = gc.get(WEEK_OF_YEAR);
1840                 if (internalGet(YEAR) != gc.getWeekYear()) {
1841                     gc.set(DAY_OF_YEAR, maxDayOfYear - 7);
1842                     value = gc.get(WEEK_OF_YEAR);
1843                 }
1844             }
1845             break;
1846 
1847         case WEEK_OF_MONTH:
1848             {
1849                 if (!gc.isCutoverYear(normalizedYear)) {
1850                     CalendarDate d = cal.newCalendarDate(null);
1851                     d.setDate(date.getYear(), date.getMonth(), 1);
1852                     int dayOfWeek = cal.getDayOfWeek(d);
1853                     int monthLength = cal.getMonthLength(d);
1854                     dayOfWeek -= getFirstDayOfWeek();
1855                     if (dayOfWeek < 0) {
1856                         dayOfWeek += 7;
1857                     }
1858                     int nDaysFirstWeek = 7 - dayOfWeek; // # of days in the first week
1859                     value = 3;
1860                     if (nDaysFirstWeek >= getMinimalDaysInFirstWeek()) {
1861                         value++;
1862                     }
1863                     monthLength -= nDaysFirstWeek + 7 * 3;
1864                     if (monthLength > 0) {
1865                         value++;
1866                         if (monthLength > 7) {
1867                             value++;
1868                         }
1869                     }
1870                     break;
1871                 }
1872 
1873                 // Cutover year handling
1874                 if (gc == this) {
1875                     gc = (GregorianCalendar) gc.clone();
1876                 }
1877                 int y = gc.internalGet(YEAR);
1878                 int m = gc.internalGet(MONTH);
1879                 do {
1880                     value = gc.get(WEEK_OF_MONTH);
1881                     gc.add(WEEK_OF_MONTH, +1);
1882                 } while (gc.get(YEAR) == y && gc.get(MONTH) == m);
1883             }
1884             break;
1885 
1886         case DAY_OF_WEEK_IN_MONTH:
1887             {
1888                 // may be in the Gregorian cutover month
1889                 int ndays, dow1;
1890                 int dow = date.getDayOfWeek();
1891                 if (!gc.isCutoverYear(normalizedYear)) {
1892                     BaseCalendar.Date d = (BaseCalendar.Date) date.clone();
1893                     ndays = cal.getMonthLength(d);
1894                     d.setDayOfMonth(1);
1895                     cal.normalize(d);
1896                     dow1 = d.getDayOfWeek();
1897                 } else {
1898                     // Let a cloned GregorianCalendar take care of the cutover cases.
1899                     if (gc == this) {
1900                         gc = (GregorianCalendar) clone();
1901                     }
1902                     ndays = gc.actualMonthLength();
1903                     gc.set(DAY_OF_MONTH, gc.getActualMinimum(DAY_OF_MONTH));
1904                     dow1 = gc.get(DAY_OF_WEEK);
1905                 }
1906                 int x = dow - dow1;
1907                 if (x < 0) {
1908                     x += 7;
1909                 }
1910                 ndays -= x;
1911                 value = (ndays + 6) / 7;
1912             }
1913             break;
1914 
1915         case YEAR:
1916             /* The year computation is no different, in principle, from the
1917              * others, however, the range of possible maxima is large.  In
1918              * addition, the way we know we've exceeded the range is different.
1919              * For these reasons, we use the special case code below to handle
1920              * this field.
1921              *
1922              * The actual maxima for YEAR depend on the type of calendar:
1923              *
1924              *     Gregorian = May 17, 292275056 BCE - Aug 17, 292278994 CE
1925              *     Julian    = Dec  2, 292269055 BCE - Jan  3, 292272993 CE
1926              *     Hybrid    = Dec  2, 292269055 BCE - Aug 17, 292278994 CE
1927              *
1928              * We know we've exceeded the maximum when either the month, date,
1929              * time, or era changes in response to setting the year.  We don't
1930              * check for month, date, and time here because the year and era are
1931              * sufficient to detect an invalid year setting.  NOTE: If code is
1932              * added to check the month and date in the future for some reason,
1933              * Feb 29 must be allowed to shift to Mar 1 when setting the year.
1934              */
1935             {
1936                 if (gc == this) {
1937                     gc = (GregorianCalendar) clone();
1938                 }
1939 
1940                 // Calculate the millisecond offset from the beginning
1941                 // of the year of this calendar and adjust the max
1942                 // year value if we are beyond the limit in the max
1943                 // year.
1944                 long current = gc.getYearOffsetInMillis();
1945 
1946                 if (gc.internalGetEra() == CE) {
1947                     gc.setTimeInMillis(Long.MAX_VALUE);
1948                     value = gc.get(YEAR);
1949                     long maxEnd = gc.getYearOffsetInMillis();
1950                     if (current > maxEnd) {
1951                         value--;
1952                     }
1953                 } else {
1954                     CalendarSystem mincal = gc.getTimeInMillis() >= gregorianCutover ?
1955                         gcal : getJulianCalendarSystem();
1956                     CalendarDate d = mincal.getCalendarDate(Long.MIN_VALUE, getZone());
1957                     long maxEnd = (cal.getDayOfYear(d) - 1) * 24 + d.getHours();
1958                     maxEnd *= 60;
1959                     maxEnd += d.getMinutes();
1960                     maxEnd *= 60;
1961                     maxEnd += d.getSeconds();
1962                     maxEnd *= 1000;
1963                     maxEnd += d.getMillis();
1964                     value = d.getYear();
1965                     if (value <= 0) {
1966                         assert mincal == gcal;
1967                         value = 1 - value;
1968                     }
1969                     if (current < maxEnd) {
1970                         value--;
1971                     }
1972                 }
1973             }
1974             break;
1975 
1976         default:
1977             throw new ArrayIndexOutOfBoundsException(field);
1978         }
1979         return value;
1980     }
1981 
1982     /**
1983      * Returns the millisecond offset from the beginning of this
1984      * year. This Calendar object must have been normalized.
1985      */
1986     private long getYearOffsetInMillis() {
1987         long t = (internalGet(DAY_OF_YEAR) - 1) * 24;
1988         t += internalGet(HOUR_OF_DAY);
1989         t *= 60;
1990         t += internalGet(MINUTE);
1991         t *= 60;
1992         t += internalGet(SECOND);
1993         t *= 1000;
1994         return t + internalGet(MILLISECOND) -
1995             (internalGet(ZONE_OFFSET) + internalGet(DST_OFFSET));
1996     }
1997 
1998     @Override
1999     public Object clone()
2000     {
2001         GregorianCalendar other = (GregorianCalendar) super.clone();
2002 
2003         other.gdate = (BaseCalendar.Date) gdate.clone();
2004         if (cdate != null) {
2005             if (cdate != gdate) {
2006                 other.cdate = (BaseCalendar.Date) cdate.clone();
2007             } else {
2008                 other.cdate = other.gdate;
2009             }
2010         }
2011         other.originalFields = null;
2012         other.zoneOffsets = null;
2013         return other;
2014     }
2015 
2016     @Override
2017     public TimeZone getTimeZone() {
2018         TimeZone zone = super.getTimeZone();
2019         // To share the zone by CalendarDates
2020         gdate.setZone(zone);
2021         if (cdate != null && cdate != gdate) {
2022             cdate.setZone(zone);
2023         }
2024         return zone;
2025     }
2026 
2027     @Override
2028     public void setTimeZone(TimeZone zone) {
2029         super.setTimeZone(zone);
2030         // To share the zone by CalendarDates
2031         gdate.setZone(zone);
2032         if (cdate != null && cdate != gdate) {
2033             cdate.setZone(zone);
2034         }
2035     }
2036 
2037     /**
2038      * Returns {@code true} indicating this {@code GregorianCalendar}
2039      * supports week dates.
2040      *
2041      * @return {@code true} (always)
2042      * @see #getWeekYear()
2043      * @see #setWeekDate(int,int,int)
2044      * @see #getWeeksInWeekYear()
2045      * @since 1.7
2046      */
2047     @Override
2048     public final boolean isWeekDateSupported() {
2049         return true;
2050     }
2051 
2052     /**
2053      * Returns the <a href="#week_year">week year</a> represented by this
2054      * {@code GregorianCalendar}. The dates in the weeks between 1 and the
2055      * maximum week number of the week year have the same week year value
2056      * that may be one year before or after the {@link Calendar#YEAR YEAR}
2057      * (calendar year) value.
2058      *
2059      * <p>This method calls {@link Calendar#complete()} before
2060      * calculating the week year.
2061      *
2062      * @return the week year represented by this {@code GregorianCalendar}.
2063      *         If the {@link Calendar#ERA ERA} value is {@link #BC}, the year is
2064      *         represented by 0 or a negative number: BC 1 is 0, BC 2
2065      *         is -1, BC 3 is -2, and so on.
2066      * @throws IllegalArgumentException
2067      *         if any of the calendar fields is invalid in non-lenient mode.
2068      * @see #isWeekDateSupported()
2069      * @see #getWeeksInWeekYear()
2070      * @see Calendar#getFirstDayOfWeek()
2071      * @see Calendar#getMinimalDaysInFirstWeek()
2072      * @since 1.7
2073      */
2074     @Override
2075     public int getWeekYear() {
2076         int year = get(YEAR); // implicitly calls complete()
2077         if (internalGetEra() == BCE) {
2078             year = 1 - year;
2079         }
2080 
2081         // Fast path for the Gregorian calendar years that are never
2082         // affected by the Julian-Gregorian transition
2083         if (year > gregorianCutoverYear + 1) {
2084             int weekOfYear = internalGet(WEEK_OF_YEAR);
2085             if (internalGet(MONTH) == JANUARY) {
2086                 if (weekOfYear >= 52) {
2087                     --year;
2088                 }
2089             } else {
2090                 if (weekOfYear == 1) {
2091                     ++year;
2092                 }
2093             }
2094             return year;
2095         }
2096 
2097         // General (slow) path
2098         int dayOfYear = internalGet(DAY_OF_YEAR);
2099         int maxDayOfYear = getActualMaximum(DAY_OF_YEAR);
2100         int minimalDays = getMinimalDaysInFirstWeek();
2101 
2102         // Quickly check the possibility of year adjustments before
2103         // cloning this GregorianCalendar.
2104         if (dayOfYear > minimalDays && dayOfYear < (maxDayOfYear - 6)) {
2105             return year;
2106         }
2107 
2108         // Create a clone to work on the calculation
2109         GregorianCalendar cal = (GregorianCalendar) clone();
2110         cal.setLenient(true);
2111         // Use GMT so that intermediate date calculations won't
2112         // affect the time of day fields.
2113         cal.setTimeZone(TimeZone.getTimeZone("GMT"));
2114         // Go to the first day of the year, which is usually January 1.
2115         cal.set(DAY_OF_YEAR, 1);
2116         cal.complete();
2117 
2118         // Get the first day of the first day-of-week in the year.
2119         int delta = getFirstDayOfWeek() - cal.get(DAY_OF_WEEK);
2120         if (delta != 0) {
2121             if (delta < 0) {
2122                 delta += 7;
2123             }
2124             cal.add(DAY_OF_YEAR, delta);
2125         }
2126         int minDayOfYear = cal.get(DAY_OF_YEAR);
2127         if (dayOfYear < minDayOfYear) {
2128             if (minDayOfYear <= minimalDays) {
2129                 --year;
2130             }
2131         } else {
2132             cal.set(YEAR, year + 1);
2133             cal.set(DAY_OF_YEAR, 1);
2134             cal.complete();
2135             int del = getFirstDayOfWeek() - cal.get(DAY_OF_WEEK);
2136             if (del != 0) {
2137                 if (del < 0) {
2138                     del += 7;
2139                 }
2140                 cal.add(DAY_OF_YEAR, del);
2141             }
2142             minDayOfYear = cal.get(DAY_OF_YEAR) - 1;
2143             if (minDayOfYear == 0) {
2144                 minDayOfYear = 7;
2145             }
2146             if (minDayOfYear >= minimalDays) {
2147                 int days = maxDayOfYear - dayOfYear + 1;
2148                 if (days <= (7 - minDayOfYear)) {
2149                     ++year;
2150                 }
2151             }
2152         }
2153         return year;
2154     }
2155 
2156     /**
2157      * Sets this {@code GregorianCalendar} to the date given by the
2158      * date specifiers - <a href="#week_year">{@code weekYear}</a>,
2159      * {@code weekOfYear}, and {@code dayOfWeek}. {@code weekOfYear}
2160      * follows the <a href="#week_and_year">{@code WEEK_OF_YEAR}
2161      * numbering</a>.  The {@code dayOfWeek} value must be one of the
2162      * {@link Calendar#DAY_OF_WEEK DAY_OF_WEEK} values: {@link
2163      * Calendar#SUNDAY SUNDAY} to {@link Calendar#SATURDAY SATURDAY}.
2164      *
2165      * <p>Note that the numeric day-of-week representation differs from
2166      * the ISO 8601 standard, and that the {@code weekOfYear}
2167      * numbering is compatible with the standard when {@code
2168      * getFirstDayOfWeek()} is {@code MONDAY} and {@code
2169      * getMinimalDaysInFirstWeek()} is 4.
2170      *
2171      * <p>Unlike the {@code set} method, all of the calendar fields
2172      * and the instant of time value are calculated upon return.
2173      *
2174      * <p>If {@code weekOfYear} is out of the valid week-of-year
2175      * range in {@code weekYear}, the {@code weekYear}
2176      * and {@code weekOfYear} values are adjusted in lenient
2177      * mode, or an {@code IllegalArgumentException} is thrown in
2178      * non-lenient mode.
2179      *
2180      * @param weekYear    the week year
2181      * @param weekOfYear  the week number based on {@code weekYear}
2182      * @param dayOfWeek   the day of week value: one of the constants
2183      *                    for the {@link #DAY_OF_WEEK DAY_OF_WEEK} field:
2184      *                    {@link Calendar#SUNDAY SUNDAY}, ...,
2185      *                    {@link Calendar#SATURDAY SATURDAY}.
2186      * @throws    IllegalArgumentException
2187      *            if any of the given date specifiers is invalid,
2188      *            or if any of the calendar fields are inconsistent
2189      *            with the given date specifiers in non-lenient mode
2190      * @see GregorianCalendar#isWeekDateSupported()
2191      * @see Calendar#getFirstDayOfWeek()
2192      * @see Calendar#getMinimalDaysInFirstWeek()
2193      * @since 1.7
2194      */
2195     @Override
2196     public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek) {
2197         if (dayOfWeek < SUNDAY || dayOfWeek > SATURDAY) {
2198             throw new IllegalArgumentException("invalid dayOfWeek: " + dayOfWeek);
2199         }
2200 
2201         // To avoid changing the time of day fields by date
2202         // calculations, use a clone with the GMT time zone.
2203         GregorianCalendar gc = (GregorianCalendar) clone();
2204         gc.setLenient(true);
2205         int era = gc.get(ERA);
2206         gc.clear();
2207         gc.setTimeZone(TimeZone.getTimeZone("GMT"));
2208         gc.set(ERA, era);
2209         gc.set(YEAR, weekYear);
2210         gc.set(WEEK_OF_YEAR, 1);
2211         gc.set(DAY_OF_WEEK, getFirstDayOfWeek());
2212         int days = dayOfWeek - getFirstDayOfWeek();
2213         if (days < 0) {
2214             days += 7;
2215         }
2216         days += 7 * (weekOfYear - 1);
2217         if (days != 0) {
2218             gc.add(DAY_OF_YEAR, days);
2219         } else {
2220             gc.complete();
2221         }
2222 
2223         if (!isLenient() &&
2224             (gc.getWeekYear() != weekYear
2225              || gc.internalGet(WEEK_OF_YEAR) != weekOfYear
2226              || gc.internalGet(DAY_OF_WEEK) != dayOfWeek)) {
2227             throw new IllegalArgumentException();
2228         }
2229 
2230         set(ERA, gc.internalGet(ERA));
2231         set(YEAR, gc.internalGet(YEAR));
2232         set(MONTH, gc.internalGet(MONTH));
2233         set(DAY_OF_MONTH, gc.internalGet(DAY_OF_MONTH));
2234 
2235         // to avoid throwing an IllegalArgumentException in
2236         // non-lenient, set WEEK_OF_YEAR internally
2237         internalSet(WEEK_OF_YEAR, weekOfYear);
2238         complete();
2239     }
2240 
2241     /**
2242      * Returns the number of weeks in the <a href="#week_year">week year</a>
2243      * represented by this {@code GregorianCalendar}.
2244      *
2245      * <p>For example, if this {@code GregorianCalendar}'s date is
2246      * December 31, 2008 with <a href="#iso8601_compatible_setting">the ISO
2247      * 8601 compatible setting</a>, this method will return 53 for the
2248      * period: December 29, 2008 to January 3, 2010 while {@link
2249      * #getActualMaximum(int) getActualMaximum(WEEK_OF_YEAR)} will return
2250      * 52 for the period: December 31, 2007 to December 28, 2008.
2251      *
2252      * @return the number of weeks in the week year.
2253      * @see Calendar#WEEK_OF_YEAR
2254      * @see #getWeekYear()
2255      * @see #getActualMaximum(int)
2256      * @since 1.7
2257      */
2258     @Override
2259     public int getWeeksInWeekYear() {
2260         GregorianCalendar gc = getNormalizedCalendar();
2261         int weekYear = gc.getWeekYear();
2262         if (weekYear == gc.internalGet(YEAR)) {
2263             return gc.getActualMaximum(WEEK_OF_YEAR);
2264         }
2265 
2266         // Use the 2nd week for calculating the max of WEEK_OF_YEAR
2267         if (gc == this) {
2268             gc = (GregorianCalendar) gc.clone();
2269         }
2270         gc.setWeekDate(weekYear, 2, internalGet(DAY_OF_WEEK));
2271         return gc.getActualMaximum(WEEK_OF_YEAR);
2272     }
2273 
2274 /////////////////////////////
2275 // Time => Fields computation
2276 /////////////////////////////
2277 
2278     /**
2279      * The fixed date corresponding to gdate. If the value is
2280      * Long.MIN_VALUE, the fixed date value is unknown. Currently,
2281      * Julian calendar dates are not cached.
2282      */
2283     private transient long cachedFixedDate = Long.MIN_VALUE;
2284 
2285     /**
2286      * Converts the time value (millisecond offset from the <a
2287      * href="Calendar.html#Epoch">Epoch</a>) to calendar field values.
2288      * The time is <em>not</em>
2289      * recomputed first; to recompute the time, then the fields, call the
2290      * {@code complete} method.
2291      *
2292      * @see Calendar#complete
2293      */
2294     @Override
2295     protected void computeFields() {
2296         int mask;
2297         if (isPartiallyNormalized()) {
2298             // Determine which calendar fields need to be computed.
2299             mask = getSetStateFields();
2300             int fieldMask = ~mask & ALL_FIELDS;
2301             // We have to call computTime in case calsys == null in
2302             // order to set calsys and cdate. (6263644)
2303             if (fieldMask != 0 || calsys == null) {
2304                 mask |= computeFields(fieldMask,
2305                                       mask & (ZONE_OFFSET_MASK|DST_OFFSET_MASK));
2306                 assert mask == ALL_FIELDS;
2307             }
2308         } else {
2309             mask = ALL_FIELDS;
2310             computeFields(mask, 0);
2311         }
2312         // After computing all the fields, set the field state to `COMPUTED'.
2313         setFieldsComputed(mask);
2314     }
2315 
2316     /**
2317      * This computeFields implements the conversion from UTC
2318      * (millisecond offset from the Epoch) to calendar
2319      * field values. fieldMask specifies which fields to change the
2320      * setting state to COMPUTED, although all fields are set to
2321      * the correct values. This is required to fix 4685354.
2322      *
2323      * @param fieldMask a bit mask to specify which fields to change
2324      * the setting state.
2325      * @param tzMask a bit mask to specify which time zone offset
2326      * fields to be used for time calculations
2327      * @return a new field mask that indicates what field values have
2328      * actually been set.
2329      */
2330     private int computeFields(int fieldMask, int tzMask) {
2331         int zoneOffset = 0;
2332         TimeZone tz = getZone();
2333         if (zoneOffsets == null) {
2334             zoneOffsets = new int[2];
2335         }
2336         if (tzMask != (ZONE_OFFSET_MASK|DST_OFFSET_MASK)) {
2337             if (tz instanceof ZoneInfo) {
2338                 zoneOffset = ((ZoneInfo)tz).getOffsets(time, zoneOffsets);
2339             } else {
2340                 zoneOffset = tz.getOffset(time);
2341                 zoneOffsets[0] = tz.getRawOffset();
2342                 zoneOffsets[1] = zoneOffset - zoneOffsets[0];
2343             }
2344         }
2345         if (tzMask != 0) {
2346             if (isFieldSet(tzMask, ZONE_OFFSET)) {
2347                 zoneOffsets[0] = internalGet(ZONE_OFFSET);
2348             }
2349             if (isFieldSet(tzMask, DST_OFFSET)) {
2350                 zoneOffsets[1] = internalGet(DST_OFFSET);
2351             }
2352             zoneOffset = zoneOffsets[0] + zoneOffsets[1];
2353         }
2354 
2355         // By computing time and zoneOffset separately, we can take
2356         // the wider range of time+zoneOffset than the previous
2357         // implementation.
2358         long fixedDate = zoneOffset / ONE_DAY;
2359         int timeOfDay = zoneOffset % (int)ONE_DAY;
2360         fixedDate += time / ONE_DAY;
2361         timeOfDay += (int) (time % ONE_DAY);
2362         if (timeOfDay >= ONE_DAY) {
2363             timeOfDay -= ONE_DAY;
2364             ++fixedDate;
2365         } else {
2366             while (timeOfDay < 0) {
2367                 timeOfDay += ONE_DAY;
2368                 --fixedDate;
2369             }
2370         }
2371         fixedDate += EPOCH_OFFSET;
2372 
2373         int era = CE;
2374         int year;
2375         if (fixedDate >= gregorianCutoverDate) {
2376             // Handle Gregorian dates.
2377             assert cachedFixedDate == Long.MIN_VALUE || gdate.isNormalized()
2378                         : "cache control: not normalized";
2379             assert cachedFixedDate == Long.MIN_VALUE ||
2380                    gcal.getFixedDate(gdate.getNormalizedYear(),
2381                                           gdate.getMonth(),
2382                                           gdate.getDayOfMonth(), gdate)
2383                                 == cachedFixedDate
2384                         : "cache control: inconsictency" +
2385                           ", cachedFixedDate=" + cachedFixedDate +
2386                           ", computed=" +
2387                           gcal.getFixedDate(gdate.getNormalizedYear(),
2388                                                  gdate.getMonth(),
2389                                                  gdate.getDayOfMonth(),
2390                                                  gdate) +
2391                           ", date=" + gdate;
2392 
2393             // See if we can use gdate to avoid date calculation.
2394             if (fixedDate != cachedFixedDate) {
2395                 gcal.getCalendarDateFromFixedDate(gdate, fixedDate);
2396                 cachedFixedDate = fixedDate;
2397             }
2398 
2399             year = gdate.getYear();
2400             if (year <= 0) {
2401                 year = 1 - year;
2402                 era = BCE;
2403             }
2404             calsys = gcal;
2405             cdate = gdate;
2406             assert cdate.getDayOfWeek() > 0 : "dow="+cdate.getDayOfWeek()+", date="+cdate;
2407         } else {
2408             // Handle Julian calendar dates.
2409             calsys = getJulianCalendarSystem();
2410             cdate = (BaseCalendar.Date) jcal.newCalendarDate(getZone());
2411             jcal.getCalendarDateFromFixedDate(cdate, fixedDate);
2412             Era e = cdate.getEra();
2413             if (e == jeras[0]) {
2414                 era = BCE;
2415             }
2416             year = cdate.getYear();
2417         }
2418 
2419         // Always set the ERA and YEAR values.
2420         internalSet(ERA, era);
2421         internalSet(YEAR, year);
2422         int mask = fieldMask | (ERA_MASK|YEAR_MASK);
2423 
2424         int month =  cdate.getMonth() - 1; // 0-based
2425         int dayOfMonth = cdate.getDayOfMonth();
2426 
2427         // Set the basic date fields.
2428         if ((fieldMask & (MONTH_MASK|DAY_OF_MONTH_MASK|DAY_OF_WEEK_MASK))
2429             != 0) {
2430             internalSet(MONTH, month);
2431             internalSet(DAY_OF_MONTH, dayOfMonth);
2432             internalSet(DAY_OF_WEEK, cdate.getDayOfWeek());
2433             mask |= MONTH_MASK|DAY_OF_MONTH_MASK|DAY_OF_WEEK_MASK;
2434         }
2435 
2436         if ((fieldMask & (HOUR_OF_DAY_MASK|AM_PM_MASK|HOUR_MASK
2437                           |MINUTE_MASK|SECOND_MASK|MILLISECOND_MASK)) != 0) {
2438             if (timeOfDay != 0) {
2439                 int hours = timeOfDay / ONE_HOUR;
2440                 internalSet(HOUR_OF_DAY, hours);
2441                 internalSet(AM_PM, hours / 12); // Assume AM == 0
2442                 internalSet(HOUR, hours % 12);
2443                 int r = timeOfDay % ONE_HOUR;
2444                 internalSet(MINUTE, r / ONE_MINUTE);
2445                 r %= ONE_MINUTE;
2446                 internalSet(SECOND, r / ONE_SECOND);
2447                 internalSet(MILLISECOND, r % ONE_SECOND);
2448             } else {
2449                 internalSet(HOUR_OF_DAY, 0);
2450                 internalSet(AM_PM, AM);
2451                 internalSet(HOUR, 0);
2452                 internalSet(MINUTE, 0);
2453                 internalSet(SECOND, 0);
2454                 internalSet(MILLISECOND, 0);
2455             }
2456             mask |= (HOUR_OF_DAY_MASK|AM_PM_MASK|HOUR_MASK
2457                      |MINUTE_MASK|SECOND_MASK|MILLISECOND_MASK);
2458         }
2459 
2460         if ((fieldMask & (ZONE_OFFSET_MASK|DST_OFFSET_MASK)) != 0) {
2461             internalSet(ZONE_OFFSET, zoneOffsets[0]);
2462             internalSet(DST_OFFSET, zoneOffsets[1]);
2463             mask |= (ZONE_OFFSET_MASK|DST_OFFSET_MASK);
2464         }
2465 
2466         if ((fieldMask & (DAY_OF_YEAR_MASK|WEEK_OF_YEAR_MASK|WEEK_OF_MONTH_MASK|DAY_OF_WEEK_IN_MONTH_MASK)) != 0) {
2467             int normalizedYear = cdate.getNormalizedYear();
2468             long fixedDateJan1 = calsys.getFixedDate(normalizedYear, 1, 1, cdate);
2469             int dayOfYear = (int)(fixedDate - fixedDateJan1) + 1;
2470             long fixedDateMonth1 = fixedDate - dayOfMonth + 1;
2471             int cutoverGap = 0;
2472             int cutoverYear = (calsys == gcal) ? gregorianCutoverYear : gregorianCutoverYearJulian;
2473             int relativeDayOfMonth = dayOfMonth - 1;
2474 
2475             // If we are in the cutover year, we need some special handling.
2476             if (normalizedYear == cutoverYear) {
2477                 // Need to take care of the "missing" days.
2478                 if (gregorianCutoverYearJulian <= gregorianCutoverYear) {
2479                     // We need to find out where we are. The cutover
2480                     // gap could even be more than one year.  (One
2481                     // year difference in ~48667 years.)
2482                     fixedDateJan1 = getFixedDateJan1(cdate, fixedDate);
2483                     if (fixedDate >= gregorianCutoverDate) {
2484                         fixedDateMonth1 = getFixedDateMonth1(cdate, fixedDate);
2485                     }
2486                 }
2487                 int realDayOfYear = (int)(fixedDate - fixedDateJan1) + 1;
2488                 cutoverGap = dayOfYear - realDayOfYear;
2489                 dayOfYear = realDayOfYear;
2490                 relativeDayOfMonth = (int)(fixedDate - fixedDateMonth1);
2491             }
2492             internalSet(DAY_OF_YEAR, dayOfYear);
2493             internalSet(DAY_OF_WEEK_IN_MONTH, relativeDayOfMonth / 7 + 1);
2494 
2495             int weekOfYear = getWeekNumber(fixedDateJan1, fixedDate);
2496 
2497             // The spec is to calculate WEEK_OF_YEAR in the
2498             // ISO8601-style. This creates problems, though.
2499             if (weekOfYear == 0) {
2500                 // If the date belongs to the last week of the
2501                 // previous year, use the week number of "12/31" of
2502                 // the "previous" year. Again, if the previous year is
2503                 // the Gregorian cutover year, we need to take care of
2504                 // it.  Usually the previous day of January 1 is
2505                 // December 31, which is not always true in
2506                 // GregorianCalendar.
2507                 long fixedDec31 = fixedDateJan1 - 1;
2508                 long prevJan1  = fixedDateJan1 - 365;
2509                 if (normalizedYear > (cutoverYear + 1)) {
2510                     if (CalendarUtils.isGregorianLeapYear(normalizedYear - 1)) {
2511                         --prevJan1;
2512                     }
2513                 } else if (normalizedYear <= gregorianCutoverYearJulian) {
2514                     if (CalendarUtils.isJulianLeapYear(normalizedYear - 1)) {
2515                         --prevJan1;
2516                     }
2517                 } else {
2518                     BaseCalendar calForJan1 = calsys;
2519                     //int prevYear = normalizedYear - 1;
2520                     int prevYear = getCalendarDate(fixedDec31).getNormalizedYear();
2521                     if (prevYear == gregorianCutoverYear) {
2522                         calForJan1 = getCutoverCalendarSystem();
2523                         if (calForJan1 == jcal) {
2524                             prevJan1 = calForJan1.getFixedDate(prevYear,
2525                                                                BaseCalendar.JANUARY,
2526                                                                1,
2527                                                                null);
2528                         } else {
2529                             prevJan1 = gregorianCutoverDate;
2530                             calForJan1 = gcal;
2531                         }
2532                     } else if (prevYear <= gregorianCutoverYearJulian) {
2533                         calForJan1 = getJulianCalendarSystem();
2534                         prevJan1 = calForJan1.getFixedDate(prevYear,
2535                                                            BaseCalendar.JANUARY,
2536                                                            1,
2537                                                            null);
2538                     }
2539                 }
2540                 weekOfYear = getWeekNumber(prevJan1, fixedDec31);
2541             } else {
2542                 if (normalizedYear > gregorianCutoverYear ||
2543                     normalizedYear < (gregorianCutoverYearJulian - 1)) {
2544                     // Regular years
2545                     if (weekOfYear >= 52) {
2546                         long nextJan1 = fixedDateJan1 + 365;
2547                         if (cdate.isLeapYear()) {
2548                             nextJan1++;
2549                         }
2550                         long nextJan1st = BaseCalendar.getDayOfWeekDateOnOrBefore(nextJan1 + 6,
2551                                                                                   getFirstDayOfWeek());
2552                         int ndays = (int)(nextJan1st - nextJan1);
2553                         if (ndays >= getMinimalDaysInFirstWeek() && fixedDate >= (nextJan1st - 7)) {
2554                             // The first days forms a week in which the date is included.
2555                             weekOfYear = 1;
2556                         }
2557                     }
2558                 } else {
2559                     BaseCalendar calForJan1 = calsys;
2560                     int nextYear = normalizedYear + 1;
2561                     if (nextYear == (gregorianCutoverYearJulian + 1) &&
2562                         nextYear < gregorianCutoverYear) {
2563                         // In case the gap is more than one year.
2564                         nextYear = gregorianCutoverYear;
2565                     }
2566                     if (nextYear == gregorianCutoverYear) {
2567                         calForJan1 = getCutoverCalendarSystem();
2568                     }
2569 
2570                     long nextJan1;
2571                     if (nextYear > gregorianCutoverYear
2572                         || gregorianCutoverYearJulian == gregorianCutoverYear
2573                         || nextYear == gregorianCutoverYearJulian) {
2574                         nextJan1 = calForJan1.getFixedDate(nextYear,
2575                                                            BaseCalendar.JANUARY,
2576                                                            1,
2577                                                            null);
2578                     } else {
2579                         nextJan1 = gregorianCutoverDate;
2580                         calForJan1 = gcal;
2581                     }
2582 
2583                     long nextJan1st = BaseCalendar.getDayOfWeekDateOnOrBefore(nextJan1 + 6,
2584                                                                               getFirstDayOfWeek());
2585                     int ndays = (int)(nextJan1st - nextJan1);
2586                     if (ndays >= getMinimalDaysInFirstWeek() && fixedDate >= (nextJan1st - 7)) {
2587                         // The first days forms a week in which the date is included.
2588                         weekOfYear = 1;
2589                     }
2590                 }
2591             }
2592             internalSet(WEEK_OF_YEAR, weekOfYear);
2593             internalSet(WEEK_OF_MONTH, getWeekNumber(fixedDateMonth1, fixedDate));
2594             mask |= (DAY_OF_YEAR_MASK|WEEK_OF_YEAR_MASK|WEEK_OF_MONTH_MASK|DAY_OF_WEEK_IN_MONTH_MASK);
2595         }
2596         return mask;
2597     }
2598 
2599     /**
2600      * Returns the number of weeks in a period between fixedDay1 and
2601      * fixedDate. The getFirstDayOfWeek-getMinimalDaysInFirstWeek rule
2602      * is applied to calculate the number of weeks.
2603      *
2604      * @param fixedDay1 the fixed date of the first day of the period
2605      * @param fixedDate the fixed date of the last day of the period
2606      * @return the number of weeks of the given period
2607      */
2608     private int getWeekNumber(long fixedDay1, long fixedDate) {
2609         // We can always use `gcal' since Julian and Gregorian are the
2610         // same thing for this calculation.
2611         long fixedDay1st = Gregorian.getDayOfWeekDateOnOrBefore(fixedDay1 + 6,
2612                                                                 getFirstDayOfWeek());
2613         int ndays = (int)(fixedDay1st - fixedDay1);
2614         assert ndays <= 7;
2615         if (ndays >= getMinimalDaysInFirstWeek()) {
2616             fixedDay1st -= 7;
2617         }
2618         int normalizedDayOfPeriod = (int)(fixedDate - fixedDay1st);
2619         if (normalizedDayOfPeriod >= 0) {
2620             return normalizedDayOfPeriod / 7 + 1;
2621         }
2622         return CalendarUtils.floorDivide(normalizedDayOfPeriod, 7) + 1;
2623     }
2624 
2625     /**
2626      * Converts calendar field values to the time value (millisecond
2627      * offset from the <a href="Calendar.html#Epoch">Epoch</a>).
2628      *
2629      * @throws    IllegalArgumentException if any calendar fields are invalid.
2630      */
2631     @Override
2632     protected void computeTime() {
2633         // In non-lenient mode, perform brief checking of calendar
2634         // fields which have been set externally. Through this
2635         // checking, the field values are stored in originalFields[]
2636         // to see if any of them are normalized later.
2637         if (!isLenient()) {
2638             if (originalFields == null) {
2639                 originalFields = new int[FIELD_COUNT];
2640             }
2641             for (int field = 0; field < FIELD_COUNT; field++) {
2642                 int value = internalGet(field);
2643                 if (isExternallySet(field)) {
2644                     // Quick validation for any out of range values
2645                     if (value < getMinimum(field) || value > getMaximum(field)) {
2646                         throw new IllegalArgumentException(getFieldName(field));
2647                     }
2648                 }
2649                 originalFields[field] = value;
2650             }
2651         }
2652 
2653         // Let the super class determine which calendar fields to be
2654         // used to calculate the time.
2655         int fieldMask = selectFields();
2656 
2657         // The year defaults to the epoch start. We don't check
2658         // fieldMask for YEAR because YEAR is a mandatory field to
2659         // determine the date.
2660         int year = isSet(YEAR) ? internalGet(YEAR) : EPOCH_YEAR;
2661 
2662         int era = internalGetEra();
2663         if (era == BCE) {
2664             year = 1 - year;
2665         } else if (era != CE) {
2666             // Even in lenient mode we disallow ERA values other than CE & BCE.
2667             // (The same normalization rule as add()/roll() could be
2668             // applied here in lenient mode. But this checking is kept
2669             // unchanged for compatibility as of 1.5.)
2670             throw new IllegalArgumentException("Invalid era");
2671         }
2672 
2673         // If year is 0 or negative, we need to set the ERA value later.
2674         if (year <= 0 && !isSet(ERA)) {
2675             fieldMask |= ERA_MASK;
2676             setFieldsComputed(ERA_MASK);
2677         }
2678 
2679         // Calculate the time of day. We rely on the convention that
2680         // an UNSET field has 0.
2681         long timeOfDay = 0;
2682         if (isFieldSet(fieldMask, HOUR_OF_DAY)) {
2683             timeOfDay += (long) internalGet(HOUR_OF_DAY);
2684         } else {
2685             timeOfDay += internalGet(HOUR);
2686             // The default value of AM_PM is 0 which designates AM.
2687             if (isFieldSet(fieldMask, AM_PM)) {
2688                 timeOfDay += 12 * internalGet(AM_PM);
2689             }
2690         }
2691         timeOfDay *= 60;
2692         timeOfDay += internalGet(MINUTE);
2693         timeOfDay *= 60;
2694         timeOfDay += internalGet(SECOND);
2695         timeOfDay *= 1000;
2696         timeOfDay += internalGet(MILLISECOND);
2697 
2698         // Convert the time of day to the number of days and the
2699         // millisecond offset from midnight.
2700         long fixedDate = timeOfDay / ONE_DAY;
2701         timeOfDay %= ONE_DAY;
2702         while (timeOfDay < 0) {
2703             timeOfDay += ONE_DAY;
2704             --fixedDate;
2705         }
2706 
2707         // Calculate the fixed date since January 1, 1 (Gregorian).
2708         calculateFixedDate: {
2709             long gfd, jfd;
2710             if (year > gregorianCutoverYear && year > gregorianCutoverYearJulian) {
2711                 gfd = fixedDate + getFixedDate(gcal, year, fieldMask);
2712                 if (gfd >= gregorianCutoverDate) {
2713                     fixedDate = gfd;
2714                     break calculateFixedDate;
2715                 }
2716                 jfd = fixedDate + getFixedDate(getJulianCalendarSystem(), year, fieldMask);
2717             } else if (year < gregorianCutoverYear && year < gregorianCutoverYearJulian) {
2718                 jfd = fixedDate + getFixedDate(getJulianCalendarSystem(), year, fieldMask);
2719                 if (jfd < gregorianCutoverDate) {
2720                     fixedDate = jfd;
2721                     break calculateFixedDate;
2722                 }
2723                 gfd = jfd;
2724             } else {
2725                 jfd = fixedDate + getFixedDate(getJulianCalendarSystem(), year, fieldMask);
2726                 gfd = fixedDate + getFixedDate(gcal, year, fieldMask);
2727             }
2728 
2729             // Now we have to determine which calendar date it is.
2730 
2731             // If the date is relative from the beginning of the year
2732             // in the Julian calendar, then use jfd;
2733             if (isFieldSet(fieldMask, DAY_OF_YEAR) || isFieldSet(fieldMask, WEEK_OF_YEAR)) {
2734                 if (gregorianCutoverYear == gregorianCutoverYearJulian) {
2735                     fixedDate = jfd;
2736                     break calculateFixedDate;
2737                 } else if (year == gregorianCutoverYear) {
2738                     fixedDate = gfd;
2739                     break calculateFixedDate;
2740                 }
2741             }
2742 
2743             if (gfd >= gregorianCutoverDate) {
2744                 if (jfd >= gregorianCutoverDate) {
2745                     fixedDate = gfd;
2746                 } else {
2747                     // The date is in an "overlapping" period. No way
2748                     // to disambiguate it. Determine it using the
2749                     // previous date calculation.
2750                     if (calsys == gcal || calsys == null) {
2751                         fixedDate = gfd;
2752                     } else {
2753                         fixedDate = jfd;
2754                     }
2755                 }
2756             } else {
2757                 if (jfd < gregorianCutoverDate) {
2758                     fixedDate = jfd;
2759                 } else {
2760                     // The date is in a "missing" period.
2761                     if (!isLenient()) {
2762                         throw new IllegalArgumentException("the specified date doesn't exist");
2763                     }
2764                     // Take the Julian date for compatibility, which
2765                     // will produce a Gregorian date.
2766                     fixedDate = jfd;
2767                 }
2768             }
2769         }
2770 
2771         // millis represents local wall-clock time in milliseconds.
2772         long millis = (fixedDate - EPOCH_OFFSET) * ONE_DAY + timeOfDay;
2773 
2774         // Compute the time zone offset and DST offset.  There are two potential
2775         // ambiguities here.  We'll assume a 2:00 am (wall time) switchover time
2776         // for discussion purposes here.
2777         // 1. The transition into DST.  Here, a designated time of 2:00 am - 2:59 am
2778         //    can be in standard or in DST depending.  However, 2:00 am is an invalid
2779         //    representation (the representation jumps from 1:59:59 am Std to 3:00:00 am DST).
2780         //    We assume standard time.
2781         // 2. The transition out of DST.  Here, a designated time of 1:00 am - 1:59 am
2782         //    can be in standard or DST.  Both are valid representations (the rep
2783         //    jumps from 1:59:59 DST to 1:00:00 Std).
2784         //    Again, we assume standard time.
2785         // We use the TimeZone object, unless the user has explicitly set the ZONE_OFFSET
2786         // or DST_OFFSET fields; then we use those fields.
2787         TimeZone zone = getZone();
2788         if (zoneOffsets == null) {
2789             zoneOffsets = new int[2];
2790         }
2791         int tzMask = fieldMask & (ZONE_OFFSET_MASK|DST_OFFSET_MASK);
2792         if (tzMask != (ZONE_OFFSET_MASK|DST_OFFSET_MASK)) {
2793             if (zone instanceof ZoneInfo) {
2794                 ((ZoneInfo)zone).getOffsetsByWall(millis, zoneOffsets);
2795             } else {
2796                 int gmtOffset = isFieldSet(fieldMask, ZONE_OFFSET) ?
2797                                     internalGet(ZONE_OFFSET) : zone.getRawOffset();
2798                 zone.getOffsets(millis - gmtOffset, zoneOffsets);
2799             }
2800         }
2801         if (tzMask != 0) {
2802             if (isFieldSet(tzMask, ZONE_OFFSET)) {
2803                 zoneOffsets[0] = internalGet(ZONE_OFFSET);
2804             }
2805             if (isFieldSet(tzMask, DST_OFFSET)) {
2806                 zoneOffsets[1] = internalGet(DST_OFFSET);
2807             }
2808         }
2809 
2810         // Adjust the time zone offset values to get the UTC time.
2811         millis -= zoneOffsets[0] + zoneOffsets[1];
2812 
2813         // Set this calendar's time in milliseconds
2814         time = millis;
2815 
2816         int mask = computeFields(fieldMask | getSetStateFields(), tzMask);
2817 
2818         if (!isLenient()) {
2819             for (int field = 0; field < FIELD_COUNT; field++) {
2820                 if (!isExternallySet(field)) {
2821                     continue;
2822                 }
2823                 if (originalFields[field] != internalGet(field)) {
2824                     String s = originalFields[field] + " -> " + internalGet(field);
2825                     // Restore the original field values
2826                     System.arraycopy(originalFields, 0, fields, 0, fields.length);
2827                     throw new IllegalArgumentException(getFieldName(field) + ": " + s);
2828                 }
2829             }
2830         }
2831         setFieldsNormalized(mask);
2832     }
2833 
2834     /**
2835      * Computes the fixed date under either the Gregorian or the
2836      * Julian calendar, using the given year and the specified calendar fields.
2837      *
2838      * @param cal the CalendarSystem to be used for the date calculation
2839      * @param year the normalized year number, with 0 indicating the
2840      * year 1 BCE, -1 indicating 2 BCE, etc.
2841      * @param fieldMask the calendar fields to be used for the date calculation
2842      * @return the fixed date
2843      * @see Calendar#selectFields
2844      */
2845     private long getFixedDate(BaseCalendar cal, int year, int fieldMask) {
2846         int month = JANUARY;
2847         if (isFieldSet(fieldMask, MONTH)) {
2848             // No need to check if MONTH has been set (no isSet(MONTH)
2849             // call) since its unset value happens to be JANUARY (0).
2850             month = internalGet(MONTH);
2851 
2852             // If the month is out of range, adjust it into range
2853             if (month > DECEMBER) {
2854                 year += month / 12;
2855                 month %= 12;
2856             } else if (month < JANUARY) {
2857                 int[] rem = new int[1];
2858                 year += CalendarUtils.floorDivide(month, 12, rem);
2859                 month = rem[0];
2860             }
2861         }
2862 
2863         // Get the fixed date since Jan 1, 1 (Gregorian). We are on
2864         // the first day of either `month' or January in 'year'.
2865         long fixedDate = cal.getFixedDate(year, month + 1, 1,
2866                                           cal == gcal ? gdate : null);
2867         if (isFieldSet(fieldMask, MONTH)) {
2868             // Month-based calculations
2869             if (isFieldSet(fieldMask, DAY_OF_MONTH)) {
2870                 // We are on the first day of the month. Just add the
2871                 // offset if DAY_OF_MONTH is set. If the isSet call
2872                 // returns false, that means DAY_OF_MONTH has been
2873                 // selected just because of the selected
2874                 // combination. We don't need to add any since the
2875                 // default value is the 1st.
2876                 if (isSet(DAY_OF_MONTH)) {
2877                     // To avoid underflow with DAY_OF_MONTH-1, add
2878                     // DAY_OF_MONTH, then subtract 1.
2879                     fixedDate += internalGet(DAY_OF_MONTH);
2880                     fixedDate--;
2881                 }
2882             } else {
2883                 if (isFieldSet(fieldMask, WEEK_OF_MONTH)) {
2884                     long firstDayOfWeek = BaseCalendar.getDayOfWeekDateOnOrBefore(fixedDate + 6,
2885                                                                                   getFirstDayOfWeek());
2886                     // If we have enough days in the first week, then
2887                     // move to the previous week.
2888                     if ((firstDayOfWeek - fixedDate) >= getMinimalDaysInFirstWeek()) {
2889                         firstDayOfWeek -= 7;
2890                     }
2891                     if (isFieldSet(fieldMask, DAY_OF_WEEK)) {
2892                         firstDayOfWeek = BaseCalendar.getDayOfWeekDateOnOrBefore(firstDayOfWeek + 6,
2893                                                                                  internalGet(DAY_OF_WEEK));
2894                     }
2895                     // In lenient mode, we treat days of the previous
2896                     // months as a part of the specified
2897                     // WEEK_OF_MONTH. See 4633646.
2898                     fixedDate = firstDayOfWeek + 7 * (internalGet(WEEK_OF_MONTH) - 1);
2899                 } else {
2900                     int dayOfWeek;
2901                     if (isFieldSet(fieldMask, DAY_OF_WEEK)) {
2902                         dayOfWeek = internalGet(DAY_OF_WEEK);
2903                     } else {
2904                         dayOfWeek = getFirstDayOfWeek();
2905                     }
2906                     // We are basing this on the day-of-week-in-month.  The only
2907                     // trickiness occurs if the day-of-week-in-month is
2908                     // negative.
2909                     int dowim;
2910                     if (isFieldSet(fieldMask, DAY_OF_WEEK_IN_MONTH)) {
2911                         dowim = internalGet(DAY_OF_WEEK_IN_MONTH);
2912                     } else {
2913                         dowim = 1;
2914                     }
2915                     if (dowim >= 0) {
2916                         fixedDate = BaseCalendar.getDayOfWeekDateOnOrBefore(fixedDate + (7 * dowim) - 1,
2917                                                                             dayOfWeek);
2918                     } else {
2919                         // Go to the first day of the next week of
2920                         // the specified week boundary.
2921                         int lastDate = monthLength(month, year) + (7 * (dowim + 1));
2922                         // Then, get the day of week date on or before the last date.
2923                         fixedDate = BaseCalendar.getDayOfWeekDateOnOrBefore(fixedDate + lastDate - 1,
2924                                                                             dayOfWeek);
2925                     }
2926                 }
2927             }
2928         } else {
2929             if (year == gregorianCutoverYear && cal == gcal
2930                 && fixedDate < gregorianCutoverDate
2931                 && gregorianCutoverYear != gregorianCutoverYearJulian) {
2932                 // January 1 of the year doesn't exist.  Use
2933                 // gregorianCutoverDate as the first day of the
2934                 // year.
2935                 fixedDate = gregorianCutoverDate;
2936             }
2937             // We are on the first day of the year.
2938             if (isFieldSet(fieldMask, DAY_OF_YEAR)) {
2939                 // Add the offset, then subtract 1. (Make sure to avoid underflow.)
2940                 fixedDate += internalGet(DAY_OF_YEAR);
2941                 fixedDate--;
2942             } else {
2943                 long firstDayOfWeek = BaseCalendar.getDayOfWeekDateOnOrBefore(fixedDate + 6,
2944                                                                               getFirstDayOfWeek());
2945                 // If we have enough days in the first week, then move
2946                 // to the previous week.
2947                 if ((firstDayOfWeek - fixedDate) >= getMinimalDaysInFirstWeek()) {
2948                     firstDayOfWeek -= 7;
2949                 }
2950                 if (isFieldSet(fieldMask, DAY_OF_WEEK)) {
2951                     int dayOfWeek = internalGet(DAY_OF_WEEK);
2952                     if (dayOfWeek != getFirstDayOfWeek()) {
2953                         firstDayOfWeek = BaseCalendar.getDayOfWeekDateOnOrBefore(firstDayOfWeek + 6,
2954                                                                                  dayOfWeek);
2955                     }
2956                 }
2957                 fixedDate = firstDayOfWeek + 7 * ((long)internalGet(WEEK_OF_YEAR) - 1);
2958             }
2959         }
2960 
2961         return fixedDate;
2962     }
2963 
2964     /**
2965      * Returns this object if it's normalized (all fields and time are
2966      * in sync). Otherwise, a cloned object is returned after calling
2967      * complete() in lenient mode.
2968      */
2969     private GregorianCalendar getNormalizedCalendar() {
2970         GregorianCalendar gc;
2971         if (isFullyNormalized()) {
2972             gc = this;
2973         } else {
2974             // Create a clone and normalize the calendar fields
2975             gc = (GregorianCalendar) this.clone();
2976             gc.setLenient(true);
2977             gc.complete();
2978         }
2979         return gc;
2980     }
2981 
2982     /**
2983      * Returns the Julian calendar system instance (singleton). 'jcal'
2984      * and 'jeras' are set upon the return.
2985      */
2986     private static synchronized BaseCalendar getJulianCalendarSystem() {
2987         if (jcal == null) {
2988             jcal = (JulianCalendar) CalendarSystem.forName("julian");
2989             jeras = jcal.getEras();
2990         }
2991         return jcal;
2992     }
2993 
2994     /**
2995      * Returns the calendar system for dates before the cutover date
2996      * in the cutover year. If the cutover date is January 1, the
2997      * method returns Gregorian. Otherwise, Julian.
2998      */
2999     private BaseCalendar getCutoverCalendarSystem() {
3000         if (gregorianCutoverYearJulian < gregorianCutoverYear) {
3001             return gcal;
3002         }
3003         return getJulianCalendarSystem();
3004     }
3005 
3006     /**
3007      * Determines if the specified year (normalized) is the Gregorian
3008      * cutover year. This object must have been normalized.
3009      */
3010     private boolean isCutoverYear(int normalizedYear) {
3011         int cutoverYear = (calsys == gcal) ? gregorianCutoverYear : gregorianCutoverYearJulian;
3012         return normalizedYear == cutoverYear;
3013     }
3014 
3015     /**
3016      * Returns the fixed date of the first day of the year (usually
3017      * January 1) before the specified date.
3018      *
3019      * @param date the date for which the first day of the year is
3020      * calculated. The date has to be in the cut-over year (Gregorian
3021      * or Julian).
3022      * @param fixedDate the fixed date representation of the date
3023      */
3024     private long getFixedDateJan1(BaseCalendar.Date date, long fixedDate) {
3025         assert date.getNormalizedYear() == gregorianCutoverYear ||
3026             date.getNormalizedYear() == gregorianCutoverYearJulian;
3027         if (gregorianCutoverYear != gregorianCutoverYearJulian) {
3028             if (fixedDate >= gregorianCutoverDate) {
3029                 // Dates before the cutover date don't exist
3030                 // in the same (Gregorian) year. So, no
3031                 // January 1 exists in the year. Use the
3032                 // cutover date as the first day of the year.
3033                 return gregorianCutoverDate;
3034             }
3035         }
3036         // January 1 of the normalized year should exist.
3037         BaseCalendar juliancal = getJulianCalendarSystem();
3038         return juliancal.getFixedDate(date.getNormalizedYear(), BaseCalendar.JANUARY, 1, null);
3039     }
3040 
3041     /**
3042      * Returns the fixed date of the first date of the month (usually
3043      * the 1st of the month) before the specified date.
3044      *
3045      * @param date the date for which the first day of the month is
3046      * calculated. The date has to be in the cut-over year (Gregorian
3047      * or Julian).
3048      * @param fixedDate the fixed date representation of the date
3049      */
3050     private long getFixedDateMonth1(BaseCalendar.Date date, long fixedDate) {
3051         assert date.getNormalizedYear() == gregorianCutoverYear ||
3052             date.getNormalizedYear() == gregorianCutoverYearJulian;
3053         BaseCalendar.Date gCutover = getGregorianCutoverDate();
3054         if (gCutover.getMonth() == BaseCalendar.JANUARY
3055             && gCutover.getDayOfMonth() == 1) {
3056             // The cutover happened on January 1.
3057             return fixedDate - date.getDayOfMonth() + 1;
3058         }
3059 
3060         long fixedDateMonth1;
3061         // The cutover happened sometime during the year.
3062         if (date.getMonth() == gCutover.getMonth()) {
3063             // The cutover happened in the month.
3064             BaseCalendar.Date jLastDate = getLastJulianDate();
3065             if (gregorianCutoverYear == gregorianCutoverYearJulian
3066                 && gCutover.getMonth() == jLastDate.getMonth()) {
3067                 // The "gap" fits in the same month.
3068                 fixedDateMonth1 = jcal.getFixedDate(date.getNormalizedYear(),
3069                                                     date.getMonth(),
3070                                                     1,
3071                                                     null);
3072             } else {
3073                 // Use the cutover date as the first day of the month.
3074                 fixedDateMonth1 = gregorianCutoverDate;
3075             }
3076         } else {
3077             // The cutover happened before the month.
3078             fixedDateMonth1 = fixedDate - date.getDayOfMonth() + 1;
3079         }
3080 
3081         return fixedDateMonth1;
3082     }
3083 
3084     /**
3085      * Returns a CalendarDate produced from the specified fixed date.
3086      *
3087      * @param fd the fixed date
3088      */
3089     private BaseCalendar.Date getCalendarDate(long fd) {
3090         BaseCalendar cal = (fd >= gregorianCutoverDate) ? gcal : getJulianCalendarSystem();
3091         BaseCalendar.Date d = (BaseCalendar.Date) cal.newCalendarDate(TimeZone.NO_TIMEZONE);
3092         cal.getCalendarDateFromFixedDate(d, fd);
3093         return d;
3094     }
3095 
3096     /**
3097      * Returns the Gregorian cutover date as a BaseCalendar.Date. The
3098      * date is a Gregorian date.
3099      */
3100     private BaseCalendar.Date getGregorianCutoverDate() {
3101         return getCalendarDate(gregorianCutoverDate);
3102     }
3103 
3104     /**
3105      * Returns the day before the Gregorian cutover date as a
3106      * BaseCalendar.Date. The date is a Julian date.
3107      */
3108     private BaseCalendar.Date getLastJulianDate() {
3109         return getCalendarDate(gregorianCutoverDate - 1);
3110     }
3111 
3112     /**
3113      * Returns the length of the specified month in the specified
3114      * year. The year number must be normalized.
3115      *
3116      * @see #isLeapYear(int)
3117      */
3118     private int monthLength(int month, int year) {
3119         return isLeapYear(year) ? LEAP_MONTH_LENGTH[month] : MONTH_LENGTH[month];
3120     }
3121 
3122     /**
3123      * Returns the length of the specified month in the year provided
3124      * by internalGet(YEAR).
3125      *
3126      * @see #isLeapYear(int)
3127      */
3128     private int monthLength(int month) {
3129         int year = internalGet(YEAR);
3130         if (internalGetEra() == BCE) {
3131             year = 1 - year;
3132         }
3133         return monthLength(month, year);
3134     }
3135 
3136     private int actualMonthLength() {
3137         int year = cdate.getNormalizedYear();
3138         if (year != gregorianCutoverYear && year != gregorianCutoverYearJulian) {
3139             return calsys.getMonthLength(cdate);
3140         }
3141         BaseCalendar.Date date = (BaseCalendar.Date) cdate.clone();
3142         long fd = calsys.getFixedDate(date);
3143         long month1 = getFixedDateMonth1(date, fd);
3144         long next1 = month1 + calsys.getMonthLength(date);
3145         if (next1 < gregorianCutoverDate) {
3146             return (int)(next1 - month1);
3147         }
3148         if (cdate != gdate) {
3149             date = (BaseCalendar.Date) gcal.newCalendarDate(TimeZone.NO_TIMEZONE);
3150         }
3151         gcal.getCalendarDateFromFixedDate(date, next1);
3152         next1 = getFixedDateMonth1(date, next1);
3153         return (int)(next1 - month1);
3154     }
3155 
3156     /**
3157      * Returns the length (in days) of the specified year. The year
3158      * must be normalized.
3159      */
3160     private int yearLength(int year) {
3161         return isLeapYear(year) ? 366 : 365;
3162     }
3163 
3164     /**
3165      * Returns the length (in days) of the year provided by
3166      * internalGet(YEAR).
3167      */
3168     private int yearLength() {
3169         int year = internalGet(YEAR);
3170         if (internalGetEra() == BCE) {
3171             year = 1 - year;
3172         }
3173         return yearLength(year);
3174     }
3175 
3176     /**
3177      * After adjustments such as add(MONTH), add(YEAR), we don't want the
3178      * month to jump around.  E.g., we don't want Jan 31 + 1 month to go to Mar
3179      * 3, we want it to go to Feb 28.  Adjustments which might run into this
3180      * problem call this method to retain the proper month.
3181      */
3182     private void pinDayOfMonth() {
3183         int year = internalGet(YEAR);
3184         int monthLen;
3185         if (year > gregorianCutoverYear || year < gregorianCutoverYearJulian) {
3186             monthLen = monthLength(internalGet(MONTH));
3187         } else {
3188             GregorianCalendar gc = getNormalizedCalendar();
3189             monthLen = gc.getActualMaximum(DAY_OF_MONTH);
3190         }
3191         int dom = internalGet(DAY_OF_MONTH);
3192         if (dom > monthLen) {
3193             set(DAY_OF_MONTH, monthLen);
3194         }
3195     }
3196 
3197     /**
3198      * Returns the fixed date value of this object. The time value and
3199      * calendar fields must be in synch.
3200      */
3201     private long getCurrentFixedDate() {
3202         return (calsys == gcal) ? cachedFixedDate : calsys.getFixedDate(cdate);
3203     }
3204 
3205     /**
3206      * Returns the new value after 'roll'ing the specified value and amount.
3207      */
3208     private static int getRolledValue(int value, int amount, int min, int max) {
3209         assert value >= min && value <= max;
3210         int range = max - min + 1;
3211         amount %= range;
3212         int n = value + amount;
3213         if (n > max) {
3214             n -= range;
3215         } else if (n < min) {
3216             n += range;
3217         }
3218         assert n >= min && n <= max;
3219         return n;
3220     }
3221 
3222     /**
3223      * Returns the ERA.  We need a special method for this because the
3224      * default ERA is CE, but a zero (unset) ERA is BCE.
3225      */
3226     private int internalGetEra() {
3227         return isSet(ERA) ? internalGet(ERA) : CE;
3228     }
3229 
3230     /**
3231      * Updates internal state.
3232      */
3233     @java.io.Serial
3234     private void readObject(ObjectInputStream stream)
3235             throws IOException, ClassNotFoundException {
3236         stream.defaultReadObject();
3237         if (gdate == null) {
3238             gdate = (BaseCalendar.Date) gcal.newCalendarDate(getZone());
3239             cachedFixedDate = Long.MIN_VALUE;
3240         }
3241         setGregorianChange(gregorianCutover);
3242     }
3243 
3244     /**
3245      * Converts this object to a {@code ZonedDateTime} that represents
3246      * the same point on the time-line as this {@code GregorianCalendar}.
3247      * <p>
3248      * Since this object supports a Julian-Gregorian cutover date and
3249      * {@code ZonedDateTime} does not, it is possible that the resulting year,
3250      * month and day will have different values.  The result will represent the
3251      * correct date in the ISO calendar system, which will also be the same value
3252      * for Modified Julian Days.
3253      *
3254      * @return a zoned date-time representing the same point on the time-line
3255      *  as this gregorian calendar
3256      * @since 1.8
3257      */
3258     public ZonedDateTime toZonedDateTime() {
3259         return ZonedDateTime.ofInstant(Instant.ofEpochMilli(getTimeInMillis()),
3260                                        getTimeZone().toZoneId());
3261     }
3262 
3263     /**
3264      * Obtains an instance of {@code GregorianCalendar} with the default locale
3265      * from a {@code ZonedDateTime} object.
3266      * <p>
3267      * Since {@code ZonedDateTime} does not support a Julian-Gregorian cutover
3268      * date and uses ISO calendar system, the return GregorianCalendar is a pure
3269      * Gregorian calendar and uses ISO 8601 standard for week definitions,
3270      * which has {@code MONDAY} as the {@link Calendar#getFirstDayOfWeek()
3271      * FirstDayOfWeek} and {@code 4} as the value of the
3272      * {@link Calendar#getMinimalDaysInFirstWeek() MinimalDaysInFirstWeek}.
3273      * <p>
3274      * {@code ZoneDateTime} can store points on the time-line further in the
3275      * future and further in the past than {@code GregorianCalendar}. In this
3276      * scenario, this method will throw an {@code IllegalArgumentException}
3277      * exception.
3278      *
3279      * @param zdt  the zoned date-time object to convert
3280      * @return  the gregorian calendar representing the same point on the
3281      *  time-line as the zoned date-time provided
3282      * @throws    NullPointerException if {@code zdt} is null
3283      * @throws    IllegalArgumentException if the zoned date-time is too
3284      * large to represent as a {@code GregorianCalendar}
3285      * @since 1.8
3286      */
3287     public static GregorianCalendar from(ZonedDateTime zdt) {
3288         GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone(zdt.getZone()));
3289         cal.setGregorianChange(new Date(Long.MIN_VALUE));
3290         cal.setFirstDayOfWeek(MONDAY);
3291         cal.setMinimalDaysInFirstWeek(4);
3292         try {
3293             cal.setTimeInMillis(Math.addExact(Math.multiplyExact(zdt.toEpochSecond(), 1000),
3294                                               zdt.get(ChronoField.MILLI_OF_SECOND)));
3295         } catch (ArithmeticException ex) {
3296             throw new IllegalArgumentException(ex);
3297         }
3298         return cal;
3299     }
3300 }