Save This Page
Home » openjdk-7 » java » util » [javadoc | source]
    1   /*
    2    * Copyright 1996-2007 Sun Microsystems, Inc.  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.  Sun designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
   22    * CA 95054 USA or visit www.sun.com if you need additional information or
   23    * have any questions.
   24    */
   25   
   26   /*
   27    * (C) Copyright Taligent, Inc. 1996-1998 - All Rights Reserved
   28    * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved
   29    *
   30    *   The original version of this source code and documentation is copyrighted
   31    * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
   32    * materials are provided under terms of a License Agreement between Taligent
   33    * and Sun. This technology is protected by multiple US and International
   34    * patents. This notice and attribution to Taligent may not be removed.
   35    *   Taligent is a registered trademark of Taligent, Inc.
   36    *
   37    */
   38   
   39   package java.util;
   40   
   41   import java.io.IOException;
   42   import java.io.ObjectInputStream;
   43   import java.io.ObjectOutputStream;
   44   import java.io.Serializable;
   45   import java.security.AccessController;
   46   import java.security.PrivilegedExceptionAction;
   47   import java.text.DateFormat;
   48   import java.text.DateFormatSymbols;
   49   import sun.util.BuddhistCalendar;
   50   import sun.util.calendar.ZoneInfo;
   51   import sun.util.resources.LocaleData;
   52   
   53   /**
   54    * The <code>Calendar</code> class is an abstract class that provides methods
   55    * for converting between a specific instant in time and a set of {@link
   56    * #fields calendar fields} such as <code>YEAR</code>, <code>MONTH</code>,
   57    * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, and so on, and for
   58    * manipulating the calendar fields, such as getting the date of the next
   59    * week. An instant in time can be represented by a millisecond value that is
   60    * an offset from the <a name="Epoch"><em>Epoch</em></a>, January 1, 1970
   61    * 00:00:00.000 GMT (Gregorian).
   62    *
   63    * <p>The class also provides additional fields and methods for
   64    * implementing a concrete calendar system outside the package. Those
   65    * fields and methods are defined as <code>protected</code>.
   66    *
   67    * <p>
   68    * Like other locale-sensitive classes, <code>Calendar</code> provides a
   69    * class method, <code>getInstance</code>, for getting a generally useful
   70    * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
   71    * returns a <code>Calendar</code> object whose
   72    * calendar fields have been initialized with the current date and time:
   73    * <blockquote>
   74    * <pre>
   75    *     Calendar rightNow = Calendar.getInstance();
   76    * </pre>
   77    * </blockquote>
   78    *
   79    * <p>A <code>Calendar</code> object can produce all the calendar field values
   80    * needed to implement the date-time formatting for a particular language and
   81    * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
   82    * <code>Calendar</code> defines the range of values returned by
   83    * certain calendar fields, as well as their meaning.  For example,
   84    * the first month of the calendar system has value <code>MONTH ==
   85    * JANUARY</code> for all calendars.  Other values are defined by the
   86    * concrete subclass, such as <code>ERA</code>.  See individual field
   87    * documentation and subclass documentation for details.
   88    *
   89    * <h4>Getting and Setting Calendar Field Values</h4>
   90    *
   91    * <p>The calendar field values can be set by calling the <code>set</code>
   92    * methods. Any field values set in a <code>Calendar</code> will not be
   93    * interpreted until it needs to calculate its time value (milliseconds from
   94    * the Epoch) or values of the calendar fields. Calling the
   95    * <code>get</code>, <code>getTimeInMillis</code>, <code>getTime</code>,
   96    * <code>add</code> and <code>roll</code> involves such calculation.
   97    *
   98    * <h4>Leniency</h4>
   99    *
  100    * <p><code>Calendar</code> has two modes for interpreting the calendar
  101    * fields, <em>lenient</em> and <em>non-lenient</em>.  When a
  102    * <code>Calendar</code> is in lenient mode, it accepts a wider range of
  103    * calendar field values than it produces.  When a <code>Calendar</code>
  104    * recomputes calendar field values for return by <code>get()</code>, all of
  105    * the calendar fields are normalized. For example, a lenient
  106    * <code>GregorianCalendar</code> interprets <code>MONTH == JANUARY</code>,
  107    * <code>DAY_OF_MONTH == 32</code> as February 1.
  108   
  109    * <p>When a <code>Calendar</code> is in non-lenient mode, it throws an
  110    * exception if there is any inconsistency in its calendar fields. For
  111    * example, a <code>GregorianCalendar</code> always produces
  112    * <code>DAY_OF_MONTH</code> values between 1 and the length of the month. A
  113    * non-lenient <code>GregorianCalendar</code> throws an exception upon
  114    * calculating its time or calendar field values if any out-of-range field
  115    * value has been set.
  116    *
  117    * <h4>First Week</h4>
  118    *
  119    * <code>Calendar</code> defines a locale-specific seven day week using two
  120    * parameters: the first day of the week and the minimal days in first week
  121    * (from 1 to 7).  These numbers are taken from the locale resource data when a
  122    * <code>Calendar</code> is constructed.  They may also be specified explicitly
  123    * through the methods for setting their values.
  124    *
  125    * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
  126    * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
  127    * first week of the month or year as a reference point.  The first week of a
  128    * month or year is defined as the earliest seven day period beginning on
  129    * <code>getFirstDayOfWeek()</code> and containing at least
  130    * <code>getMinimalDaysInFirstWeek()</code> days of that month or year.  Weeks
  131    * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
  132    * it.  Note that the normalized numbering returned by <code>get()</code> may be
  133    * different.  For example, a specific <code>Calendar</code> subclass may
  134    * designate the week before week 1 of a year as week <code><i>n</i></code> of
  135    * the previous year.
  136    *
  137    * <h4>Calendar Fields Resolution</h4>
  138    *
  139    * When computing a date and time from the calendar fields, there
  140    * may be insufficient information for the computation (such as only
  141    * year and month with no day of month), or there may be inconsistent
  142    * information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,
  143    * 1996 is actually a Monday). <code>Calendar</code> will resolve
  144    * calendar field values to determine the date and time in the
  145    * following way.
  146    *
  147    * <p>If there is any conflict in calendar field values,
  148    * <code>Calendar</code> gives priorities to calendar fields that have been set
  149    * more recently. The following are the default combinations of the
  150    * calendar fields. The most recent combination, as determined by the
  151    * most recently set single field, will be used.
  152    *
  153    * <p><a name="date_resolution">For the date fields</a>:
  154    * <blockquote>
  155    * <pre>
  156    * YEAR + MONTH + DAY_OF_MONTH
  157    * YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
  158    * YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
  159    * YEAR + DAY_OF_YEAR
  160    * YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
  161    * </pre></blockquote>
  162    *
  163    * <a name="time_resolution">For the time of day fields</a>:
  164    * <blockquote>
  165    * <pre>
  166    * HOUR_OF_DAY
  167    * AM_PM + HOUR
  168    * </pre></blockquote>
  169    *
  170    * <p>If there are any calendar fields whose values haven't been set in the selected
  171    * field combination, <code>Calendar</code> uses their default values. The default
  172    * value of each field may vary by concrete calendar systems. For example, in
  173    * <code>GregorianCalendar</code>, the default of a field is the same as that
  174    * of the start of the Epoch: i.e., <code>YEAR = 1970</code>, <code>MONTH =
  175    * JANUARY</code>, <code>DAY_OF_MONTH = 1</code>, etc.
  176    *
  177    * <p>
  178    * <strong>Note:</strong> There are certain possible ambiguities in
  179    * interpretation of certain singular times, which are resolved in the
  180    * following ways:
  181    * <ol>
  182    *     <li> 23:59 is the last minute of the day and 00:00 is the first
  183    *          minute of the next day. Thus, 23:59 on Dec 31, 1999 &lt; 00:00 on
  184    *          Jan 1, 2000 &lt; 00:01 on Jan 1, 2000.
  185    *
  186    *     <li> Although historically not precise, midnight also belongs to "am",
  187    *          and noon belongs to "pm", so on the same day,
  188    *          12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
  189    * </ol>
  190    *
  191    * <p>
  192    * The date or time format strings are not part of the definition of a
  193    * calendar, as those must be modifiable or overridable by the user at
  194    * runtime. Use {@link DateFormat}
  195    * to format dates.
  196    *
  197    * <h4>Field Manipulation</h4>
  198    *
  199    * The calendar fields can be changed using three methods:
  200    * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
  201    *
  202    * <p><strong><code>set(f, value)</code></strong> changes calendar field
  203    * <code>f</code> to <code>value</code>.  In addition, it sets an
  204    * internal member variable to indicate that calendar field <code>f</code> has
  205    * been changed. Although calendar field <code>f</code> is changed immediately,
  206    * the calendar's time value in milliseconds is not recomputed until the next call to
  207    * <code>get()</code>, <code>getTime()</code>, <code>getTimeInMillis()</code>,
  208    * <code>add()</code>, or <code>roll()</code> is made. Thus, multiple calls to
  209    * <code>set()</code> do not trigger multiple, unnecessary
  210    * computations. As a result of changing a calendar field using
  211    * <code>set()</code>, other calendar fields may also change, depending on the
  212    * calendar field, the calendar field value, and the calendar system. In addition,
  213    * <code>get(f)</code> will not necessarily return <code>value</code> set by
  214    * the call to the <code>set</code> method
  215    * after the calendar fields have been recomputed. The specifics are determined by
  216    * the concrete calendar class.</p>
  217    *
  218    * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
  219    * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
  220    * Calendar.SEPTEMBER)</code> sets the date to September 31,
  221    * 1999. This is a temporary internal representation that resolves to
  222    * October 1, 1999 if <code>getTime()</code>is then called. However, a
  223    * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
  224    * <code>getTime()</code> sets the date to September 30, 1999, since
  225    * no recomputation occurs after <code>set()</code> itself.</p>
  226    *
  227    * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
  228    * to field <code>f</code>.  This is equivalent to calling <code>set(f,
  229    * get(f) + delta)</code> with two adjustments:</p>
  230    *
  231    * <blockquote>
  232    *   <p><strong>Add rule 1</strong>. The value of field <code>f</code>
  233    *   after the call minus the value of field <code>f</code> before the
  234    *   call is <code>delta</code>, modulo any overflow that has occurred in
  235    *   field <code>f</code>. Overflow occurs when a field value exceeds its
  236    *   range and, as a result, the next larger field is incremented or
  237    *   decremented and the field value is adjusted back into its range.</p>
  238    *
  239    *   <p><strong>Add rule 2</strong>. If a smaller field is expected to be
  240    *   invariant, but it is impossible for it to be equal to its
  241    *   prior value because of changes in its minimum or maximum after field
  242    *   <code>f</code> is changed or other constraints, such as time zone
  243    *   offset changes, then its value is adjusted to be as close
  244    *   as possible to its expected value. A smaller field represents a
  245    *   smaller unit of time. <code>HOUR</code> is a smaller field than
  246    *   <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
  247    *   that are not expected to be invariant. The calendar system
  248    *   determines what fields are expected to be invariant.</p>
  249    * </blockquote>
  250    *
  251    * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
  252    * an immediate recomputation of the calendar's milliseconds and all
  253    * fields.</p>
  254    *
  255    * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
  256    * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
  257    * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
  258    * 1</strong> sets the <code>MONTH</code> field to September, since
  259    * adding 13 months to August gives September of the next year. Since
  260    * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
  261    * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
  262    * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
  263    * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
  264    * rule 2, since it is expected to change when the month changes in a
  265    * <code>GregorianCalendar</code>.</p>
  266    *
  267    * <p><strong><code>roll(f, delta)</code></strong> adds
  268    * <code>delta</code> to field <code>f</code> without changing larger
  269    * fields. This is equivalent to calling <code>add(f, delta)</code> with
  270    * the following adjustment:</p>
  271    *
  272    * <blockquote>
  273    *   <p><strong>Roll rule</strong>. Larger fields are unchanged after the
  274    *   call. A larger field represents a larger unit of
  275    *   time. <code>DAY_OF_MONTH</code> is a larger field than
  276    *   <code>HOUR</code>.</p>
  277    * </blockquote>
  278    *
  279    * <p><em>Example</em>: See {@link java.util.GregorianCalendar#roll(int, int)}.
  280    *
  281    * <p><strong>Usage model</strong>. To motivate the behavior of
  282    * <code>add()</code> and <code>roll()</code>, consider a user interface
  283    * component with increment and decrement buttons for the month, day, and
  284    * year, and an underlying <code>GregorianCalendar</code>. If the
  285    * interface reads January 31, 1999 and the user presses the month
  286    * increment button, what should it read? If the underlying
  287    * implementation uses <code>set()</code>, it might read March 3, 1999. A
  288    * better result would be February 28, 1999. Furthermore, if the user
  289    * presses the month increment button again, it should read March 31,
  290    * 1999, not March 28, 1999. By saving the original date and using either
  291    * <code>add()</code> or <code>roll()</code>, depending on whether larger
  292    * fields should be affected, the user interface can behave as most users
  293    * will intuitively expect.</p>
  294    *
  295    * @see          java.lang.System#currentTimeMillis()
  296    * @see          Date
  297    * @see          GregorianCalendar
  298    * @see          TimeZone
  299    * @see          java.text.DateFormat
  300    * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
  301    * @since JDK1.1
  302    */
  303   public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
  304   
  305       // Data flow in Calendar
  306       // ---------------------
  307   
  308       // The current time is represented in two ways by Calendar: as UTC
  309       // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
  310       // fields such as MONTH, HOUR, AM_PM, etc.  It is possible to compute the
  311       // millis from the fields, and vice versa.  The data needed to do this
  312       // conversion is encapsulated by a TimeZone object owned by the Calendar.
  313       // The data provided by the TimeZone object may also be overridden if the
  314       // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
  315       // keeps track of what information was most recently set by the caller, and
  316       // uses that to compute any other information as needed.
  317   
  318       // If the user sets the fields using set(), the data flow is as follows.
  319       // This is implemented by the Calendar subclass's computeTime() method.
  320       // During this process, certain fields may be ignored.  The disambiguation
  321       // algorithm for resolving which fields to pay attention to is described
  322       // in the class documentation.
  323   
  324       //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
  325       //           |
  326       //           | Using Calendar-specific algorithm
  327       //           V
  328       //   local standard millis
  329       //           |
  330       //           | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
  331       //           V
  332       //   UTC millis (in time data member)
  333   
  334       // If the user sets the UTC millis using setTime() or setTimeInMillis(),
  335       // the data flow is as follows.  This is implemented by the Calendar
  336       // subclass's computeFields() method.
  337   
  338       //   UTC millis (in time data member)
  339       //           |
  340       //           | Using TimeZone getOffset()
  341       //           V
  342       //   local standard millis
  343       //           |
  344       //           | Using Calendar-specific algorithm
  345       //           V
  346       //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
  347   
  348       // In general, a round trip from fields, through local and UTC millis, and
  349       // back out to fields is made when necessary.  This is implemented by the
  350       // complete() method.  Resolving a partial set of fields into a UTC millis
  351       // value allows all remaining fields to be generated from that value.  If
  352       // the Calendar is lenient, the fields are also renormalized to standard
  353       // ranges when they are regenerated.
  354   
  355       /**
  356        * Field number for <code>get</code> and <code>set</code> indicating the
  357        * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
  358        * value; see subclass documentation.
  359        *
  360        * @see GregorianCalendar#AD
  361        * @see GregorianCalendar#BC
  362        */
  363       public final static int ERA = 0;
  364   
  365       /**
  366        * Field number for <code>get</code> and <code>set</code> indicating the
  367        * year. This is a calendar-specific value; see subclass documentation.
  368        */
  369       public final static int YEAR = 1;
  370   
  371       /**
  372        * Field number for <code>get</code> and <code>set</code> indicating the
  373        * month. This is a calendar-specific value. The first month of
  374        * the year in the Gregorian and Julian calendars is
  375        * <code>JANUARY</code> which is 0; the last depends on the number
  376        * of months in a year.
  377        *
  378        * @see #JANUARY
  379        * @see #FEBRUARY
  380        * @see #MARCH
  381        * @see #APRIL
  382        * @see #MAY
  383        * @see #JUNE
  384        * @see #JULY
  385        * @see #AUGUST
  386        * @see #SEPTEMBER
  387        * @see #OCTOBER
  388        * @see #NOVEMBER
  389        * @see #DECEMBER
  390        * @see #UNDECIMBER
  391        */
  392       public final static int MONTH = 2;
  393   
  394       /**
  395        * Field number for <code>get</code> and <code>set</code> indicating the
  396        * week number within the current year.  The first week of the year, as
  397        * defined by <code>getFirstDayOfWeek()</code> and
  398        * <code>getMinimalDaysInFirstWeek()</code>, has value 1.  Subclasses define
  399        * the value of <code>WEEK_OF_YEAR</code> for days before the first week of
  400        * the year.
  401        *
  402        * @see #getFirstDayOfWeek
  403        * @see #getMinimalDaysInFirstWeek
  404        */
  405       public final static int WEEK_OF_YEAR = 3;
  406   
  407       /**
  408        * Field number for <code>get</code> and <code>set</code> indicating the
  409        * week number within the current month.  The first week of the month, as
  410        * defined by <code>getFirstDayOfWeek()</code> and
  411        * <code>getMinimalDaysInFirstWeek()</code>, has value 1.  Subclasses define
  412        * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
  413        * the month.
  414        *
  415        * @see #getFirstDayOfWeek
  416        * @see #getMinimalDaysInFirstWeek
  417        */
  418       public final static int WEEK_OF_MONTH = 4;
  419   
  420       /**
  421        * Field number for <code>get</code> and <code>set</code> indicating the
  422        * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
  423        * The first day of the month has value 1.
  424        *
  425        * @see #DAY_OF_MONTH
  426        */
  427       public final static int DATE = 5;
  428   
  429       /**
  430        * Field number for <code>get</code> and <code>set</code> indicating the
  431        * day of the month. This is a synonym for <code>DATE</code>.
  432        * The first day of the month has value 1.
  433        *
  434        * @see #DATE
  435        */
  436       public final static int DAY_OF_MONTH = 5;
  437   
  438       /**
  439        * Field number for <code>get</code> and <code>set</code> indicating the day
  440        * number within the current year.  The first day of the year has value 1.
  441        */
  442       public final static int DAY_OF_YEAR = 6;
  443   
  444       /**
  445        * Field number for <code>get</code> and <code>set</code> indicating the day
  446        * of the week.  This field takes values <code>SUNDAY</code>,
  447        * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
  448        * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
  449        *
  450        * @see #SUNDAY
  451        * @see #MONDAY
  452        * @see #TUESDAY
  453        * @see #WEDNESDAY
  454        * @see #THURSDAY
  455        * @see #FRIDAY
  456        * @see #SATURDAY
  457        */
  458       public final static int DAY_OF_WEEK = 7;
  459   
  460       /**
  461        * Field number for <code>get</code> and <code>set</code> indicating the
  462        * ordinal number of the day of the week within the current month. Together
  463        * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
  464        * within a month.  Unlike <code>WEEK_OF_MONTH</code> and
  465        * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
  466        * <code>getFirstDayOfWeek()</code> or
  467        * <code>getMinimalDaysInFirstWeek()</code>.  <code>DAY_OF_MONTH 1</code>
  468        * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
  469        * 1</code>; <code>8</code> through <code>14</code> correspond to
  470        * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
  471        * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
  472        * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
  473        * end of the month, so the last Sunday of a month is specified as
  474        * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
  475        * negative values count backward they will usually be aligned differently
  476        * within the month than positive values.  For example, if a month has 31
  477        * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
  478        * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
  479        *
  480        * @see #DAY_OF_WEEK
  481        * @see #WEEK_OF_MONTH
  482        */
  483       public final static int DAY_OF_WEEK_IN_MONTH = 8;
  484   
  485       /**
  486        * Field number for <code>get</code> and <code>set</code> indicating
  487        * whether the <code>HOUR</code> is before or after noon.
  488        * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
  489        *
  490        * @see #AM
  491        * @see #PM
  492        * @see #HOUR
  493        */
  494       public final static int AM_PM = 9;
  495   
  496       /**
  497        * Field number for <code>get</code> and <code>set</code> indicating the
  498        * hour of the morning or afternoon. <code>HOUR</code> is used for the
  499        * 12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12.
  500        * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
  501        *
  502        * @see #AM_PM
  503        * @see #HOUR_OF_DAY
  504        */
  505       public final static int HOUR = 10;
  506   
  507       /**
  508        * Field number for <code>get</code> and <code>set</code> indicating the
  509        * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
  510        * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
  511        *
  512        * @see #HOUR
  513        */
  514       public final static int HOUR_OF_DAY = 11;
  515   
  516       /**
  517        * Field number for <code>get</code> and <code>set</code> indicating the
  518        * minute within the hour.
  519        * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
  520        */
  521       public final static int MINUTE = 12;
  522   
  523       /**
  524        * Field number for <code>get</code> and <code>set</code> indicating the
  525        * second within the minute.
  526        * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
  527        */
  528       public final static int SECOND = 13;
  529   
  530       /**
  531        * Field number for <code>get</code> and <code>set</code> indicating the
  532        * millisecond within the second.
  533        * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
  534        */
  535       public final static int MILLISECOND = 14;
  536   
  537       /**
  538        * Field number for <code>get</code> and <code>set</code>
  539        * indicating the raw offset from GMT in milliseconds.
  540        * <p>
  541        * This field reflects the correct GMT offset value of the time
  542        * zone of this <code>Calendar</code> if the
  543        * <code>TimeZone</code> implementation subclass supports
  544        * historical GMT offset changes.
  545        */
  546       public final static int ZONE_OFFSET = 15;
  547   
  548       /**
  549        * Field number for <code>get</code> and <code>set</code> indicating the
  550        * daylight savings offset in milliseconds.
  551        * <p>
  552        * This field reflects the correct daylight saving offset value of
  553        * the time zone of this <code>Calendar</code> if the
  554        * <code>TimeZone</code> implementation subclass supports
  555        * historical Daylight Saving Time schedule changes.
  556        */
  557       public final static int DST_OFFSET = 16;
  558   
  559       /**
  560        * The number of distinct fields recognized by <code>get</code> and <code>set</code>.
  561        * Field numbers range from <code>0..FIELD_COUNT-1</code>.
  562        */
  563       public final static int FIELD_COUNT = 17;
  564   
  565       /**
  566        * Value of the {@link #DAY_OF_WEEK} field indicating
  567        * Sunday.
  568        */
  569       public final static int SUNDAY = 1;
  570   
  571       /**
  572        * Value of the {@link #DAY_OF_WEEK} field indicating
  573        * Monday.
  574        */
  575       public final static int MONDAY = 2;
  576   
  577       /**
  578        * Value of the {@link #DAY_OF_WEEK} field indicating
  579        * Tuesday.
  580        */
  581       public final static int TUESDAY = 3;
  582   
  583       /**
  584        * Value of the {@link #DAY_OF_WEEK} field indicating
  585        * Wednesday.
  586        */
  587       public final static int WEDNESDAY = 4;
  588   
  589       /**
  590        * Value of the {@link #DAY_OF_WEEK} field indicating
  591        * Thursday.
  592        */
  593       public final static int THURSDAY = 5;
  594   
  595       /**
  596        * Value of the {@link #DAY_OF_WEEK} field indicating
  597        * Friday.
  598        */
  599       public final static int FRIDAY = 6;
  600   
  601       /**
  602        * Value of the {@link #DAY_OF_WEEK} field indicating
  603        * Saturday.
  604        */
  605       public final static int SATURDAY = 7;
  606   
  607       /**
  608        * Value of the {@link #MONTH} field indicating the
  609        * first month of the year in the Gregorian and Julian calendars.
  610        */
  611       public final static int JANUARY = 0;
  612   
  613       /**
  614        * Value of the {@link #MONTH} field indicating the
  615        * second month of the year in the Gregorian and Julian calendars.
  616        */
  617       public final static int FEBRUARY = 1;
  618   
  619       /**
  620        * Value of the {@link #MONTH} field indicating the
  621        * third month of the year in the Gregorian and Julian calendars.
  622        */
  623       public final static int MARCH = 2;
  624   
  625       /**
  626        * Value of the {@link #MONTH} field indicating the
  627        * fourth month of the year in the Gregorian and Julian calendars.
  628        */
  629       public final static int APRIL = 3;
  630   
  631       /**
  632        * Value of the {@link #MONTH} field indicating the
  633        * fifth month of the year in the Gregorian and Julian calendars.
  634        */
  635       public final static int MAY = 4;
  636   
  637       /**
  638        * Value of the {@link #MONTH} field indicating the
  639        * sixth month of the year in the Gregorian and Julian calendars.
  640        */
  641       public final static int JUNE = 5;
  642   
  643       /**
  644        * Value of the {@link #MONTH} field indicating the
  645        * seventh month of the year in the Gregorian and Julian calendars.
  646        */
  647       public final static int JULY = 6;
  648   
  649       /**
  650        * Value of the {@link #MONTH} field indicating the
  651        * eighth month of the year in the Gregorian and Julian calendars.
  652        */
  653       public final static int AUGUST = 7;
  654   
  655       /**
  656        * Value of the {@link #MONTH} field indicating the
  657        * ninth month of the year in the Gregorian and Julian calendars.
  658        */
  659       public final static int SEPTEMBER = 8;
  660   
  661       /**
  662        * Value of the {@link #MONTH} field indicating the
  663        * tenth month of the year in the Gregorian and Julian calendars.
  664        */
  665       public final static int OCTOBER = 9;
  666   
  667       /**
  668        * Value of the {@link #MONTH} field indicating the
  669        * eleventh month of the year in the Gregorian and Julian calendars.
  670        */
  671       public final static int NOVEMBER = 10;
  672   
  673       /**
  674        * Value of the {@link #MONTH} field indicating the
  675        * twelfth month of the year in the Gregorian and Julian calendars.
  676        */
  677       public final static int DECEMBER = 11;
  678   
  679       /**
  680        * Value of the {@link #MONTH} field indicating the
  681        * thirteenth month of the year. Although <code>GregorianCalendar</code>
  682        * does not use this value, lunar calendars do.
  683        */
  684       public final static int UNDECIMBER = 12;
  685   
  686       /**
  687        * Value of the {@link #AM_PM} field indicating the
  688        * period of the day from midnight to just before noon.
  689        */
  690       public final static int AM = 0;
  691   
  692       /**
  693        * Value of the {@link #AM_PM} field indicating the
  694        * period of the day from noon to just before midnight.
  695        */
  696       public final static int PM = 1;
  697   
  698       /**
  699        * A style specifier for {@link #getDisplayNames(int, int, Locale)
  700        * getDisplayNames} indicating names in all styles, such as
  701        * "January" and "Jan".
  702        *
  703        * @see #SHORT
  704        * @see #LONG
  705        * @since 1.6
  706        */
  707       public static final int ALL_STYLES = 0;
  708   
  709       /**
  710        * A style specifier for {@link #getDisplayName(int, int, Locale)
  711        * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
  712        * getDisplayNames} indicating a short name, such as "Jan".
  713        *
  714        * @see #LONG
  715        * @since 1.6
  716        */
  717       public static final int SHORT = 1;
  718   
  719       /**
  720        * A style specifier for {@link #getDisplayName(int, int, Locale)
  721        * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
  722        * getDisplayNames} indicating a long name, such as "January".
  723        *
  724        * @see #SHORT
  725        * @since 1.6
  726        */
  727       public static final int LONG = 2;
  728   
  729       // Internal notes:
  730       // Calendar contains two kinds of time representations: current "time" in
  731       // milliseconds, and a set of calendar "fields" representing the current time.
  732       // The two representations are usually in sync, but can get out of sync
  733       // as follows.
  734       // 1. Initially, no fields are set, and the time is invalid.
  735       // 2. If the time is set, all fields are computed and in sync.
  736       // 3. If a single field is set, the time is invalid.
  737       // Recomputation of the time and fields happens when the object needs
  738       // to return a result to the user, or use a result for a computation.
  739   
  740       /**
  741        * The calendar field values for the currently set time for this calendar.
  742        * This is an array of <code>FIELD_COUNT</code> integers, with index values
  743        * <code>ERA</code> through <code>DST_OFFSET</code>.
  744        * @serial
  745        */
  746       protected int           fields[];
  747   
  748       /**
  749        * The flags which tell if a specified calendar field for the calendar is set.
  750        * A new object has no fields set.  After the first call to a method
  751        * which generates the fields, they all remain set after that.
  752        * This is an array of <code>FIELD_COUNT</code> booleans, with index values
  753        * <code>ERA</code> through <code>DST_OFFSET</code>.
  754        * @serial
  755        */
  756       protected boolean       isSet[];
  757   
  758       /**
  759        * Pseudo-time-stamps which specify when each field was set. There
  760        * are two special values, UNSET and COMPUTED. Values from
  761        * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.
  762        */
  763       transient private int   stamp[];
  764   
  765       /**
  766        * The currently set time for this calendar, expressed in milliseconds after
  767        * January 1, 1970, 0:00:00 GMT.
  768        * @see #isTimeSet
  769        * @serial
  770        */
  771       protected long          time;
  772   
  773       /**
  774        * True if then the value of <code>time</code> is valid.
  775        * The time is made invalid by a change to an item of <code>field[]</code>.
  776        * @see #time
  777        * @serial
  778        */
  779       protected boolean       isTimeSet;
  780   
  781       /**
  782        * True if <code>fields[]</code> are in sync with the currently set time.
  783        * If false, then the next attempt to get the value of a field will
  784        * force a recomputation of all fields from the current value of
  785        * <code>time</code>.
  786        * @serial
  787        */
  788       protected boolean       areFieldsSet;
  789   
  790       /**
  791        * True if all fields have been set.
  792        * @serial
  793        */
  794       transient boolean       areAllFieldsSet;
  795   
  796       /**
  797        * <code>True</code> if this calendar allows out-of-range field values during computation
  798        * of <code>time</code> from <code>fields[]</code>.
  799        * @see #setLenient
  800        * @see #isLenient
  801        * @serial
  802        */
  803       private boolean         lenient = true;
  804   
  805       /**
  806        * The <code>TimeZone</code> used by this calendar. <code>Calendar</code>
  807        * uses the time zone data to translate between locale and GMT time.
  808        * @serial
  809        */
  810       private TimeZone        zone;
  811   
  812       /**
  813        * <code>True</code> if zone references to a shared TimeZone object.
  814        */
  815       transient private boolean sharedZone = false;
  816   
  817       /**
  818        * The first day of the week, with possible values <code>SUNDAY</code>,
  819        * <code>MONDAY</code>, etc.  This is a locale-dependent value.
  820        * @serial
  821        */
  822       private int             firstDayOfWeek;
  823   
  824       /**
  825        * The number of days required for the first week in a month or year,
  826        * with possible values from 1 to 7.  This is a locale-dependent value.
  827        * @serial
  828        */
  829       private int             minimalDaysInFirstWeek;
  830   
  831       /**
  832        * Cache to hold the firstDayOfWeek and minimalDaysInFirstWeek
  833        * of a Locale.
  834        */
  835       private static Hashtable<Locale, int[]> cachedLocaleData = new Hashtable<Locale, int[]>(3);
  836   
  837       // Special values of stamp[]
  838       /**
  839        * The corresponding fields[] has no value.
  840        */
  841       private static final int        UNSET = 0;
  842   
  843       /**
  844        * The value of the corresponding fields[] has been calculated internally.
  845        */
  846       private static final int        COMPUTED = 1;
  847   
  848       /**
  849        * The value of the corresponding fields[] has been set externally. Stamp
  850        * values which are greater than 1 represents the (pseudo) time when the
  851        * corresponding fields[] value was set.
  852        */
  853       private static final int        MINIMUM_USER_STAMP = 2;
  854   
  855       /**
  856        * The mask value that represents all of the fields.
  857        */
  858       static final int ALL_FIELDS = (1 << FIELD_COUNT) - 1;
  859   
  860       /**
  861        * The next available value for <code>stamp[]</code>, an internal array.
  862        * This actually should not be written out to the stream, and will probably
  863        * be removed from the stream in the near future.  In the meantime,
  864        * a value of <code>MINIMUM_USER_STAMP</code> should be used.
  865        * @serial
  866        */
  867       private int             nextStamp = MINIMUM_USER_STAMP;
  868   
  869       // the internal serial version which says which version was written
  870       // - 0 (default) for version up to JDK 1.1.5
  871       // - 1 for version from JDK 1.1.6, which writes a correct 'time' value
  872       //     as well as compatible values for other fields.  This is a
  873       //     transitional format.
  874       // - 2 (not implemented yet) a future version, in which fields[],
  875       //     areFieldsSet, and isTimeSet become transient, and isSet[] is
  876       //     removed. In JDK 1.1.6 we write a format compatible with version 2.
  877       static final int        currentSerialVersion = 1;
  878   
  879       /**
  880        * The version of the serialized data on the stream.  Possible values:
  881        * <dl>
  882        * <dt><b>0</b> or not present on stream</dt>
  883        * <dd>
  884        * JDK 1.1.5 or earlier.
  885        * </dd>
  886        * <dt><b>1</b></dt>
  887        * <dd>
  888        * JDK 1.1.6 or later.  Writes a correct 'time' value
  889        * as well as compatible values for other fields.  This is a
  890        * transitional format.
  891        * </dd>
  892        * </dl>
  893        * When streaming out this class, the most recent format
  894        * and the highest allowable <code>serialVersionOnStream</code>
  895        * is written.
  896        * @serial
  897        * @since JDK1.1.6
  898        */
  899       private int             serialVersionOnStream = currentSerialVersion;
  900   
  901       // Proclaim serialization compatibility with JDK 1.1
  902       static final long       serialVersionUID = -1807547505821590642L;
  903   
  904       // Mask values for calendar fields
  905       final static int ERA_MASK           = (1 << ERA);
  906       final static int YEAR_MASK          = (1 << YEAR);
  907       final static int MONTH_MASK         = (1 << MONTH);
  908       final static int WEEK_OF_YEAR_MASK  = (1 << WEEK_OF_YEAR);
  909       final static int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
  910       final static int DAY_OF_MONTH_MASK  = (1 << DAY_OF_MONTH);
  911       final static int DATE_MASK          = DAY_OF_MONTH_MASK;
  912       final static int DAY_OF_YEAR_MASK   = (1 << DAY_OF_YEAR);
  913       final static int DAY_OF_WEEK_MASK   = (1 << DAY_OF_WEEK);
  914       final static int DAY_OF_WEEK_IN_MONTH_MASK  = (1 << DAY_OF_WEEK_IN_MONTH);
  915       final static int AM_PM_MASK         = (1 << AM_PM);
  916       final static int HOUR_MASK          = (1 << HOUR);
  917       final static int HOUR_OF_DAY_MASK   = (1 << HOUR_OF_DAY);
  918       final static int MINUTE_MASK        = (1 << MINUTE);
  919       final static int SECOND_MASK        = (1 << SECOND);
  920       final static int MILLISECOND_MASK   = (1 << MILLISECOND);
  921       final static int ZONE_OFFSET_MASK   = (1 << ZONE_OFFSET);
  922       final static int DST_OFFSET_MASK    = (1 << DST_OFFSET);
  923   
  924       /**
  925        * Constructs a Calendar with the default time zone
  926        * and locale.
  927        * @see     TimeZone#getDefault
  928        */
  929       protected Calendar()
  930       {
  931           this(TimeZone.getDefaultRef(), Locale.getDefault());
  932           sharedZone = true;
  933       }
  934   
  935       /**
  936        * Constructs a calendar with the specified time zone and locale.
  937        *
  938        * @param zone the time zone to use
  939        * @param aLocale the locale for the week data
  940        */
  941       protected Calendar(TimeZone zone, Locale aLocale)
  942       {
  943           fields = new int[FIELD_COUNT];
  944           isSet = new boolean[FIELD_COUNT];
  945           stamp = new int[FIELD_COUNT];
  946   
  947           this.zone = zone;
  948           setWeekCountData(aLocale);
  949       }
  950   
  951       /**
  952        * Gets a calendar using the default time zone and locale. The
  953        * <code>Calendar</code> returned is based on the current time
  954        * in the default time zone with the default locale.
  955        *
  956        * @return a Calendar.
  957        */
  958       public static Calendar getInstance()
  959       {
  960           Calendar cal = createCalendar(TimeZone.getDefaultRef(), Locale.getDefault());
  961           cal.sharedZone = true;
  962           return cal;
  963       }
  964   
  965       /**
  966        * Gets a calendar using the specified time zone and default locale.
  967        * The <code>Calendar</code> returned is based on the current time
  968        * in the given time zone with the default locale.
  969        *
  970        * @param zone the time zone to use
  971        * @return a Calendar.
  972        */
  973       public static Calendar getInstance(TimeZone zone)
  974       {
  975           return createCalendar(zone, Locale.getDefault());
  976       }
  977   
  978       /**
  979        * Gets a calendar using the default time zone and specified locale.
  980        * The <code>Calendar</code> returned is based on the current time
  981        * in the default time zone with the given locale.
  982        *
  983        * @param aLocale the locale for the week data
  984        * @return a Calendar.
  985        */
  986       public static Calendar getInstance(Locale aLocale)
  987       {
  988           Calendar cal = createCalendar(TimeZone.getDefaultRef(), aLocale);
  989           cal.sharedZone = true;
  990           return cal;
  991       }
  992   
  993       /**
  994        * Gets a calendar with the specified time zone and locale.
  995        * The <code>Calendar</code> returned is based on the current time
  996        * in the given time zone with the given locale.
  997        *
  998        * @param zone the time zone to use
  999        * @param aLocale the locale for the week data
 1000        * @return a Calendar.
 1001        */
 1002       public static Calendar getInstance(TimeZone zone,
 1003                                          Locale aLocale)
 1004       {
 1005           return createCalendar(zone, aLocale);
 1006       }
 1007   
 1008       private static Calendar createCalendar(TimeZone zone,
 1009                                              Locale aLocale)
 1010       {
 1011           // If the specified locale is a Thai locale, returns a BuddhistCalendar
 1012           // instance.
 1013           if ("th".equals(aLocale.getLanguage())
 1014               && ("TH".equals(aLocale.getCountry()))) {
 1015               return new sun.util.BuddhistCalendar(zone, aLocale);
 1016           } else if ("JP".equals(aLocale.getVariant())
 1017                      && "JP".equals(aLocale.getCountry())
 1018                      && "ja".equals(aLocale.getLanguage())) {
 1019               return new JapaneseImperialCalendar(zone, aLocale);
 1020           }
 1021   
 1022           // else create the default calendar
 1023           return new GregorianCalendar(zone, aLocale);
 1024       }
 1025   
 1026       /**
 1027        * Returns an array of all locales for which the <code>getInstance</code>
 1028        * methods of this class can return localized instances.
 1029        * The array returned must contain at least a <code>Locale</code>
 1030        * instance equal to {@link java.util.Locale#US Locale.US}.
 1031        *
 1032        * @return An array of locales for which localized
 1033        *         <code>Calendar</code> instances are available.
 1034        */
 1035       public static synchronized Locale[] getAvailableLocales()
 1036       {
 1037           return DateFormat.getAvailableLocales();
 1038       }
 1039   
 1040       /**
 1041        * Converts the current calendar field values in {@link #fields fields[]}
 1042        * to the millisecond time value
 1043        * {@link #time}.
 1044        *
 1045        * @see #complete()
 1046        * @see #computeFields()
 1047        */
 1048       protected abstract void computeTime();
 1049   
 1050       /**
 1051        * Converts the current millisecond time value {@link #time}
 1052        * to calendar field values in {@link #fields fields[]}.
 1053        * This allows you to sync up the calendar field values with
 1054        * a new time that is set for the calendar.  The time is <em>not</em>
 1055        * recomputed first; to recompute the time, then the fields, call the
 1056        * {@link #complete()} method.
 1057        *
 1058        * @see #computeTime()
 1059        */
 1060       protected abstract void computeFields();
 1061   
 1062       /**
 1063        * Returns a <code>Date</code> object representing this
 1064        * <code>Calendar</code>'s time value (millisecond offset from the <a
 1065        * href="#Epoch">Epoch</a>").
 1066        *
 1067        * @return a <code>Date</code> representing the time value.
 1068        * @see #setTime(Date)
 1069        * @see #getTimeInMillis()
 1070        */
 1071       public final Date getTime() {
 1072           return new Date(getTimeInMillis());
 1073       }
 1074   
 1075       /**
 1076        * Sets this Calendar's time with the given <code>Date</code>.
 1077        * <p>
 1078        * Note: Calling <code>setTime()</code> with
 1079        * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
 1080        * may yield incorrect field values from <code>get()</code>.
 1081        *
 1082        * @param date the given Date.
 1083        * @see #getTime()
 1084        * @see #setTimeInMillis(long)
 1085        */
 1086       public final void setTime(Date date) {
 1087           setTimeInMillis(date.getTime());
 1088       }
 1089   
 1090       /**
 1091        * Returns this Calendar's time value in milliseconds.
 1092        *
 1093        * @return the current time as UTC milliseconds from the epoch.
 1094        * @see #getTime()
 1095        * @see #setTimeInMillis(long)
 1096        */
 1097       public long getTimeInMillis() {
 1098           if (!isTimeSet) {
 1099               updateTime();
 1100           }
 1101           return time;
 1102       }
 1103   
 1104       /**
 1105        * Sets this Calendar's current time from the given long value.
 1106        *
 1107        * @param millis the new time in UTC milliseconds from the epoch.
 1108        * @see #setTime(Date)
 1109        * @see #getTimeInMillis()
 1110        */
 1111       public void setTimeInMillis(long millis) {
 1112           // If we don't need to recalculate the calendar field values,
 1113           // do nothing.
 1114           if (time == millis && isTimeSet && areFieldsSet && areAllFieldsSet
 1115               && (zone instanceof ZoneInfo) && !((ZoneInfo)zone).isDirty()) {
 1116               return;
 1117           }
 1118           time = millis;
 1119           isTimeSet = true;
 1120           areFieldsSet = false;
 1121           computeFields();
 1122           areAllFieldsSet = areFieldsSet = true;
 1123       }
 1124   
 1125       /**
 1126        * Returns the value of the given calendar field. In lenient mode,
 1127        * all calendar fields are normalized. In non-lenient mode, all
 1128        * calendar fields are validated and this method throws an
 1129        * exception if any calendar fields have out-of-range values. The
 1130        * normalization and validation are handled by the
 1131        * {@link #complete()} method, which process is calendar
 1132        * system dependent.
 1133        *
 1134        * @param field the given calendar field.
 1135        * @return the value for the given calendar field.
 1136        * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
 1137        *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1138        * @see #set(int,int)
 1139        * @see #complete()
 1140        */
 1141       public int get(int field)
 1142       {
 1143           complete();
 1144           return internalGet(field);
 1145       }
 1146   
 1147       /**
 1148        * Returns the value of the given calendar field. This method does
 1149        * not involve normalization or validation of the field value.
 1150        *
 1151        * @param field the given calendar field.
 1152        * @return the value for the given calendar field.
 1153        * @see #get(int)
 1154        */
 1155       protected final int internalGet(int field)
 1156       {
 1157           return fields[field];
 1158       }
 1159   
 1160       /**
 1161        * Sets the value of the given calendar field. This method does
 1162        * not affect any setting state of the field in this
 1163        * <code>Calendar</code> instance.
 1164        *
 1165        * @throws IndexOutOfBoundsException if the specified field is out of range
 1166        *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1167        * @see #areFieldsSet
 1168        * @see #isTimeSet
 1169        * @see #areAllFieldsSet
 1170        * @see #set(int,int)
 1171        */
 1172       final void internalSet(int field, int value)
 1173       {
 1174           fields[field] = value;
 1175       }
 1176   
 1177       /**
 1178        * Sets the given calendar field to the given value. The value is not
 1179        * interpreted by this method regardless of the leniency mode.
 1180        *
 1181        * @param field the given calendar field.
 1182        * @param value the value to be set for the given calendar field.
 1183        * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
 1184        *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1185        * in non-lenient mode.
 1186        * @see #set(int,int,int)
 1187        * @see #set(int,int,int,int,int)
 1188        * @see #set(int,int,int,int,int,int)
 1189        * @see #get(int)
 1190        */
 1191       public void set(int field, int value)
 1192       {
 1193           if (isLenient() && areFieldsSet && !areAllFieldsSet) {
 1194               computeFields();
 1195           }
 1196           internalSet(field, value);
 1197           isTimeSet = false;
 1198           areFieldsSet = false;
 1199           isSet[field] = true;
 1200           stamp[field] = nextStamp++;
 1201           if (nextStamp == Integer.MAX_VALUE) {
 1202               adjustStamp();
 1203           }
 1204       }
 1205   
 1206       /**
 1207        * Sets the values for the calendar fields <code>YEAR</code>,
 1208        * <code>MONTH</code>, and <code>DAY_OF_MONTH</code>.
 1209        * Previous values of other calendar fields are retained.  If this is not desired,
 1210        * call {@link #clear()} first.
 1211        *
 1212        * @param year the value used to set the <code>YEAR</code> calendar field.
 1213        * @param month the value used to set the <code>MONTH</code> calendar field.
 1214        * Month value is 0-based. e.g., 0 for January.
 1215        * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
 1216        * @see #set(int,int)
 1217        * @see #set(int,int,int,int,int)
 1218        * @see #set(int,int,int,int,int,int)
 1219        */
 1220       public final void set(int year, int month, int date)
 1221       {
 1222           set(YEAR, year);
 1223           set(MONTH, month);
 1224           set(DATE, date);
 1225       }
 1226   
 1227       /**
 1228        * Sets the values for the calendar fields <code>YEAR</code>,
 1229        * <code>MONTH</code>, <code>DAY_OF_MONTH</code>,
 1230        * <code>HOUR_OF_DAY</code>, and <code>MINUTE</code>.
 1231        * Previous values of other fields are retained.  If this is not desired,
 1232        * call {@link #clear()} first.
 1233        *
 1234        * @param year the value used to set the <code>YEAR</code> calendar field.
 1235        * @param month the value used to set the <code>MONTH</code> calendar field.
 1236        * Month value is 0-based. e.g., 0 for January.
 1237        * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
 1238        * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
 1239        * @param minute the value used to set the <code>MINUTE</code> calendar field.
 1240        * @see #set(int,int)
 1241        * @see #set(int,int,int)
 1242        * @see #set(int,int,int,int,int,int)
 1243        */
 1244       public final void set(int year, int month, int date, int hourOfDay, int minute)
 1245       {
 1246           set(YEAR, year);
 1247           set(MONTH, month);
 1248           set(DATE, date);
 1249           set(HOUR_OF_DAY, hourOfDay);
 1250           set(MINUTE, minute);
 1251       }
 1252   
 1253       /**
 1254        * Sets the values for the fields <code>YEAR</code>, <code>MONTH</code>,
 1255        * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, <code>MINUTE</code>, and
 1256        * <code>SECOND</code>.
 1257        * Previous values of other fields are retained.  If this is not desired,
 1258        * call {@link #clear()} first.
 1259        *
 1260        * @param year the value used to set the <code>YEAR</code> calendar field.
 1261        * @param month the value used to set the <code>MONTH</code> calendar field.
 1262        * Month value is 0-based. e.g., 0 for January.
 1263        * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
 1264        * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
 1265        * @param minute the value used to set the <code>MINUTE</code> calendar field.
 1266        * @param second the value used to set the <code>SECOND</code> calendar field.
 1267        * @see #set(int,int)
 1268        * @see #set(int,int,int)
 1269        * @see #set(int,int,int,int,int)
 1270        */
 1271       public final void set(int year, int month, int date, int hourOfDay, int minute,
 1272                             int second)
 1273       {
 1274           set(YEAR, year);
 1275           set(MONTH, month);
 1276           set(DATE, date);
 1277           set(HOUR_OF_DAY, hourOfDay);
 1278           set(MINUTE, minute);
 1279           set(SECOND, second);
 1280       }
 1281   
 1282       /**
 1283        * Sets all the calendar field values and the time value
 1284        * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
 1285        * this <code>Calendar</code> undefined. This means that {@link
 1286        * #isSet(int) isSet()} will return <code>false</code> for all the
 1287        * calendar fields, and the date and time calculations will treat
 1288        * the fields as if they had never been set. A
 1289        * <code>Calendar</code> implementation class may use its specific
 1290        * default field values for date/time calculations. For example,
 1291        * <code>GregorianCalendar</code> uses 1970 if the
 1292        * <code>YEAR</code> field value is undefined.
 1293        *
 1294        * @see #clear(int)
 1295        */
 1296       public final void clear()
 1297       {
 1298           for (int i = 0; i < fields.length; ) {
 1299               stamp[i] = fields[i] = 0; // UNSET == 0
 1300               isSet[i++] = false;
 1301           }
 1302           areAllFieldsSet = areFieldsSet = false;
 1303           isTimeSet = false;
 1304       }
 1305   
 1306       /**
 1307        * Sets the given calendar field value and the time value
 1308        * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
 1309        * this <code>Calendar</code> undefined. This means that {@link
 1310        * #isSet(int) isSet(field)} will return <code>false</code>, and
 1311        * the date and time calculations will treat the field as if it
 1312        * had never been set. A <code>Calendar</code> implementation
 1313        * class may use the field's specific default value for date and
 1314        * time calculations.
 1315        *
 1316        * <p>The {@link #HOUR_OF_DAY}, {@link #HOUR} and {@link #AM_PM}
 1317        * fields are handled independently and the <a
 1318        * href="#time_resolution">the resolution rule for the time of
 1319        * day</a> is applied. Clearing one of the fields doesn't reset
 1320        * the hour of day value of this <code>Calendar</code>. Use {@link
 1321        * #set(int,int) set(Calendar.HOUR_OF_DAY, 0)} to reset the hour
 1322        * value.
 1323        *
 1324        * @param field the calendar field to be cleared.
 1325        * @see #clear()
 1326        */
 1327       public final void clear(int field)
 1328       {
 1329           fields[field] = 0;
 1330           stamp[field] = UNSET;
 1331           isSet[field] = false;
 1332   
 1333           areAllFieldsSet = areFieldsSet = false;
 1334           isTimeSet = false;
 1335       }
 1336   
 1337       /**
 1338        * Determines if the given calendar field has a value set,
 1339        * including cases that the value has been set by internal fields
 1340        * calculations triggered by a <code>get</code> method call.
 1341        *
 1342        * @return <code>true</code> if the given calendar field has a value set;
 1343        * <code>false</code> otherwise.
 1344        */
 1345       public final boolean isSet(int field)
 1346       {
 1347           return stamp[field] != UNSET;
 1348       }
 1349   
 1350       /**
 1351        * Returns the string representation of the calendar
 1352        * <code>field</code> value in the given <code>style</code> and
 1353        * <code>locale</code>.  If no string representation is
 1354        * applicable, <code>null</code> is returned. This method calls
 1355        * {@link Calendar#get(int) get(field)} to get the calendar
 1356        * <code>field</code> value if the string representation is
 1357        * applicable to the given calendar <code>field</code>.
 1358        *
 1359        * <p>For example, if this <code>Calendar</code> is a
 1360        * <code>GregorianCalendar</code> and its date is 2005-01-01, then
 1361        * the string representation of the {@link #MONTH} field would be
 1362        * "January" in the long style in an English locale or "Jan" in
 1363        * the short style. However, no string representation would be
 1364        * available for the {@link #DAY_OF_MONTH} field, and this method
 1365        * would return <code>null</code>.
 1366        *
 1367        * <p>The default implementation supports the calendar fields for
 1368        * which a {@link DateFormatSymbols} has names in the given
 1369        * <code>locale</code>.
 1370        *
 1371        * @param field
 1372        *        the calendar field for which the string representation
 1373        *        is returned
 1374        * @param style
 1375        *        the style applied to the string representation; one of
 1376        *        {@link #SHORT} or {@link #LONG}.
 1377        * @param locale
 1378        *        the locale for the string representation
 1379        * @return the string representation of the given
 1380        *        <code>field</code> in the given <code>style</code>, or
 1381        *        <code>null</code> if no string representation is
 1382        *        applicable.
 1383        * @exception IllegalArgumentException
 1384        *        if <code>field</code> or <code>style</code> is invalid,
 1385        *        or if this <code>Calendar</code> is non-lenient and any
 1386        *        of the calendar fields have invalid values
 1387        * @exception NullPointerException
 1388        *        if <code>locale</code> is null
 1389        * @since 1.6
 1390        */
 1391       public String getDisplayName(int field, int style, Locale locale) {
 1392           if (!checkDisplayNameParams(field, style, ALL_STYLES, LONG, locale,
 1393                                       ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
 1394               return null;
 1395           }
 1396   
 1397           DateFormatSymbols symbols = DateFormatSymbols.getInstance(locale);
 1398           String[] strings = getFieldStrings(field, style, symbols);
 1399           if (strings != null) {
 1400               int fieldValue = get(field);
 1401               if (fieldValue < strings.length) {
 1402                   return strings[fieldValue];
 1403               }
 1404           }
 1405           return null;
 1406       }
 1407   
 1408       /**
 1409        * Returns a <code>Map</code> containing all names of the calendar
 1410        * <code>field</code> in the given <code>style</code> and
 1411        * <code>locale</code> and their corresponding field values. For
 1412        * example, if this <code>Calendar</code> is a {@link
 1413        * GregorianCalendar}, the returned map would contain "Jan" to
 1414        * {@link #JANUARY}, "Feb" to {@link #FEBRUARY}, and so on, in the
 1415        * {@linkplain #SHORT short} style in an English locale.
 1416        *
 1417        * <p>The values of other calendar fields may be taken into
 1418        * account to determine a set of display names. For example, if
 1419        * this <code>Calendar</code> is a lunisolar calendar system and
 1420        * the year value given by the {@link #YEAR} field has a leap
 1421        * month, this method would return month names containing the leap
 1422        * month name, and month names are mapped to their values specific
 1423        * for the year.
 1424        *
 1425        * <p>The default implementation supports display names contained in
 1426        * a {@link DateFormatSymbols}. For example, if <code>field</code>
 1427        * is {@link #MONTH} and <code>style</code> is {@link
 1428        * #ALL_STYLES}, this method returns a <code>Map</code> containing
 1429        * all strings returned by {@link DateFormatSymbols#getShortMonths()}
 1430        * and {@link DateFormatSymbols#getMonths()}.
 1431        *
 1432        * @param field
 1433        *        the calendar field for which the display names are returned
 1434        * @param style
 1435        *        the style applied to the display names; one of {@link
 1436        *        #SHORT}, {@link #LONG}, or {@link #ALL_STYLES}.
 1437        * @param locale
 1438        *        the locale for the display names
 1439        * @return a <code>Map</code> containing all display names in
 1440        *        <code>style</code> and <code>locale</code> and their
 1441        *        field values, or <code>null</code> if no display names
 1442        *        are defined for <code>field</code>
 1443        * @exception IllegalArgumentException
 1444        *        if <code>field</code> or <code>style</code> is invalid,
 1445        *        or if this <code>Calendar</code> is non-lenient and any
 1446        *        of the calendar fields have invalid values
 1447        * @exception NullPointerException
 1448        *        if <code>locale</code> is null
 1449        * @since 1.6
 1450        */
 1451       public Map<String, Integer> getDisplayNames(int field, int style, Locale locale) {
 1452           if (!checkDisplayNameParams(field, style, ALL_STYLES, LONG, locale,
 1453                                       ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
 1454               return null;
 1455           }
 1456   
 1457           // ALL_STYLES
 1458           if (style == ALL_STYLES) {
 1459               Map<String,Integer> shortNames = getDisplayNamesImpl(field, SHORT, locale);
 1460               if (field == ERA || field == AM_PM) {
 1461                   return shortNames;
 1462               }
 1463               Map<String,Integer> longNames = getDisplayNamesImpl(field, LONG, locale);
 1464               if (shortNames == null) {
 1465                   return longNames;
 1466               }
 1467               if (longNames != null) {
 1468                   shortNames.putAll(longNames);
 1469               }
 1470               return shortNames;
 1471           }
 1472   
 1473           // SHORT or LONG
 1474           return getDisplayNamesImpl(field, style, locale);
 1475       }
 1476   
 1477       private Map<String,Integer> getDisplayNamesImpl(int field, int style, Locale locale) {
 1478           DateFormatSymbols symbols = DateFormatSymbols.getInstance(locale);
 1479           String[] strings = getFieldStrings(field, style, symbols);
 1480           if (strings != null) {
 1481               Map<String,Integer> names = new HashMap<String,Integer>();
 1482               for (int i = 0; i < strings.length; i++) {
 1483                   if (strings[i].length() == 0) {
 1484                       continue;
 1485                   }
 1486                   names.put(strings[i], i);
 1487               }
 1488               return names;
 1489           }
 1490           return null;
 1491       }
 1492   
 1493       boolean checkDisplayNameParams(int field, int style, int minStyle, int maxStyle,
 1494                                      Locale locale, int fieldMask) {
 1495           if (field < 0 || field >= fields.length ||
 1496               style < minStyle || style > maxStyle) {
 1497               throw new IllegalArgumentException();
 1498           }
 1499           if (locale == null) {
 1500               throw new NullPointerException();
 1501           }
 1502           return isFieldSet(fieldMask, field);
 1503       }
 1504   
 1505       private String[] getFieldStrings(int field, int style, DateFormatSymbols symbols) {
 1506           String[] strings = null;
 1507           switch (field) {
 1508           case ERA:
 1509               strings = symbols.getEras();
 1510               break;
 1511   
 1512           case MONTH:
 1513               strings = (style == LONG) ? symbols.getMonths() : symbols.getShortMonths();
 1514               break;
 1515   
 1516           case DAY_OF_WEEK:
 1517               strings = (style == LONG) ? symbols.getWeekdays() : symbols.getShortWeekdays();
 1518               break;
 1519   
 1520           case AM_PM:
 1521               strings = symbols.getAmPmStrings();
 1522               break;
 1523           }
 1524           return strings;
 1525       }
 1526   
 1527       /**
 1528        * Fills in any unset fields in the calendar fields. First, the {@link
 1529        * #computeTime()} method is called if the time value (millisecond offset
 1530        * from the <a href="#Epoch">Epoch</a>) has not been calculated from
 1531        * calendar field values. Then, the {@link #computeFields()} method is
 1532        * called to calculate all calendar field values.
 1533        */
 1534       protected void complete()
 1535       {
 1536           if (!isTimeSet)
 1537               updateTime();
 1538           if (!areFieldsSet || !areAllFieldsSet) {
 1539               computeFields(); // fills in unset fields
 1540               areAllFieldsSet = areFieldsSet = true;
 1541           }
 1542       }
 1543   
 1544       /**
 1545        * Returns whether the value of the specified calendar field has been set
 1546        * externally by calling one of the setter methods rather than by the
 1547        * internal time calculation.
 1548        *
 1549        * @return <code>true</code> if the field has been set externally,
 1550        * <code>false</code> otherwise.
 1551        * @exception IndexOutOfBoundsException if the specified
 1552        *                <code>field</code> is out of range
 1553        *               (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1554        * @see #selectFields()
 1555        * @see #setFieldsComputed(int)
 1556        */
 1557       final boolean isExternallySet(int field) {
 1558           return stamp[field] >= MINIMUM_USER_STAMP;
 1559       }
 1560   
 1561       /**
 1562        * Returns a field mask (bit mask) indicating all calendar fields that
 1563        * have the state of externally or internally set.
 1564        *
 1565        * @return a bit mask indicating set state fields
 1566        */
 1567       final int getSetStateFields() {
 1568           int mask = 0;
 1569           for (int i = 0; i < fields.length; i++) {
 1570               if (stamp[i] != UNSET) {
 1571                   mask |= 1 << i;
 1572               }
 1573           }
 1574           return mask;
 1575       }
 1576   
 1577       /**
 1578        * Sets the state of the specified calendar fields to
 1579        * <em>computed</em>. This state means that the specified calendar fields
 1580        * have valid values that have been set by internal time calculation
 1581        * rather than by calling one of the setter methods.
 1582        *
 1583        * @param fieldMask the field to be marked as computed.
 1584        * @exception IndexOutOfBoundsException if the specified
 1585        *                <code>field</code> is out of range
 1586        *               (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1587        * @see #isExternallySet(int)
 1588        * @see #selectFields()
 1589        */
 1590       final void setFieldsComputed(int fieldMask) {
 1591           if (fieldMask == ALL_FIELDS) {
 1592               for (int i = 0; i < fields.length; i++) {
 1593                   stamp[i] = COMPUTED;
 1594                   isSet[i] = true;
 1595               }
 1596               areFieldsSet = areAllFieldsSet = true;
 1597           } else {
 1598               for (int i = 0; i < fields.length; i++) {
 1599                   if ((fieldMask & 1) == 1) {
 1600                       stamp[i] = COMPUTED;
 1601                       isSet[i] = true;
 1602                   } else {
 1603                       if (areAllFieldsSet && !isSet[i]) {
 1604                           areAllFieldsSet = false;
 1605                       }
 1606                   }
 1607                   fieldMask >>>= 1;
 1608               }
 1609           }
 1610       }
 1611   
 1612       /**
 1613        * Sets the state of the calendar fields that are <em>not</em> specified
 1614        * by <code>fieldMask</code> to <em>unset</em>. If <code>fieldMask</code>
 1615        * specifies all the calendar fields, then the state of this
 1616        * <code>Calendar</code> becomes that all the calendar fields are in sync
 1617        * with the time value (millisecond offset from the Epoch).
 1618        *
 1619        * @param fieldMask the field mask indicating which calendar fields are in
 1620        * sync with the time value.
 1621        * @exception IndexOutOfBoundsException if the specified
 1622        *                <code>field</code> is out of range
 1623        *               (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
 1624        * @see #isExternallySet(int)
 1625        * @see #selectFields()
 1626        */
 1627       final void setFieldsNormalized(int fieldMask) {
 1628           if (fieldMask != ALL_FIELDS) {
 1629               for (int i = 0; i < fields.length; i++) {
 1630                   if ((fieldMask & 1) == 0) {
 1631                       stamp[i] = fields[i] = 0; // UNSET == 0
 1632                       isSet[i] = false;
 1633                   }
 1634                   fieldMask >>= 1;
 1635               }
 1636           }
 1637   
 1638           // Some or all of the fields are in sync with the
 1639           // milliseconds, but the stamp values are not normalized yet.
 1640           areFieldsSet = true;
 1641           areAllFieldsSet = false;
 1642       }
 1643   
 1644       /**
 1645        * Returns whether the calendar fields are partially in sync with the time
 1646        * value or fully in sync but not stamp values are not normalized yet.
 1647        */
 1648       final boolean isPartiallyNormalized() {
 1649           return areFieldsSet && !areAllFieldsSet;
 1650       }
 1651   
 1652       /**
 1653        * Returns whether the calendar fields are fully in sync with the time
 1654        * value.
 1655        */
 1656       final boolean isFullyNormalized() {
 1657           return areFieldsSet && areAllFieldsSet;
 1658       }
 1659   
 1660       /**
 1661        * Marks this Calendar as not sync'd.
 1662        */
 1663       final void setUnnormalized() {
 1664           areFieldsSet = areAllFieldsSet = false;
 1665       }
 1666   
 1667       /**
 1668        * Returns whether the specified <code>field</code> is on in the
 1669        * <code>fieldMask</code>.
 1670        */
 1671       static final boolean isFieldSet(int fieldMask, int field) {
 1672           return (fieldMask & (1 << field)) != 0;
 1673       }
 1674   
 1675       /**
 1676        * Returns a field mask indicating which calendar field values
 1677        * to be used to calculate the time value. The calendar fields are
 1678        * returned as a bit mask, each bit of which corresponds to a field, i.e.,
 1679        * the mask value of <code>field</code> is <code>(1 &lt;&lt;
 1680        * field)</code>. For example, 0x26 represents the <code>YEAR</code>,
 1681        * <code>MONTH</code>, and <code>DAY_OF_MONTH</code> fields (i.e., 0x26 is
 1682        * equal to
 1683        * <code>(1&lt;&lt;YEAR)|(1&lt;&lt;MONTH)|(1&lt;&lt;DAY_OF_MONTH))</code>.
 1684        *
 1685        * <p>This method supports the calendar fields resolution as described in
 1686        * the class description. If the bit mask for a given field is on and its
 1687        * field has not been set (i.e., <code>isSet(field)</code> is
 1688        * <code>false</code>), then the default value of the field has to be
 1689        * used, which case means that the field has been selected because the
 1690        * selected combination involves the field.
 1691        *
 1692        * @return a bit mask of selected fields
 1693        * @see #isExternallySet(int)
 1694        * @see #setInternallySetState(int)
 1695        */
 1696       final int selectFields() {
 1697           // This implementation has been taken from the GregorianCalendar class.
 1698   
 1699           // The YEAR field must always be used regardless of its SET
 1700           // state because YEAR is a mandatory field to determine the date
 1701           // and the default value (EPOCH_YEAR) may change through the
 1702           // normalization process.
 1703           int fieldMask = YEAR_MASK;
 1704   
 1705           if (stamp[ERA] != UNSET) {
 1706               fieldMask |= ERA_MASK;
 1707           }
 1708           // Find the most recent group of fields specifying the day within
 1709           // the year.  These may be any of the following combinations:
 1710           //   MONTH + DAY_OF_MONTH
 1711           //   MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 1712           //   MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 1713           //   DAY_OF_YEAR
 1714           //   WEEK_OF_YEAR + DAY_OF_WEEK
 1715           // We look for the most recent of the fields in each group to determine
 1716           // the age of the group.  For groups involving a week-related field such
 1717           // as WEEK_OF_MONTH, DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR, both the
 1718           // week-related field and the DAY_OF_WEEK must be set for the group as a
 1719           // whole to be considered.  (See bug 4153860 - liu 7/24/98.)
 1720           int dowStamp = stamp[DAY_OF_WEEK];
 1721           int monthStamp = stamp[MONTH];
 1722           int domStamp = stamp[DAY_OF_MONTH];
 1723           int womStamp = aggregateStamp(stamp[WEEK_OF_MONTH], dowStamp);
 1724           int dowimStamp = aggregateStamp(stamp[DAY_OF_WEEK_IN_MONTH], dowStamp);
 1725           int doyStamp = stamp[DAY_OF_YEAR];
 1726           int woyStamp = aggregateStamp(stamp[WEEK_OF_YEAR], dowStamp);
 1727   
 1728           int bestStamp = domStamp;
 1729           if (womStamp > bestStamp) {
 1730               bestStamp = womStamp;
 1731           }
 1732           if (dowimStamp > bestStamp) {
 1733               bestStamp = dowimStamp;
 1734           }
 1735           if (doyStamp > bestStamp) {
 1736               bestStamp = doyStamp;
 1737           }
 1738           if (woyStamp > bestStamp) {
 1739               bestStamp = woyStamp;
 1740           }
 1741   
 1742           /* No complete combination exists.  Look for WEEK_OF_MONTH,
 1743            * DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR alone.  Treat DAY_OF_WEEK alone
 1744            * as DAY_OF_WEEK_IN_MONTH.
 1745            */
 1746           if (bestStamp == UNSET) {
 1747               womStamp = stamp[WEEK_OF_MONTH];
 1748               dowimStamp = Math.max(stamp[DAY_OF_WEEK_IN_MONTH], dowStamp);
 1749               woyStamp = stamp[WEEK_OF_YEAR];
 1750               bestStamp = Math.max(Math.max(womStamp, dowimStamp), woyStamp);
 1751   
 1752               /* Treat MONTH alone or no fields at all as DAY_OF_MONTH.  This may
 1753                * result in bestStamp = domStamp = UNSET if no fields are set,
 1754                * which indicates DAY_OF_MONTH.
 1755                */
 1756               if (bestStamp == UNSET) {
 1757                   bestStamp = domStamp = monthStamp;
 1758               }
 1759           }
 1760   
 1761           if (bestStamp == domStamp ||
 1762              (bestStamp == womStamp && stamp[WEEK_OF_MONTH] >= stamp[WEEK_OF_YEAR]) ||
 1763              (bestStamp == dowimStamp && stamp[DAY_OF_WEEK_IN_MONTH] >= stamp[WEEK_OF_YEAR])) {
 1764               fieldMask |= MONTH_MASK;
 1765               if (bestStamp == domStamp) {
 1766                   fieldMask |= DAY_OF_MONTH_MASK;
 1767               } else {
 1768                   assert (bestStamp == womStamp || bestStamp == dowimStamp);
 1769                   if (dowStamp != UNSET) {
 1770                       fieldMask |= DAY_OF_WEEK_MASK;
 1771                   }
 1772                   if (womStamp == dowimStamp) {
 1773                       // When they are equal, give the priority to
 1774                       // WEEK_OF_MONTH for compatibility.
 1775                       if (stamp[WEEK_OF_MONTH] >= stamp[DAY_OF_WEEK_IN_MONTH]) {
 1776                           fieldMask |= WEEK_OF_MONTH_MASK;
 1777                       } else {
 1778                           fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
 1779                       }
 1780                   } else {
 1781                       if (bestStamp == womStamp) {
 1782                           fieldMask |= WEEK_OF_MONTH_MASK;
 1783                       } else {
 1784                           assert (bestStamp == dowimStamp);
 1785                           if (stamp[DAY_OF_WEEK_IN_MONTH] != UNSET) {
 1786                               fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
 1787                           }
 1788                       }
 1789                   }
 1790               }
 1791           } else {
 1792               assert (bestStamp == doyStamp || bestStamp == woyStamp ||
 1793                       bestStamp == UNSET);
 1794               if (bestStamp == doyStamp) {
 1795                   fieldMask |= DAY_OF_YEAR_MASK;
 1796               } else {
 1797                   assert (bestStamp == woyStamp);
 1798                   if (dowStamp != UNSET) {
 1799                       fieldMask |= DAY_OF_WEEK_MASK;
 1800                   }
 1801                   fieldMask |= WEEK_OF_YEAR_MASK;
 1802               }
 1803           }
 1804   
 1805           // Find the best set of fields specifying the time of day.  There
 1806           // are only two possibilities here; the HOUR_OF_DAY or the
 1807           // AM_PM and the HOUR.
 1808           int hourOfDayStamp = stamp[HOUR_OF_DAY];
 1809           int hourStamp = aggregateStamp(stamp[HOUR], stamp[AM_PM]);
 1810           bestStamp = (hourStamp > hourOfDayStamp) ? hourStamp : hourOfDayStamp;
 1811   
 1812           // if bestStamp is still UNSET, then take HOUR or AM_PM. (See 4846659)
 1813           if (bestStamp == UNSET) {
 1814               bestStamp = Math.max(stamp[HOUR], stamp[AM_PM]);
 1815           }
 1816   
 1817           // Hours
 1818           if (bestStamp != UNSET) {
 1819               if (bestStamp == hourOfDayStamp) {
 1820                   fieldMask |= HOUR_OF_DAY_MASK;
 1821               } else {
 1822                   fieldMask |= HOUR_MASK;
 1823                   if (stamp[AM_PM] != UNSET) {
 1824                       fieldMask |= AM_PM_MASK;
 1825                   }
 1826               }
 1827           }
 1828           if (stamp[MINUTE] != UNSET) {
 1829               fieldMask |= MINUTE_MASK;
 1830           }
 1831           if (stamp[SECOND] != UNSET) {
 1832               fieldMask |= SECOND_MASK;
 1833           }
 1834           if (stamp[MILLISECOND] != UNSET) {
 1835               fieldMask |= MILLISECOND_MASK;
 1836           }
 1837           if (stamp[ZONE_OFFSET] >= MINIMUM_USER_STAMP) {
 1838                   fieldMask |= ZONE_OFFSET_MASK;
 1839           }
 1840           if (stamp[DST_OFFSET] >= MINIMUM_USER_STAMP) {
 1841               fieldMask |= DST_OFFSET_MASK;
 1842           }
 1843   
 1844           return fieldMask;
 1845       }
 1846   
 1847       /**
 1848        * Returns the pseudo-time-stamp for two fields, given their
 1849        * individual pseudo-time-stamps.  If either of the fields
 1850        * is unset, then the aggregate is unset.  Otherwise, the
 1851        * aggregate is the later of the two stamps.
 1852        */
 1853       private static final int aggregateStamp(int stamp_a, int stamp_b) {
 1854           if (stamp_a == UNSET || stamp_b == UNSET) {
 1855               return UNSET;
 1856           }
 1857           return (stamp_a > stamp_b) ? stamp_a : stamp_b;
 1858       }
 1859   
 1860       /**
 1861        * Compares this <code>Calendar</code> to the specified
 1862        * <code>Object</code>.  The result is <code>true</code> if and only if
 1863        * the argument is a <code>Calendar</code> object of the same calendar
 1864        * system that represents the same time value (millisecond offset from the
 1865        * <a href="#Epoch">Epoch</a>) under the same
 1866        * <code>Calendar</code> parameters as this object.
 1867        *
 1868        * <p>The <code>Calendar</code> parameters are the values represented
 1869        * by the <code>isLenient</code>, <code>getFirstDayOfWeek</code>,
 1870        * <code>getMinimalDaysInFirstWeek</code> and <code>getTimeZone</code>
 1871        * methods. If there is any difference in those parameters
 1872        * between the two <code>Calendar</code>s, this method returns
 1873        * <code>false</code>.
 1874        *
 1875        * <p>Use the {@link #compareTo(Calendar) compareTo} method to
 1876        * compare only the time values.
 1877        *
 1878        * @param obj the object to compare with.
 1879        * @return <code>true</code> if this object is equal to <code>obj</code>;
 1880        * <code>false</code> otherwise.
 1881        */
 1882       public boolean equals(Object obj) {
 1883           if (this == obj)
 1884               return true;
 1885           try {
 1886               Calendar that = (Calendar)obj;
 1887               return compareTo(getMillisOf(that)) == 0 &&
 1888                   lenient == that.lenient &&
 1889                   firstDayOfWeek == that.firstDayOfWeek &&
 1890                   minimalDaysInFirstWeek == that.minimalDaysInFirstWeek &&
 1891                   zone.equals(that.zone);
 1892           } catch (Exception e) {
 1893               // Note: GregorianCalendar.computeTime throws
 1894               // IllegalArgumentException if the ERA value is invalid
 1895               // even it's in lenient mode.
 1896           }
 1897           return false;
 1898       }
 1899   
 1900       /**
 1901        * Returns a hash code for this calendar.
 1902        *
 1903        * @return a hash code value for this object.
 1904        * @since 1.2
 1905        */
 1906       public int hashCode() {
 1907           // 'otheritems' represents the hash code for the previous versions.
 1908           int otheritems = (lenient ? 1 : 0)
 1909               | (firstDayOfWeek << 1)
 1910               | (minimalDaysInFirstWeek << 4)
 1911               | (zone.hashCode() << 7);
 1912           long t = getMillisOf(this);
 1913           return (int) t ^ (int)(t >> 32) ^ otheritems;
 1914       }
 1915   
 1916       /**
 1917        * Returns whether this <code>Calendar</code> represents a time
 1918        * before the time represented by the specified
 1919        * <code>Object</code>. This method is equivalent to:
 1920        * <pre><blockquote>
 1921        *         compareTo(when) < 0
 1922        * </blockquote></pre>
 1923        * if and only if <code>when</code> is a <code>Calendar</code>
 1924        * instance. Otherwise, the method returns <code>false</code>.
 1925        *
 1926        * @param when the <code>Object</code> to be compared
 1927        * @return <code>true</code> if the time of this
 1928        * <code>Calendar</code> is before the time represented by
 1929        * <code>when</code>; <code>false</code> otherwise.
 1930        * @see     #compareTo(Calendar)
 1931        */
 1932       public boolean before(Object when) {
 1933           return when instanceof Calendar
 1934               && compareTo((Calendar)when) < 0;
 1935       }
 1936   
 1937       /**
 1938        * Returns whether this <code>Calendar</code> represents a time
 1939        * after the time represented by the specified
 1940        * <code>Object</code>. This method is equivalent to:
 1941        * <pre><blockquote>
 1942        *         compareTo(when) > 0
 1943        * </blockquote></pre>
 1944        * if and only if <code>when</code> is a <code>Calendar</code>
 1945        * instance. Otherwise, the method returns <code>false</code>.
 1946        *
 1947        * @param when the <code>Object</code> to be compared
 1948        * @return <code>true</code> if the time of this <code>Calendar</code> is
 1949        * after the time represented by <code>when</code>; <code>false</code>
 1950        * otherwise.
 1951        * @see     #compareTo(Calendar)
 1952        */
 1953       public boolean after(Object when) {
 1954           return when instanceof Calendar
 1955               && compareTo((Calendar)when) > 0;
 1956       }
 1957   
 1958       /**
 1959        * Compares the time values (millisecond offsets from the <a
 1960        * href="#Epoch">Epoch</a>) represented by two
 1961        * <code>Calendar</code> objects.
 1962        *
 1963        * @param anotherCalendar the <code>Calendar</code> to be compared.
 1964        * @return the value <code>0</code> if the time represented by the argument
 1965        * is equal to the time represented by this <code>Calendar</code>; a value
 1966        * less than <code>0</code> if the time of this <code>Calendar</code> is
 1967        * before the time represented by the argument; and a value greater than
 1968        * <code>0</code> if the time of this <code>Calendar</code> is after the
 1969        * time represented by the argument.
 1970        * @exception NullPointerException if the specified <code>Calendar</code> is
 1971        *            <code>null</code>.
 1972        * @exception IllegalArgumentException if the time value of the
 1973        * specified <code>Calendar</code> object can't be obtained due to
 1974        * any invalid calendar values.
 1975        * @since   1.5
 1976        */
 1977       public int compareTo(Calendar anotherCalendar) {
 1978           return compareTo(getMillisOf(anotherCalendar));
 1979       }
 1980   
 1981       /**
 1982        * Adds or subtracts the specified amount of time to the given calendar field,
 1983        * based on the calendar's rules. For example, to subtract 5 days from
 1984        * the current time of the calendar, you can achieve it by calling:
 1985        * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
 1986        *
 1987        * @param field the calendar field.
 1988        * @param amount the amount of date or time to be added to the field.
 1989        * @see #roll(int,int)
 1990        * @see #set(int,int)
 1991        */
 1992       abstract public void add(int field, int amount);
 1993   
 1994       /**
 1995        * Adds or subtracts (up/down) a single unit of time on the given time
 1996        * field without changing larger fields. For example, to roll the current
 1997        * date up by one day, you can achieve it by calling:
 1998        * <p>roll(Calendar.DATE, true).
 1999        * When rolling on the year or Calendar.YEAR field, it will roll the year
 2000        * value in the range between 1 and the value returned by calling
 2001        * <code>getMaximum(Calendar.YEAR)</code>.
 2002        * When rolling on the month or Calendar.MONTH field, other fields like
 2003        * date might conflict and, need to be changed. For instance,
 2004        * rolling the month on the date 01/31/96 will result in 02/29/96.
 2005        * When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
 2006        * roll the hour value in the range between 0 and 23, which is zero-based.
 2007        *
 2008        * @param field the time field.
 2009        * @param up indicates if the value of the specified time field is to be
 2010        * rolled up or rolled down. Use true if rolling up, false otherwise.
 2011        * @see Calendar#add(int,int)
 2012        * @see Calendar#set(int,int)
 2013        */
 2014       abstract public void roll(int field, boolean up);
 2015   
 2016       /**
 2017        * Adds the specified (signed) amount to the specified calendar field
 2018        * without changing larger fields.  A negative amount means to roll
 2019        * down.
 2020        *
 2021        * <p>NOTE:  This default implementation on <code>Calendar</code> just repeatedly calls the
 2022        * version of {@link #roll(int,boolean) roll()} that rolls by one unit.  This may not
 2023        * always do the right thing.  For example, if the <code>DAY_OF_MONTH</code> field is 31,
 2024        * rolling through February will leave it set to 28.  The <code>GregorianCalendar</code>
 2025        * version of this function takes care of this problem.  Other subclasses
 2026        * should also provide overrides of this function that do the right thing.
 2027        *
 2028        * @param field the calendar field.
 2029        * @param amount the signed amount to add to the calendar <code>field</code>.
 2030        * @since 1.2
 2031        * @see #roll(int,boolean)
 2032        * @see #add(int,int)
 2033        * @see #set(int,int)
 2034        */
 2035       public void roll(int field, int amount)
 2036       {
 2037           while (amount > 0) {
 2038               roll(field, true);
 2039               amount--;
 2040           }
 2041           while (amount < 0) {
 2042               roll(field, false);
 2043               amount++;
 2044           }
 2045       }
 2046   
 2047       /**
 2048        * Sets the time zone with the given time zone value.
 2049        *
 2050        * @param value the given time zone.
 2051        */
 2052       public void setTimeZone(TimeZone value)
 2053       {
 2054           zone = value;
 2055           sharedZone = false;
 2056           /* Recompute the fields from the time using the new zone.  This also
 2057            * works if isTimeSet is false (after a call to set()).  In that case
 2058            * the time will be computed from the fields using the new zone, then
 2059            * the fields will get recomputed from that.  Consider the sequence of
 2060            * calls: cal.setTimeZone(EST); cal.set(HOUR, 1); cal.setTimeZone(PST).
 2061            * Is cal set to 1 o'clock EST or 1 o'clock PST?  Answer: PST.  More
 2062            * generally, a call to setTimeZone() affects calls to set() BEFORE AND
 2063            * AFTER it up to the next call to complete().
 2064            */
 2065           areAllFieldsSet = areFieldsSet = false;
 2066       }
 2067   
 2068       /**
 2069        * Gets the time zone.
 2070        *
 2071        * @return the time zone object associated with this calendar.
 2072        */
 2073       public TimeZone getTimeZone()
 2074       {
 2075           // If the TimeZone object is shared by other Calendar instances, then
 2076           // create a clone.
 2077           if (sharedZone) {
 2078               zone = (TimeZone) zone.clone();
 2079               sharedZone = false;
 2080           }
 2081           return zone;
 2082       }
 2083   
 2084       /**
 2085        * Returns the time zone (without cloning).
 2086        */
 2087       TimeZone getZone() {
 2088           return zone;
 2089       }
 2090   
 2091       /**
 2092        * Sets the sharedZone flag to <code>shared</code>.
 2093        */
 2094       void setZoneShared(boolean shared) {
 2095           sharedZone = shared;
 2096       }
 2097   
 2098       /**
 2099        * Specifies whether or not date/time interpretation is to be lenient.  With
 2100        * lenient interpretation, a date such as "February 942, 1996" will be
 2101        * treated as being equivalent to the 941st day after February 1, 1996.
 2102        * With strict (non-lenient) interpretation, such dates will cause an exception to be
 2103        * thrown. The default is lenient.
 2104        *
 2105        * @param lenient <code>true</code> if the lenient mode is to be turned
 2106        * on; <code>false</code> if it is to be turned off.
 2107        * @see #isLenient()
 2108        * @see java.text.DateFormat#setLenient
 2109        */
 2110       public void setLenient(boolean lenient)
 2111       {
 2112           this.lenient = lenient;
 2113       }
 2114   
 2115       /**
 2116        * Tells whether date/time interpretation is to be lenient.
 2117        *
 2118        * @return <code>true</code> if the interpretation mode of this calendar is lenient;
 2119        * <code>false</code> otherwise.
 2120        * @see #setLenient(boolean)
 2121        */
 2122       public boolean isLenient()
 2123       {
 2124           return lenient;
 2125       }
 2126   
 2127       /**
 2128        * Sets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
 2129        * <code>MONDAY</code> in France.
 2130        *
 2131        * @param value the given first day of the week.
 2132        * @see #getFirstDayOfWeek()
 2133        * @see #getMinimalDaysInFirstWeek()
 2134        */
 2135       public void setFirstDayOfWeek(int value)
 2136       {
 2137           if (firstDayOfWeek == value) {
 2138               return;
 2139           }
 2140           firstDayOfWeek = value;
 2141           invalidateWeekFields();
 2142       }
 2143   
 2144       /**
 2145        * Gets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
 2146        * <code>MONDAY</code> in France.
 2147        *
 2148        * @return the first day of the week.
 2149        * @see #setFirstDayOfWeek(int)
 2150        * @see #getMinimalDaysInFirstWeek()
 2151        */
 2152       public int getFirstDayOfWeek()
 2153       {
 2154           return firstDayOfWeek;
 2155       }
 2156   
 2157       /**
 2158        * Sets what the minimal days required in the first week of the year are;
 2159        * For example, if the first week is defined as one that contains the first
 2160        * day of the first month of a year, call this method with value 1. If it
 2161        * must be a full week, use value 7.
 2162        *
 2163        * @param value the given minimal days required in the first week
 2164        * of the year.
 2165        * @see #getMinimalDaysInFirstWeek()
 2166        */
 2167       public void setMinimalDaysInFirstWeek(int value)
 2168       {
 2169           if (minimalDaysInFirstWeek == value) {
 2170               return;
 2171           }
 2172           minimalDaysInFirstWeek = value;
 2173           invalidateWeekFields();
 2174       }
 2175   
 2176       /**
 2177        * Gets what the minimal days required in the first week of the year are;
 2178        * e.g., if the first week is defined as one that contains the first day
 2179        * of the first month of a year, this method returns 1. If
 2180        * the minimal days required must be a full week, this method
 2181        * returns 7.
 2182        *
 2183        * @return the minimal days required in the first week of the year.
 2184        * @see #setMinimalDaysInFirstWeek(int)
 2185        */
 2186       public int getMinimalDaysInFirstWeek()
 2187       {
 2188           return minimalDaysInFirstWeek;
 2189       }
 2190   
 2191       /**
 2192        * Returns the minimum value for the given calendar field of this
 2193        * <code>Calendar</code> instance. The minimum value is defined as
 2194        * the smallest value returned by the {@link #get(int) get} method
 2195        * for any possible time value.  The minimum value depends on
 2196        * calendar system specific parameters of the instance.
 2197        *
 2198        * @param field the calendar field.
 2199        * @return the minimum value for the given calendar field.
 2200        * @see #getMaximum(int)
 2201        * @see #getGreatestMinimum(int)
 2202        * @see #getLeastMaximum(int)
 2203        * @see #getActualMinimum(int)
 2204        * @see #getActualMaximum(int)
 2205        */
 2206       abstract public int getMinimum(int field);
 2207   
 2208       /**
 2209        * Returns the maximum value for the given calendar field of this
 2210        * <code>Calendar</code> instance. The maximum value is defined as
 2211        * the largest value returned by the {@link #get(int) get} method
 2212        * for any possible time value. The maximum value depends on
 2213        * calendar system specific parameters of the instance.
 2214        *
 2215        * @param field the calendar field.
 2216        * @return the maximum value for the given calendar field.
 2217        * @see #getMinimum(int)
 2218        * @see #getGreatestMinimum(int)
 2219        * @see #getLeastMaximum(int)
 2220        * @see #getActualMinimum(int)
 2221        * @see #getActualMaximum(int)
 2222        */
 2223       abstract public int getMaximum(int field);
 2224   
 2225       /**
 2226        * Returns the highest minimum value for the given calendar field
 2227        * of this <code>Calendar</code> instance. The highest minimum
 2228        * value is defined as the largest value returned by {@link
 2229        * #getActualMinimum(int)} for any possible time value. The
 2230        * greatest minimum value depends on calendar system specific
 2231        * parameters of the instance.
 2232        *
 2233        * @param field the calendar field.
 2234        * @return the highest minimum value for the given calendar field.
 2235        * @see #getMinimum(int)
 2236        * @see #getMaximum(int)
 2237        * @see #getLeastMaximum(int)
 2238        * @see #getActualMinimum(int)
 2239        * @see #getActualMaximum(int)
 2240        */
 2241       abstract public int getGreatestMinimum(int field);
 2242   
 2243       /**
 2244        * Returns the lowest maximum value for the given calendar field
 2245        * of this <code>Calendar</code> instance. The lowest maximum
 2246        * value is defined as the smallest value returned by {@link
 2247        * #getActualMaximum(int)} for any possible time value. The least
 2248        * maximum value depends on calendar system specific parameters of
 2249        * the instance. For example, a <code>Calendar</code> for the
 2250        * Gregorian calendar system returns 28 for the
 2251        * <code>DAY_OF_MONTH</code> field, because the 28th is the last
 2252        * day of the shortest month of this calendar, February in a
 2253        * common year.
 2254        *
 2255        * @param field the calendar field.
 2256        * @return the lowest maximum value for the given calendar field.
 2257        * @see #getMinimum(int)
 2258        * @see #getMaximum(int)
 2259        * @see #getGreatestMinimum(int)
 2260        * @see #getActualMinimum(int)
 2261        * @see #getActualMaximum(int)
 2262        */
 2263       abstract public int getLeastMaximum(int field);
 2264   
 2265       /**
 2266        * Returns the minimum value that the specified calendar field
 2267        * could have, given the time value of this <code>Calendar</code>.
 2268        *
 2269        * <p>The default implementation of this method uses an iterative
 2270        * algorithm to determine the actual minimum value for the
 2271        * calendar field. Subclasses should, if possible, override this
 2272        * with a more efficient implementation - in many cases, they can
 2273        * simply return <code>getMinimum()</code>.
 2274        *
 2275        * @param field the calendar field
 2276        * @return the minimum of the given calendar field for the time
 2277        * value of this <code>Calendar</code>
 2278        * @see #getMinimum(int)
 2279        * @see #getMaximum(int)
 2280        * @see #getGreatestMinimum(int)
 2281        * @see #getLeastMaximum(int)
 2282        * @see #getActualMaximum(int)
 2283        * @since 1.2
 2284        */
 2285       public int getActualMinimum(int field) {
 2286           int fieldValue = getGreatestMinimum(field);
 2287           int endValue = getMinimum(field);
 2288   
 2289           // if we know that the minimum value is always the same, just return it
 2290           if (fieldValue == endValue) {
 2291               return fieldValue;
 2292           }
 2293   
 2294           // clone the calendar so we don't mess with the real one, and set it to
 2295           // accept anything for the field values
 2296           Calendar work = (Calendar)this.clone();
 2297           work.setLenient(true);
 2298   
 2299           // now try each value from getLeastMaximum() to getMaximum() one by one until
 2300           // we get a value that normalizes to another value.  The last value that
 2301           // normalizes to itself is the actual minimum for the current date
 2302           int result = fieldValue;
 2303   
 2304           do {
 2305               work.set(field, fieldValue);
 2306               if (work.get(field) != fieldValue) {
 2307                   break;
 2308               } else {
 2309                   result = fieldValue;
 2310                   fieldValue--;
 2311               }
 2312           } while (fieldValue >= endValue);
 2313   
 2314           return result;
 2315       }
 2316   
 2317       /**
 2318        * Returns the maximum value that the specified calendar field
 2319        * could have, given the time value of this
 2320        * <code>Calendar</code>. For example, the actual maximum value of
 2321        * the <code>MONTH</code> field is 12 in some years, and 13 in
 2322        * other years in the Hebrew calendar system.
 2323        *
 2324        * <p>The default implementation of this method uses an iterative
 2325        * algorithm to determine the actual maximum value for the
 2326        * calendar field. Subclasses should, if possible, override this
 2327        * with a more efficient implementation.
 2328        *
 2329        * @param field the calendar field
 2330        * @return the maximum of the given calendar field for the time
 2331        * value of this <code>Calendar</code>
 2332        * @see #getMinimum(int)
 2333        * @see #getMaximum(int)
 2334        * @see #getGreatestMinimum(int)
 2335        * @see #getLeastMaximum(int)
 2336        * @see #getActualMinimum(int)
 2337        * @since 1.2
 2338        */
 2339       public int getActualMaximum(int field) {
 2340           int fieldValue = getLeastMaximum(field);
 2341           int endValue = getMaximum(field);
 2342   
 2343           // if we know that the maximum value is always the same, just return it.
 2344           if (fieldValue == endValue) {
 2345               return fieldValue;
 2346           }
 2347   
 2348           // clone the calendar so we don't mess with the real one, and set it to
 2349           // accept anything for the field values.
 2350           Calendar work = (Calendar)this.clone();
 2351           work.setLenient(true);
 2352   
 2353           // if we're counting weeks, set the day of the week to Sunday.  We know the
 2354           // last week of a month or year will contain the first day of the week.
 2355           if (field == WEEK_OF_YEAR || field == WEEK_OF_MONTH)
 2356               work.set(DAY_OF_WEEK, firstDayOfWeek);
 2357   
 2358           // now try each value from getLeastMaximum() to getMaximum() one by one until
 2359           // we get a value that normalizes to another value.  The last value that
 2360           // normalizes to itself is the actual maximum for the current date
 2361           int result = fieldValue;
 2362   
 2363           do {
 2364               work.set(field, fieldValue);
 2365               if (work.get(field) != fieldValue) {
 2366                   break;
 2367               } else {
 2368                   result = fieldValue;
 2369                   fieldValue++;
 2370               }
 2371           } while (fieldValue <= endValue);
 2372   
 2373           return result;
 2374       }
 2375   
 2376       /**
 2377        * Creates and returns a copy of this object.
 2378        *
 2379        * @return a copy of this object.
 2380        */
 2381       public Object clone()
 2382       {
 2383           try {
 2384               Calendar other = (Calendar) super.clone();
 2385   
 2386               other.fields = new int[FIELD_COUNT];
 2387               other.isSet = new boolean[FIELD_COUNT];
 2388               other.stamp = new int[FIELD_COUNT];
 2389               for (int i = 0; i < FIELD_COUNT; i++) {
 2390                   other.fields[i] = fields[i];
 2391                   other.stamp[i] = stamp[i];
 2392                   other.isSet[i] = isSet[i];
 2393               }
 2394               other.zone = (TimeZone) zone.clone();
 2395               return other;
 2396           }
 2397           catch (CloneNotSupportedException e) {
 2398               // this shouldn't happen, since we are Cloneable
 2399               throw new InternalError();
 2400           }
 2401       }
 2402   
 2403       private static final String[] FIELD_NAME = {
 2404           "ERA", "YEAR", "MONTH", "WEEK_OF_YEAR", "WEEK_OF_MONTH", "DAY_OF_MONTH",
 2405           "DAY_OF_YEAR", "DAY_OF_WEEK", "DAY_OF_WEEK_IN_MONTH", "AM_PM", "HOUR",
 2406           "HOUR_OF_DAY", "MINUTE", "SECOND", "MILLISECOND", "ZONE_OFFSET",
 2407           "DST_OFFSET"
 2408       };
 2409   
 2410       /**
 2411        * Returns the name of the specified calendar field.
 2412        *
 2413        * @param field the calendar field
 2414        * @return the calendar field name
 2415        * @exception IndexOutOfBoundsException if <code>field</code> is negative,
 2416        * equal to or greater then <code>FIELD_COUNT</code>.
 2417        */
 2418       static final String getFieldName(int field) {
 2419           return FIELD_NAME[field];
 2420       }
 2421   
 2422       /**
 2423        * Return a string representation of this calendar. This method
 2424        * is intended to be used only for debugging purposes, and the
 2425        * format of the returned string may vary between implementations.
 2426        * The returned string may be empty but may not be <code>null</code>.
 2427        *
 2428        * @return  a string representation of this calendar.
 2429        */
 2430       public String toString() {
 2431           // NOTE: BuddhistCalendar.toString() interprets the string
 2432           // produced by this method so that the Gregorian year number
 2433           // is substituted by its B.E. year value. It relies on
 2434           // "...,YEAR=<year>,..." or "...,YEAR=?,...".
 2435           StringBuilder buffer = new StringBuilder(800);
 2436           buffer.append(getClass().getName()).append('[');
 2437           appendValue(buffer, "time", isTimeSet, time);
 2438           buffer.append(",areFieldsSet=").append(areFieldsSet);
 2439           buffer.append(",areAllFieldsSet=").append(areAllFieldsSet);
 2440           buffer.append(",lenient=").append(lenient);
 2441           buffer.append(",zone=").append(zone);
 2442           appendValue(buffer, ",firstDayOfWeek", true, (long) firstDayOfWeek);
 2443           appendValue(buffer, ",minimalDaysInFirstWeek", true, (long) minimalDaysInFirstWeek);
 2444           for (int i = 0; i < FIELD_COUNT; ++i) {
 2445               buffer.append(',');
 2446               appendValue(buffer, FIELD_NAME[i], isSet(i), (long) fields[i]);
 2447           }
 2448           buffer.append(']');
 2449           return buffer.toString();
 2450       }
 2451   
 2452       // =======================privates===============================
 2453   
 2454       private static final void appendValue(StringBuilder sb, String item, boolean valid, long value) {
 2455           sb.append(item).append('=');
 2456           if (valid) {
 2457               sb.append(value);
 2458           } else {
 2459               sb.append('?');
 2460           }
 2461       }
 2462   
 2463       /**
 2464        * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent.
 2465        * They are used to figure out the week count for a specific date for
 2466        * a given locale. These must be set when a Calendar is constructed.
 2467        * @param desiredLocale the given locale.
 2468        */
 2469       private void setWeekCountData(Locale desiredLocale)
 2470       {
 2471           /* try to get the Locale data from the cache */
 2472           int[] data = cachedLocaleData.get(desiredLocale);
 2473           if (data == null) {  /* cache miss */
 2474               ResourceBundle bundle = LocaleData.getCalendarData(desiredLocale);
 2475               data = new int[2];
 2476               data[0] = Integer.parseInt(bundle.getString("firstDayOfWeek"));
 2477               data[1] = Integer.parseInt(bundle.getString("minimalDaysInFirstWeek"));
 2478               cachedLocaleData.put(desiredLocale, data);
 2479           }
 2480           firstDayOfWeek = data[0];
 2481           minimalDaysInFirstWeek = data[1];
 2482       }
 2483   
 2484       /**
 2485        * Recomputes the time and updates the status fields isTimeSet
 2486        * and areFieldsSet.  Callers should check isTimeSet and only
 2487        * call this method if isTimeSet is false.
 2488        */
 2489       private void updateTime() {
 2490           computeTime();
 2491           // The areFieldsSet and areAllFieldsSet values are no longer
 2492           // controlled here (as of 1.5).
 2493           isTimeSet = true;
 2494       }
 2495   
 2496       private int compareTo(long t) {
 2497           long thisTime = getMillisOf(this);
 2498           return (thisTime > t) ? 1 : (thisTime == t) ? 0 : -1;
 2499       }
 2500   
 2501       private static final long getMillisOf(Calendar calendar) {
 2502           if (calendar.isTimeSet) {
 2503               return calendar.time;
 2504           }
 2505           Calendar cal = (Calendar) calendar.clone();
 2506           cal.setLenient(true);
 2507           return cal.getTimeInMillis();
 2508       }
 2509   
 2510       /**
 2511        * Adjusts the stamp[] values before nextStamp overflow. nextStamp
 2512        * is set to the next stamp value upon the return.
 2513        */
 2514       private final void adjustStamp() {
 2515           int max = MINIMUM_USER_STAMP;
 2516           int newStamp = MINIMUM_USER_STAMP;
 2517   
 2518           for (;;) {
 2519               int min = Integer.MAX_VALUE;
 2520               for (int i = 0; i < stamp.length; i++) {
 2521                   int v = stamp[i];
 2522                   if (v >= newStamp && min > v) {
 2523                       min = v;
 2524                   }
 2525                   if (max < v) {
 2526                       max = v;
 2527                   }
 2528               }
 2529               if (max != min && min == Integer.MAX_VALUE) {
 2530                   break;
 2531               }
 2532               for (int i = 0; i < stamp.length; i++) {
 2533                   if (stamp[i] == min) {
 2534                       stamp[i] = newStamp;
 2535                   }
 2536               }
 2537               newStamp++;
 2538               if (min == max) {
 2539                   break;
 2540               }
 2541           }
 2542           nextStamp = newStamp;
 2543       }
 2544   
 2545       /**
 2546        * Sets the WEEK_OF_MONTH and WEEK_OF_YEAR fields to new values with the
 2547        * new parameter value if they have been calculated internally.
 2548        */
 2549       private void invalidateWeekFields()
 2550       {
 2551           if (stamp[WEEK_OF_MONTH] != COMPUTED &&
 2552               stamp[WEEK_OF_YEAR] != COMPUTED) {
 2553               return;
 2554           }
 2555   
 2556           // We have to check the new values of these fields after changing
 2557           // firstDayOfWeek and/or minimalDaysInFirstWeek. If the field values
 2558           // have been changed, then set the new values. (4822110)
 2559           Calendar cal = (Calendar) clone();
 2560           cal.setLenient(true);
 2561           cal.clear(WEEK_OF_MONTH);
 2562           cal.clear(WEEK_OF_YEAR);
 2563   
 2564           if (stamp[WEEK_OF_MONTH] == COMPUTED) {
 2565               int weekOfMonth = cal.get(WEEK_OF_MONTH);
 2566               if (fields[WEEK_OF_MONTH] != weekOfMonth) {
 2567                   fields[WEEK_OF_MONTH] = weekOfMonth;
 2568               }
 2569           }
 2570   
 2571           if (stamp[WEEK_OF_YEAR] == COMPUTED) {
 2572               int weekOfYear = cal.get(WEEK_OF_YEAR);
 2573               if (fields[WEEK_OF_YEAR] != weekOfYear) {
 2574                   fields[WEEK_OF_YEAR] = weekOfYear;
 2575               }
 2576           }
 2577       }
 2578   
 2579       /**
 2580        * Save the state of this object to a stream (i.e., serialize it).
 2581        *
 2582        * Ideally, <code>Calendar</code> would only write out its state data and
 2583        * the current time, and not write any field data out, such as
 2584        * <code>fields[]</code>, <code>isTimeSet</code>, <code>areFieldsSet</code>,
 2585        * and <code>isSet[]</code>.  <code>nextStamp</code> also should not be part
 2586        * of the persistent state. Unfortunately, this didn't happen before JDK 1.1
 2587        * shipped. To be compatible with JDK 1.1, we will always have to write out
 2588        * the field values and state flags.  However, <code>nextStamp</code> can be
 2589        * removed from the serialization stream; this will probably happen in the
 2590        * near future.
 2591        */
 2592       private void writeObject(ObjectOutputStream stream)
 2593            throws IOException
 2594       {
 2595           // Try to compute the time correctly, for the future (stream
 2596           // version 2) in which we don't write out fields[] or isSet[].
 2597           if (!isTimeSet) {
 2598               try {
 2599                   updateTime();
 2600               }
 2601               catch (IllegalArgumentException e) {}
 2602           }
 2603   
 2604           // If this Calendar has a ZoneInfo, save it and set a
 2605           // SimpleTimeZone equivalent (as a single DST schedule) for
 2606           // backward compatibility.
 2607           TimeZone savedZone = null;
 2608           if (zone instanceof ZoneInfo) {
 2609               SimpleTimeZone stz = ((ZoneInfo)zone).getLastRuleInstance();
 2610               if (stz == null) {
 2611                   stz = new SimpleTimeZone(zone.getRawOffset(), zone.getID());
 2612               }
 2613               savedZone = zone;
 2614               zone = stz;
 2615           }
 2616   
 2617           // Write out the 1.1 FCS object.
 2618           stream.defaultWriteObject();
 2619   
 2620           // Write out the ZoneInfo object
 2621           // 4802409: we write out even if it is null, a temporary workaround
 2622           // the real fix for bug 4844924 in corba-iiop
 2623           stream.writeObject(savedZone);
 2624           if (savedZone != null) {
 2625               zone = savedZone;
 2626           }
 2627       }
 2628   
 2629       /**
 2630        * Reconstitutes this object from a stream (i.e., deserialize it).
 2631        */
 2632       private void readObject(ObjectInputStream stream)
 2633            throws IOException, ClassNotFoundException
 2634       {
 2635           final ObjectInputStream input = stream;
 2636           input.defaultReadObject();
 2637   
 2638           stamp = new int[FIELD_COUNT];
 2639   
 2640           // Starting with version 2 (not implemented yet), we expect that
 2641           // fields[], isSet[], isTimeSet, and areFieldsSet may not be
 2642           // streamed out anymore.  We expect 'time' to be correct.
 2643           if (serialVersionOnStream >= 2)
 2644           {
 2645               isTimeSet = true;
 2646               if (fields == null) fields = new int[FIELD_COUNT];
 2647               if (isSet == null) isSet = new boolean[FIELD_COUNT];
 2648           }
 2649           else if (serialVersionOnStream >= 0)
 2650           {
 2651               for (int i=0; i<FIELD_COUNT; ++i)
 2652                   stamp[i] = isSet[i] ? COMPUTED : UNSET;
 2653           }
 2654   
 2655           serialVersionOnStream = currentSerialVersion;
 2656   
 2657           // If there's a ZoneInfo object, use it for zone.
 2658           try {
 2659               ZoneInfo zi = (ZoneInfo) AccessController.doPrivileged(
 2660                   new PrivilegedExceptionAction() {
 2661                       public Object run() throws Exception {
 2662                           return input.readObject();
 2663                       }
 2664                   });
 2665               if (zi != null) {
 2666                   zone = zi;
 2667               }
 2668           } catch (Exception e) {
 2669           }
 2670   
 2671           // If the deserialized object has a SimpleTimeZone, try to
 2672           // replace it with a ZoneInfo equivalent (as of 1.4) in order
 2673           // to be compatible with the SimpleTimeZone-based
 2674           // implementation as much as possible.
 2675           if (zone instanceof SimpleTimeZone) {
 2676               String id = zone.getID();
 2677               TimeZone zi = TimeZone.getTimeZone(id);
 2678               if (zi != null && zi.hasSameRules(zone) && zi.getID().equals(id)) {
 2679                   zone = zi;
 2680               }
 2681           }
 2682       }
 2683   }

Save This Page
Home » openjdk-7 » java » util » [javadoc | source]