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 BigInteger ey = gc.getEonAndYear(); 722 int result = 31 + ((ey == null) ? 0 : ey.hashCode()); 723 int[] elements = {gc.getMonth(), gc.getDay(), gc.getHour(), 724 gc.getMinute(), gc.getSecond()}; 725 result = 31 * result + Arrays.hashCode(elements); 726 BigDecimal fs = gc.getFractionalSecond(); 727 result = 31 * result + ((fs == null) ? 0 : fs.hashCode()); 728 return result; 729 } 730 731 /** 732 * Return the lexical representation of {@code this} instance. 733 * The format is specified in 734 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1, 735 * <i>Lexical Representation</i>".</a> 736 * 737 * <p>Specific target lexical representation format is determined by 738 * {@link #getXMLSchemaType()}. 739 * 740 * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar} 741 * 742 * @throws IllegalStateException if the combination of set fields 743 * does not match one of the eight defined XML Schema builtin date/time datatypes. 744 */ 745 public abstract String toXMLFormat(); 746 747 /** 748 * Return the name of the XML Schema date/time type that this instance 749 * maps to. Type is computed based on fields that are set. 750 * 751 * <table class="striped"> 752 * <caption>Required fields for XML Schema 1.0 Date/Time Datatypes.<br> 753 * <i>(timezone is optional for all date/time datatypes)</i></caption> 754 * <thead> 755 * <tr> 756 * <th scope="col">Datatype</th> 757 * <th scope="col">year</th> 758 * <th scope="col">month</th> 759 * <th scope="col">day</th> 760 * <th scope="col">hour</th> 761 * <th scope="col">minute</th> 762 * <th scope="col">second</th> 763 * </tr> 764 * </thead> 765 * <tbody> 766 * <tr> 767 * <th scope="row">{@link DatatypeConstants#DATETIME}</th> 768 * <td>X</td> 769 * <td>X</td> 770 * <td>X</td> 771 * <td>X</td> 772 * <td>X</td> 773 * <td>X</td> 774 * </tr> 775 * <tr> 776 * <th scope="row">{@link DatatypeConstants#DATE}</th> 777 * <td>X</td> 778 * <td>X</td> 779 * <td>X</td> 780 * <td></td> 781 * <td></td> 782 * <td></td> 783 * </tr> 784 * <tr> 785 * <th scope="row">{@link DatatypeConstants#TIME}</th> 786 * <td></td> 787 * <td></td> 788 * <td></td> 789 * <td>X</td> 790 * <td>X</td> 791 * <td>X</td> 792 * </tr> 793 * <tr> 794 * <th scope="row">{@link DatatypeConstants#GYEARMONTH}</th> 795 * <td>X</td> 796 * <td>X</td> 797 * <td></td> 798 * <td></td> 799 * <td></td> 800 * <td></td> 801 * </tr> 802 * <tr> 803 * <th scope="row">{@link DatatypeConstants#GMONTHDAY}</th> 804 * <td></td> 805 * <td>X</td> 806 * <td>X</td> 807 * <td></td> 808 * <td></td> 809 * <td></td> 810 * </tr> 811 * <tr> 812 * <th scope="row">{@link DatatypeConstants#GYEAR}</th> 813 * <td>X</td> 814 * <td></td> 815 * <td></td> 816 * <td></td> 817 * <td></td> 818 * <td></td> 819 * </tr> 820 * <tr> 821 * <th scope="row">{@link DatatypeConstants#GMONTH}</th> 822 * <td></td> 823 * <td>X</td> 824 * <td></td> 825 * <td></td> 826 * <td></td> 827 * <td></td> 828 * </tr> 829 * <tr> 830 * <th scope="row">{@link DatatypeConstants#GDAY}</th> 831 * <td></td> 832 * <td></td> 833 * <td>X</td> 834 * <td></td> 835 * <td></td> 836 * <td></td> 837 * </tr> 838 * </tbody> 839 * </table> 840 * 841 * @throws java.lang.IllegalStateException if the combination of set fields 842 * does not match one of the eight defined XML Schema builtin 843 * date/time datatypes. 844 * @return One of the following class constants: 845 * {@link DatatypeConstants#DATETIME}, 846 * {@link DatatypeConstants#TIME}, 847 * {@link DatatypeConstants#DATE}, 848 * {@link DatatypeConstants#GYEARMONTH}, 849 * {@link DatatypeConstants#GMONTHDAY}, 850 * {@link DatatypeConstants#GYEAR}, 851 * {@link DatatypeConstants#GMONTH} or 852 * {@link DatatypeConstants#GDAY}. 853 */ 854 public abstract QName getXMLSchemaType(); 855 856 /** 857 * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}. 858 * 859 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}. 860 * 861 * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}. 862 * 863 * @throws IllegalStateException if the combination of set fields 864 * does not match one of the eight defined XML Schema builtin date/time datatypes. 865 * 866 * @see #toXMLFormat() 867 */ 868 @Override 869 public String toString() { 870 871 return toXMLFormat(); 872 } 873 874 /** 875 * Validate instance by {@code getXMLSchemaType()} constraints. 876 * @return true if data values are valid. 877 */ 878 public abstract boolean isValid(); 879 880 /** 881 * Add {@code duration} to this instance. 882 * 883 * <p>The computation is specified in 884 * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E, 885 * <i>Adding durations to dateTimes</i></a>. 886 * <a href="#datetimefieldmapping">date/time field mapping table</a> 887 * defines the mapping from XML Schema 1.0 {@code dateTime} fields 888 * to this class' representation of those fields. 889 * 890 * @param duration Duration to add to this {@code XMLGregorianCalendar}. 891 * 892 * @throws NullPointerException when {@code duration} parameter is {@code null}. 893 */ 894 public abstract void add(Duration duration); 895 896 /** 897 * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}. 898 * 899 * <p>When {@code this} instance has an undefined field, this 900 * conversion relies on the {@code java.util.GregorianCalendar} default 901 * for its corresponding field. A notable difference between 902 * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar} 903 * is that Timezone value is optional for date/time datatypes and it is 904 * a required field for {@code java.util.GregorianCalendar}. See javadoc 905 * for {@code java.util.TimeZone.getDefault()} on how the default 906 * is determined. To explicitly specify the {@code TimeZone} 907 * instance, see 908 * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}. 909 * 910 * <table class="striped"> 911 * <caption>Field by Field Conversion from this class to 912 * {@code java.util.GregorianCalendar}</caption> 913 * <thead> 914 * <tr> 915 * <th scope="col">{@code java.util.GregorianCalendar} field</th> 916 * <th scope="col">{@code javax.xml.datatype.XMLGregorianCalendar} field</th> 917 * </tr> 918 * </thead> 919 * <tbody> 920 * <tr> 921 * <th scope="row">{@code ERA}</th> 922 * <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td> 923 * </tr> 924 * <tr> 925 * <th scope="row">{@code YEAR}</th> 926 * <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td> 927 * </tr> 928 * <tr> 929 * <th scope="row">{@code MONTH}</th> 930 * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td> 931 * </tr> 932 * <tr> 933 * <th scope="row">{@code DAY_OF_MONTH}</th> 934 * <td>{@link #getDay()}</td> 935 * </tr> 936 * <tr> 937 * <th scope="row">{@code HOUR_OF_DAY}</th> 938 * <td>{@link #getHour()}</td> 939 * </tr> 940 * <tr> 941 * <th scope="row">{@code MINUTE}</th> 942 * <td>{@link #getMinute()}</td> 943 * </tr> 944 * <tr> 945 * <th scope="row">{@code SECOND}</th> 946 * <td>{@link #getSecond()}</td> 947 * </tr> 948 * <tr> 949 * <th scope="row">{@code MILLISECOND}</th> 950 * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td> 951 * </tr> 952 * <tr> 953 * <th scope="row">{@code GregorianCalendar.setTimeZone(TimeZone)}</th> 954 * <td>{@link #getTimezone()} formatted into Custom timezone id</td> 955 * </tr> 956 * </tbody> 957 * </table> 958 * <i>*</i> designates possible loss of precision during the conversion due 959 * to source datatype having higher precision than target datatype. 960 * 961 * <p>To ensure consistency in conversion implementations, the new 962 * {@code GregorianCalendar} should be instantiated in following 963 * manner. 964 * <ul> 965 * <li>Using {@code timeZone} value as defined above, create a new 966 * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}. 967 * </li> 968 * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li> 969 * <li>Obtain a pure Gregorian Calendar by invoking 970 * {@code GregorianCalendar.setGregorianChange( 971 * new Date(Long.MIN_VALUE))}.</li> 972 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 973 * MINUTE, SECOND and MILLISECOND are set using the method 974 * {@code Calendar.set(int,int)}</li> 975 * </ul> 976 * 977 * @return An instance of {@link java.util.GregorianCalendar}. 978 * 979 * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) 980 */ 981 public abstract GregorianCalendar toGregorianCalendar(); 982 983 /** 984 * Convert this {@code XMLGregorianCalendar} along with provided parameters 985 * to a {@link GregorianCalendar} instance. 986 * 987 * <p> Since XML Schema 1.0 date/time datetypes has no concept of 988 * timezone ids or daylight savings timezone ids, this conversion operation 989 * allows the user to explicitly specify one with 990 * {@code timezone} parameter. 991 * 992 * <p>To compute the return value's {@code TimeZone} field, 993 * <ul> 994 * <li>when parameter {@code timeZone} is non-null, 995 * it is the timezone field.</li> 996 * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED}, 997 * create a {@code java.util.TimeZone} with a custom timezone id 998 * using the {@code this.getTimezone()}.</li> 999 * <li>else when {@code defaults.getTimezone() != FIELD_UNDEFINED}, 1000 * create a {@code java.util.TimeZone} with a custom timezone id 1001 * using {@code defaults.getTimezone()}.</li> 1002 * <li>else use the {@code GregorianCalendar} default timezone value 1003 * for the host is defined as specified by 1004 * {@code java.util.TimeZone.getDefault()}.</li> 1005 * </ul> 1006 * 1007 * <p>To ensure consistency in conversion implementations, the new 1008 * {@code GregorianCalendar} should be instantiated in following 1009 * manner. 1010 * <ul> 1011 * <li>Create a new {@code java.util.GregorianCalendar(TimeZone, 1012 * Locale)} with TimeZone set as specified above and the 1013 * {@code Locale} parameter. 1014 * </li> 1015 * <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li> 1016 * <li>Obtain a pure Gregorian Calendar by invoking 1017 * {@code GregorianCalendar.setGregorianChange( 1018 * new Date(Long.MIN_VALUE))}.</li> 1019 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 1020 * MINUTE, SECOND and MILLISECOND are set using the method 1021 * {@code Calendar.set(int,int)}</li> 1022 * </ul> 1023 * 1024 * @param timezone provide Timezone. {@code null} is a legal value. 1025 * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if 1026 * value is {@code null}. 1027 * @param defaults provide default field values to use when corresponding 1028 * field for this instance is FIELD_UNDEFINED or null. 1029 * If {@code defaults}is {@code null} or a field 1030 * within the specified {@code defaults} is undefined, 1031 * just use {@code java.util.GregorianCalendar} defaults. 1032 * @return a java.util.GregorianCalendar conversion of this instance. 1033 */ 1034 public abstract GregorianCalendar toGregorianCalendar( 1035 java.util.TimeZone timezone, 1036 java.util.Locale aLocale, 1037 XMLGregorianCalendar defaults); 1038 1039 /** 1040 * Returns a {@code java.util.TimeZone} for this class. 1041 * 1042 * <p>If timezone field is defined for this instance, 1043 * returns TimeZone initialized with custom timezone id 1044 * of zoneoffset. If timezone field is undefined, 1045 * try the defaultZoneoffset that was passed in. 1046 * If defaultZoneoffset is FIELD_UNDEFINED, return 1047 * default timezone for this host. 1048 * (Same default as java.util.GregorianCalendar). 1049 * 1050 * @param defaultZoneoffset default zoneoffset if this zoneoffset is 1051 * {@link DatatypeConstants#FIELD_UNDEFINED}. 1052 * 1053 * @return TimeZone for this. 1054 */ 1055 public abstract TimeZone getTimeZone(int defaultZoneoffset); 1056 1057 1058 1059 /** 1060 * Creates and returns a copy of this object. 1061 * 1062 * @return copy of this {@code Object} 1063 */ 1064 @Override 1065 public abstract Object clone(); 1066 }