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 * Returns the 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 The 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 * Returns the 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 The year of this {@code XMLGregorianCalendar}.
491 *
492 * @see #getEon()
493 * @see #getEonAndYear()
494 */
495 public abstract int getYear();
496
497 /**
498 * Returns the 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 The month of this {@code XMLGregorianCalendar}, from 1 to 12.
521 *
522 */
523 public abstract int getMonth();
524
525 /**
526 * Returns the day of 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 The day of month of this {@code XMLGregorianCalendar}, from 1 to 31.
532 *
533 * @see #setDay(int)
534 */
535 public abstract int getDay();
536
537 /**
538 * Returns the 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 The Timezone offset in minutes of this {@code XMLGregorianCalendar}.
545 *
546 * @see #setTimezone(int)
547 */
548 public abstract int getTimezone();
549
550 /**
551 * Returns the hour of day or
552 * {@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 The hour of day of this {@code XMLGregorianCalendar}, from 0 to 23.
558 *
559 * @see #setTime(int, int, int)
560 */
561 public abstract int getHour();
562
563 /**
564 * Returns the minute of hour or
565 * {@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 The minute of hour of this {@code XMLGregorianCalendar}, from 0 to 59.
571 *
572 * @see #setTime(int, int, int)
573 */
574 public abstract int getMinute();
575
576 /**
577 * Returns the second of minute or
578 * {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
579 * When this field is not defined, the optional xs:dateTime
580 * fractional seconds field, represented by
581 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
582 * must not be defined.
583 *
584 * <p>Value constraints for this value are summarized in
585 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
586 *
587 * @return The second of minute of this {@code XMLGregorianCalendar}, from 0 to 59.
588 *
589 * @see #getFractionalSecond()
590 * @see #getMillisecond()
591 * @see #setTime(int, int, int)
592 */
593 public abstract int getSecond();
594
595 /**
596 * Returns the millisecond precision of {@link #getFractionalSecond()}.
597 *
598 * <p>This method represents a convenience accessor to infinite
599 * precision fractional second value returned by
600 * {@link #getFractionalSecond()}. The returned value is the rounded
601 * down to milliseconds value of
602 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
603 * returns {@code null}, this method must return
604 * {@link DatatypeConstants#FIELD_UNDEFINED}.
605 *
606 * <p>Value constraints for this value are summarized in
607 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
608 *
609 * @return The millisecond precision of this {@code XMLGregorianCalendar}.
610 *
611 * @see #getFractionalSecond()
612 * @see #setTime(int, int, int)
613 */
614 public int getMillisecond() {
615
616 BigDecimal fractionalSeconds = getFractionalSecond();
617
618 // is field undefined?
619 if (fractionalSeconds == null) {
620 return DatatypeConstants.FIELD_UNDEFINED;
621 }
622
623 return getFractionalSecond().movePointRight(3).intValue();
624 }
625
626 /**
627 * Returns fractional seconds.
628 *
629 * <p>{@code null} is returned when this optional field is not defined.
630 *
631 * <p>Value constraints are detailed in
632 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
633 *
634 * <p>This optional field can only have a defined value when the
635 * xs:dateTime second field, represented by {@link #getSecond()},
636 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.
637 *
638 * @return Fractional seconds of this {@code XMLGregorianCalendar}.
639 *
640 * @see #getSecond()
641 * @see #setTime(int, int, int, BigDecimal)
642 */
643 public abstract BigDecimal getFractionalSecond();
644
645 // comparisons
646 /**
647 * Compare two instances of W3C XML Schema 1.0 date/time datatypes
648 * according to partial order relation defined in
649 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
650 * <i>Order relation on dateTime</i></a>.
651 *
652 * <p>{@code xsd:dateTime} datatype field mapping to accessors of
653 * this class are defined in
654 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
655 *
656 * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare
657 *
658 * @return The relationship between {@code this} {@code XMLGregorianCalendar} and
659 * the specified {@code xmlGregorianCalendar} as
660 * {@link DatatypeConstants#LESSER},
661 * {@link DatatypeConstants#EQUAL},
662 * {@link DatatypeConstants#GREATER} or
663 * {@link DatatypeConstants#INDETERMINATE}.
664 *
665 * @throws NullPointerException if {@code xmlGregorianCalendar} is null.
666 */
667 public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar);
668
669 /**
670 * Normalize this instance to UTC.
671 *
672 * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z
673 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
674 *
675 * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
676 */
677 public abstract XMLGregorianCalendar normalize();
678
679 /**
680 * Compares this calendar to the specified object. The result is
681 * {@code true} if and only if the argument is not null and is an
682 * {@code XMLGregorianCalendar} object that represents the same
683 * instant in time as this object.
684 *
685 * @param obj to compare.
686 *
687 * @return {@code true} when {@code obj} is an instance of
688 * {@code XMLGregorianCalendar} and
689 * {@link #compare(XMLGregorianCalendar obj)}
690 * returns {@link DatatypeConstants#EQUAL},
691 * otherwise {@code false}.
692 */
693 @Override
694 public boolean equals(Object obj) {
695
696 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
697 return false;
698 }
699 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
700 }
701
702 /**
703 * Returns a hash code consistent with the definition of the equals method.
704 *
705 * @return hash code of this object.
706 */
707 @Override
708 public int hashCode() {
709
710 // Following two dates compare to EQUALS since in different timezones.
711 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
712 //
713 // Must ensure both instances generate same hashcode by normalizing
714 // this to UTC timezone.
715 int timezone = getTimezone();
716 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
717 timezone = 0;
718 }
719 XMLGregorianCalendar gc = this;
720 if (timezone != 0) {
721 gc = this.normalize();
722 }
723 return gc.getYear()
724 + gc.getMonth()
725 + gc.getDay()
726 + gc.getHour()
727 + gc.getMinute()
728 + gc.getSecond();
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 border="2" rules="all" cellpadding="2">
752 * <thead>
753 * <tr>
754 * <th align="center" colspan="7">
755 * Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
756 * <i>(timezone is optional for all date/time datatypes)</i>
757 * </th>
758 * </tr>
759 * </thead>
760 * <tbody>
761 * <tr>
762 * <td>Datatype</td>
763 * <td>year</td>
764 * <td>month</td>
765 * <td>day</td>
766 * <td>hour</td>
767 * <td>minute</td>
768 * <td>second</td>
769 * </tr>
770 * <tr>
771 * <td>{@link DatatypeConstants#DATETIME}</td>
772 * <td>X</td>
773 * <td>X</td>
774 * <td>X</td>
775 * <td>X</td>
776 * <td>X</td>
777 * <td>X</td>
778 * </tr>
779 * <tr>
780 * <td>{@link DatatypeConstants#DATE}</td>
781 * <td>X</td>
782 * <td>X</td>
783 * <td>X</td>
784 * <td></td>
785 * <td></td>
786 * <td></td>
787 * </tr>
788 * <tr>
789 * <td>{@link DatatypeConstants#TIME}</td>
790 * <td></td>
791 * <td></td>
792 * <td></td>
793 * <td>X</td>
794 * <td>X</td>
795 * <td>X</td>
796 * </tr>
797 * <tr>
798 * <td>{@link DatatypeConstants#GYEARMONTH}</td>
799 * <td>X</td>
800 * <td>X</td>
801 * <td></td>
802 * <td></td>
803 * <td></td>
804 * <td></td>
805 * </tr>
806 * <tr>
807 * <td>{@link DatatypeConstants#GMONTHDAY}</td>
808 * <td></td>
809 * <td>X</td>
810 * <td>X</td>
811 * <td></td>
812 * <td></td>
813 * <td></td>
814 * </tr>
815 * <tr>
816 * <td>{@link DatatypeConstants#GYEAR}</td>
817 * <td>X</td>
818 * <td></td>
819 * <td></td>
820 * <td></td>
821 * <td></td>
822 * <td></td>
823 * </tr>
824 * <tr>
825 * <td>{@link DatatypeConstants#GMONTH}</td>
826 * <td></td>
827 * <td>X</td>
828 * <td></td>
829 * <td></td>
830 * <td></td>
831 * <td></td>
832 * </tr>
833 * <tr>
834 * <td>{@link DatatypeConstants#GDAY}</td>
835 * <td></td>
836 * <td></td>
837 * <td>X</td>
838 * <td></td>
839 * <td></td>
840 * <td></td>
841 * </tr>
842 * </tbody>
843 * </table>
844 *
845 * @throws java.lang.IllegalStateException if the combination of set fields
846 * does not match one of the eight defined XML Schema builtin
847 * date/time datatypes.
848 * @return One of the following class constants:
849 * {@link DatatypeConstants#DATETIME},
850 * {@link DatatypeConstants#TIME},
851 * {@link DatatypeConstants#DATE},
852 * {@link DatatypeConstants#GYEARMONTH},
853 * {@link DatatypeConstants#GMONTHDAY},
854 * {@link DatatypeConstants#GYEAR},
855 * {@link DatatypeConstants#GMONTH} or
856 * {@link DatatypeConstants#GDAY}.
857 */
858 public abstract QName getXMLSchemaType();
859
860 /**
861 * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
862 *
863 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
864 *
865 * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
866 *
867 * @throws IllegalStateException if the combination of set fields
868 * does not match one of the eight defined XML Schema builtin date/time datatypes.
869 *
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 An instance of {@link java.util.GregorianCalendar}.
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 /**
1068 * Creates and returns a copy of this object.
1069 *
1070 * @return copy of this {@code Object}
1071 */
1072 @Override
1073 public abstract Object clone();
1074 }