View Javadoc
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 }