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