0001: /*
0002: * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
0003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004: *
0005: * This code is free software; you can redistribute it and/or modify it
0006: * under the terms of the GNU General Public License version 2 only, as
0007: * published by the Free Software Foundation. Sun designates this
0008: * particular file as subject to the "Classpath" exception as provided
0009: * by Sun in the LICENSE file that accompanied this code.
0010: *
0011: * This code is distributed in the hope that it will be useful, but WITHOUT
0012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014: * version 2 for more details (a copy is included in the LICENSE file that
0015: * accompanied this code).
0016: *
0017: * You should have received a copy of the GNU General Public License version
0018: * 2 along with this work; if not, write to the Free Software Foundation,
0019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020: *
0021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022: * CA 95054 USA or visit www.sun.com if you need additional information or
0023: * have any questions.
0024: */
0025:
0026: /*
0027: * (C) Copyright Taligent, Inc. 1996-1998 - All Rights Reserved
0028: * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved
0029: *
0030: * The original version of this source code and documentation is copyrighted
0031: * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
0032: * materials are provided under terms of a License Agreement between Taligent
0033: * and Sun. This technology is protected by multiple US and International
0034: * patents. This notice and attribution to Taligent may not be removed.
0035: * Taligent is a registered trademark of Taligent, Inc.
0036: *
0037: */
0038:
0039: package java.util;
0040:
0041: import java.io.IOException;
0042: import java.io.ObjectInputStream;
0043: import java.io.ObjectOutputStream;
0044: import java.io.Serializable;
0045: import java.security.AccessController;
0046: import java.security.PrivilegedExceptionAction;
0047: import java.text.DateFormat;
0048: import java.text.DateFormatSymbols;
0049: import sun.util.BuddhistCalendar;
0050: import sun.util.calendar.ZoneInfo;
0051: import sun.util.resources.LocaleData;
0052:
0053: /**
0054: * The <code>Calendar</code> class is an abstract class that provides methods
0055: * for converting between a specific instant in time and a set of {@link
0056: * #fields calendar fields} such as <code>YEAR</code>, <code>MONTH</code>,
0057: * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, and so on, and for
0058: * manipulating the calendar fields, such as getting the date of the next
0059: * week. An instant in time can be represented by a millisecond value that is
0060: * an offset from the <a name="Epoch"><em>Epoch</em></a>, January 1, 1970
0061: * 00:00:00.000 GMT (Gregorian).
0062: *
0063: * <p>The class also provides additional fields and methods for
0064: * implementing a concrete calendar system outside the package. Those
0065: * fields and methods are defined as <code>protected</code>.
0066: *
0067: * <p>
0068: * Like other locale-sensitive classes, <code>Calendar</code> provides a
0069: * class method, <code>getInstance</code>, for getting a generally useful
0070: * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
0071: * returns a <code>Calendar</code> object whose
0072: * calendar fields have been initialized with the current date and time:
0073: * <blockquote>
0074: * <pre>
0075: * Calendar rightNow = Calendar.getInstance();
0076: * </pre>
0077: * </blockquote>
0078: *
0079: * <p>A <code>Calendar</code> object can produce all the calendar field values
0080: * needed to implement the date-time formatting for a particular language and
0081: * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
0082: * <code>Calendar</code> defines the range of values returned by
0083: * certain calendar fields, as well as their meaning. For example,
0084: * the first month of the calendar system has value <code>MONTH ==
0085: * JANUARY</code> for all calendars. Other values are defined by the
0086: * concrete subclass, such as <code>ERA</code>. See individual field
0087: * documentation and subclass documentation for details.
0088: *
0089: * <h4>Getting and Setting Calendar Field Values</h4>
0090: *
0091: * <p>The calendar field values can be set by calling the <code>set</code>
0092: * methods. Any field values set in a <code>Calendar</code> will not be
0093: * interpreted until it needs to calculate its time value (milliseconds from
0094: * the Epoch) or values of the calendar fields. Calling the
0095: * <code>get</code>, <code>getTimeInMillis</code>, <code>getTime</code>,
0096: * <code>add</code> and <code>roll</code> involves such calculation.
0097: *
0098: * <h4>Leniency</h4>
0099: *
0100: * <p><code>Calendar</code> has two modes for interpreting the calendar
0101: * fields, <em>lenient</em> and <em>non-lenient</em>. When a
0102: * <code>Calendar</code> is in lenient mode, it accepts a wider range of
0103: * calendar field values than it produces. When a <code>Calendar</code>
0104: * recomputes calendar field values for return by <code>get()</code>, all of
0105: * the calendar fields are normalized. For example, a lenient
0106: * <code>GregorianCalendar</code> interprets <code>MONTH == JANUARY</code>,
0107: * <code>DAY_OF_MONTH == 32</code> as February 1.
0108:
0109: * <p>When a <code>Calendar</code> is in non-lenient mode, it throws an
0110: * exception if there is any inconsistency in its calendar fields. For
0111: * example, a <code>GregorianCalendar</code> always produces
0112: * <code>DAY_OF_MONTH</code> values between 1 and the length of the month. A
0113: * non-lenient <code>GregorianCalendar</code> throws an exception upon
0114: * calculating its time or calendar field values if any out-of-range field
0115: * value has been set.
0116: *
0117: * <h4>First Week</h4>
0118: *
0119: * <code>Calendar</code> defines a locale-specific seven day week using two
0120: * parameters: the first day of the week and the minimal days in first week
0121: * (from 1 to 7). These numbers are taken from the locale resource data when a
0122: * <code>Calendar</code> is constructed. They may also be specified explicitly
0123: * through the methods for setting their values.
0124: *
0125: * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
0126: * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
0127: * first week of the month or year as a reference point. The first week of a
0128: * month or year is defined as the earliest seven day period beginning on
0129: * <code>getFirstDayOfWeek()</code> and containing at least
0130: * <code>getMinimalDaysInFirstWeek()</code> days of that month or year. Weeks
0131: * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
0132: * it. Note that the normalized numbering returned by <code>get()</code> may be
0133: * different. For example, a specific <code>Calendar</code> subclass may
0134: * designate the week before week 1 of a year as week <code><i>n</i></code> of
0135: * the previous year.
0136: *
0137: * <h4>Calendar Fields Resolution</h4>
0138: *
0139: * When computing a date and time from the calendar fields, there
0140: * may be insufficient information for the computation (such as only
0141: * year and month with no day of month), or there may be inconsistent
0142: * information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,
0143: * 1996 is actually a Monday). <code>Calendar</code> will resolve
0144: * calendar field values to determine the date and time in the
0145: * following way.
0146: *
0147: * <p>If there is any conflict in calendar field values,
0148: * <code>Calendar</code> gives priorities to calendar fields that have been set
0149: * more recently. The following are the default combinations of the
0150: * calendar fields. The most recent combination, as determined by the
0151: * most recently set single field, will be used.
0152: *
0153: * <p><a name="date_resolution">For the date fields</a>:
0154: * <blockquote>
0155: * <pre>
0156: * YEAR + MONTH + DAY_OF_MONTH
0157: * YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
0158: * YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
0159: * YEAR + DAY_OF_YEAR
0160: * YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
0161: * </pre></blockquote>
0162: *
0163: * <a name="time_resolution">For the time of day fields</a>:
0164: * <blockquote>
0165: * <pre>
0166: * HOUR_OF_DAY
0167: * AM_PM + HOUR
0168: * </pre></blockquote>
0169: *
0170: * <p>If there are any calendar fields whose values haven't been set in the selected
0171: * field combination, <code>Calendar</code> uses their default values. The default
0172: * value of each field may vary by concrete calendar systems. For example, in
0173: * <code>GregorianCalendar</code>, the default of a field is the same as that
0174: * of the start of the Epoch: i.e., <code>YEAR = 1970</code>, <code>MONTH =
0175: * JANUARY</code>, <code>DAY_OF_MONTH = 1</code>, etc.
0176: *
0177: * <p>
0178: * <strong>Note:</strong> There are certain possible ambiguities in
0179: * interpretation of certain singular times, which are resolved in the
0180: * following ways:
0181: * <ol>
0182: * <li> 23:59 is the last minute of the day and 00:00 is the first
0183: * minute of the next day. Thus, 23:59 on Dec 31, 1999 < 00:00 on
0184: * Jan 1, 2000 < 00:01 on Jan 1, 2000.
0185: *
0186: * <li> Although historically not precise, midnight also belongs to "am",
0187: * and noon belongs to "pm", so on the same day,
0188: * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
0189: * </ol>
0190: *
0191: * <p>
0192: * The date or time format strings are not part of the definition of a
0193: * calendar, as those must be modifiable or overridable by the user at
0194: * runtime. Use {@link DateFormat}
0195: * to format dates.
0196: *
0197: * <h4>Field Manipulation</h4>
0198: *
0199: * The calendar fields can be changed using three methods:
0200: * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
0201: *
0202: * <p><strong><code>set(f, value)</code></strong> changes calendar field
0203: * <code>f</code> to <code>value</code>. In addition, it sets an
0204: * internal member variable to indicate that calendar field <code>f</code> has
0205: * been changed. Although calendar field <code>f</code> is changed immediately,
0206: * the calendar's time value in milliseconds is not recomputed until the next call to
0207: * <code>get()</code>, <code>getTime()</code>, <code>getTimeInMillis()</code>,
0208: * <code>add()</code>, or <code>roll()</code> is made. Thus, multiple calls to
0209: * <code>set()</code> do not trigger multiple, unnecessary
0210: * computations. As a result of changing a calendar field using
0211: * <code>set()</code>, other calendar fields may also change, depending on the
0212: * calendar field, the calendar field value, and the calendar system. In addition,
0213: * <code>get(f)</code> will not necessarily return <code>value</code> set by
0214: * the call to the <code>set</code> method
0215: * after the calendar fields have been recomputed. The specifics are determined by
0216: * the concrete calendar class.</p>
0217: *
0218: * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
0219: * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
0220: * Calendar.SEPTEMBER)</code> sets the date to September 31,
0221: * 1999. This is a temporary internal representation that resolves to
0222: * October 1, 1999 if <code>getTime()</code>is then called. However, a
0223: * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
0224: * <code>getTime()</code> sets the date to September 30, 1999, since
0225: * no recomputation occurs after <code>set()</code> itself.</p>
0226: *
0227: * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
0228: * to field <code>f</code>. This is equivalent to calling <code>set(f,
0229: * get(f) + delta)</code> with two adjustments:</p>
0230: *
0231: * <blockquote>
0232: * <p><strong>Add rule 1</strong>. The value of field <code>f</code>
0233: * after the call minus the value of field <code>f</code> before the
0234: * call is <code>delta</code>, modulo any overflow that has occurred in
0235: * field <code>f</code>. Overflow occurs when a field value exceeds its
0236: * range and, as a result, the next larger field is incremented or
0237: * decremented and the field value is adjusted back into its range.</p>
0238: *
0239: * <p><strong>Add rule 2</strong>. If a smaller field is expected to be
0240: * invariant, but it is impossible for it to be equal to its
0241: * prior value because of changes in its minimum or maximum after field
0242: * <code>f</code> is changed or other constraints, such as time zone
0243: * offset changes, then its value is adjusted to be as close
0244: * as possible to its expected value. A smaller field represents a
0245: * smaller unit of time. <code>HOUR</code> is a smaller field than
0246: * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
0247: * that are not expected to be invariant. The calendar system
0248: * determines what fields are expected to be invariant.</p>
0249: * </blockquote>
0250: *
0251: * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
0252: * an immediate recomputation of the calendar's milliseconds and all
0253: * fields.</p>
0254: *
0255: * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
0256: * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
0257: * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
0258: * 1</strong> sets the <code>MONTH</code> field to September, since
0259: * adding 13 months to August gives September of the next year. Since
0260: * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
0261: * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
0262: * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
0263: * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
0264: * rule 2, since it is expected to change when the month changes in a
0265: * <code>GregorianCalendar</code>.</p>
0266: *
0267: * <p><strong><code>roll(f, delta)</code></strong> adds
0268: * <code>delta</code> to field <code>f</code> without changing larger
0269: * fields. This is equivalent to calling <code>add(f, delta)</code> with
0270: * the following adjustment:</p>
0271: *
0272: * <blockquote>
0273: * <p><strong>Roll rule</strong>. Larger fields are unchanged after the
0274: * call. A larger field represents a larger unit of
0275: * time. <code>DAY_OF_MONTH</code> is a larger field than
0276: * <code>HOUR</code>.</p>
0277: * </blockquote>
0278: *
0279: * <p><em>Example</em>: See {@link java.util.GregorianCalendar#roll(int, int)}.
0280: *
0281: * <p><strong>Usage model</strong>. To motivate the behavior of
0282: * <code>add()</code> and <code>roll()</code>, consider a user interface
0283: * component with increment and decrement buttons for the month, day, and
0284: * year, and an underlying <code>GregorianCalendar</code>. If the
0285: * interface reads January 31, 1999 and the user presses the month
0286: * increment button, what should it read? If the underlying
0287: * implementation uses <code>set()</code>, it might read March 3, 1999. A
0288: * better result would be February 28, 1999. Furthermore, if the user
0289: * presses the month increment button again, it should read March 31,
0290: * 1999, not March 28, 1999. By saving the original date and using either
0291: * <code>add()</code> or <code>roll()</code>, depending on whether larger
0292: * fields should be affected, the user interface can behave as most users
0293: * will intuitively expect.</p>
0294: *
0295: * @see java.lang.System#currentTimeMillis()
0296: * @see Date
0297: * @see GregorianCalendar
0298: * @see TimeZone
0299: * @see java.text.DateFormat
0300: * @version 1.95, 05/05/07
0301: * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
0302: * @since JDK1.1
0303: */
0304: public abstract class Calendar implements Serializable, Cloneable,
0305: Comparable<Calendar> {
0306:
0307: // Data flow in Calendar
0308: // ---------------------
0309:
0310: // The current time is represented in two ways by Calendar: as UTC
0311: // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
0312: // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the
0313: // millis from the fields, and vice versa. The data needed to do this
0314: // conversion is encapsulated by a TimeZone object owned by the Calendar.
0315: // The data provided by the TimeZone object may also be overridden if the
0316: // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
0317: // keeps track of what information was most recently set by the caller, and
0318: // uses that to compute any other information as needed.
0319:
0320: // If the user sets the fields using set(), the data flow is as follows.
0321: // This is implemented by the Calendar subclass's computeTime() method.
0322: // During this process, certain fields may be ignored. The disambiguation
0323: // algorithm for resolving which fields to pay attention to is described
0324: // in the class documentation.
0325:
0326: // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
0327: // |
0328: // | Using Calendar-specific algorithm
0329: // V
0330: // local standard millis
0331: // |
0332: // | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
0333: // V
0334: // UTC millis (in time data member)
0335:
0336: // If the user sets the UTC millis using setTime() or setTimeInMillis(),
0337: // the data flow is as follows. This is implemented by the Calendar
0338: // subclass's computeFields() method.
0339:
0340: // UTC millis (in time data member)
0341: // |
0342: // | Using TimeZone getOffset()
0343: // V
0344: // local standard millis
0345: // |
0346: // | Using Calendar-specific algorithm
0347: // V
0348: // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
0349:
0350: // In general, a round trip from fields, through local and UTC millis, and
0351: // back out to fields is made when necessary. This is implemented by the
0352: // complete() method. Resolving a partial set of fields into a UTC millis
0353: // value allows all remaining fields to be generated from that value. If
0354: // the Calendar is lenient, the fields are also renormalized to standard
0355: // ranges when they are regenerated.
0356:
0357: /**
0358: * Field number for <code>get</code> and <code>set</code> indicating the
0359: * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
0360: * value; see subclass documentation.
0361: *
0362: * @see GregorianCalendar#AD
0363: * @see GregorianCalendar#BC
0364: */
0365: public final static int ERA = 0;
0366:
0367: /**
0368: * Field number for <code>get</code> and <code>set</code> indicating the
0369: * year. This is a calendar-specific value; see subclass documentation.
0370: */
0371: public final static int YEAR = 1;
0372:
0373: /**
0374: * Field number for <code>get</code> and <code>set</code> indicating the
0375: * month. This is a calendar-specific value. The first month of
0376: * the year in the Gregorian and Julian calendars is
0377: * <code>JANUARY</code> which is 0; the last depends on the number
0378: * of months in a year.
0379: *
0380: * @see #JANUARY
0381: * @see #FEBRUARY
0382: * @see #MARCH
0383: * @see #APRIL
0384: * @see #MAY
0385: * @see #JUNE
0386: * @see #JULY
0387: * @see #AUGUST
0388: * @see #SEPTEMBER
0389: * @see #OCTOBER
0390: * @see #NOVEMBER
0391: * @see #DECEMBER
0392: * @see #UNDECIMBER
0393: */
0394: public final static int MONTH = 2;
0395:
0396: /**
0397: * Field number for <code>get</code> and <code>set</code> indicating the
0398: * week number within the current year. The first week of the year, as
0399: * defined by <code>getFirstDayOfWeek()</code> and
0400: * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
0401: * the value of <code>WEEK_OF_YEAR</code> for days before the first week of
0402: * the year.
0403: *
0404: * @see #getFirstDayOfWeek
0405: * @see #getMinimalDaysInFirstWeek
0406: */
0407: public final static int WEEK_OF_YEAR = 3;
0408:
0409: /**
0410: * Field number for <code>get</code> and <code>set</code> indicating the
0411: * week number within the current month. The first week of the month, as
0412: * defined by <code>getFirstDayOfWeek()</code> and
0413: * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
0414: * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
0415: * the month.
0416: *
0417: * @see #getFirstDayOfWeek
0418: * @see #getMinimalDaysInFirstWeek
0419: */
0420: public final static int WEEK_OF_MONTH = 4;
0421:
0422: /**
0423: * Field number for <code>get</code> and <code>set</code> indicating the
0424: * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
0425: * The first day of the month has value 1.
0426: *
0427: * @see #DAY_OF_MONTH
0428: */
0429: public final static int DATE = 5;
0430:
0431: /**
0432: * Field number for <code>get</code> and <code>set</code> indicating the
0433: * day of the month. This is a synonym for <code>DATE</code>.
0434: * The first day of the month has value 1.
0435: *
0436: * @see #DATE
0437: */
0438: public final static int DAY_OF_MONTH = 5;
0439:
0440: /**
0441: * Field number for <code>get</code> and <code>set</code> indicating the day
0442: * number within the current year. The first day of the year has value 1.
0443: */
0444: public final static int DAY_OF_YEAR = 6;
0445:
0446: /**
0447: * Field number for <code>get</code> and <code>set</code> indicating the day
0448: * of the week. This field takes values <code>SUNDAY</code>,
0449: * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
0450: * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
0451: *
0452: * @see #SUNDAY
0453: * @see #MONDAY
0454: * @see #TUESDAY
0455: * @see #WEDNESDAY
0456: * @see #THURSDAY
0457: * @see #FRIDAY
0458: * @see #SATURDAY
0459: */
0460: public final static int DAY_OF_WEEK = 7;
0461:
0462: /**
0463: * Field number for <code>get</code> and <code>set</code> indicating the
0464: * ordinal number of the day of the week within the current month. Together
0465: * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
0466: * within a month. Unlike <code>WEEK_OF_MONTH</code> and
0467: * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
0468: * <code>getFirstDayOfWeek()</code> or
0469: * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
0470: * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
0471: * 1</code>; <code>8</code> through <code>14</code> correspond to
0472: * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
0473: * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
0474: * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
0475: * end of the month, so the last Sunday of a month is specified as
0476: * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
0477: * negative values count backward they will usually be aligned differently
0478: * within the month than positive values. For example, if a month has 31
0479: * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
0480: * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
0481: *
0482: * @see #DAY_OF_WEEK
0483: * @see #WEEK_OF_MONTH
0484: */
0485: public final static int DAY_OF_WEEK_IN_MONTH = 8;
0486:
0487: /**
0488: * Field number for <code>get</code> and <code>set</code> indicating
0489: * whether the <code>HOUR</code> is before or after noon.
0490: * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
0491: *
0492: * @see #AM
0493: * @see #PM
0494: * @see #HOUR
0495: */
0496: public final static int AM_PM = 9;
0497:
0498: /**
0499: * Field number for <code>get</code> and <code>set</code> indicating the
0500: * hour of the morning or afternoon. <code>HOUR</code> is used for the
0501: * 12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12.
0502: * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
0503: *
0504: * @see #AM_PM
0505: * @see #HOUR_OF_DAY
0506: */
0507: public final static int HOUR = 10;
0508:
0509: /**
0510: * Field number for <code>get</code> and <code>set</code> indicating the
0511: * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
0512: * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
0513: *
0514: * @see #HOUR
0515: */
0516: public final static int HOUR_OF_DAY = 11;
0517:
0518: /**
0519: * Field number for <code>get</code> and <code>set</code> indicating the
0520: * minute within the hour.
0521: * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
0522: */
0523: public final static int MINUTE = 12;
0524:
0525: /**
0526: * Field number for <code>get</code> and <code>set</code> indicating the
0527: * second within the minute.
0528: * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
0529: */
0530: public final static int SECOND = 13;
0531:
0532: /**
0533: * Field number for <code>get</code> and <code>set</code> indicating the
0534: * millisecond within the second.
0535: * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
0536: */
0537: public final static int MILLISECOND = 14;
0538:
0539: /**
0540: * Field number for <code>get</code> and <code>set</code>
0541: * indicating the raw offset from GMT in milliseconds.
0542: * <p>
0543: * This field reflects the correct GMT offset value of the time
0544: * zone of this <code>Calendar</code> if the
0545: * <code>TimeZone</code> implementation subclass supports
0546: * historical GMT offset changes.
0547: */
0548: public final static int ZONE_OFFSET = 15;
0549:
0550: /**
0551: * Field number for <code>get</code> and <code>set</code> indicating the
0552: * daylight savings offset in milliseconds.
0553: * <p>
0554: * This field reflects the correct daylight saving offset value of
0555: * the time zone of this <code>Calendar</code> if the
0556: * <code>TimeZone</code> implementation subclass supports
0557: * historical Daylight Saving Time schedule changes.
0558: */
0559: public final static int DST_OFFSET = 16;
0560:
0561: /**
0562: * The number of distinct fields recognized by <code>get</code> and <code>set</code>.
0563: * Field numbers range from <code>0..FIELD_COUNT-1</code>.
0564: */
0565: public final static int FIELD_COUNT = 17;
0566:
0567: /**
0568: * Value of the {@link #DAY_OF_WEEK} field indicating
0569: * Sunday.
0570: */
0571: public final static int SUNDAY = 1;
0572:
0573: /**
0574: * Value of the {@link #DAY_OF_WEEK} field indicating
0575: * Monday.
0576: */
0577: public final static int MONDAY = 2;
0578:
0579: /**
0580: * Value of the {@link #DAY_OF_WEEK} field indicating
0581: * Tuesday.
0582: */
0583: public final static int TUESDAY = 3;
0584:
0585: /**
0586: * Value of the {@link #DAY_OF_WEEK} field indicating
0587: * Wednesday.
0588: */
0589: public final static int WEDNESDAY = 4;
0590:
0591: /**
0592: * Value of the {@link #DAY_OF_WEEK} field indicating
0593: * Thursday.
0594: */
0595: public final static int THURSDAY = 5;
0596:
0597: /**
0598: * Value of the {@link #DAY_OF_WEEK} field indicating
0599: * Friday.
0600: */
0601: public final static int FRIDAY = 6;
0602:
0603: /**
0604: * Value of the {@link #DAY_OF_WEEK} field indicating
0605: * Saturday.
0606: */
0607: public final static int SATURDAY = 7;
0608:
0609: /**
0610: * Value of the {@link #MONTH} field indicating the
0611: * first month of the year in the Gregorian and Julian calendars.
0612: */
0613: public final static int JANUARY = 0;
0614:
0615: /**
0616: * Value of the {@link #MONTH} field indicating the
0617: * second month of the year in the Gregorian and Julian calendars.
0618: */
0619: public final static int FEBRUARY = 1;
0620:
0621: /**
0622: * Value of the {@link #MONTH} field indicating the
0623: * third month of the year in the Gregorian and Julian calendars.
0624: */
0625: public final static int MARCH = 2;
0626:
0627: /**
0628: * Value of the {@link #MONTH} field indicating the
0629: * fourth month of the year in the Gregorian and Julian calendars.
0630: */
0631: public final static int APRIL = 3;
0632:
0633: /**
0634: * Value of the {@link #MONTH} field indicating the
0635: * fifth month of the year in the Gregorian and Julian calendars.
0636: */
0637: public final static int MAY = 4;
0638:
0639: /**
0640: * Value of the {@link #MONTH} field indicating the
0641: * sixth month of the year in the Gregorian and Julian calendars.
0642: */
0643: public final static int JUNE = 5;
0644:
0645: /**
0646: * Value of the {@link #MONTH} field indicating the
0647: * seventh month of the year in the Gregorian and Julian calendars.
0648: */
0649: public final static int JULY = 6;
0650:
0651: /**
0652: * Value of the {@link #MONTH} field indicating the
0653: * eighth month of the year in the Gregorian and Julian calendars.
0654: */
0655: public final static int AUGUST = 7;
0656:
0657: /**
0658: * Value of the {@link #MONTH} field indicating the
0659: * ninth month of the year in the Gregorian and Julian calendars.
0660: */
0661: public final static int SEPTEMBER = 8;
0662:
0663: /**
0664: * Value of the {@link #MONTH} field indicating the
0665: * tenth month of the year in the Gregorian and Julian calendars.
0666: */
0667: public final static int OCTOBER = 9;
0668:
0669: /**
0670: * Value of the {@link #MONTH} field indicating the
0671: * eleventh month of the year in the Gregorian and Julian calendars.
0672: */
0673: public final static int NOVEMBER = 10;
0674:
0675: /**
0676: * Value of the {@link #MONTH} field indicating the
0677: * twelfth month of the year in the Gregorian and Julian calendars.
0678: */
0679: public final static int DECEMBER = 11;
0680:
0681: /**
0682: * Value of the {@link #MONTH} field indicating the
0683: * thirteenth month of the year. Although <code>GregorianCalendar</code>
0684: * does not use this value, lunar calendars do.
0685: */
0686: public final static int UNDECIMBER = 12;
0687:
0688: /**
0689: * Value of the {@link #AM_PM} field indicating the
0690: * period of the day from midnight to just before noon.
0691: */
0692: public final static int AM = 0;
0693:
0694: /**
0695: * Value of the {@link #AM_PM} field indicating the
0696: * period of the day from noon to just before midnight.
0697: */
0698: public final static int PM = 1;
0699:
0700: /**
0701: * A style specifier for {@link #getDisplayNames(int, int, Locale)
0702: * getDisplayNames} indicating names in all styles, such as
0703: * "January" and "Jan".
0704: *
0705: * @see #SHORT
0706: * @see #LONG
0707: * @since 1.6
0708: */
0709: public static final int ALL_STYLES = 0;
0710:
0711: /**
0712: * A style specifier for {@link #getDisplayName(int, int, Locale)
0713: * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
0714: * getDisplayNames} indicating a short name, such as "Jan".
0715: *
0716: * @see #LONG
0717: * @since 1.6
0718: */
0719: public static final int SHORT = 1;
0720:
0721: /**
0722: * A style specifier for {@link #getDisplayName(int, int, Locale)
0723: * getDisplayName} and {@link #getDisplayNames(int, int, Locale)
0724: * getDisplayNames} indicating a long name, such as "January".
0725: *
0726: * @see #SHORT
0727: * @since 1.6
0728: */
0729: public static final int LONG = 2;
0730:
0731: // Internal notes:
0732: // Calendar contains two kinds of time representations: current "time" in
0733: // milliseconds, and a set of calendar "fields" representing the current time.
0734: // The two representations are usually in sync, but can get out of sync
0735: // as follows.
0736: // 1. Initially, no fields are set, and the time is invalid.
0737: // 2. If the time is set, all fields are computed and in sync.
0738: // 3. If a single field is set, the time is invalid.
0739: // Recomputation of the time and fields happens when the object needs
0740: // to return a result to the user, or use a result for a computation.
0741:
0742: /**
0743: * The calendar field values for the currently set time for this calendar.
0744: * This is an array of <code>FIELD_COUNT</code> integers, with index values
0745: * <code>ERA</code> through <code>DST_OFFSET</code>.
0746: * @serial
0747: */
0748: protected int fields[];
0749:
0750: /**
0751: * The flags which tell if a specified calendar field for the calendar is set.
0752: * A new object has no fields set. After the first call to a method
0753: * which generates the fields, they all remain set after that.
0754: * This is an array of <code>FIELD_COUNT</code> booleans, with index values
0755: * <code>ERA</code> through <code>DST_OFFSET</code>.
0756: * @serial
0757: */
0758: protected boolean isSet[];
0759:
0760: /**
0761: * Pseudo-time-stamps which specify when each field was set. There
0762: * are two special values, UNSET and COMPUTED. Values from
0763: * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.
0764: */
0765: transient private int stamp[];
0766:
0767: /**
0768: * The currently set time for this calendar, expressed in milliseconds after
0769: * January 1, 1970, 0:00:00 GMT.
0770: * @see #isTimeSet
0771: * @serial
0772: */
0773: protected long time;
0774:
0775: /**
0776: * True if then the value of <code>time</code> is valid.
0777: * The time is made invalid by a change to an item of <code>field[]</code>.
0778: * @see #time
0779: * @serial
0780: */
0781: protected boolean isTimeSet;
0782:
0783: /**
0784: * True if <code>fields[]</code> are in sync with the currently set time.
0785: * If false, then the next attempt to get the value of a field will
0786: * force a recomputation of all fields from the current value of
0787: * <code>time</code>.
0788: * @serial
0789: */
0790: protected boolean areFieldsSet;
0791:
0792: /**
0793: * True if all fields have been set.
0794: * @serial
0795: */
0796: transient boolean areAllFieldsSet;
0797:
0798: /**
0799: * <code>True</code> if this calendar allows out-of-range field values during computation
0800: * of <code>time</code> from <code>fields[]</code>.
0801: * @see #setLenient
0802: * @see #isLenient
0803: * @serial
0804: */
0805: private boolean lenient = true;
0806:
0807: /**
0808: * The <code>TimeZone</code> used by this calendar. <code>Calendar</code>
0809: * uses the time zone data to translate between locale and GMT time.
0810: * @serial
0811: */
0812: private TimeZone zone;
0813:
0814: /**
0815: * <code>True</code> if zone references to a shared TimeZone object.
0816: */
0817: transient private boolean sharedZone = false;
0818:
0819: /**
0820: * The first day of the week, with possible values <code>SUNDAY</code>,
0821: * <code>MONDAY</code>, etc. This is a locale-dependent value.
0822: * @serial
0823: */
0824: private int firstDayOfWeek;
0825:
0826: /**
0827: * The number of days required for the first week in a month or year,
0828: * with possible values from 1 to 7. This is a locale-dependent value.
0829: * @serial
0830: */
0831: private int minimalDaysInFirstWeek;
0832:
0833: /**
0834: * Cache to hold the firstDayOfWeek and minimalDaysInFirstWeek
0835: * of a Locale.
0836: */
0837: private static Hashtable<Locale, int[]> cachedLocaleData = new Hashtable<Locale, int[]>(
0838: 3);
0839:
0840: // Special values of stamp[]
0841: /**
0842: * The corresponding fields[] has no value.
0843: */
0844: private static final int UNSET = 0;
0845:
0846: /**
0847: * The value of the corresponding fields[] has been calculated internally.
0848: */
0849: private static final int COMPUTED = 1;
0850:
0851: /**
0852: * The value of the corresponding fields[] has been set externally. Stamp
0853: * values which are greater than 1 represents the (pseudo) time when the
0854: * corresponding fields[] value was set.
0855: */
0856: private static final int MINIMUM_USER_STAMP = 2;
0857:
0858: /**
0859: * The mask value that represents all of the fields.
0860: */
0861: static final int ALL_FIELDS = (1 << FIELD_COUNT) - 1;
0862:
0863: /**
0864: * The next available value for <code>stamp[]</code>, an internal array.
0865: * This actually should not be written out to the stream, and will probably
0866: * be removed from the stream in the near future. In the meantime,
0867: * a value of <code>MINIMUM_USER_STAMP</code> should be used.
0868: * @serial
0869: */
0870: private int nextStamp = MINIMUM_USER_STAMP;
0871:
0872: // the internal serial version which says which version was written
0873: // - 0 (default) for version up to JDK 1.1.5
0874: // - 1 for version from JDK 1.1.6, which writes a correct 'time' value
0875: // as well as compatible values for other fields. This is a
0876: // transitional format.
0877: // - 2 (not implemented yet) a future version, in which fields[],
0878: // areFieldsSet, and isTimeSet become transient, and isSet[] is
0879: // removed. In JDK 1.1.6 we write a format compatible with version 2.
0880: static final int currentSerialVersion = 1;
0881:
0882: /**
0883: * The version of the serialized data on the stream. Possible values:
0884: * <dl>
0885: * <dt><b>0</b> or not present on stream</dt>
0886: * <dd>
0887: * JDK 1.1.5 or earlier.
0888: * </dd>
0889: * <dt><b>1</b></dt>
0890: * <dd>
0891: * JDK 1.1.6 or later. Writes a correct 'time' value
0892: * as well as compatible values for other fields. This is a
0893: * transitional format.
0894: * </dd>
0895: * </dl>
0896: * When streaming out this class, the most recent format
0897: * and the highest allowable <code>serialVersionOnStream</code>
0898: * is written.
0899: * @serial
0900: * @since JDK1.1.6
0901: */
0902: private int serialVersionOnStream = currentSerialVersion;
0903:
0904: // Proclaim serialization compatibility with JDK 1.1
0905: static final long serialVersionUID = -1807547505821590642L;
0906:
0907: // Mask values for calendar fields
0908: final static int ERA_MASK = (1 << ERA);
0909: final static int YEAR_MASK = (1 << YEAR);
0910: final static int MONTH_MASK = (1 << MONTH);
0911: final static int WEEK_OF_YEAR_MASK = (1 << WEEK_OF_YEAR);
0912: final static int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
0913: final static int DAY_OF_MONTH_MASK = (1 << DAY_OF_MONTH);
0914: final static int DATE_MASK = DAY_OF_MONTH_MASK;
0915: final static int DAY_OF_YEAR_MASK = (1 << DAY_OF_YEAR);
0916: final static int DAY_OF_WEEK_MASK = (1 << DAY_OF_WEEK);
0917: final static int DAY_OF_WEEK_IN_MONTH_MASK = (1 << DAY_OF_WEEK_IN_MONTH);
0918: final static int AM_PM_MASK = (1 << AM_PM);
0919: final static int HOUR_MASK = (1 << HOUR);
0920: final static int HOUR_OF_DAY_MASK = (1 << HOUR_OF_DAY);
0921: final static int MINUTE_MASK = (1 << MINUTE);
0922: final static int SECOND_MASK = (1 << SECOND);
0923: final static int MILLISECOND_MASK = (1 << MILLISECOND);
0924: final static int ZONE_OFFSET_MASK = (1 << ZONE_OFFSET);
0925: final static int DST_OFFSET_MASK = (1 << DST_OFFSET);
0926:
0927: /**
0928: * Constructs a Calendar with the default time zone
0929: * and locale.
0930: * @see TimeZone#getDefault
0931: */
0932: protected Calendar() {
0933: this (TimeZone.getDefaultRef(), Locale.getDefault());
0934: sharedZone = true;
0935: }
0936:
0937: /**
0938: * Constructs a calendar with the specified time zone and locale.
0939: *
0940: * @param zone the time zone to use
0941: * @param aLocale the locale for the week data
0942: */
0943: protected Calendar(TimeZone zone, Locale aLocale) {
0944: fields = new int[FIELD_COUNT];
0945: isSet = new boolean[FIELD_COUNT];
0946: stamp = new int[FIELD_COUNT];
0947:
0948: this .zone = zone;
0949: setWeekCountData(aLocale);
0950: }
0951:
0952: /**
0953: * Gets a calendar using the default time zone and locale. The
0954: * <code>Calendar</code> returned is based on the current time
0955: * in the default time zone with the default locale.
0956: *
0957: * @return a Calendar.
0958: */
0959: public static Calendar getInstance() {
0960: Calendar cal = createCalendar(TimeZone.getDefaultRef(), Locale
0961: .getDefault());
0962: cal.sharedZone = true;
0963: return cal;
0964: }
0965:
0966: /**
0967: * Gets a calendar using the specified time zone and default locale.
0968: * The <code>Calendar</code> returned is based on the current time
0969: * in the given time zone with the default locale.
0970: *
0971: * @param zone the time zone to use
0972: * @return a Calendar.
0973: */
0974: public static Calendar getInstance(TimeZone zone) {
0975: return createCalendar(zone, Locale.getDefault());
0976: }
0977:
0978: /**
0979: * Gets a calendar using the default time zone and specified locale.
0980: * The <code>Calendar</code> returned is based on the current time
0981: * in the default time zone with the given locale.
0982: *
0983: * @param aLocale the locale for the week data
0984: * @return a Calendar.
0985: */
0986: public static Calendar getInstance(Locale aLocale) {
0987: Calendar cal = createCalendar(TimeZone.getDefaultRef(), aLocale);
0988: cal.sharedZone = true;
0989: return cal;
0990: }
0991:
0992: /**
0993: * Gets a calendar with the specified time zone and locale.
0994: * The <code>Calendar</code> returned is based on the current time
0995: * in the given time zone with the given locale.
0996: *
0997: * @param zone the time zone to use
0998: * @param aLocale the locale for the week data
0999: * @return a Calendar.
1000: */
1001: public static Calendar getInstance(TimeZone zone, Locale aLocale) {
1002: return createCalendar(zone, aLocale);
1003: }
1004:
1005: private static Calendar createCalendar(TimeZone zone, Locale aLocale) {
1006: // If the specified locale is a Thai locale, returns a BuddhistCalendar
1007: // instance.
1008: if ("th".equals(aLocale.getLanguage())
1009: && ("TH".equals(aLocale.getCountry()))) {
1010: return new sun.util.BuddhistCalendar(zone, aLocale);
1011: } else if ("JP".equals(aLocale.getVariant())
1012: && "JP".equals(aLocale.getCountry())
1013: && "ja".equals(aLocale.getLanguage())) {
1014: return new JapaneseImperialCalendar(zone, aLocale);
1015: }
1016:
1017: // else create the default calendar
1018: return new GregorianCalendar(zone, aLocale);
1019: }
1020:
1021: /**
1022: * Returns an array of all locales for which the <code>getInstance</code>
1023: * methods of this class can return localized instances.
1024: * The array returned must contain at least a <code>Locale</code>
1025: * instance equal to {@link java.util.Locale#US Locale.US}.
1026: *
1027: * @return An array of locales for which localized
1028: * <code>Calendar</code> instances are available.
1029: */
1030: public static synchronized Locale[] getAvailableLocales() {
1031: return DateFormat.getAvailableLocales();
1032: }
1033:
1034: /**
1035: * Converts the current calendar field values in {@link #fields fields[]}
1036: * to the millisecond time value
1037: * {@link #time}.
1038: *
1039: * @see #complete()
1040: * @see #computeFields()
1041: */
1042: protected abstract void computeTime();
1043:
1044: /**
1045: * Converts the current millisecond time value {@link #time}
1046: * to calendar field values in {@link #fields fields[]}.
1047: * This allows you to sync up the calendar field values with
1048: * a new time that is set for the calendar. The time is <em>not</em>
1049: * recomputed first; to recompute the time, then the fields, call the
1050: * {@link #complete()} method.
1051: *
1052: * @see #computeTime()
1053: */
1054: protected abstract void computeFields();
1055:
1056: /**
1057: * Returns a <code>Date</code> object representing this
1058: * <code>Calendar</code>'s time value (millisecond offset from the <a
1059: * href="#Epoch">Epoch</a>").
1060: *
1061: * @return a <code>Date</code> representing the time value.
1062: * @see #setTime(Date)
1063: * @see #getTimeInMillis()
1064: */
1065: public final Date getTime() {
1066: return new Date(getTimeInMillis());
1067: }
1068:
1069: /**
1070: * Sets this Calendar's time with the given <code>Date</code>.
1071: * <p>
1072: * Note: Calling <code>setTime()</code> with
1073: * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
1074: * may yield incorrect field values from <code>get()</code>.
1075: *
1076: * @param date the given Date.
1077: * @see #getTime()
1078: * @see #setTimeInMillis(long)
1079: */
1080: public final void setTime(Date date) {
1081: setTimeInMillis(date.getTime());
1082: }
1083:
1084: /**
1085: * Returns this Calendar's time value in milliseconds.
1086: *
1087: * @return the current time as UTC milliseconds from the epoch.
1088: * @see #getTime()
1089: * @see #setTimeInMillis(long)
1090: */
1091: public long getTimeInMillis() {
1092: if (!isTimeSet) {
1093: updateTime();
1094: }
1095: return time;
1096: }
1097:
1098: /**
1099: * Sets this Calendar's current time from the given long value.
1100: *
1101: * @param millis the new time in UTC milliseconds from the epoch.
1102: * @see #setTime(Date)
1103: * @see #getTimeInMillis()
1104: */
1105: public void setTimeInMillis(long millis) {
1106: // If we don't need to recalculate the calendar field values,
1107: // do nothing.
1108: if (time == millis && isTimeSet && areFieldsSet
1109: && areAllFieldsSet && (zone instanceof ZoneInfo)
1110: && !((ZoneInfo) zone).isDirty()) {
1111: return;
1112: }
1113: time = millis;
1114: isTimeSet = true;
1115: areFieldsSet = false;
1116: computeFields();
1117: areAllFieldsSet = areFieldsSet = true;
1118: }
1119:
1120: /**
1121: * Returns the value of the given calendar field. In lenient mode,
1122: * all calendar fields are normalized. In non-lenient mode, all
1123: * calendar fields are validated and this method throws an
1124: * exception if any calendar fields have out-of-range values. The
1125: * normalization and validation are handled by the
1126: * {@link #complete()} method, which process is calendar
1127: * system dependent.
1128: *
1129: * @param field the given calendar field.
1130: * @return the value for the given calendar field.
1131: * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
1132: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1133: * @see #set(int,int)
1134: * @see #complete()
1135: */
1136: public int get(int field) {
1137: complete();
1138: return internalGet(field);
1139: }
1140:
1141: /**
1142: * Returns the value of the given calendar field. This method does
1143: * not involve normalization or validation of the field value.
1144: *
1145: * @param field the given calendar field.
1146: * @return the value for the given calendar field.
1147: * @see #get(int)
1148: */
1149: protected final int internalGet(int field) {
1150: return fields[field];
1151: }
1152:
1153: /**
1154: * Sets the value of the given calendar field. This method does
1155: * not affect any setting state of the field in this
1156: * <code>Calendar</code> instance.
1157: *
1158: * @throws IndexOutOfBoundsException if the specified field is out of range
1159: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1160: * @see #areFieldsSet
1161: * @see #isTimeSet
1162: * @see #areAllFieldsSet
1163: * @see #set(int,int)
1164: */
1165: final void internalSet(int field, int value) {
1166: fields[field] = value;
1167: }
1168:
1169: /**
1170: * Sets the given calendar field to the given value. The value is not
1171: * interpreted by this method regardless of the leniency mode.
1172: *
1173: * @param field the given calendar field.
1174: * @param value the value to be set for the given calendar field.
1175: * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
1176: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1177: * in non-lenient mode.
1178: * @see #set(int,int,int)
1179: * @see #set(int,int,int,int,int)
1180: * @see #set(int,int,int,int,int,int)
1181: * @see #get(int)
1182: */
1183: public void set(int field, int value) {
1184: if (isLenient() && areFieldsSet && !areAllFieldsSet) {
1185: computeFields();
1186: }
1187: internalSet(field, value);
1188: isTimeSet = false;
1189: areFieldsSet = false;
1190: isSet[field] = true;
1191: stamp[field] = nextStamp++;
1192: if (nextStamp == Integer.MAX_VALUE) {
1193: adjustStamp();
1194: }
1195: }
1196:
1197: /**
1198: * Sets the values for the calendar fields <code>YEAR</code>,
1199: * <code>MONTH</code>, and <code>DAY_OF_MONTH</code>.
1200: * Previous values of other calendar fields are retained. If this is not desired,
1201: * call {@link #clear()} first.
1202: *
1203: * @param year the value used to set the <code>YEAR</code> calendar field.
1204: * @param month the value used to set the <code>MONTH</code> calendar field.
1205: * Month value is 0-based. e.g., 0 for January.
1206: * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1207: * @see #set(int,int)
1208: * @see #set(int,int,int,int,int)
1209: * @see #set(int,int,int,int,int,int)
1210: */
1211: public final void set(int year, int month, int date) {
1212: set(YEAR, year);
1213: set(MONTH, month);
1214: set(DATE, date);
1215: }
1216:
1217: /**
1218: * Sets the values for the calendar fields <code>YEAR</code>,
1219: * <code>MONTH</code>, <code>DAY_OF_MONTH</code>,
1220: * <code>HOUR_OF_DAY</code>, and <code>MINUTE</code>.
1221: * Previous values of other fields are retained. If this is not desired,
1222: * call {@link #clear()} first.
1223: *
1224: * @param year the value used to set the <code>YEAR</code> calendar field.
1225: * @param month the value used to set the <code>MONTH</code> calendar field.
1226: * Month value is 0-based. e.g., 0 for January.
1227: * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1228: * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
1229: * @param minute the value used to set the <code>MINUTE</code> calendar field.
1230: * @see #set(int,int)
1231: * @see #set(int,int,int)
1232: * @see #set(int,int,int,int,int,int)
1233: */
1234: public final void set(int year, int month, int date, int hourOfDay,
1235: int minute) {
1236: set(YEAR, year);
1237: set(MONTH, month);
1238: set(DATE, date);
1239: set(HOUR_OF_DAY, hourOfDay);
1240: set(MINUTE, minute);
1241: }
1242:
1243: /**
1244: * Sets the values for the fields <code>YEAR</code>, <code>MONTH</code>,
1245: * <code>DAY_OF_MONTH</code>, <code>HOUR</code>, <code>MINUTE</code>, and
1246: * <code>SECOND</code>.
1247: * Previous values of other fields are retained. If this is not desired,
1248: * call {@link #clear()} first.
1249: *
1250: * @param year the value used to set the <code>YEAR</code> calendar field.
1251: * @param month the value used to set the <code>MONTH</code> calendar field.
1252: * Month value is 0-based. e.g., 0 for January.
1253: * @param date the value used to set the <code>DAY_OF_MONTH</code> calendar field.
1254: * @param hourOfDay the value used to set the <code>HOUR_OF_DAY</code> calendar field.
1255: * @param minute the value used to set the <code>MINUTE</code> calendar field.
1256: * @param second the value used to set the <code>SECOND</code> calendar field.
1257: * @see #set(int,int)
1258: * @see #set(int,int,int)
1259: * @see #set(int,int,int,int,int)
1260: */
1261: public final void set(int year, int month, int date, int hourOfDay,
1262: int minute, int second) {
1263: set(YEAR, year);
1264: set(MONTH, month);
1265: set(DATE, date);
1266: set(HOUR_OF_DAY, hourOfDay);
1267: set(MINUTE, minute);
1268: set(SECOND, second);
1269: }
1270:
1271: /**
1272: * Sets all the calendar field values and the time value
1273: * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
1274: * this <code>Calendar</code> undefined. This means that {@link
1275: * #isSet(int) isSet()} will return <code>false</code> for all the
1276: * calendar fields, and the date and time calculations will treat
1277: * the fields as if they had never been set. A
1278: * <code>Calendar</code> implementation class may use its specific
1279: * default field values for date/time calculations. For example,
1280: * <code>GregorianCalendar</code> uses 1970 if the
1281: * <code>YEAR</code> field value is undefined.
1282: *
1283: * @see #clear(int)
1284: */
1285: public final void clear() {
1286: for (int i = 0; i < fields.length;) {
1287: stamp[i] = fields[i] = 0; // UNSET == 0
1288: isSet[i++] = false;
1289: }
1290: areAllFieldsSet = areFieldsSet = false;
1291: isTimeSet = false;
1292: }
1293:
1294: /**
1295: * Sets the given calendar field value and the time value
1296: * (millisecond offset from the <a href="#Epoch">Epoch</a>) of
1297: * this <code>Calendar</code> undefined. This means that {@link
1298: * #isSet(int) isSet(field)} will return <code>false</code>, and
1299: * the date and time calculations will treat the field as if it
1300: * had never been set. A <code>Calendar</code> implementation
1301: * class may use the field's specific default value for date and
1302: * time calculations.
1303: *
1304: * <p>The {@link #HOUR_OF_DAY}, {@link #HOUR} and {@link #AM_PM}
1305: * fields are handled independently and the <a
1306: * href="#time_resolution">the resolution rule for the time of
1307: * day</a> is applied. Clearing one of the fields doesn't reset
1308: * the hour of day value of this <code>Calendar</code>. Use {@link
1309: * #set(int,int) set(Calendar.HOUR_OF_DAY, 0)} to reset the hour
1310: * value.
1311: *
1312: * @param field the calendar field to be cleared.
1313: * @see #clear()
1314: */
1315: public final void clear(int field) {
1316: fields[field] = 0;
1317: stamp[field] = UNSET;
1318: isSet[field] = false;
1319:
1320: areAllFieldsSet = areFieldsSet = false;
1321: isTimeSet = false;
1322: }
1323:
1324: /**
1325: * Determines if the given calendar field has a value set,
1326: * including cases that the value has been set by internal fields
1327: * calculations triggered by a <code>get</code> method call.
1328: *
1329: * @return <code>true</code> if the given calendar field has a value set;
1330: * <code>false</code> otherwise.
1331: */
1332: public final boolean isSet(int field) {
1333: return stamp[field] != UNSET;
1334: }
1335:
1336: /**
1337: * Returns the string representation of the calendar
1338: * <code>field</code> value in the given <code>style</code> and
1339: * <code>locale</code>. If no string representation is
1340: * applicable, <code>null</code> is returned. This method calls
1341: * {@link Calendar#get(int) get(field)} to get the calendar
1342: * <code>field</code> value if the string representation is
1343: * applicable to the given calendar <code>field</code>.
1344: *
1345: * <p>For example, if this <code>Calendar</code> is a
1346: * <code>GregorianCalendar</code> and its date is 2005-01-01, then
1347: * the string representation of the {@link #MONTH} field would be
1348: * "January" in the long style in an English locale or "Jan" in
1349: * the short style. However, no string representation would be
1350: * available for the {@link #DAY_OF_MONTH} field, and this method
1351: * would return <code>null</code>.
1352: *
1353: * <p>The default implementation supports the calendar fields for
1354: * which a {@link DateFormatSymbols} has names in the given
1355: * <code>locale</code>.
1356: *
1357: * @param field
1358: * the calendar field for which the string representation
1359: * is returned
1360: * @param style
1361: * the style applied to the string representation; one of
1362: * {@link #SHORT} or {@link #LONG}.
1363: * @param locale
1364: * the locale for the string representation
1365: * @return the string representation of the given
1366: * <code>field</code> in the given <code>style</code>, or
1367: * <code>null</code> if no string representation is
1368: * applicable.
1369: * @exception IllegalArgumentException
1370: * if <code>field</code> or <code>style</code> is invalid,
1371: * or if this <code>Calendar</code> is non-lenient and any
1372: * of the calendar fields have invalid values
1373: * @exception NullPointerException
1374: * if <code>locale</code> is null
1375: * @since 1.6
1376: */
1377: public String getDisplayName(int field, int style, Locale locale) {
1378: if (!checkDisplayNameParams(field, style, ALL_STYLES, LONG,
1379: locale, ERA_MASK | MONTH_MASK | DAY_OF_WEEK_MASK
1380: | AM_PM_MASK)) {
1381: return null;
1382: }
1383:
1384: DateFormatSymbols symbols = DateFormatSymbols
1385: .getInstance(locale);
1386: String[] strings = getFieldStrings(field, style, symbols);
1387: if (strings != null) {
1388: int fieldValue = get(field);
1389: if (fieldValue < strings.length) {
1390: return strings[fieldValue];
1391: }
1392: }
1393: return null;
1394: }
1395:
1396: /**
1397: * Returns a <code>Map</code> containing all names of the calendar
1398: * <code>field</code> in the given <code>style</code> and
1399: * <code>locale</code> and their corresponding field values. For
1400: * example, if this <code>Calendar</code> is a {@link
1401: * GregorianCalendar}, the returned map would contain "Jan" to
1402: * {@link #JANUARY}, "Feb" to {@link #FEBRUARY}, and so on, in the
1403: * {@linkplain #SHORT short} style in an English locale.
1404: *
1405: * <p>The values of other calendar fields may be taken into
1406: * account to determine a set of display names. For example, if
1407: * this <code>Calendar</code> is a lunisolar calendar system and
1408: * the year value given by the {@link #YEAR} field has a leap
1409: * month, this method would return month names containing the leap
1410: * month name, and month names are mapped to their values specific
1411: * for the year.
1412: *
1413: * <p>The default implementation supports display names contained in
1414: * a {@link DateFormatSymbols}. For example, if <code>field</code>
1415: * is {@link #MONTH} and <code>style</code> is {@link
1416: * #ALL_STYLES}, this method returns a <code>Map</code> containing
1417: * all strings returned by {@link DateFormatSymbols#getShortMonths()}
1418: * and {@link DateFormatSymbols#getMonths()}.
1419: *
1420: * @param field
1421: * the calendar field for which the display names are returned
1422: * @param style
1423: * the style applied to the display names; one of {@link
1424: * #SHORT}, {@link #LONG}, or {@link #ALL_STYLES}.
1425: * @param locale
1426: * the locale for the display names
1427: * @return a <code>Map</code> containing all display names in
1428: * <code>style</code> and <code>locale</code> and their
1429: * field values, or <code>null</code> if no display names
1430: * are defined for <code>field</code>
1431: * @exception IllegalArgumentException
1432: * if <code>field</code> or <code>style</code> is invalid,
1433: * or if this <code>Calendar</code> is non-lenient and any
1434: * of the calendar fields have invalid values
1435: * @exception NullPointerException
1436: * if <code>locale</code> is null
1437: * @since 1.6
1438: */
1439: public Map<String, Integer> getDisplayNames(int field, int style,
1440: Locale locale) {
1441: if (!checkDisplayNameParams(field, style, ALL_STYLES, LONG,
1442: locale, ERA_MASK | MONTH_MASK | DAY_OF_WEEK_MASK
1443: | AM_PM_MASK)) {
1444: return null;
1445: }
1446:
1447: // ALL_STYLES
1448: if (style == ALL_STYLES) {
1449: Map<String, Integer> shortNames = getDisplayNamesImpl(
1450: field, SHORT, locale);
1451: if (field == ERA || field == AM_PM) {
1452: return shortNames;
1453: }
1454: Map<String, Integer> longNames = getDisplayNamesImpl(field,
1455: LONG, locale);
1456: if (shortNames == null) {
1457: return longNames;
1458: }
1459: if (longNames != null) {
1460: shortNames.putAll(longNames);
1461: }
1462: return shortNames;
1463: }
1464:
1465: // SHORT or LONG
1466: return getDisplayNamesImpl(field, style, locale);
1467: }
1468:
1469: private Map<String, Integer> getDisplayNamesImpl(int field,
1470: int style, Locale locale) {
1471: DateFormatSymbols symbols = DateFormatSymbols
1472: .getInstance(locale);
1473: String[] strings = getFieldStrings(field, style, symbols);
1474: if (strings != null) {
1475: Map<String, Integer> names = new HashMap<String, Integer>();
1476: for (int i = 0; i < strings.length; i++) {
1477: if (strings[i].length() == 0) {
1478: continue;
1479: }
1480: names.put(strings[i], i);
1481: }
1482: return names;
1483: }
1484: return null;
1485: }
1486:
1487: boolean checkDisplayNameParams(int field, int style, int minStyle,
1488: int maxStyle, Locale locale, int fieldMask) {
1489: if (field < 0 || field >= fields.length || style < minStyle
1490: || style > maxStyle) {
1491: throw new IllegalArgumentException();
1492: }
1493: if (locale == null) {
1494: throw new NullPointerException();
1495: }
1496: return isFieldSet(fieldMask, field);
1497: }
1498:
1499: private String[] getFieldStrings(int field, int style,
1500: DateFormatSymbols symbols) {
1501: String[] strings = null;
1502: switch (field) {
1503: case ERA:
1504: strings = symbols.getEras();
1505: break;
1506:
1507: case MONTH:
1508: strings = (style == LONG) ? symbols.getMonths() : symbols
1509: .getShortMonths();
1510: break;
1511:
1512: case DAY_OF_WEEK:
1513: strings = (style == LONG) ? symbols.getWeekdays() : symbols
1514: .getShortWeekdays();
1515: break;
1516:
1517: case AM_PM:
1518: strings = symbols.getAmPmStrings();
1519: break;
1520: }
1521: return strings;
1522: }
1523:
1524: /**
1525: * Fills in any unset fields in the calendar fields. First, the {@link
1526: * #computeTime()} method is called if the time value (millisecond offset
1527: * from the <a href="#Epoch">Epoch</a>) has not been calculated from
1528: * calendar field values. Then, the {@link #computeFields()} method is
1529: * called to calculate all calendar field values.
1530: */
1531: protected void complete() {
1532: if (!isTimeSet)
1533: updateTime();
1534: if (!areFieldsSet || !areAllFieldsSet) {
1535: computeFields(); // fills in unset fields
1536: areAllFieldsSet = areFieldsSet = true;
1537: }
1538: }
1539:
1540: /**
1541: * Returns whether the value of the specified calendar field has been set
1542: * externally by calling one of the setter methods rather than by the
1543: * internal time calculation.
1544: *
1545: * @return <code>true</code> if the field has been set externally,
1546: * <code>false</code> otherwise.
1547: * @exception IndexOutOfBoundsException if the specified
1548: * <code>field</code> is out of range
1549: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1550: * @see #selectFields()
1551: * @see #setFieldsComputed(int)
1552: */
1553: final boolean isExternallySet(int field) {
1554: return stamp[field] >= MINIMUM_USER_STAMP;
1555: }
1556:
1557: /**
1558: * Returns a field mask (bit mask) indicating all calendar fields that
1559: * have the state of externally or internally set.
1560: *
1561: * @return a bit mask indicating set state fields
1562: */
1563: final int getSetStateFields() {
1564: int mask = 0;
1565: for (int i = 0; i < fields.length; i++) {
1566: if (stamp[i] != UNSET) {
1567: mask |= 1 << i;
1568: }
1569: }
1570: return mask;
1571: }
1572:
1573: /**
1574: * Sets the state of the specified calendar fields to
1575: * <em>computed</em>. This state means that the specified calendar fields
1576: * have valid values that have been set by internal time calculation
1577: * rather than by calling one of the setter methods.
1578: *
1579: * @param fieldMask the field to be marked as computed.
1580: * @exception IndexOutOfBoundsException if the specified
1581: * <code>field</code> is out of range
1582: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1583: * @see #isExternallySet(int)
1584: * @see #selectFields()
1585: */
1586: final void setFieldsComputed(int fieldMask) {
1587: if (fieldMask == ALL_FIELDS) {
1588: for (int i = 0; i < fields.length; i++) {
1589: stamp[i] = COMPUTED;
1590: isSet[i] = true;
1591: }
1592: areFieldsSet = areAllFieldsSet = true;
1593: } else {
1594: for (int i = 0; i < fields.length; i++) {
1595: if ((fieldMask & 1) == 1) {
1596: stamp[i] = COMPUTED;
1597: isSet[i] = true;
1598: } else {
1599: if (areAllFieldsSet && !isSet[i]) {
1600: areAllFieldsSet = false;
1601: }
1602: }
1603: fieldMask >>>= 1;
1604: }
1605: }
1606: }
1607:
1608: /**
1609: * Sets the state of the calendar fields that are <em>not</em> specified
1610: * by <code>fieldMask</code> to <em>unset</em>. If <code>fieldMask</code>
1611: * specifies all the calendar fields, then the state of this
1612: * <code>Calendar</code> becomes that all the calendar fields are in sync
1613: * with the time value (millisecond offset from the Epoch).
1614: *
1615: * @param fieldMask the field mask indicating which calendar fields are in
1616: * sync with the time value.
1617: * @exception IndexOutOfBoundsException if the specified
1618: * <code>field</code> is out of range
1619: * (<code>field < 0 || field >= FIELD_COUNT</code>).
1620: * @see #isExternallySet(int)
1621: * @see #selectFields()
1622: */
1623: final void setFieldsNormalized(int fieldMask) {
1624: if (fieldMask != ALL_FIELDS) {
1625: for (int i = 0; i < fields.length; i++) {
1626: if ((fieldMask & 1) == 0) {
1627: stamp[i] = fields[i] = 0; // UNSET == 0
1628: isSet[i] = false;
1629: }
1630: fieldMask >>= 1;
1631: }
1632: }
1633:
1634: // Some or all of the fields are in sync with the
1635: // milliseconds, but the stamp values are not normalized yet.
1636: areFieldsSet = true;
1637: areAllFieldsSet = false;
1638: }
1639:
1640: /**
1641: * Returns whether the calendar fields are partially in sync with the time
1642: * value or fully in sync but not stamp values are not normalized yet.
1643: */
1644: final boolean isPartiallyNormalized() {
1645: return areFieldsSet && !areAllFieldsSet;
1646: }
1647:
1648: /**
1649: * Returns whether the calendar fields are fully in sync with the time
1650: * value.
1651: */
1652: final boolean isFullyNormalized() {
1653: return areFieldsSet && areAllFieldsSet;
1654: }
1655:
1656: /**
1657: * Marks this Calendar as not sync'd.
1658: */
1659: final void setUnnormalized() {
1660: areFieldsSet = areAllFieldsSet = false;
1661: }
1662:
1663: /**
1664: * Returns whether the specified <code>field</code> is on in the
1665: * <code>fieldMask</code>.
1666: */
1667: static final boolean isFieldSet(int fieldMask, int field) {
1668: return (fieldMask & (1 << field)) != 0;
1669: }
1670:
1671: /**
1672: * Returns a field mask indicating which calendar field values
1673: * to be used to calculate the time value. The calendar fields are
1674: * returned as a bit mask, each bit of which corresponds to a field, i.e.,
1675: * the mask value of <code>field</code> is <code>(1 <<
1676: * field)</code>. For example, 0x26 represents the <code>YEAR</code>,
1677: * <code>MONTH</code>, and <code>DAY_OF_MONTH</code> fields (i.e., 0x26 is
1678: * equal to
1679: * <code>(1<<YEAR)|(1<<MONTH)|(1<<DAY_OF_MONTH))</code>.
1680: *
1681: * <p>This method supports the calendar fields resolution as described in
1682: * the class description. If the bit mask for a given field is on and its
1683: * field has not been set (i.e., <code>isSet(field)</code> is
1684: * <code>false</code>), then the default value of the field has to be
1685: * used, which case means that the field has been selected because the
1686: * selected combination involves the field.
1687: *
1688: * @return a bit mask of selected fields
1689: * @see #isExternallySet(int)
1690: * @see #setInternallySetState(int)
1691: */
1692: final int selectFields() {
1693: // This implementation has been taken from the GregorianCalendar class.
1694:
1695: // The YEAR field must always be used regardless of its SET
1696: // state because YEAR is a mandatory field to determine the date
1697: // and the default value (EPOCH_YEAR) may change through the
1698: // normalization process.
1699: int fieldMask = YEAR_MASK;
1700:
1701: if (stamp[ERA] != UNSET) {
1702: fieldMask |= ERA_MASK;
1703: }
1704: // Find the most recent group of fields specifying the day within
1705: // the year. These may be any of the following combinations:
1706: // MONTH + DAY_OF_MONTH
1707: // MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
1708: // MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
1709: // DAY_OF_YEAR
1710: // WEEK_OF_YEAR + DAY_OF_WEEK
1711: // We look for the most recent of the fields in each group to determine
1712: // the age of the group. For groups involving a week-related field such
1713: // as WEEK_OF_MONTH, DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR, both the
1714: // week-related field and the DAY_OF_WEEK must be set for the group as a
1715: // whole to be considered. (See bug 4153860 - liu 7/24/98.)
1716: int dowStamp = stamp[DAY_OF_WEEK];
1717: int monthStamp = stamp[MONTH];
1718: int domStamp = stamp[DAY_OF_MONTH];
1719: int womStamp = aggregateStamp(stamp[WEEK_OF_MONTH], dowStamp);
1720: int dowimStamp = aggregateStamp(stamp[DAY_OF_WEEK_IN_MONTH],
1721: dowStamp);
1722: int doyStamp = stamp[DAY_OF_YEAR];
1723: int woyStamp = aggregateStamp(stamp[WEEK_OF_YEAR], dowStamp);
1724:
1725: int bestStamp = domStamp;
1726: if (womStamp > bestStamp) {
1727: bestStamp = womStamp;
1728: }
1729: if (dowimStamp > bestStamp) {
1730: bestStamp = dowimStamp;
1731: }
1732: if (doyStamp > bestStamp) {
1733: bestStamp = doyStamp;
1734: }
1735: if (woyStamp > bestStamp) {
1736: bestStamp = woyStamp;
1737: }
1738:
1739: /* No complete combination exists. Look for WEEK_OF_MONTH,
1740: * DAY_OF_WEEK_IN_MONTH, or WEEK_OF_YEAR alone. Treat DAY_OF_WEEK alone
1741: * as DAY_OF_WEEK_IN_MONTH.
1742: */
1743: if (bestStamp == UNSET) {
1744: womStamp = stamp[WEEK_OF_MONTH];
1745: dowimStamp = Math
1746: .max(stamp[DAY_OF_WEEK_IN_MONTH], dowStamp);
1747: woyStamp = stamp[WEEK_OF_YEAR];
1748: bestStamp = Math.max(Math.max(womStamp, dowimStamp),
1749: woyStamp);
1750:
1751: /* Treat MONTH alone or no fields at all as DAY_OF_MONTH. This may
1752: * result in bestStamp = domStamp = UNSET if no fields are set,
1753: * which indicates DAY_OF_MONTH.
1754: */
1755: if (bestStamp == UNSET) {
1756: bestStamp = domStamp = monthStamp;
1757: }
1758: }
1759:
1760: if (bestStamp == domStamp
1761: || (bestStamp == womStamp && stamp[WEEK_OF_MONTH] >= stamp[WEEK_OF_YEAR])
1762: || (bestStamp == dowimStamp && stamp[DAY_OF_WEEK_IN_MONTH] >= stamp[WEEK_OF_YEAR])) {
1763: fieldMask |= MONTH_MASK;
1764: if (bestStamp == domStamp) {
1765: fieldMask |= DAY_OF_MONTH_MASK;
1766: } else {
1767: assert (bestStamp == womStamp || bestStamp == dowimStamp);
1768: if (dowStamp != UNSET) {
1769: fieldMask |= DAY_OF_WEEK_MASK;
1770: }
1771: if (womStamp == dowimStamp) {
1772: // When they are equal, give the priority to
1773: // WEEK_OF_MONTH for compatibility.
1774: if (stamp[WEEK_OF_MONTH] >= stamp[DAY_OF_WEEK_IN_MONTH]) {
1775: fieldMask |= WEEK_OF_MONTH_MASK;
1776: } else {
1777: fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
1778: }
1779: } else {
1780: if (bestStamp == womStamp) {
1781: fieldMask |= WEEK_OF_MONTH_MASK;
1782: } else {
1783: assert (bestStamp == dowimStamp);
1784: if (stamp[DAY_OF_WEEK_IN_MONTH] != UNSET) {
1785: fieldMask |= DAY_OF_WEEK_IN_MONTH_MASK;
1786: }
1787: }
1788: }
1789: }
1790: } else {
1791: assert (bestStamp == doyStamp || bestStamp == woyStamp || bestStamp == UNSET);
1792: if (bestStamp == doyStamp) {
1793: fieldMask |= DAY_OF_YEAR_MASK;
1794: } else {
1795: assert (bestStamp == woyStamp);
1796: if (dowStamp != UNSET) {
1797: fieldMask |= DAY_OF_WEEK_MASK;
1798: }
1799: fieldMask |= WEEK_OF_YEAR_MASK;
1800: }
1801: }
1802:
1803: // Find the best set of fields specifying the time of day. There
1804: // are only two possibilities here; the HOUR_OF_DAY or the
1805: // AM_PM and the HOUR.
1806: int hourOfDayStamp = stamp[HOUR_OF_DAY];
1807: int hourStamp = aggregateStamp(stamp[HOUR], stamp[AM_PM]);
1808: bestStamp = (hourStamp > hourOfDayStamp) ? hourStamp
1809: : hourOfDayStamp;
1810:
1811: // if bestStamp is still UNSET, then take HOUR or AM_PM. (See 4846659)
1812: if (bestStamp == UNSET) {
1813: bestStamp = Math.max(stamp[HOUR], stamp[AM_PM]);
1814: }
1815:
1816: // Hours
1817: if (bestStamp != UNSET) {
1818: if (bestStamp == hourOfDayStamp) {
1819: fieldMask |= HOUR_OF_DAY_MASK;
1820: } else {
1821: fieldMask |= HOUR_MASK;
1822: if (stamp[AM_PM] != UNSET) {
1823: fieldMask |= AM_PM_MASK;
1824: }
1825: }
1826: }
1827: if (stamp[MINUTE] != UNSET) {
1828: fieldMask |= MINUTE_MASK;
1829: }
1830: if (stamp[SECOND] != UNSET) {
1831: fieldMask |= SECOND_MASK;
1832: }
1833: if (stamp[MILLISECOND] != UNSET) {
1834: fieldMask |= MILLISECOND_MASK;
1835: }
1836: if (stamp[ZONE_OFFSET] >= MINIMUM_USER_STAMP) {
1837: fieldMask |= ZONE_OFFSET_MASK;
1838: }
1839: if (stamp[DST_OFFSET] >= MINIMUM_USER_STAMP) {
1840: fieldMask |= DST_OFFSET_MASK;
1841: }
1842:
1843: return fieldMask;
1844: }
1845:
1846: /**
1847: * Returns the pseudo-time-stamp for two fields, given their
1848: * individual pseudo-time-stamps. If either of the fields
1849: * is unset, then the aggregate is unset. Otherwise, the
1850: * aggregate is the later of the two stamps.
1851: */
1852: private static final int aggregateStamp(int stamp_a, int stamp_b) {
1853: if (stamp_a == UNSET || stamp_b == UNSET) {
1854: return UNSET;
1855: }
1856: return (stamp_a > stamp_b) ? stamp_a : stamp_b;
1857: }
1858:
1859: /**
1860: * Compares this <code>Calendar</code> to the specified
1861: * <code>Object</code>. The result is <code>true</code> if and only if
1862: * the argument is a <code>Calendar</code> object of the same calendar
1863: * system that represents the same time value (millisecond offset from the
1864: * <a href="#Epoch">Epoch</a>) under the same
1865: * <code>Calendar</code> parameters as this object.
1866: *
1867: * <p>The <code>Calendar</code> parameters are the values represented
1868: * by the <code>isLenient</code>, <code>getFirstDayOfWeek</code>,
1869: * <code>getMinimalDaysInFirstWeek</code> and <code>getTimeZone</code>
1870: * methods. If there is any difference in those parameters
1871: * between the two <code>Calendar</code>s, this method returns
1872: * <code>false</code>.
1873: *
1874: * <p>Use the {@link #compareTo(Calendar) compareTo} method to
1875: * compare only the time values.
1876: *
1877: * @param obj the object to compare with.
1878: * @return <code>true</code> if this object is equal to <code>obj</code>;
1879: * <code>false</code> otherwise.
1880: */
1881: public boolean equals(Object obj) {
1882: if (this == obj)
1883: return true;
1884: try {
1885: Calendar that = (Calendar) obj;
1886: return compareTo(getMillisOf(that)) == 0
1887: && lenient == that.lenient
1888: && firstDayOfWeek == that.firstDayOfWeek
1889: && minimalDaysInFirstWeek == that.minimalDaysInFirstWeek
1890: && zone.equals(that.zone);
1891: } catch (Exception e) {
1892: // Note: GregorianCalendar.computeTime throws
1893: // IllegalArgumentException if the ERA value is invalid
1894: // even it's in lenient mode.
1895: }
1896: return false;
1897: }
1898:
1899: /**
1900: * Returns a hash code for this calendar.
1901: *
1902: * @return a hash code value for this object.
1903: * @since 1.2
1904: */
1905: public int hashCode() {
1906: // 'otheritems' represents the hash code for the previous versions.
1907: int otheritems = (lenient ? 1 : 0) | (firstDayOfWeek << 1)
1908: | (minimalDaysInFirstWeek << 4)
1909: | (zone.hashCode() << 7);
1910: long t = getMillisOf(this );
1911: return (int) t ^ (int) (t >> 32) ^ otheritems;
1912: }
1913:
1914: /**
1915: * Returns whether this <code>Calendar</code> represents a time
1916: * before the time represented by the specified
1917: * <code>Object</code>. This method is equivalent to:
1918: * <pre><blockquote>
1919: * compareTo(when) < 0
1920: * </blockquote></pre>
1921: * if and only if <code>when</code> is a <code>Calendar</code>
1922: * instance. Otherwise, the method returns <code>false</code>.
1923: *
1924: * @param when the <code>Object</code> to be compared
1925: * @return <code>true</code> if the time of this
1926: * <code>Calendar</code> is before the time represented by
1927: * <code>when</code>; <code>false</code> otherwise.
1928: * @see #compareTo(Calendar)
1929: */
1930: public boolean before(Object when) {
1931: return when instanceof Calendar
1932: && compareTo((Calendar) when) < 0;
1933: }
1934:
1935: /**
1936: * Returns whether this <code>Calendar</code> represents a time
1937: * after the time represented by the specified
1938: * <code>Object</code>. This method is equivalent to:
1939: * <pre><blockquote>
1940: * compareTo(when) > 0
1941: * </blockquote></pre>
1942: * if and only if <code>when</code> is a <code>Calendar</code>
1943: * instance. Otherwise, the method returns <code>false</code>.
1944: *
1945: * @param when the <code>Object</code> to be compared
1946: * @return <code>true</code> if the time of this <code>Calendar</code> is
1947: * after the time represented by <code>when</code>; <code>false</code>
1948: * otherwise.
1949: * @see #compareTo(Calendar)
1950: */
1951: public boolean after(Object when) {
1952: return when instanceof Calendar
1953: && compareTo((Calendar) when) > 0;
1954: }
1955:
1956: /**
1957: * Compares the time values (millisecond offsets from the <a
1958: * href="#Epoch">Epoch</a>) represented by two
1959: * <code>Calendar</code> objects.
1960: *
1961: * @param anotherCalendar the <code>Calendar</code> to be compared.
1962: * @return the value <code>0</code> if the time represented by the argument
1963: * is equal to the time represented by this <code>Calendar</code>; a value
1964: * less than <code>0</code> if the time of this <code>Calendar</code> is
1965: * before the time represented by the argument; and a value greater than
1966: * <code>0</code> if the time of this <code>Calendar</code> is after the
1967: * time represented by the argument.
1968: * @exception NullPointerException if the specified <code>Calendar</code> is
1969: * <code>null</code>.
1970: * @exception IllegalArgumentException if the time value of the
1971: * specified <code>Calendar</code> object can't be obtained due to
1972: * any invalid calendar values.
1973: * @since 1.5
1974: */
1975: public int compareTo(Calendar anotherCalendar) {
1976: return compareTo(getMillisOf(anotherCalendar));
1977: }
1978:
1979: /**
1980: * Adds or subtracts the specified amount of time to the given calendar field,
1981: * based on the calendar's rules. For example, to subtract 5 days from
1982: * the current time of the calendar, you can achieve it by calling:
1983: * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
1984: *
1985: * @param field the calendar field.
1986: * @param amount the amount of date or time to be added to the field.
1987: * @see #roll(int,int)
1988: * @see #set(int,int)
1989: */
1990: abstract public void add(int field, int amount);
1991:
1992: /**
1993: * Adds or subtracts (up/down) a single unit of time on the given time
1994: * field without changing larger fields. For example, to roll the current
1995: * date up by one day, you can achieve it by calling:
1996: * <p>roll(Calendar.DATE, true).
1997: * When rolling on the year or Calendar.YEAR field, it will roll the year
1998: * value in the range between 1 and the value returned by calling
1999: * <code>getMaximum(Calendar.YEAR)</code>.
2000: * When rolling on the month or Calendar.MONTH field, other fields like
2001: * date might conflict and, need to be changed. For instance,
2002: * rolling the month on the date 01/31/96 will result in 02/29/96.
2003: * When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
2004: * roll the hour value in the range between 0 and 23, which is zero-based.
2005: *
2006: * @param field the time field.
2007: * @param up indicates if the value of the specified time field is to be
2008: * rolled up or rolled down. Use true if rolling up, false otherwise.
2009: * @see Calendar#add(int,int)
2010: * @see Calendar#set(int,int)
2011: */
2012: abstract public void roll(int field, boolean up);
2013:
2014: /**
2015: * Adds the specified (signed) amount to the specified calendar field
2016: * without changing larger fields. A negative amount means to roll
2017: * down.
2018: *
2019: * <p>NOTE: This default implementation on <code>Calendar</code> just repeatedly calls the
2020: * version of {@link #roll(int,boolean) roll()} that rolls by one unit. This may not
2021: * always do the right thing. For example, if the <code>DAY_OF_MONTH</code> field is 31,
2022: * rolling through February will leave it set to 28. The <code>GregorianCalendar</code>
2023: * version of this function takes care of this problem. Other subclasses
2024: * should also provide overrides of this function that do the right thing.
2025: *
2026: * @param field the calendar field.
2027: * @param amount the signed amount to add to the calendar <code>field</code>.
2028: * @since 1.2
2029: * @see #roll(int,boolean)
2030: * @see #add(int,int)
2031: * @see #set(int,int)
2032: */
2033: public void roll(int field, int amount) {
2034: while (amount > 0) {
2035: roll(field, true);
2036: amount--;
2037: }
2038: while (amount < 0) {
2039: roll(field, false);
2040: amount++;
2041: }
2042: }
2043:
2044: /**
2045: * Sets the time zone with the given time zone value.
2046: *
2047: * @param value the given time zone.
2048: */
2049: public void setTimeZone(TimeZone value) {
2050: zone = value;
2051: sharedZone = false;
2052: /* Recompute the fields from the time using the new zone. This also
2053: * works if isTimeSet is false (after a call to set()). In that case
2054: * the time will be computed from the fields using the new zone, then
2055: * the fields will get recomputed from that. Consider the sequence of
2056: * calls: cal.setTimeZone(EST); cal.set(HOUR, 1); cal.setTimeZone(PST).
2057: * Is cal set to 1 o'clock EST or 1 o'clock PST? Answer: PST. More
2058: * generally, a call to setTimeZone() affects calls to set() BEFORE AND
2059: * AFTER it up to the next call to complete().
2060: */
2061: areAllFieldsSet = areFieldsSet = false;
2062: }
2063:
2064: /**
2065: * Gets the time zone.
2066: *
2067: * @return the time zone object associated with this calendar.
2068: */
2069: public TimeZone getTimeZone() {
2070: // If the TimeZone object is shared by other Calendar instances, then
2071: // create a clone.
2072: if (sharedZone) {
2073: zone = (TimeZone) zone.clone();
2074: sharedZone = false;
2075: }
2076: return zone;
2077: }
2078:
2079: /**
2080: * Returns the time zone (without cloning).
2081: */
2082: TimeZone getZone() {
2083: return zone;
2084: }
2085:
2086: /**
2087: * Sets the sharedZone flag to <code>shared</code>.
2088: */
2089: void setZoneShared(boolean shared) {
2090: sharedZone = shared;
2091: }
2092:
2093: /**
2094: * Specifies whether or not date/time interpretation is to be lenient. With
2095: * lenient interpretation, a date such as "February 942, 1996" will be
2096: * treated as being equivalent to the 941st day after February 1, 1996.
2097: * With strict (non-lenient) interpretation, such dates will cause an exception to be
2098: * thrown. The default is lenient.
2099: *
2100: * @param lenient <code>true</code> if the lenient mode is to be turned
2101: * on; <code>false</code> if it is to be turned off.
2102: * @see #isLenient()
2103: * @see java.text.DateFormat#setLenient
2104: */
2105: public void setLenient(boolean lenient) {
2106: this .lenient = lenient;
2107: }
2108:
2109: /**
2110: * Tells whether date/time interpretation is to be lenient.
2111: *
2112: * @return <code>true</code> if the interpretation mode of this calendar is lenient;
2113: * <code>false</code> otherwise.
2114: * @see #setLenient(boolean)
2115: */
2116: public boolean isLenient() {
2117: return lenient;
2118: }
2119:
2120: /**
2121: * Sets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
2122: * <code>MONDAY</code> in France.
2123: *
2124: * @param value the given first day of the week.
2125: * @see #getFirstDayOfWeek()
2126: * @see #getMinimalDaysInFirstWeek()
2127: */
2128: public void setFirstDayOfWeek(int value) {
2129: if (firstDayOfWeek == value) {
2130: return;
2131: }
2132: firstDayOfWeek = value;
2133: invalidateWeekFields();
2134: }
2135:
2136: /**
2137: * Gets what the first day of the week is; e.g., <code>SUNDAY</code> in the U.S.,
2138: * <code>MONDAY</code> in France.
2139: *
2140: * @return the first day of the week.
2141: * @see #setFirstDayOfWeek(int)
2142: * @see #getMinimalDaysInFirstWeek()
2143: */
2144: public int getFirstDayOfWeek() {
2145: return firstDayOfWeek;
2146: }
2147:
2148: /**
2149: * Sets what the minimal days required in the first week of the year are;
2150: * For example, if the first week is defined as one that contains the first
2151: * day of the first month of a year, call this method with value 1. If it
2152: * must be a full week, use value 7.
2153: *
2154: * @param value the given minimal days required in the first week
2155: * of the year.
2156: * @see #getMinimalDaysInFirstWeek()
2157: */
2158: public void setMinimalDaysInFirstWeek(int value) {
2159: if (minimalDaysInFirstWeek == value) {
2160: return;
2161: }
2162: minimalDaysInFirstWeek = value;
2163: invalidateWeekFields();
2164: }
2165:
2166: /**
2167: * Gets what the minimal days required in the first week of the year are;
2168: * e.g., if the first week is defined as one that contains the first day
2169: * of the first month of a year, this method returns 1. If
2170: * the minimal days required must be a full week, this method
2171: * returns 7.
2172: *
2173: * @return the minimal days required in the first week of the year.
2174: * @see #setMinimalDaysInFirstWeek(int)
2175: */
2176: public int getMinimalDaysInFirstWeek() {
2177: return minimalDaysInFirstWeek;
2178: }
2179:
2180: /**
2181: * Returns the minimum value for the given calendar field of this
2182: * <code>Calendar</code> instance. The minimum value is defined as
2183: * the smallest value returned by the {@link #get(int) get} method
2184: * for any possible time value. The minimum value depends on
2185: * calendar system specific parameters of the instance.
2186: *
2187: * @param field the calendar field.
2188: * @return the minimum value for the given calendar field.
2189: * @see #getMaximum(int)
2190: * @see #getGreatestMinimum(int)
2191: * @see #getLeastMaximum(int)
2192: * @see #getActualMinimum(int)
2193: * @see #getActualMaximum(int)
2194: */
2195: abstract public int getMinimum(int field);
2196:
2197: /**
2198: * Returns the maximum value for the given calendar field of this
2199: * <code>Calendar</code> instance. The maximum value is defined as
2200: * the largest value returned by the {@link #get(int) get} method
2201: * for any possible time value. The maximum value depends on
2202: * calendar system specific parameters of the instance.
2203: *
2204: * @param field the calendar field.
2205: * @return the maximum value for the given calendar field.
2206: * @see #getMinimum(int)
2207: * @see #getGreatestMinimum(int)
2208: * @see #getLeastMaximum(int)
2209: * @see #getActualMinimum(int)
2210: * @see #getActualMaximum(int)
2211: */
2212: abstract public int getMaximum(int field);
2213:
2214: /**
2215: * Returns the highest minimum value for the given calendar field
2216: * of this <code>Calendar</code> instance. The highest minimum
2217: * value is defined as the largest value returned by {@link
2218: * #getActualMinimum(int)} for any possible time value. The
2219: * greatest minimum value depends on calendar system specific
2220: * parameters of the instance.
2221: *
2222: * @param field the calendar field.
2223: * @return the highest minimum value for the given calendar field.
2224: * @see #getMinimum(int)
2225: * @see #getMaximum(int)
2226: * @see #getLeastMaximum(int)
2227: * @see #getActualMinimum(int)
2228: * @see #getActualMaximum(int)
2229: */
2230: abstract public int getGreatestMinimum(int field);
2231:
2232: /**
2233: * Returns the lowest maximum value for the given calendar field
2234: * of this <code>Calendar</code> instance. The lowest maximum
2235: * value is defined as the smallest value returned by {@link
2236: * #getActualMaximum(int)} for any possible time value. The least
2237: * maximum value depends on calendar system specific parameters of
2238: * the instance. For example, a <code>Calendar</code> for the
2239: * Gregorian calendar system returns 28 for the
2240: * <code>DAY_OF_MONTH</code> field, because the 28th is the last
2241: * day of the shortest month of this calendar, February in a
2242: * common year.
2243: *
2244: * @param field the calendar field.
2245: * @return the lowest maximum value for the given calendar field.
2246: * @see #getMinimum(int)
2247: * @see #getMaximum(int)
2248: * @see #getGreatestMinimum(int)
2249: * @see #getActualMinimum(int)
2250: * @see #getActualMaximum(int)
2251: */
2252: abstract public int getLeastMaximum(int field);
2253:
2254: /**
2255: * Returns the minimum value that the specified calendar field
2256: * could have, given the time value of this <code>Calendar</code>.
2257: *
2258: * <p>The default implementation of this method uses an iterative
2259: * algorithm to determine the actual minimum value for the
2260: * calendar field. Subclasses should, if possible, override this
2261: * with a more efficient implementation - in many cases, they can
2262: * simply return <code>getMinimum()</code>.
2263: *
2264: * @param field the calendar field
2265: * @return the minimum of the given calendar field for the time
2266: * value of this <code>Calendar</code>
2267: * @see #getMinimum(int)
2268: * @see #getMaximum(int)
2269: * @see #getGreatestMinimum(int)
2270: * @see #getLeastMaximum(int)
2271: * @see #getActualMaximum(int)
2272: * @since 1.2
2273: */
2274: public int getActualMinimum(int field) {
2275: int fieldValue = getGreatestMinimum(field);
2276: int endValue = getMinimum(field);
2277:
2278: // if we know that the minimum value is always the same, just return it
2279: if (fieldValue == endValue) {
2280: return fieldValue;
2281: }
2282:
2283: // clone the calendar so we don't mess with the real one, and set it to
2284: // accept anything for the field values
2285: Calendar work = (Calendar) this .clone();
2286: work.setLenient(true);
2287:
2288: // now try each value from getLeastMaximum() to getMaximum() one by one until
2289: // we get a value that normalizes to another value. The last value that
2290: // normalizes to itself is the actual minimum for the current date
2291: int result = fieldValue;
2292:
2293: do {
2294: work.set(field, fieldValue);
2295: if (work.get(field) != fieldValue) {
2296: break;
2297: } else {
2298: result = fieldValue;
2299: fieldValue--;
2300: }
2301: } while (fieldValue >= endValue);
2302:
2303: return result;
2304: }
2305:
2306: /**
2307: * Returns the maximum value that the specified calendar field
2308: * could have, given the time value of this
2309: * <code>Calendar</code>. For example, the actual maximum value of
2310: * the <code>MONTH</code> field is 12 in some years, and 13 in
2311: * other years in the Hebrew calendar system.
2312: *
2313: * <p>The default implementation of this method uses an iterative
2314: * algorithm to determine the actual maximum value for the
2315: * calendar field. Subclasses should, if possible, override this
2316: * with a more efficient implementation.
2317: *
2318: * @param field the calendar field
2319: * @return the maximum of the given calendar field for the time
2320: * value of this <code>Calendar</code>
2321: * @see #getMinimum(int)
2322: * @see #getMaximum(int)
2323: * @see #getGreatestMinimum(int)
2324: * @see #getLeastMaximum(int)
2325: * @see #getActualMinimum(int)
2326: * @since 1.2
2327: */
2328: public int getActualMaximum(int field) {
2329: int fieldValue = getLeastMaximum(field);
2330: int endValue = getMaximum(field);
2331:
2332: // if we know that the maximum value is always the same, just return it.
2333: if (fieldValue == endValue) {
2334: return fieldValue;
2335: }
2336:
2337: // clone the calendar so we don't mess with the real one, and set it to
2338: // accept anything for the field values.
2339: Calendar work = (Calendar) this .clone();
2340: work.setLenient(true);
2341:
2342: // if we're counting weeks, set the day of the week to Sunday. We know the
2343: // last week of a month or year will contain the first day of the week.
2344: if (field == WEEK_OF_YEAR || field == WEEK_OF_MONTH)
2345: work.set(DAY_OF_WEEK, firstDayOfWeek);
2346:
2347: // now try each value from getLeastMaximum() to getMaximum() one by one until
2348: // we get a value that normalizes to another value. The last value that
2349: // normalizes to itself is the actual maximum for the current date
2350: int result = fieldValue;
2351:
2352: do {
2353: work.set(field, fieldValue);
2354: if (work.get(field) != fieldValue) {
2355: break;
2356: } else {
2357: result = fieldValue;
2358: fieldValue++;
2359: }
2360: } while (fieldValue <= endValue);
2361:
2362: return result;
2363: }
2364:
2365: /**
2366: * Creates and returns a copy of this object.
2367: *
2368: * @return a copy of this object.
2369: */
2370: public Object clone() {
2371: try {
2372: Calendar other = (Calendar) super .clone();
2373:
2374: other.fields = new int[FIELD_COUNT];
2375: other.isSet = new boolean[FIELD_COUNT];
2376: other.stamp = new int[FIELD_COUNT];
2377: for (int i = 0; i < FIELD_COUNT; i++) {
2378: other.fields[i] = fields[i];
2379: other.stamp[i] = stamp[i];
2380: other.isSet[i] = isSet[i];
2381: }
2382: other.zone = (TimeZone) zone.clone();
2383: return other;
2384: } catch (CloneNotSupportedException e) {
2385: // this shouldn't happen, since we are Cloneable
2386: throw new InternalError();
2387: }
2388: }
2389:
2390: private static final String[] FIELD_NAME = { "ERA", "YEAR",
2391: "MONTH", "WEEK_OF_YEAR", "WEEK_OF_MONTH", "DAY_OF_MONTH",
2392: "DAY_OF_YEAR", "DAY_OF_WEEK", "DAY_OF_WEEK_IN_MONTH",
2393: "AM_PM", "HOUR", "HOUR_OF_DAY", "MINUTE", "SECOND",
2394: "MILLISECOND", "ZONE_OFFSET", "DST_OFFSET" };
2395:
2396: /**
2397: * Returns the name of the specified calendar field.
2398: *
2399: * @param field the calendar field
2400: * @return the calendar field name
2401: * @exception IndexOutOfBoundsException if <code>field</code> is negative,
2402: * equal to or greater then <code>FIELD_COUNT</code>.
2403: */
2404: static final String getFieldName(int field) {
2405: return FIELD_NAME[field];
2406: }
2407:
2408: /**
2409: * Return a string representation of this calendar. This method
2410: * is intended to be used only for debugging purposes, and the
2411: * format of the returned string may vary between implementations.
2412: * The returned string may be empty but may not be <code>null</code>.
2413: *
2414: * @return a string representation of this calendar.
2415: */
2416: public String toString() {
2417: // NOTE: BuddhistCalendar.toString() interprets the string
2418: // produced by this method so that the Gregorian year number
2419: // is substituted by its B.E. year value. It relies on
2420: // "...,YEAR=<year>,..." or "...,YEAR=?,...".
2421: StringBuilder buffer = new StringBuilder(800);
2422: buffer.append(getClass().getName()).append('[');
2423: appendValue(buffer, "time", isTimeSet, time);
2424: buffer.append(",areFieldsSet=").append(areFieldsSet);
2425: buffer.append(",areAllFieldsSet=").append(areAllFieldsSet);
2426: buffer.append(",lenient=").append(lenient);
2427: buffer.append(",zone=").append(zone);
2428: appendValue(buffer, ",firstDayOfWeek", true,
2429: (long) firstDayOfWeek);
2430: appendValue(buffer, ",minimalDaysInFirstWeek", true,
2431: (long) minimalDaysInFirstWeek);
2432: for (int i = 0; i < FIELD_COUNT; ++i) {
2433: buffer.append(',');
2434: appendValue(buffer, FIELD_NAME[i], isSet(i),
2435: (long) fields[i]);
2436: }
2437: buffer.append(']');
2438: return buffer.toString();
2439: }
2440:
2441: // =======================privates===============================
2442:
2443: private static final void appendValue(StringBuilder sb,
2444: String item, boolean valid, long value) {
2445: sb.append(item).append('=');
2446: if (valid) {
2447: sb.append(value);
2448: } else {
2449: sb.append('?');
2450: }
2451: }
2452:
2453: /**
2454: * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent.
2455: * They are used to figure out the week count for a specific date for
2456: * a given locale. These must be set when a Calendar is constructed.
2457: * @param desiredLocale the given locale.
2458: */
2459: private void setWeekCountData(Locale desiredLocale) {
2460: /* try to get the Locale data from the cache */
2461: int[] data = cachedLocaleData.get(desiredLocale);
2462: if (data == null) { /* cache miss */
2463: ResourceBundle bundle = LocaleData
2464: .getCalendarData(desiredLocale);
2465: data = new int[2];
2466: data[0] = Integer.parseInt(bundle
2467: .getString("firstDayOfWeek"));
2468: data[1] = Integer.parseInt(bundle
2469: .getString("minimalDaysInFirstWeek"));
2470: cachedLocaleData.put(desiredLocale, data);
2471: }
2472: firstDayOfWeek = data[0];
2473: minimalDaysInFirstWeek = data[1];
2474: }
2475:
2476: /**
2477: * Recomputes the time and updates the status fields isTimeSet
2478: * and areFieldsSet. Callers should check isTimeSet and only
2479: * call this method if isTimeSet is false.
2480: */
2481: private void updateTime() {
2482: computeTime();
2483: // The areFieldsSet and areAllFieldsSet values are no longer
2484: // controlled here (as of 1.5).
2485: isTimeSet = true;
2486: }
2487:
2488: private int compareTo(long t) {
2489: long this Time = getMillisOf(this );
2490: return (this Time > t) ? 1 : (this Time == t) ? 0 : -1;
2491: }
2492:
2493: private static final long getMillisOf(Calendar calendar) {
2494: if (calendar.isTimeSet) {
2495: return calendar.time;
2496: }
2497: Calendar cal = (Calendar) calendar.clone();
2498: cal.setLenient(true);
2499: return cal.getTimeInMillis();
2500: }
2501:
2502: /**
2503: * Adjusts the stamp[] values before nextStamp overflow. nextStamp
2504: * is set to the next stamp value upon the return.
2505: */
2506: private final void adjustStamp() {
2507: int max = MINIMUM_USER_STAMP;
2508: int newStamp = MINIMUM_USER_STAMP;
2509:
2510: for (;;) {
2511: int min = Integer.MAX_VALUE;
2512: for (int i = 0; i < stamp.length; i++) {
2513: int v = stamp[i];
2514: if (v >= newStamp && min > v) {
2515: min = v;
2516: }
2517: if (max < v) {
2518: max = v;
2519: }
2520: }
2521: if (max != min && min == Integer.MAX_VALUE) {
2522: break;
2523: }
2524: for (int i = 0; i < stamp.length; i++) {
2525: if (stamp[i] == min) {
2526: stamp[i] = newStamp;
2527: }
2528: }
2529: newStamp++;
2530: if (min == max) {
2531: break;
2532: }
2533: }
2534: nextStamp = newStamp;
2535: }
2536:
2537: /**
2538: * Sets the WEEK_OF_MONTH and WEEK_OF_YEAR fields to new values with the
2539: * new parameter value if they have been calculated internally.
2540: */
2541: private void invalidateWeekFields() {
2542: if (stamp[WEEK_OF_MONTH] != COMPUTED
2543: && stamp[WEEK_OF_YEAR] != COMPUTED) {
2544: return;
2545: }
2546:
2547: // We have to check the new values of these fields after changing
2548: // firstDayOfWeek and/or minimalDaysInFirstWeek. If the field values
2549: // have been changed, then set the new values. (4822110)
2550: Calendar cal = (Calendar) clone();
2551: cal.setLenient(true);
2552: cal.clear(WEEK_OF_MONTH);
2553: cal.clear(WEEK_OF_YEAR);
2554:
2555: if (stamp[WEEK_OF_MONTH] == COMPUTED) {
2556: int weekOfMonth = cal.get(WEEK_OF_MONTH);
2557: if (fields[WEEK_OF_MONTH] != weekOfMonth) {
2558: fields[WEEK_OF_MONTH] = weekOfMonth;
2559: }
2560: }
2561:
2562: if (stamp[WEEK_OF_YEAR] == COMPUTED) {
2563: int weekOfYear = cal.get(WEEK_OF_YEAR);
2564: if (fields[WEEK_OF_YEAR] != weekOfYear) {
2565: fields[WEEK_OF_YEAR] = weekOfYear;
2566: }
2567: }
2568: }
2569:
2570: /**
2571: * Save the state of this object to a stream (i.e., serialize it).
2572: *
2573: * Ideally, <code>Calendar</code> would only write out its state data and
2574: * the current time, and not write any field data out, such as
2575: * <code>fields[]</code>, <code>isTimeSet</code>, <code>areFieldsSet</code>,
2576: * and <code>isSet[]</code>. <code>nextStamp</code> also should not be part
2577: * of the persistent state. Unfortunately, this didn't happen before JDK 1.1
2578: * shipped. To be compatible with JDK 1.1, we will always have to write out
2579: * the field values and state flags. However, <code>nextStamp</code> can be
2580: * removed from the serialization stream; this will probably happen in the
2581: * near future.
2582: */
2583: private void writeObject(ObjectOutputStream stream)
2584: throws IOException {
2585: // Try to compute the time correctly, for the future (stream
2586: // version 2) in which we don't write out fields[] or isSet[].
2587: if (!isTimeSet) {
2588: try {
2589: updateTime();
2590: } catch (IllegalArgumentException e) {
2591: }
2592: }
2593:
2594: // If this Calendar has a ZoneInfo, save it and set a
2595: // SimpleTimeZone equivalent (as a single DST schedule) for
2596: // backward compatibility.
2597: TimeZone savedZone = null;
2598: if (zone instanceof ZoneInfo) {
2599: SimpleTimeZone stz = ((ZoneInfo) zone)
2600: .getLastRuleInstance();
2601: if (stz == null) {
2602: stz = new SimpleTimeZone(zone.getRawOffset(), zone
2603: .getID());
2604: }
2605: savedZone = zone;
2606: zone = stz;
2607: }
2608:
2609: // Write out the 1.1 FCS object.
2610: stream.defaultWriteObject();
2611:
2612: // Write out the ZoneInfo object
2613: // 4802409: we write out even if it is null, a temporary workaround
2614: // the real fix for bug 4844924 in corba-iiop
2615: stream.writeObject(savedZone);
2616: if (savedZone != null) {
2617: zone = savedZone;
2618: }
2619: }
2620:
2621: /**
2622: * Reconstitutes this object from a stream (i.e., deserialize it).
2623: */
2624: private void readObject(ObjectInputStream stream)
2625: throws IOException, ClassNotFoundException {
2626: final ObjectInputStream input = stream;
2627: input.defaultReadObject();
2628:
2629: stamp = new int[FIELD_COUNT];
2630:
2631: // Starting with version 2 (not implemented yet), we expect that
2632: // fields[], isSet[], isTimeSet, and areFieldsSet may not be
2633: // streamed out anymore. We expect 'time' to be correct.
2634: if (serialVersionOnStream >= 2) {
2635: isTimeSet = true;
2636: if (fields == null)
2637: fields = new int[FIELD_COUNT];
2638: if (isSet == null)
2639: isSet = new boolean[FIELD_COUNT];
2640: } else if (serialVersionOnStream >= 0) {
2641: for (int i = 0; i < FIELD_COUNT; ++i)
2642: stamp[i] = isSet[i] ? COMPUTED : UNSET;
2643: }
2644:
2645: serialVersionOnStream = currentSerialVersion;
2646:
2647: // If there's a ZoneInfo object, use it for zone.
2648: try {
2649: ZoneInfo zi = (ZoneInfo) AccessController
2650: .doPrivileged(new PrivilegedExceptionAction() {
2651: public Object run() throws Exception {
2652: return input.readObject();
2653: }
2654: });
2655: if (zi != null) {
2656: zone = zi;
2657: }
2658: } catch (Exception e) {
2659: }
2660:
2661: // If the deserialized object has a SimpleTimeZone, try to
2662: // replace it with a ZoneInfo equivalent (as of 1.4) in order
2663: // to be compatible with the SimpleTimeZone-based
2664: // implementation as much as possible.
2665: if (zone instanceof SimpleTimeZone) {
2666: String id = zone.getID();
2667: TimeZone zi = TimeZone.getTimeZone(id);
2668: if (zi != null && zi.hasSameRules(zone)
2669: && zi.getID().equals(id)) {
2670: zone = zi;
2671: }
2672: }
2673: }
2674: }
|
