xmlgregoriancalendarimpl.java

来自「JAVA 所有包」· Java 代码 · 共 1,796 行 · 第 1/5 页

/*
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the "License").  You may not use this file except
 * in compliance with the License.
 *
 * You can obtain a copy of the license at
 * https://jaxp.dev.java.net/CDDLv1.0.html.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * HEADER in each file and include the License file at
 * https://jaxp.dev.java.net/CDDLv1.0.html
 * If applicable add the following below this CDDL HEADER
 * with the fields enclosed by brackets "[]" replaced with
 * your own identifying information: Portions Copyright
 * [year] [name of copyright owner]
 */

/*
 * $Id: XMLGregorianCalendarImpl.java,v 1.7 2005/11/03 17:54:07 jeffsuttor Exp $
 * @(#)XMLGregorianCalendarImpl.java	1.15 06/07/27
 *
 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
 */

package com.sun.org.apache.xerces.internal.jaxp.datatype;

import java.io.Serializable;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.TimeZone;
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.Date;
import java.util.Locale;

import javax.xml.datatype.DatatypeConstants;
import javax.xml.datatype.Duration;
import javax.xml.datatype.XMLGregorianCalendar;
import javax.xml.namespace.QName;
import com.sun.org.apache.xerces.internal.util.DatatypeMessageFormatter;


/**
 * <p>Representation for W3C XML Schema 1.0 date/time datatypes.
 * Specifically, these date/time datatypes are
 * {@link DatatypeConstants#DATETIME dateTime},
 * {@link DatatypeConstants#TIME time},
 * {@link DatatypeConstants#DATE date},
 * {@link DatatypeConstants#GYEARMONTH gYearMonth},
 * {@link DatatypeConstants#GMONTHDAY gMonthDay},
 * {@link DatatypeConstants#GYEAR gYear},
 * {@link DatatypeConstants#GMONTH gMonth} and
 * {@link DatatypeConstants#GDAY gDay}
 * defined in the XML Namespace
 * <code>"http://www.w3.org/2001/XMLSchema"</code>.
 * These datatypes are normatively defined in
 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p>
 *
 * <p>The table below defines the mapping between XML Schema 1.0
 * date/time datatype fields and this class' fields. It also summarizes
 * the value constraints for the date and time fields defined in
 * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
 * <i>ISO 8601 Date and Time Formats</i></a>.</p>
 *
 * <a name="datetimefieldsmapping"/>
 * <table border="2" rules="all" cellpadding="2">
 *   <thead>
 *     <tr>
 *       <th align="center" colspan="3">
 *         Date/time datatype field mapping between XML Schema 1.0 and Java representation
 *       </th>
 *     </tr>
 *   </thead>
 *   <tbody>
 *     <tr>
 *       <th>XML Schema 1.0<br/>
 *           datatype<br/>
 *            field</th>
 *       <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th>
 *       <th>Value Range</th>
 *     </tr>
 *     <a name="datetimefield-year"/>
 *     <tr>
 *       <td> year </td>
 *       <td> {@link #getYear()} + {@link #getEon()} or<br/>
 *            {@link #getEonAndYear}
 *       </td>
 *       <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1
 *            or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
 *            {@link #getEon()} is high order year value in billion of years.<br/>
 *            <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9).
 *            A value of null indicates field is undefined.</br>
 *            Given that <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-63">XML Schema 1.0 errata</a> states that the year zero
 *            will be a valid lexical value in a future version of XML Schema,
 *            this class allows the year field to be set to zero. Otherwise,
 *            the year field value is handled exactly as described
 *            in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
 *            validation does not allow for the year field to have a value of zero.
 *            </td>
 *     </tr>
 *     <a name="datetimefield-month"/>
 *     <tr>
 *       <td> month </td>
 *       <td> {@link #getMonth()} </td>
 *       <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
 *     </tr>
 *     <a name="datetimefield-day"/>
 *     <tr>
 *       <td> day </td>
 *       <td> {@link #getDay()} </td>
 *       <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
 *            The normative value constraint stated relative to month
 *            field's value is in <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D</a>.
 *       </td>
 *     </tr>
 *     <a name="datetimefield-hour"/>
 *     <tr>
 *       <td> hour </td>
 *       <td> {@link #getHour()} </td>
 *       <td>
 *         0 to 24 or {@link DatatypeConstants#FIELD_UNDEFINED}
 *         <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">For a value of 24, the minute and second field must be zero.</a>
 *       </td>
 *     </tr>
 *     <a name="datetimefield-minute"/>
 *     <tr>
 *       <td> minute </td>
 *       <td> {@link #getMinute()} </td>
 *       <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
 *     </tr>
 *     <a name="datetimefield-second"/>
 *     <tr>
 *       <td>second</td>
 *       <td>
 *         {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/>
 *         {@link #getSecond()} + {@link #getFractionalSecond()}
 *       </td>
 *       <td>
 *         {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
 *         <i>(Note: 60 only allowable for leap second.)</i><br/>
 *         {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
 *         the {@link #getSecond()} is defined.<br/>
 *         <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br />
 *            {@link #getMillisecond()} is the convenience
 *            millisecond precision of value of {@link #getFractionalSecond()}.
 *       </td>
 *     </tr>
 *     <tr id="datetimefield-timezone">
 *       <td> timezone </td>
 *       <td> {@link #getTimezone()} </td>
 *       <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
 *         Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
 *       </td>
 *     </tr>
 *   </tbody>
 *  </table>
 *
 * <p>All maximum value space constraints listed for the fields in the table
 * above are checked by factory methods, setter methods and parse methods of
 * this class. <code>IllegalArgumentException</code> is thrown when
 * parameter's value is outside the maximum value constraint for the field.
 * Validation checks, for example, whether days in month should be
 * limited to 29, 30 or 31 days, that are dependent on the values of other
 * fields are not checked by these methods.
 * </p>
 *
 * <p>The following operations are defined for this class:
 * <ul>
 *   <li>factory methods to create instances</li>
 *   <li>accessors/mutators for independent date/time fields</li>
 *   <li>conversion between this class and W3C XML Schema 1.0 lexical representation</li>
 *   <li>conversion between this class and <code>java.util.GregorianCalendar</code></li>
 *   <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar)}</li>
 *   <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar)}.</li>
 *   <li> addition operation with {@link javax.xml.datatype.Duration}.
 * instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">
 * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.</li>
 * </ul>
 * </p>
 *
 * @author <a href="mailto:[e-mail]">Kohsuke Kawaguchi</a>
 * @author <a href="mailto:[e-mail]">Joseph Fialli</a>
 * @author <a href="mailto:[e-mail]">Sunitha Reddy</a>
 * @version $Revision: 1.7 $, $Date: 2005/11/03 17:54:07 $
 * @see javax.xml.datatype.Duration
 * @since 1.5
 */

public class XMLGregorianCalendarImpl
	extends XMLGregorianCalendar
	implements Serializable, Cloneable {

    /**
     * <p>Eon of this <code>XMLGregorianCalendar</code>.</p>
     */
    private BigInteger eon = null;

    /**
     * <p>Year of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int year = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Month of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int month = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Day of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int day = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Timezone of this <code>XMLGregorianCalendar</code> in minutes.</p>
     */
    private int timezone = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Hour of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int hour = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Minute of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int minute = DatatypeConstants.FIELD_UNDEFINED;

    /**
     * <p>Second of this <code>XMLGregorianCalendar</code>.</p>
     */
    private int second = DatatypeConstants.FIELD_UNDEFINED ;

    /**
     * <p>Fractional second of this <code>XMLGregorianCalendar</code>.</p>
     */
    private BigDecimal fractionalSecond = null;

    /**
     * <p>Constant to represent a billion.</p>
     */
    private static final BigInteger BILLION = new BigInteger("1000000000");

    /**
     *   <p>Obtain a pure Gregorian Calendar by calling
     *   GregorianCalendar.setChange(PURE_GREGORIAN_CHANGE). </p>
     */
    private static final Date PURE_GREGORIAN_CHANGE =
	new Date(Long.MIN_VALUE);

    /**
     * Year index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int YEAR   = 0;

    /**
     * Month index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int MONTH  = 1;

    /**
     * Day index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int DAY    = 2;

    /**
     * Hour index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int HOUR   = 3;

    /**
     * Minute index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int MINUTE = 4;

    /**
     * Second index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int SECOND = 5;

    /**
     * Second index for MIN_ and MAX_FIELD_VALUES.
     */
    private static final int MILLISECOND = 6;

    /**
     * Timezone index for MIN_ and MAX_FIELD_VALUES
     */
    private static final int TIMEZONE = 7;


    /**
     * field names indexed by YEAR..TIMEZONE.
     */
    private static final String FIELD_NAME[] = {
	"Year",
	"Month",
	"Day",
	"Hour",
	"Minute",
	"Second",
	"Millisecond",
	"Timezone"
    };

    /**
     * <p>Stream Unique Identifier.</p>
     *
     * <p>TODO: Serialization should use the XML string representation as
     * the serialization format to ensure future compatibility.</p>
     */
    private static final long serialVersionUID = 1L;

    /**
     * <p>Use as a template for default field values when
     * converting to a {@link GregorianCalendar}, set to a leap
     * year date of January 1, 0400 at midnight.</p>
     *
     * <p>Fields that are optional for an <code>xsd:dateTime</code> instances are defaulted to not being set to any value.
     * <code>XMLGregorianCalendar</code> fields millisecond, fractional second and timezone return the value indicating
     * that the field is not set, {@link DatatypeConstants#FIELD_UNDEFINED} for millisecond and timezone
     * and <code>null</code> for fractional second.</p>
     *
     * @see #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)
     */
    public static final XMLGregorianCalendar LEAP_YEAR_DEFAULT =
		createDateTime(
			400,  //year
		DatatypeConstants.JANUARY,  //month
			1,  // day
		    0,  // hour
		    0,  // minute
		    0,  // second
		    DatatypeConstants.FIELD_UNDEFINED,  // milliseconds
		    DatatypeConstants.FIELD_UNDEFINED // timezone
		);

    // Constructors

    /**
     * Constructs a new XMLGregorianCalendar object.
     *
     * String parsing documented by {@link #parse(String)}.
     *
     * Returns a non-null valid XMLGregorianCalendar object that holds the
     * value indicated by the lexicalRepresentation parameter.
     *
     * @param lexicalRepresentation
     *      Lexical representation of one the eight
     *      XML Schema date/time datatypes.
     * @throws IllegalArgumentException
     *      If the given string does not conform as documented in
     *      {@link #parse(String)}.
     * @throws NullPointerException
     *      If the given string is null.
     */
    protected XMLGregorianCalendarImpl(String lexicalRepresentation)
            throws IllegalArgumentException {