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