/*

 * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * (C) Copyright Taligent, Inc. 1996-1998 - All Rights Reserved

 * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved

 *

 *   The original version of this source code and documentation is copyrighted

 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These

 * materials are provided under terms of a License Agreement between Taligent

 * and Sun. This technology is protected by multiple US and International

 * patents. This notice and attribution to Taligent may not be removed.

 *   Taligent is a registered trademark of Taligent, Inc.

 *

 */

package java.util;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.OptionalDataException;

import java.io.Serializable;

import java.security.AccessControlContext;

import java.security.AccessController;

import java.security.PermissionCollection;

import java.security.PrivilegedActionException;

import java.security.PrivilegedExceptionAction;

import java.security.ProtectionDomain;

import java.text.DateFormat;

import java.text.DateFormatSymbols;

import java.time.Instant;

import java.util.concurrent.ConcurrentHashMap;

import java.util.concurrent.ConcurrentMap;

import sun.util.BuddhistCalendar;

import sun.util.calendar.ZoneInfo;

import sun.util.locale.provider.CalendarDataUtility;

import sun.util.locale.provider.LocaleProviderAdapter;

import sun.util.locale.provider.TimeZoneNameUtility;

import sun.util.spi.CalendarProvider;

/**

 * for converting between a specific instant in time and a set of {@link

 * manipulating the calendar fields, such as getting the date of the next

 * week. An instant in time can be represented by a millisecond value that is

 * an offset from the <a id="Epoch"><em>Epoch</em></a>, January 1, 1970

 * 00:00:00.000 GMT (Gregorian).

 *

 * <p>The class also provides additional fields and methods for

 * implementing a concrete calendar system outside the package. Those

 *

 * <p>

 * calendar fields have been initialized with the current date and time:

 * <blockquote>

 * <pre>

 *     Calendar rightNow = Calendar.getInstance();

 * </pre>

 * </blockquote>

 *

 * needed to implement the date-time formatting for a particular language and

 * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

 * certain calendar fields, as well as their meaning.  For example,

 * the first month of the calendar system has value <code>MONTH ==

 * JANUARY</code> for all calendars.  Other values are defined by the

 * documentation and subclass documentation for details.

 *

 * <h2>Getting and Setting Calendar Field Values</h2>

 *

 * interpreted until it needs to calculate its time value (milliseconds from

 * the Epoch) or values of the calendar fields. Calling the

 *

 * <h3>Leniency</h3>

 *

 * fields, <em>lenient</em> and <em>non-lenient</em>.  When a

 * the calendar fields are normalized. For example, a lenient

 * exception if there is any inconsistency in its calendar fields. For

 * calculating its time or calendar field values if any out-of-range field

 * value has been set.

 *

 * <h3><a id="first_week">First Week</a></h3>

 *

 * parameters: the first day of the week and the minimal days in first week

 * (from 1 to 7).  These numbers are taken from the locale resource data or the

 * locale itself when a {@code Calendar} is constructed. If the designated

 * locale contains "fw" and/or "rg" <a href="./Locale.html#def_locale_extension">

 * Unicode extensions</a>, the first day of the week will be obtained according to

 * those extensions. If both "fw" and "rg" are specified, the value from the "fw"

 * extension supersedes the implicit one from the "rg" extension.

 * They may also be specified explicitly through the methods for setting their

 * values.

 *

 * first week of the month or year as a reference point.  The first week of a

 * month or year is defined as the earliest seven day period beginning on

 * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow

 * designate the week before week 1 of a year as week <code><i>n</i></code> of

 * the previous year.

 *

 * <h3>Calendar Fields Resolution</h3>

 *

 * When computing a date and time from the calendar fields, there

 * may be insufficient information for the computation (such as only

 * year and month with no day of month), or there may be inconsistent

 * information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,

 * calendar field values to determine the date and time in the

 * following way.

 *

 * <p><a id="resolution">If there is any conflict in calendar field values,

 * more recently.</a> The following are the default combinations of the

 * calendar fields. The most recent combination, as determined by the

 * most recently set single field, will be used.

 *

 * <p><a id="date_resolution">For the date fields</a>:

 * <blockquote>

 * <pre>

 * YEAR + MONTH + DAY_OF_MONTH

 * YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK

 * YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK

 * YEAR + DAY_OF_YEAR

 * YEAR + DAY_OF_WEEK + WEEK_OF_YEAR

 * </pre></blockquote>

 *

 * <a id="time_resolution">For the time of day fields</a>:

 * <blockquote>

 * <pre>

 * HOUR_OF_DAY

 * AM_PM + HOUR

 * </pre></blockquote>

 *

 * <p>If there are any calendar fields whose values haven't been set in the selected

 * value of each field may vary by concrete calendar systems. For example, in

 *

 * <p>

 * <strong>Note:</strong> There are certain possible ambiguities in

 * interpretation of certain singular times, which are resolved in the

 * following ways:

 * <ol>

 *     <li> 23:59 is the last minute of the day and 00:00 is the first

 *          minute of the next day. Thus, 23:59 on Dec 31, 1999 < 00:00 on

 *          Jan 1, 2000 < 00:01 on Jan 1, 2000.

 *

 *     <li> Although historically not precise, midnight also belongs to "am",

 *          and noon belongs to "pm", so on the same day,

 *          12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

 * </ol>

 *

 * <p>

 * The date or time format strings are not part of the definition of a

 * calendar, as those must be modifiable or overridable by the user at

 * runtime. Use {@link DateFormat}

 * to format dates.

 *

 * <h3>Field Manipulation</h3>

 *

 * The calendar fields can be changed using three methods:

 *

 * the calendar's time value in milliseconds is not recomputed until the next call to

 * computations. As a result of changing a calendar field using

 * calendar field, the calendar field value, and the calendar system. In addition,

 * after the calendar fields have been recomputed. The specifics are determined by

 * the concrete calendar class.</p>

 *

 * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,

 * Calendar.SEPTEMBER)</code> sets the date to September 31,

 * 1999. This is a temporary internal representation that resolves to

 *

 * get(f) + delta)</code> with two adjustments:</p>

 *

 * <blockquote>

 *   range and, as a result, the next larger field is incremented or

 *   decremented and the field value is adjusted back into its range.</p>

 *

 *   <p><strong>Add rule 2</strong>. If a smaller field is expected to be

 *   invariant, but it is impossible for it to be equal to its

 *   prior value because of changes in its minimum or maximum after field

 *   offset changes, then its value is adjusted to be as close

 *   as possible to its expected value. A smaller field represents a

 *   that are not expected to be invariant. The calendar system

 *   determines what fields are expected to be invariant.</p>

 * </blockquote>

 *

 * an immediate recomputation of the calendar's milliseconds and all

 * fields.</p>

 *

 * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,

 * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule

 * adding 13 months to August gives September of the next year. Since

 * rule 2, since it is expected to change when the month changes in a

 *

 * the following adjustment:</p>

 *

 * <blockquote>

 *   <p><strong>Roll rule</strong>. Larger fields are unchanged after the

 *   call. A larger field represents a larger unit of

 * </blockquote>

 *

 * <p><em>Example</em>: See {@link java.util.GregorianCalendar#roll(int, int)}.

 *

 * <p><strong>Usage model</strong>. To motivate the behavior of

 * component with increment and decrement buttons for the month, day, and

 * interface reads January 31, 1999 and the user presses the month

 * increment button, what should it read? If the underlying

 * better result would be February 28, 1999. Furthermore, if the user

 * presses the month increment button again, it should read March 31,

 * 1999, not March 28, 1999. By saving the original date and using either

 * fields should be affected, the user interface can behave as most users

 * will intuitively expect.</p>

 *

 * @see          java.lang.System#currentTimeMillis()

 * @see          Date

 * @see          GregorianCalendar

 * @see          TimeZone

 * @see          java.text.DateFormat

 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu

 * @since 1.1

 */

public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {

    // Data flow in Calendar

    // ---------------------

    // The current time is represented in two ways by Calendar: as UTC

    // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local

    // fields such as MONTH, HOUR, AM_PM, etc.  It is possible to compute the

    // millis from the fields, and vice versa.  The data needed to do this

    // conversion is encapsulated by a TimeZone object owned by the Calendar.

    // The data provided by the TimeZone object may also be overridden if the

    // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class

    // keeps track of what information was most recently set by the caller, and

    // uses that to compute any other information as needed.

    // If the user sets the fields using set(), the data flow is as follows.

    // This is implemented by the Calendar subclass's computeTime() method.

    // During this process, certain fields may be ignored.  The disambiguation

    // algorithm for resolving which fields to pay attention to is described

    // in the class documentation.

    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)

    //           |

    //           | Using Calendar-specific algorithm

    //           V

    //   local standard millis

    //           |

    //           | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET

    //           V

    //   UTC millis (in time data member)

    // If the user sets the UTC millis using setTime() or setTimeInMillis(),

    // the data flow is as follows.  This is implemented by the Calendar

    // subclass's computeFields() method.

    //   UTC millis (in time data member)

    //           |

    //           | Using TimeZone getOffset()

    //           V

    //   local standard millis

    //           |

    //           | Using Calendar-specific algorithm

    //           V

    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)

    // In general, a round trip from fields, through local and UTC millis, and

    // back out to fields is made when necessary.  This is implemented by the

    // complete() method.  Resolving a partial set of fields into a UTC millis

    // value allows all remaining fields to be generated from that value.  If

    // the Calendar is lenient, the fields are also renormalized to standard

    // ranges when they are regenerated.

    /**

     * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific

     * value; see subclass documentation.

     *

     * @see GregorianCalendar#AD

     * @see GregorianCalendar#BC

     */

    public static final int ERA = 0;

    /**

     * year. This is a calendar-specific value; see subclass documentation.

     */

    public static final int YEAR = 1;

    /**

     * month. This is a calendar-specific value. The first month of

     * the year in the Gregorian and Julian calendars is

     * of months in a year.

     *

     * @see #JANUARY

     * @see #FEBRUARY

     * @see #MARCH

     * @see #APRIL

     * @see #MAY

     * @see #JUNE

     * @see #JULY

     * @see #AUGUST

     * @see #SEPTEMBER

     * @see #OCTOBER

     * @see #NOVEMBER

     * @see #DECEMBER

     * @see #UNDECIMBER

     */

    public static final int MONTH = 2;

    /**

     * week number within the current year.  The first week of the year, as

     * the year.

     *

     * @see #getFirstDayOfWeek

     * @see #getMinimalDaysInFirstWeek

     */

    public static final int WEEK_OF_YEAR = 3;

    /**

     * week number within the current month.  The first week of the month, as

     * the month.

     *

     * @see #getFirstDayOfWeek

     * @see #getMinimalDaysInFirstWeek

     */

    public static final int WEEK_OF_MONTH = 4;

    /**

     * The first day of the month has value 1.

     *

     * @see #DAY_OF_MONTH

     */

    public static final int DATE = 5;

    /**

     * The first day of the month has value 1.

     *

     * @see #DATE

     */

    public static final int DAY_OF_MONTH = 5;

    /**

     * number within the current year.  The first day of the year has value 1.

     */

    public static final int DAY_OF_YEAR = 6;

    /**

     *

     * @see #SUNDAY

     * @see #MONDAY

     * @see #TUESDAY

     * @see #WEDNESDAY

     * @see #THURSDAY

     * @see #FRIDAY

     * @see #SATURDAY

     */

    public static final int DAY_OF_WEEK = 7;

    /**

     * ordinal number of the day of the week within the current month. Together

     * end of the month, so the last Sunday of a month is specified as

     * negative values count backward they will usually be aligned differently

     * within the month than positive values.  For example, if a month has 31

     *

     * @see #DAY_OF_WEEK

     * @see #WEEK_OF_MONTH

     */

    public static final int DAY_OF_WEEK_IN_MONTH = 8;

    /**

     *