1 /*
   2  * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.datatype;
  27 
  28 import javax.xml.namespace.QName;
  29 import java.math.BigDecimal;
  30 import java.math.BigInteger;
  31 import java.util.Arrays;
  32 import java.util.TimeZone;
  33 import java.util.GregorianCalendar;
  34 
  35 /**
  36  * <p>Representation for W3C XML Schema 1.0 date/time datatypes.
  37  * Specifically, these date/time datatypes are
  38  * {@link DatatypeConstants#DATETIME},
  39  * {@link DatatypeConstants#TIME},
  40  * {@link DatatypeConstants#DATE},
  41  * {@link DatatypeConstants#GYEARMONTH},
  42  * {@link DatatypeConstants#GMONTHDAY},
  43  * {@link DatatypeConstants#GYEAR},
  44  * {@link DatatypeConstants#GMONTH}, and
  45  * {@link DatatypeConstants#GDAY}
  46  * defined in the XML Namespace
  47  * {@code "http://www.w3.org/2001/XMLSchema"}.
  48  * These datatypes are normatively defined in
  49  * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.
  50  *
  51  * <p>The table below defines the mapping between XML Schema 1.0
  52  * date/time datatype fields and this class' fields. It also summarizes
  53  * the value constraints for the date and time fields defined in
  54  * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
  55  * <i>ISO 8601 Date and Time Formats</i></a>.
  56  *
  57  * <a id="datetimefieldmapping"></a>
  58  * <table class="striped">
  59  *   <caption>Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</caption>
  60  *   <thead>
  61  *     <tr>
  62  *       <th scope="col">XML Schema 1.0<br>
  63  *           datatype<br>
  64  *            field</th>
  65  *       <th scope="col">Related<br>XMLGregorianCalendar<br>Accessor(s)</th>
  66  *       <th scope="col">Value Range</th>
  67  *     </tr>
  68  *   </thead>
  69  *   <tbody>
  70  *     <tr>
  71  *       <th scope="row"><a id="datetimefield-year">year</a></th>
  72  *       <td> {@link #getYear()} + {@link #getEon()} or<br>
  73  *            {@link #getEonAndYear}
  74  *       </td>
  75  *       <td> {@code getYear()} is a value between -(10^9-1) to (10^9)-1
  76  *            or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
  77  *            {@link #getEon()} is high order year value in billion of years.<br>
  78  *            {@code getEon()} has values greater than or equal to (10^9) or less than or equal to -(10^9).
  79  *            A value of null indicates field is undefined.<br>
  80  *            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
  81  *            will be a valid lexical value in a future version of XML Schema,
  82  *            this class allows the year field to be set to zero. Otherwise,
  83  *            the year field value is handled exactly as described
  84  *            in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
  85  *            validation does not allow for the year field to have a value of zero.
  86  *            </td>
  87  *     </tr>
  88  *     <tr>
  89  *       <th scope="row"><a id="datetimefield-month">month</a></th>
  90  *       <td> {@link #getMonth()} </td>
  91  *       <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
  92  *     </tr>
  93  *     <tr>
  94  *       <th scope="row"><a id="datetimefield-day">day</a></th>
  95  *       <td> {@link #getDay()} </td>
  96  *       <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
  97  *            The normative value constraint stated relative to month
  98  *            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>.
  99  *       </td>
 100  *     </tr>
 101  *     <tr>
 102  *       <th scope="row"><a id="datetimefield-hour">hour</a></th>
 103  *       <td>{@link #getHour()}</td>
 104  *       <td>
 105  *         0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
 106  *         An hour value of 24 is allowed to be set in the lexical space provided the minute and second
 107  *         field values are zero. However, an hour value of 24 is not allowed in value space and will be
 108  *         transformed to represent the value of the first instance of the following day as per
 109  *         <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes">
 110  *         XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>.
 111  *       </td>
 112  *     </tr>
 113  *     <tr>
 114  *       <th scope="row"><a id="datetimefield-minute">minute</a></th>
 115  *       <td> {@link #getMinute()} </td>
 116  *       <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
 117  *     </tr>
 118  *     <tr>
 119  *       <th scope="row"><a id="datetimefield-second">second</a></th>
 120  *       <td>
 121  *         {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br>
 122  *         {@link #getSecond()} + {@link #getFractionalSecond()}
 123  *       </td>
 124  *       <td>
 125  *         {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
 126  *         <i>(Note: 60 only allowable for leap second.)</i><br>
 127  *         {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
 128  *         the {@link #getSecond()} is defined.<br>
 129  *         {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined.<br>
 130  *            {@link #getMillisecond()} is the convenience
 131  *            millisecond precision of value of {@link #getFractionalSecond()}.
 132  *       </td>
 133  *     </tr>
 134  *     <tr>
 135  *       <th scope="row"><a id="datetimefield-timezone">timezone</a></th>
 136  *       <td> {@link #getTimezone()} </td>
 137  *       <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
 138  *         Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
 139  *       </td>
 140  *     </tr>
 141  *   </tbody>
 142  *  </table>
 143  *
 144  * <p>All maximum value space constraints listed for the fields in the table
 145  * above are checked by factory methods, {@link DatatypeFactory},
 146  * setter methods and parse methods of
 147  * this class. {@code IllegalArgumentException} is thrown when a
 148  * parameter's value is outside the value constraint for the field or
 149  * if the composite
 150  * values constitute an invalid XMLGregorianCalendar instance (for example, if
 151  * the 31st of June is specified).
 152  *
 153  * <p>The following operations are defined for this class:
 154  * <ul>
 155  *   <li>accessors/mutators for independent date/time fields</li>
 156  *   <li>conversion between this class and W3C XML Schema 1.0 lexical representation,
 157  *     {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li>
 158  *   <li>conversion between this class and {@link GregorianCalendar},
 159  *     {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)},
 160  *     {@link DatatypeFactory}</li>
 161  *   <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li>
 162  *   <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li>
 163  *   <li>addition operation with {@link Duration}
 164  *      instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">
 165  *      W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.
 166  *   </li>
 167  * </ul>
 168  *
 169  * @author Joseph Fialli
 170  * @author Kohsuke Kawaguchi
 171  * @author Jeff Suttor
 172  * @author Sunitha Reddy
 173  * @see Duration
 174  * @see DatatypeFactory
 175  * @since 1.5
 176  */
 177 
 178 public abstract class XMLGregorianCalendar
 179         implements Cloneable {
 180 
 181     /**
 182      * Default no-arg constructor.
 183      *
 184      * <p>Note: Always use the {@link DatatypeFactory} to
 185      * construct an instance of {@code XMLGregorianCalendar}.
 186      * The constructor on this class cannot be guaranteed to
 187      * produce an object with a consistent state and may be
 188      * removed in the future.
 189      */
 190     public XMLGregorianCalendar() {
 191     }
 192 
 193     /**
 194      * Unset all fields to undefined.
 195      *
 196      * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields
 197      * to null.
 198      */
 199     public abstract void clear();
 200 
 201     /**
 202      * Reset this {@code XMLGregorianCalendar} to its original values.
 203      *
 204      * <p>{@code XMLGregorianCalendar} is reset to the same values as when it was created with
 205      * {@link DatatypeFactory#newXMLGregorianCalendar()},
 206      * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)},
 207      * {@link DatatypeFactory#newXMLGregorianCalendar(
 208      *   BigInteger year,
 209      *   int month,
 210      *   int day,
 211      *   int hour,
 212      *   int minute,
 213      *   int second,
 214      *   BigDecimal fractionalSecond,
 215      *   int timezone)},
 216      * {@link DatatypeFactory#newXMLGregorianCalendar(
 217      *   int year,
 218      *   int month,
 219      *   int day,
 220      *   int hour,
 221      *   int minute,
 222      *   int second,
 223      *   int millisecond,
 224      *   int timezone)},
 225      * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)},
 226      * {@link DatatypeFactory#newXMLGregorianCalendarDate(
 227      *   int year,
 228      *   int month,
 229      *   int day,
 230      *   int timezone)},
 231      * {@link DatatypeFactory#newXMLGregorianCalendarTime(
 232      *   int hours,
 233      *   int minutes,
 234      *   int seconds,
 235      *   int timezone)},
 236      * {@link DatatypeFactory#newXMLGregorianCalendarTime(
 237      *   int hours,
 238      *   int minutes,
 239      *   int seconds,
 240      *   BigDecimal fractionalSecond,
 241      *   int timezone)} or
 242      * {@link DatatypeFactory#newXMLGregorianCalendarTime(
 243      *   int hours,
 244      *   int minutes,
 245      *   int seconds,
 246      *   int milliseconds,
 247      *   int timezone)}.
 248      *
 249      * <p>{@code reset()} is designed to allow the reuse of existing {@code XMLGregorianCalendar}s
 250      * thus saving resources associated with the creation of new {@code XMLGregorianCalendar}s.
 251      */
 252     public abstract void reset();
 253 
 254     /**
 255      * Set low and high order component of XSD {@code dateTime} year field.
 256      *
 257      * <p>Unset this field by invoking the setter with a parameter value of {@code null}.
 258      *
 259      * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
 260      *
 261      * @throws IllegalArgumentException if {@code year} parameter is
 262      * outside value constraints for the field as specified in
 263      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 264      */
 265     public abstract void setYear(BigInteger year);
 266 
 267     /**
 268      * Set year of XSD {@code dateTime} year field.
 269      *
 270      * <p>Unset this field by invoking the setter with a parameter value of
 271      * {@link DatatypeConstants#FIELD_UNDEFINED}.
 272      *
 273      * <p>Note: if the absolute value of the {@code year} parameter
 274      * is less than 10^9, the eon component of the XSD year field is set to
 275      * {@code null} by this method.
 276      *
 277      * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
 278      *   If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to {@code null}.
 279      */
 280     public abstract void setYear(int year);
 281 
 282     /**
 283      * Set month.
 284      *
 285      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 286      *
 287      * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.
 288      *
 289      * @throws IllegalArgumentException if {@code month} parameter is
 290      * outside value constraints for the field as specified in
 291      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 292      */
 293     public abstract void setMonth(int month);
 294 
 295     /**
 296      * Set days in month.
 297      *
 298      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 299      *
 300      * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.
 301      *
 302      * @throws IllegalArgumentException if {@code day} parameter is
 303      * outside value constraints for the field as specified in
 304      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 305      */
 306     public abstract void setDay(int day);
 307 
 308     /**
 309      * Set the number of minutes in the timezone offset.
 310      *
 311      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 312      *
 313      * @param offset value constraints summarized in <a href="#datetimefield-timezone">
 314      *   timezone field of date/time field mapping table</a>.
 315      *
 316      * @throws IllegalArgumentException if {@code offset} parameter is
 317      * outside value constraints for the field as specified in
 318      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 319      */
 320     public abstract void setTimezone(int offset);
 321 
 322     /**
 323      * Set time as one unit.
 324      *
 325      * @param hour value constraints are summarized in
 326      * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
 327      * @param minute value constraints are summarized in
 328      * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
 329      * @param second value constraints are summarized in
 330      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 331      *
 332      * @see #setTime(int, int, int, BigDecimal)
 333      *
 334      * @throws IllegalArgumentException if any parameter is
 335      * outside value constraints for the field as specified in
 336      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 337      */
 338     public void setTime(int hour, int minute, int second) {
 339 
 340         setTime(
 341                 hour,
 342                 minute,
 343                 second,
 344                 null // fractional
 345         );
 346     }
 347 
 348     /**
 349      * Set hours.
 350      *
 351      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 352      *
 353      * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
 354      *
 355      * @throws IllegalArgumentException if {@code hour} parameter is outside value constraints for the field as specified in
 356      *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
 357      */
 358     public abstract void setHour(int hour);
 359 
 360     /**
 361      * Set minutes.
 362      *
 363      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 364      *
 365      * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
 366      *
 367      * @throws IllegalArgumentException if {@code minute} parameter is outside value constraints for the field as specified in
 368      *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
 369      */
 370     public abstract void setMinute(int minute);
 371 
 372     /**
 373      * Set seconds.
 374      *
 375      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 376      *
 377      * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 378      *
 379      * @throws IllegalArgumentException if {@code second} parameter is outside value constraints for the field as specified in
 380      *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
 381      */
 382     public abstract void setSecond(int second);
 383 
 384     /**
 385      * Set milliseconds.
 386      *
 387      * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
 388      *
 389      * @param millisecond value constraints summarized in
 390      *   <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 391      *
 392      * @throws IllegalArgumentException if {@code millisecond} parameter is outside value constraints for the field as specified
 393      *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.
 394      */
 395     public abstract void setMillisecond(int millisecond);
 396 
 397     /**
 398      * Set fractional seconds.
 399      *
 400      * <p>Unset this field by invoking the setter with a parameter value of {@code null}.
 401      *
 402      * @param fractional value constraints summarized in
 403      *   <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 404      *
 405      * @throws IllegalArgumentException if {@code fractional} parameter is outside value constraints for the field as specified
 406      *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.
 407      */
 408     public abstract void setFractionalSecond(BigDecimal fractional);
 409 
 410 
 411     /**
 412      * Set time as one unit, including the optional infinite precision
 413      * fractional seconds.
 414      *
 415      * @param hour value constraints are summarized in
 416      * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
 417      * @param minute value constraints are summarized in
 418      * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
 419      * @param second value constraints are summarized in
 420      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 421      * @param fractional value of {@code null} indicates this optional
 422      *   field is not set.
 423      *
 424      * @throws IllegalArgumentException if any parameter is
 425      * outside value constraints for the field as specified in
 426      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 427      */
 428     public void setTime(
 429             int hour,
 430             int minute,
 431             int second,
 432             BigDecimal fractional) {
 433 
 434         setHour(hour);
 435         setMinute(minute);
 436         setSecond(second);
 437         setFractionalSecond(fractional);
 438     }
 439 
 440 
 441     /**
 442      * Set time as one unit, including optional milliseconds.
 443      *
 444      * @param hour value constraints are summarized in
 445      * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
 446      * @param minute value constraints are summarized in
 447      * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
 448      * @param second value constraints are summarized in
 449      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 450      * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this
 451      *                    optional field is not set.
 452      *
 453      * @throws IllegalArgumentException if any parameter is
 454      * outside value constraints for the field as specified in
 455      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 456      */
 457     public void setTime(int hour, int minute, int second, int millisecond) {
 458 
 459         setHour(hour);
 460         setMinute(minute);
 461         setSecond(second);
 462         setMillisecond(millisecond);
 463     }
 464 
 465     /**
 466      * Returns the high order component for XML Schema 1.0 dateTime datatype field for
 467      * {@code year}.
 468      * {@code null} if this optional part of the year field is not defined.
 469      *
 470      * <p>Value constraints for this value are summarized in
 471      * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
 472      * @return The eon of this {@code XMLGregorianCalendar}. The value
 473      * returned is an integer multiple of 10^9.
 474      *
 475      * @see #getYear()
 476      * @see #getEonAndYear()
 477      */
 478     public abstract BigInteger getEon();
 479 
 480     /**
 481      * Returns the low order component for XML Schema 1.0 dateTime datatype field for
 482      * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}.
 483      *
 484      * <p>Value constraints for this value are summarized in
 485      * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
 486      *
 487      * @return The year of this {@code XMLGregorianCalendar}.
 488      *
 489      * @see #getEon()
 490      * @see #getEonAndYear()
 491      */
 492     public abstract int getYear();
 493 
 494     /**
 495      * Returns the XML Schema 1.0 dateTime datatype field for
 496      * {@code year}.
 497      *
 498      * <p>Value constraints for this value are summarized in
 499      * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
 500      *
 501      * @return sum of {@code eon} and {@code BigInteger.valueOf(year)}
 502      * when both fields are defined. When only {@code year} is defined,
 503      * return it. When both {@code eon} and {@code year} are not
 504      * defined, return {@code null}.
 505      *
 506      * @see #getEon()
 507      * @see #getYear()
 508      */
 509     public abstract BigInteger getEonAndYear();
 510 
 511     /**
 512      * Returns the month of this calendar or {@link DatatypeConstants#FIELD_UNDEFINED}.
 513      *
 514      * <p>Value constraints for this value are summarized in
 515      * <a href="#datetimefield-month">month field of date/time field mapping table</a>.
 516      *
 517      * @return The month of this {@code XMLGregorianCalendar}, from 1 to 12.
 518      *
 519      */
 520     public abstract int getMonth();
 521 
 522     /**
 523      * Returns the day of month or {@link DatatypeConstants#FIELD_UNDEFINED}.
 524      *
 525      * <p>Value constraints for this value are summarized in
 526      * <a href="#datetimefield-day">day field of date/time field mapping table</a>.
 527      *
 528      * @return The day of month of this {@code XMLGregorianCalendar}, from 1 to 31.
 529      *
 530      * @see #setDay(int)
 531      */
 532     public abstract int getDay();
 533 
 534     /**
 535      * Returns the Timezone offset in minutes or
 536      * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
 537      *
 538      * <p>Value constraints for this value are summarized in
 539      * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.
 540      *
 541      * @return The Timezone offset in minutes of this {@code XMLGregorianCalendar}.
 542      *
 543      * @see #setTimezone(int)
 544      */
 545     public abstract int getTimezone();
 546 
 547     /**
 548      * Returns the hour of day or
 549      * {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
 550      *
 551      * <p>Value constraints for this value are summarized in
 552      * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
 553      *
 554      * @return The hour of day of this {@code XMLGregorianCalendar}, from 0 to 23.
 555      *
 556      * @see #setTime(int, int, int)
 557      */
 558     public abstract int getHour();
 559 
 560     /**
 561      * Returns the minute of hour or
 562      * {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
 563      *
 564      * <p>Value constraints for this value are summarized in
 565      * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
 566      *
 567      * @return The minute of hour of this {@code XMLGregorianCalendar}, from 0 to 59.
 568      *
 569      * @see #setTime(int, int, int)
 570      */
 571     public abstract int getMinute();
 572 
 573     /**
 574      * Returns the second of minute or
 575      * {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
 576      * When this field is not defined, the optional xs:dateTime
 577      * fractional seconds field, represented by
 578      * {@link #getFractionalSecond()} and {@link #getMillisecond()},
 579      * must not be defined.
 580      *
 581      * <p>Value constraints for this value are summarized in
 582      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 583      *
 584      * @return The second of minute of this {@code XMLGregorianCalendar},  from 0 to 59.
 585      *
 586      * @see #getFractionalSecond()
 587      * @see #getMillisecond()
 588      * @see #setTime(int, int, int)
 589      */
 590     public abstract int getSecond();
 591 
 592     /**
 593      * Returns the millisecond precision of {@link #getFractionalSecond()}.
 594      *
 595      * <p>This method represents a convenience accessor to infinite
 596      * precision fractional second value returned by
 597      * {@link #getFractionalSecond()}. The returned value is the rounded
 598      * down to milliseconds value of
 599      * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
 600      * returns {@code null}, this method must return
 601      * {@link DatatypeConstants#FIELD_UNDEFINED}.
 602      *
 603      * <p>Value constraints for this value are summarized in
 604      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 605      *
 606      * @return The millisecond precision of this {@code XMLGregorianCalendar}.
 607      *
 608      * @see #getFractionalSecond()
 609      * @see #setTime(int, int, int)
 610      */
 611     public int getMillisecond() {
 612 
 613         BigDecimal fractionalSeconds = getFractionalSecond();
 614 
 615         // is field undefined?
 616         if (fractionalSeconds == null) {
 617             return DatatypeConstants.FIELD_UNDEFINED;
 618         }
 619 
 620         return getFractionalSecond().movePointRight(3).intValue();
 621     }
 622 
 623     /**
 624      * Returns fractional seconds.
 625      *
 626      * <p>{@code null} is returned when this optional field is not defined.
 627      *
 628      * <p>Value constraints are detailed in
 629      * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
 630      *
 631      * <p>This optional field can only have a defined value when the
 632      * xs:dateTime second field, represented by {@link #getSecond()},
 633      * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.
 634      *
 635      * @return Fractional seconds of this {@code XMLGregorianCalendar}.
 636      *
 637      * @see #getSecond()
 638      * @see #setTime(int, int, int, BigDecimal)
 639      */
 640     public abstract BigDecimal getFractionalSecond();
 641 
 642     // comparisons
 643     /**
 644      * Compare two instances of W3C XML Schema 1.0 date/time datatypes
 645      * according to partial order relation defined in
 646      * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
 647      * <i>Order relation on dateTime</i></a>.
 648      *
 649      * <p>{@code xsd:dateTime} datatype field mapping to accessors of
 650      * this class are defined in
 651      * <a href="#datetimefieldmapping">date/time field mapping table</a>.
 652      *
 653      * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare
 654      *
 655      * @return The relationship between {@code this} {@code XMLGregorianCalendar} and
 656      *   the specified {@code xmlGregorianCalendar} as
 657      *   {@link DatatypeConstants#LESSER},
 658      *   {@link DatatypeConstants#EQUAL},
 659      *   {@link DatatypeConstants#GREATER} or
 660      *   {@link DatatypeConstants#INDETERMINATE}.
 661      *
 662      * @throws NullPointerException if {@code xmlGregorianCalendar} is null.
 663      */
 664     public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar);
 665 
 666     /**
 667      * Normalize this instance to UTC.
 668      *
 669      * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z
 670      * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
 671      *
 672      * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
 673      */
 674     public abstract XMLGregorianCalendar normalize();
 675 
 676     /**
 677      * Compares this calendar to the specified object. The result is
 678      * {@code true} if and only if the argument is not null and is an
 679      * {@code XMLGregorianCalendar} object that represents the same
 680      * instant in time as this object.
 681      *
 682      * @param obj to compare.
 683      *
 684      * @return {@code true} when {@code obj} is an instance of
 685      * {@code XMLGregorianCalendar} and
 686      * {@link #compare(XMLGregorianCalendar obj)}
 687      * returns {@link DatatypeConstants#EQUAL},
 688      * otherwise {@code false}.
 689      */
 690     @Override
 691     public boolean equals(Object obj) {
 692 
 693         if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
 694             return false;
 695         }
 696         return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
 697     }
 698 
 699     /**
 700      * Returns a hash code consistent with the definition of the equals method.
 701      *
 702      * @return hash code of this object.
 703      */
 704     @Override
 705     public int hashCode() {
 706 
 707         // Following two dates compare to EQUALS since in different timezones.
 708         // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
 709         //
 710         // Must ensure both instances generate same hashcode by normalizing
 711         // this to UTC timezone.
 712         int timezone = getTimezone();
 713         if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
 714             timezone = 0;
 715         }
 716         XMLGregorianCalendar gc = this;
 717         if (timezone != 0) {
 718             gc = this.normalize();
 719         }
 720         
 721         int[] elements = {gc.getYear(), gc.getMonth(), gc.getDay(), gc.getHour(), 
 722             gc.getMinute(), gc.getSecond(), gc.getMillisecond()};
 723         return Arrays.hashCode(elements);
 724     }
 725 
 726     /**
 727      * Return the lexical representation of {@code this} instance.
 728      * The format is specified in
 729      * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
 730      * <i>Lexical Representation</i>".</a>
 731      *
 732      * <p>Specific target lexical representation format is determined by
 733      * {@link #getXMLSchemaType()}.
 734      *
 735      * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar}
 736      *
 737      * @throws IllegalStateException if the combination of set fields
 738      *    does not match one of the eight defined XML Schema builtin date/time datatypes.
 739      */
 740     public abstract String toXMLFormat();
 741 
 742     /**
 743      * Return the name of the XML Schema date/time type that this instance
 744      * maps to. Type is computed based on fields that are set.
 745      *
 746      * <table class="striped">
 747      *   <caption>Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
 748      *         <i>(timezone is optional for all date/time datatypes)</i></caption>
 749      *   <thead>
 750      *     <tr>
 751      *       <th scope="col">Datatype</th>
 752      *       <th scope="col">year</th>
 753      *       <th scope="col">month</th>
 754      *       <th scope="col">day</th>
 755      *       <th scope="col">hour</th>
 756      *       <th scope="col">minute</th>
 757      *       <th scope="col">second</th>
 758      *     </tr>
 759      *   </thead>
 760      *   <tbody>
 761      *     <tr>
 762      *       <th scope="row">{@link DatatypeConstants#DATETIME}</th>
 763      *       <td>X</td>
 764      *       <td>X</td>
 765      *       <td>X</td>
 766      *       <td>X</td>
 767      *       <td>X</td>
 768      *       <td>X</td>
 769      *     </tr>
 770      *     <tr>
 771      *       <th scope="row">{@link DatatypeConstants#DATE}</th>
 772      *       <td>X</td>
 773      *       <td>X</td>
 774      *       <td>X</td>
 775      *       <td></td>
 776      *       <td></td>
 777      *       <td></td>
 778      *     </tr>
 779      *     <tr>
 780      *       <th scope="row">{@link DatatypeConstants#TIME}</th>
 781      *       <td></td>
 782      *       <td></td>
 783      *       <td></td>
 784      *       <td>X</td>
 785      *       <td>X</td>
 786      *       <td>X</td>
 787      *     </tr>
 788      *     <tr>
 789      *       <th scope="row">{@link DatatypeConstants#GYEARMONTH}</th>
 790      *       <td>X</td>
 791      *       <td>X</td>
 792      *       <td></td>
 793      *       <td></td>
 794      *       <td></td>
 795      *       <td></td>
 796      *     </tr>
 797      *     <tr>
 798      *       <th scope="row">{@link DatatypeConstants#GMONTHDAY}</th>
 799      *       <td></td>
 800      *       <td>X</td>
 801      *       <td>X</td>
 802      *       <td></td>
 803      *       <td></td>
 804      *       <td></td>
 805      *     </tr>
 806      *     <tr>
 807      *       <th scope="row">{@link DatatypeConstants#GYEAR}</th>
 808      *       <td>X</td>
 809      *       <td></td>
 810      *       <td></td>
 811      *       <td></td>
 812      *       <td></td>
 813      *       <td></td>
 814      *     </tr>
 815      *     <tr>
 816      *       <th scope="row">{@link DatatypeConstants#GMONTH}</th>
 817      *       <td></td>
 818      *       <td>X</td>
 819      *       <td></td>
 820      *       <td></td>
 821      *       <td></td>
 822      *       <td></td>
 823      *     </tr>
 824      *     <tr>
 825      *       <th scope="row">{@link DatatypeConstants#GDAY}</th>
 826      *       <td></td>
 827      *       <td></td>
 828      *       <td>X</td>
 829      *       <td></td>
 830      *       <td></td>
 831      *       <td></td>
 832      *     </tr>
 833      *   </tbody>
 834      * </table>
 835      *
 836      * @throws java.lang.IllegalStateException if the combination of set fields
 837      *    does not match one of the eight defined XML Schema builtin
 838      *    date/time datatypes.
 839      * @return One of the following class constants:
 840      *   {@link DatatypeConstants#DATETIME},
 841      *   {@link DatatypeConstants#TIME},
 842      *   {@link DatatypeConstants#DATE},
 843      *   {@link DatatypeConstants#GYEARMONTH},
 844      *   {@link DatatypeConstants#GMONTHDAY},
 845      *   {@link DatatypeConstants#GYEAR},
 846      *   {@link DatatypeConstants#GMONTH} or
 847      *   {@link DatatypeConstants#GDAY}.
 848      */
 849     public abstract QName getXMLSchemaType();
 850 
 851     /**
 852      * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
 853      *
 854      * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
 855      *
 856      * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
 857      *
 858      * @throws IllegalStateException if the combination of set fields
 859      *    does not match one of the eight defined XML Schema builtin date/time datatypes.
 860      *
 861      * @see #toXMLFormat()
 862      */
 863     @Override
 864     public String toString() {
 865 
 866         return toXMLFormat();
 867     }
 868 
 869     /**
 870      * Validate instance by {@code getXMLSchemaType()} constraints.
 871      * @return true if data values are valid.
 872      */
 873     public abstract boolean isValid();
 874 
 875     /**
 876      * Add {@code duration} to this instance.
 877      *
 878      * <p>The computation is specified in
 879      * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
 880      * <i>Adding durations to dateTimes</i></a>.
 881      * <a href="#datetimefieldmapping">date/time field mapping table</a>
 882      * defines the mapping from XML Schema 1.0 {@code dateTime} fields
 883      * to this class' representation of those fields.
 884      *
 885      * @param duration Duration to add to this {@code XMLGregorianCalendar}.
 886      *
 887      * @throws NullPointerException  when {@code duration} parameter is {@code null}.
 888      */
 889     public abstract void add(Duration duration);
 890 
 891     /**
 892      * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}.
 893      *
 894      * <p>When {@code this} instance has an undefined field, this
 895      * conversion relies on the {@code java.util.GregorianCalendar} default
 896      * for its corresponding field. A notable difference between
 897      * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar}
 898      * is that Timezone value is optional for date/time datatypes and it is
 899      * a required field for {@code java.util.GregorianCalendar}. See javadoc
 900      * for {@code java.util.TimeZone.getDefault()} on how the default
 901      * is determined. To explicitly specify the {@code TimeZone}
 902      * instance, see
 903      * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
 904      *
 905      * <table class="striped">
 906      *   <caption>Field by Field Conversion from this class to
 907      *          {@code java.util.GregorianCalendar}</caption>
 908      *   <thead>
 909      *     <tr>
 910      *        <th scope="col">{@code java.util.GregorianCalendar} field</th>
 911      *        <th scope="col">{@code javax.xml.datatype.XMLGregorianCalendar} field</th>
 912      *     </tr>
 913      *   </thead>
 914      *   <tbody>
 915      *     <tr>
 916      *       <th scope="row">{@code ERA}</th>
 917      *       <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td>
 918      *     </tr>
 919      *     <tr>
 920      *       <th scope="row">{@code YEAR}</th>
 921      *       <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td>
 922      *     </tr>
 923      *     <tr>
 924      *       <th scope="row">{@code MONTH}</th>
 925      *       <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
 926      *     </tr>
 927      *     <tr>
 928      *       <th scope="row">{@code DAY_OF_MONTH}</th>
 929      *       <td>{@link #getDay()}</td>
 930      *     </tr>
 931      *     <tr>
 932      *       <th scope="row">{@code HOUR_OF_DAY}</th>
 933      *       <td>{@link #getHour()}</td>
 934      *     </tr>
 935      *     <tr>
 936      *       <th scope="row">{@code MINUTE}</th>
 937      *       <td>{@link #getMinute()}</td>
 938      *     </tr>
 939      *     <tr>
 940      *       <th scope="row">{@code SECOND}</th>
 941      *       <td>{@link #getSecond()}</td>
 942      *     </tr>
 943      *     <tr>
 944      *       <th scope="row">{@code MILLISECOND}</th>
 945      *       <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td>
 946      *     </tr>
 947      *     <tr>
 948      *       <th scope="row">{@code GregorianCalendar.setTimeZone(TimeZone)}</th>
 949      *       <td>{@link #getTimezone()} formatted into Custom timezone id</td>
 950      *     </tr>
 951      *   </tbody>
 952      * </table>
 953      * <i>*</i> designates possible loss of precision during the conversion due
 954      * to source datatype having higher precision than target datatype.
 955      *
 956      * <p>To ensure consistency in conversion implementations, the new
 957      * {@code GregorianCalendar} should be instantiated in following
 958      * manner.
 959      * <ul>
 960      *   <li>Using {@code timeZone} value as defined above, create a new
 961      * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}.
 962      *   </li>
 963      *   <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
 964      *   <li>Obtain a pure Gregorian Calendar by invoking
 965      *   {@code GregorianCalendar.setGregorianChange(
 966      *   new Date(Long.MIN_VALUE))}.</li>
 967      *   <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
 968      *       MINUTE, SECOND and MILLISECOND are set using the method
 969      *       {@code Calendar.set(int,int)}</li>
 970      * </ul>
 971      *
 972      * @return An instance of {@link java.util.GregorianCalendar}.
 973      *
 974      * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
 975      */
 976     public abstract GregorianCalendar toGregorianCalendar();
 977 
 978     /**
 979      * Convert this {@code XMLGregorianCalendar} along with provided parameters
 980      * to a {@link GregorianCalendar} instance.
 981      *
 982      * <p> Since XML Schema 1.0 date/time datetypes has no concept of
 983      * timezone ids or daylight savings timezone ids, this conversion operation
 984      * allows the user to explicitly specify one with
 985      * {@code timezone} parameter.
 986      *
 987      * <p>To compute the return value's {@code TimeZone} field,
 988      * <ul>
 989      * <li>when parameter {@code timeZone} is non-null,
 990      * it is the timezone field.</li>
 991      * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED},
 992      * create a {@code java.util.TimeZone} with a custom timezone id
 993      * using the {@code this.getTimezone()}.</li>
 994      * <li>else when {@code defaults.getTimezone() != FIELD_UNDEFINED},
 995      * create a {@code java.util.TimeZone} with a custom timezone id
 996      * using {@code defaults.getTimezone()}.</li>
 997      * <li>else use the {@code GregorianCalendar} default timezone value
 998      * for the host is defined as specified by
 999      * {@code java.util.TimeZone.getDefault()}.</li>
1000      * </ul>
1001      *
1002      * <p>To ensure consistency in conversion implementations, the new
1003      * {@code GregorianCalendar} should be instantiated in following
1004      * manner.
1005      * <ul>
1006      *   <li>Create a new {@code java.util.GregorianCalendar(TimeZone,
1007      *       Locale)} with TimeZone set as specified above and the
1008      *       {@code Locale} parameter.
1009      *   </li>
1010      *   <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li>
1011      *   <li>Obtain a pure Gregorian Calendar by invoking
1012      *   {@code GregorianCalendar.setGregorianChange(
1013      *   new Date(Long.MIN_VALUE))}.</li>
1014      *   <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
1015      *       MINUTE, SECOND and MILLISECOND are set using the method
1016      *       {@code Calendar.set(int,int)}</li>
1017      * </ul>
1018      *
1019      * @param timezone provide Timezone. {@code null} is a legal value.
1020      * @param aLocale  provide explicit Locale. Use default GregorianCalendar locale if
1021      *                 value is {@code null}.
1022      * @param defaults provide default field values to use when corresponding
1023      *                 field for this instance is FIELD_UNDEFINED or null.
1024      *                 If {@code defaults}is {@code null} or a field
1025      *                 within the specified {@code defaults} is undefined,
1026      *                 just use {@code java.util.GregorianCalendar} defaults.
1027      * @return a java.util.GregorianCalendar conversion of this instance.
1028      */
1029     public abstract GregorianCalendar toGregorianCalendar(
1030             java.util.TimeZone timezone,
1031             java.util.Locale aLocale,
1032             XMLGregorianCalendar defaults);
1033 
1034     /**
1035      * Returns a {@code java.util.TimeZone} for this class.
1036      *
1037      * <p>If timezone field is defined for this instance,
1038      * returns TimeZone initialized with custom timezone id
1039      * of zoneoffset. If timezone field is undefined,
1040      * try the defaultZoneoffset that was passed in.
1041      * If defaultZoneoffset is FIELD_UNDEFINED, return
1042      * default timezone for this host.
1043      * (Same default as java.util.GregorianCalendar).
1044      *
1045      * @param defaultZoneoffset default zoneoffset if this zoneoffset is
1046      * {@link DatatypeConstants#FIELD_UNDEFINED}.
1047      *
1048      * @return TimeZone for this.
1049      */
1050     public abstract TimeZone getTimeZone(int defaultZoneoffset);
1051 
1052 
1053 
1054     /**
1055      * Creates and returns a copy of this object.
1056      *
1057      * @return copy of this {@code Object}
1058      */
1059     @Override
1060     public abstract Object clone();
1061 }