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