/*

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

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

 *

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

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

 * published by the Free Software Foundation.  Oracle designates this

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

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

 *

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

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

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

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

 * accompanied this code).

 *

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

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

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

 *

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

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

 * questions.

 */

package javax.xml.datatype;

import javax.xml.namespace.QName;

import java.math.BigDecimal;

import java.math.BigInteger;

import java.util.TimeZone;

import java.util.GregorianCalendar;

/**

 * <p>Representation for W3C XML Schema 1.0 date/time datatypes.

 * Specifically, these date/time datatypes are

 * {@link DatatypeConstants#DATETIME},

 * {@link DatatypeConstants#TIME},

 * {@link DatatypeConstants#DATE},

 * {@link DatatypeConstants#GYEARMONTH},

 * {@link DatatypeConstants#GMONTHDAY},

 * {@link DatatypeConstants#GYEAR},

 * {@link DatatypeConstants#GMONTH}, and

 * {@link DatatypeConstants#GDAY}

 * defined in the XML Namespace

 * These datatypes are normatively defined in

 *

 * <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,

 *

 * <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>

 *            field</th>

 *       <th>Value Range</th>

 *     </tr>

 *     <tr>

 *            {@link #getEonAndYear}

 *       </td>

 *            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>

 *     <tr>

 *       <td> {@link #getMonth()} </td>

 *       <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>

 *     </tr>

 *     <tr>

 *       <td> {@link #getDay()} </td>

 *            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>

 *     <tr>

 *       <td>{@link #getHour()}</td>

 *       <td>

 *         0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.

 *         An hour value of 24 is allowed to be set in the lexical space provided the minute and second

 *         field values are zero. However, an hour value of 24 is not allowed in value space and will be

 *         transformed to represent the value of the first instance of the following day as per

 *         <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes">

 *         XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>.

 *       </td>

 *     </tr>

 *     <tr>

 *       <td> {@link #getMinute()} </td>

 *       <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>

 *     </tr>

 *     <tr>

 *       <td>

 *         {@link #getSecond()} + {@link #getFractionalSecond()}

 *       </td>

 *       <td>

 *         {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when

 *            {@link #getMillisecond()} is the convenience

 *            millisecond precision of value of {@link #getFractionalSecond()}.

 *       </td>

 *     </tr>

 *     <tr>

 *       <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

 * setter methods and parse methods of

 * parameter's value is outside the value constraint for the field or

 * if the composite

 * values constitute an invalid XMLGregorianCalendar instance (for example, if

 * the 31st of June is specified).

 *

 * <p>The following operations are defined for this class:

 * <ul>

 *   <li>accessors/mutators for independent date/time fields</li>

 *   <li>conversion between this class and W3C XML Schema 1.0 lexical representation,

 *     {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li>

 *   <li>conversion between this class and {@link GregorianCalendar},

 *     {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)},

 *     {@link DatatypeFactory}</li>

 *   <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li>

 *   <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li>

 *   <li>addition operation with {@link 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>

 *

 * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>

 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>

 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>

 * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a>

 * @see Duration

 * @see DatatypeFactory

 * @since 1.5

 */

public abstract class XMLGregorianCalendar

        implements Cloneable {

        /**

         * Default no-arg constructor.

         *

         * <p>Note: Always use the {@link DatatypeFactory} to

         * The constructor on this class cannot be guaranteed to

         * produce an object with a consistent state and may be

         */

         public XMLGregorianCalendar() {

         }

        /**

         *

         * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields

         */

        public abstract void clear();

        /**

         *

         * {@link DatatypeFactory#newXMLGregorianCalendar()},

         * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)},

         * {@link DatatypeFactory#newXMLGregorianCalendar(

         *   BigInteger year,

         *   int month,

         *   int day,

         *   int hour,

         *   int minute,

         *   int second,

         *   BigDecimal fractionalSecond,

         *   int timezone)},

         * {@link DatatypeFactory#newXMLGregorianCalendar(

         *   int year,

         *   int month,

         *   int day,

         *   int hour,

         *   int minute,

         *   int second,

         *   int millisecond,

         *   int timezone)},

         * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)},

         * {@link DatatypeFactory#newXMLGregorianCalendarDate(

         *   int year,

         *   int month,

         *   int day,

         *   int timezone)},

         * {@link DatatypeFactory#newXMLGregorianCalendarTime(

         *   int hours,

         *   int minutes,

         *   int seconds,

         *   int timezone)},

         * {@link DatatypeFactory#newXMLGregorianCalendarTime(

         *   int hours,

         *   int minutes,

         *   int seconds,

         *   BigDecimal fractionalSecond,

         *   int timezone)} or

         * {@link DatatypeFactory#newXMLGregorianCalendarTime(

         *   int hours,

         *   int minutes,

         *   int seconds,

         *   int milliseconds,

         *   int timezone)}.

         *

         */

        public abstract void reset();

    /**

     *

     *

     * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.

     *

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public abstract void setYear(BigInteger year);

    /**

     *

     * <p>Unset this field by invoking the setter with a parameter value of

     *

     * is less than 10^9, the eon component of the XSD year field is set to

     *

     * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.

     */

    public abstract void setYear(int year);

    /**

     *

     *

     * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.

     *

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public abstract void setMonth(int month);

    /**

     *

     *

     * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.

     *

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public abstract void setDay(int day);

    /**

     *

     *

     * @param offset value constraints summarized in <a href="#datetimefield-timezone">

     *   timezone field of date/time field mapping table</a>.

     *

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public abstract void setTimezone(int offset);

    /**

     *

     * @param hour value constraints are summarized in

     * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.

     * @param minute value constraints are summarized in

     * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.

     * @param second value constraints are summarized in

     * <a href="#datetimefield-second">second field of date/time field mapping table</a>.

     *

     * @see #setTime(int, int, int, BigDecimal)

     *

     * @throws IllegalArgumentException if any parameter is

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public void setTime(int hour, int minute, int second) {

                setTime(

                        hour,

                        minute,

                        second,

                        null // fractional

                );

    }

        /**

         *

         *

         * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.

         *

         *   <a href="#datetimefieldmapping">date/time field mapping table</a>.

        */

        public abstract void setHour(int hour);

        /**

         *

         *

         * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.

         *

         *   <a href="#datetimefieldmapping">date/time field mapping table</a>.

        */

        public abstract void setMinute(int minute);

        /**

         *

         *

         * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>.

         *

         *   <a href="#datetimefieldmapping">date/time field mapping table</a>.

        */

        public abstract void setSecond(int second);

        /**

         *

         *

         * @param millisecond value constraints summarized in

         *   <a href="#datetimefield-second">second field of date/time field mapping table</a>.

         *

         *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.

        */

        public abstract void setMillisecond(int millisecond);

        /**

         *

         *

         * @param fractional value constraints summarized in

         *   <a href="#datetimefield-second">second field of date/time field mapping table</a>.

         *

         *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.

        */

        public abstract void setFractionalSecond(BigDecimal fractional);

    /**

     *

     * @param hour value constraints are summarized in

     * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.

     * @param minute value constraints are summarized in

     * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.

     * @param second value constraints are summarized in

     * <a href="#datetimefield-second">second field of date/time field mapping table</a>.

     *   field is not set.

     *

     * @throws IllegalArgumentException if any parameter is

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public void setTime(

        int hour,

        int minute,

        int second,

        BigDecimal fractional) {

                setHour(hour);

        setMinute(minute);

        setSecond(second);

        setFractionalSecond(fractional);

    }

    /**

     *

     * @param hour value constraints are summarized in

     * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.

     * @param minute value constraints are summarized in

     * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.

     * @param second value constraints are summarized in

     * <a href="#datetimefield-second">second field of date/time field mapping table</a>.

     * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this

     *                    optional field is not set.

     *

     * @throws IllegalArgumentException if any parameter is

     * outside value constraints for the field as specified in

     * <a href="#datetimefieldmapping">date/time field mapping table</a>.

     */

    public void setTime(int hour, int minute, int second, int millisecond) {

        setHour(hour);

        setMinute(minute);

        setSecond(second);

        setMillisecond(millisecond);

    }

        /**

         *

         * <p>Value constraints for this value are summarized in

         * returned is an integer multiple of 10^9.

         *

         * @see #getYear()

         * @see #getEonAndYear()

         */

        public abstract BigInteger getEon();

        /**

         *

         * <p>Value constraints for this value are summarized in

         *

         *

         * @see #getEon()

         * @see #getEonAndYear()

         */

        public abstract int getYear();

        /**

         *

         * <p>Value constraints for this value are summarized in

         *

         *

         * @see #getEon()

         * @see #getYear()

         */

        public abstract BigInteger getEonAndYear();