calendar.java

来自「《移动Agent技术》一书的所有章节源代码。」· Java 代码 · 共 1,118 行 · 第 1/3 页

/*
 * @(#)Calendar.java	1.32 98/02/02
 *
 * (C) Copyright Taligent, Inc. 1996-1997 - All Rights Reserved
 * (C) Copyright IBM Corp. 1996-1997 - All Rights Reserved
 *
 * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
 *
 *   The original version of this source code and documentation is copyrighted
 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
 * materials are provided under terms of a License Agreement between Taligent
 * and Sun. This technology is protected by multiple US and International
 * patents. This notice and attribution to Taligent may not be removed.
 *   Taligent is a registered trademark of Taligent, Inc.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL purposes and without
 * fee is hereby granted provided that this copyright notice
 * appears in all copies. Please refer to the file "copyright.html"
 * for further important copyright and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 *
 */

package java.util;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.text.DateFormat;

/**
 * <code>Calendar</code> is an abstract base class for converting between
 * a <code>Date</code> object and a set of integer fields such as
 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,
 * and so on. (A <code>Date</code> object represents a specific instant in
 * time with millisecond precision. See
 * <a href="java.util.Date.html"><code>java.util.Date</code></a>
 * for information about the <code>Date</code> class.)
 *
 * <p>
 * Subclasses of <code>Calendar</code> interpret a <code>Date</code>
 * according to the rules of a specific calendar system. The JDK
 * provides one concrete subclass of <code>Calendar</code>:
 * <code>GregorianCalendar</code>. Future subclasses could represent
 * the various types of lunar calendars in use in many parts of the world.
 *
 * <p>
 * Like other locale-sensitive classes, <code>Calendar</code> provides a
 * class method, <code>getInstance</code>, for getting a generally useful
 * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
 * returns a <code>GregorianCalendar</code> object whose
 * time fields have been initialized with the current date and time:
 * <blockquote>
 * <pre>
 * Calendar rightNow = Calendar.getInstance();
 * </pre>
 * </blockquote>
 *
 * <p>
 * A <code>Calendar</code> object can produce all the time field values
 * needed to implement the date-time formatting for a particular language
 * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
 *
 * <p>
 * When computing a <code>Date</code> from time fields, two special circumstances
 * may arise: there may be insufficient information to compute the
 * <code>Date</code> (such as only year and month but no day in the month),
 * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
 * -- July 15, 1996 is actually a Monday).
 *
 * <p>
 * <strong>Insufficient information.</strong> The calendar will use default
 * information to specify the missing fields. This may vary by calendar; for
 * the Gregorian calendar, the default for a field is the same as that of the
 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.
 *
 * <p>
 * <strong>Inconsistent information.</strong> If fields conflict, the calendar
 * will give preference to fields set more recently. For example, when
 * determining the day, the calendar will look for one of the following
 * combinations of fields.  The most recent combination, as determined by the
 * most recently set single field, will be used.
 *
 * <blockquote>
 * <pre>
 * MONTH + DAY_OF_MONTH
 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 * DAY_OF_YEAR
 * DAY_OF_WEEK + WEEK_OF_YEAR
 * </pre>
 * </blockquote>
 *
 * For the time of day:
 *
 * <blockquote>
 * <pre>
 * HOUR_OF_DAY
 * AM_PM + HOUR
 * </pre>
 * </blockquote>
 *
 * <p>
 * <strong>Note:</strong> for some non-Gregorian calendars, different
 * fields may be necessary for complete disambiguation. For example, a full
 * specification of the historial Arabic astronomical calendar requires year,
 * month, day-of-month <em>and</em> day-of-week in some cases.
 *
 * <p>
 * <strong>Note:</strong> There are certain possible ambiguities in
 * interpretation of certain singular times, which are resolved in the
 * following ways:
 * <ol>
 *     <li> 24:00:00 "belongs" to the following day. That is,
 *          23:59 on Dec 31, 1969 &lt; 24:00 on Jan 1, 1970 &lt; 24:01:00 on Jan 1, 1970
 *
 *     <li> Although historically not precise, midnight also belongs to "am",
 *          and noon belongs to "pm", so on the same day,
 *          12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
 * </ol>
 *
 * <p>
 * The date or time format strings are not part of the definition of a
 * calendar, as those must be modifiable or overridable by the user at
 * runtime. Use <a href="java.text.DateFormat.html">java.text.DateFormat</a>
 * to format dates.
 *
 * <p>
 * <code>Calendar</code> provides an API for field "rolling", where fields
 * can be incremented or decremented, but wrap around. For example, rolling the
 * month up in the date "September 12, 1996" results in "October 12, 1996".
 *
 * <p>
 * <code>Calendar</code> also provides a date arithmetic function for
 * adding the specified (signed) amount of time to a particular time field.
 * For example, subtracting 5 days from the date "September 12, 1996" results
 * in "September 7, 1996".
 *
 * @see          Date
 * @see          GregorianCalendar
 * @see          TimeZone
 * @see          java.text.DateFormat
 * @version      1.17 06 Jan 1997
 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
 */
public abstract class Calendar implements Serializable, Cloneable {

    // Data flow in Calendar
    // ---------------------

    // The current time is represented in two ways by Calendar: as UTC
    // milliseconds from the epoch start (1 January 1970 0:00 UTC), and as local
    // fields such as MONTH, HOUR, AM_PM, etc.  It is possible to compute the
    // millis from the fields, and vice versa.  The data needed to do this
    // conversion is encapsulated by a TimeZone object owned by the Calendar.
    // The data provided by the TimeZone object may also be overridden if the
    // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
    // keeps track of what information was most recently set by the caller, and
    // uses that to compute any other information as needed.

    // If the user sets the fields using set(), the data flow is as follows.
    // This is implemented by the Calendar subclass's computeTime() method.
    // During this process, certain fields may be ignored.  The disambiguation
    // algorithm for resolving which fields to pay attention to is described
    // above.

    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
    //           |
    //           | Using Calendar-specific algorithm
    //           V
    //   local standard millis
    //           |
    //           | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
    //           V
    //   UTC millis (in time data member)

    // If the user sets the UTC millis using setTime(), the data flow is as
    // follows.  This is implemented by the Calendar subclass's computeFields()
    // method.

    //   UTC millis (in time data member)
    //           |
    //           | Using TimeZone getOffset()
    //           V
    //   local standard millis
    //           |
    //           | Using Calendar-specific algorithm
    //           V
    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)

    // In general, a round trip from fields, through local and UTC millis, and
    // back out to fields is made when necessary.  This is implemented by the
    // complete() method.  Resolving a partial set of fields into a UTC millis
    // value allows all remaining fields to be generated from that value.  If
    // the Calendar is lenient, the fields are also renormalized to standard
    // ranges when they are regenerated.

    /**
     * Useful constant for date and time. Used in time fields.
     * ERA is calendar specific.
     */
    public final static int ERA = 0;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int YEAR = 1;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int MONTH = 2;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int WEEK_OF_YEAR = 3;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int WEEK_OF_MONTH = 4;
    /**
     * Useful constant for date and time. Used in time fields.
     * This is a synonym for DAY_OF_MONTH.
     */
    public final static int DATE = 5;
    /**
     * Useful constant for date and time. Used in time fields.
     * This is a synonym for DATE.
     */
    public final static int DAY_OF_MONTH = 5;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int DAY_OF_YEAR = 6;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int DAY_OF_WEEK = 7;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int DAY_OF_WEEK_IN_MONTH = 8;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int AM_PM = 9;
    /**
     * Useful constant for date and time. Used in time fields.
     * HOUR is used for the 12-hour clock.
     */
    public final static int HOUR = 10;
    /**
     * Useful constant for date and time. Used in time fields.
     * HOUR_OF_DAY is used for the 24-hour clock.
     */
    public final static int HOUR_OF_DAY = 11;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int MINUTE = 12;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int SECOND = 13;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int MILLISECOND = 14;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int ZONE_OFFSET = 15;
    /**
     * Useful constant for date and time. Used in time fields.
     */
    public final static int DST_OFFSET = 16;
    /**
     * Useful constant for date and time.
     * FIELD_COUNT is used for the time field array creation.
     */
    public final static int FIELD_COUNT = 17;

    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int SUNDAY = 1;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int MONDAY = 2;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int TUESDAY = 3;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int WEDNESDAY = 4;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int THURSDAY = 5;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int FRIDAY = 6;
    /**
     * Useful constant for days of week. Used in GregorianCalendar.
     */
    public final static int SATURDAY = 7;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     * Note: Calendar month is now 0-based.
     */
    public final static int JANUARY = 0;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int FEBRUARY = 1;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int MARCH = 2;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int APRIL = 3;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int MAY = 4;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int JUNE = 5;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int JULY = 6;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int AUGUST = 7;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int SEPTEMBER = 8;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int OCTOBER = 9;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int NOVEMBER = 10;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     */
    public final static int DECEMBER = 11;
    /**
     * Useful constant for month. Used in GregorianCalendar.
     * UNDECIMBER is an artifical name. This 13th month is for lunar
     * calendars.
     */
    public final static int UNDECIMBER = 12;
    /**
     * Useful constant for hour in 12-hour clock. Used in GregorianCalendar.
     */