KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > datatype > XMLGregorianCalendar


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