1 /*
2 * Copyright (c) 2004, 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 com.sun.org.apache.xerces.internal.jaxp.datatype;
27
28 import java.io.Serializable;
29 import java.math.BigDecimal;
30 import java.math.BigInteger;
31 import java.util.TimeZone;
32 import java.util.Calendar;
33 import java.util.GregorianCalendar;
34 import java.util.Date;
35 import java.util.Locale;
36
37 import javax.xml.datatype.DatatypeConstants;
38 import javax.xml.datatype.Duration;
39 import javax.xml.datatype.XMLGregorianCalendar;
40 import javax.xml.namespace.QName;
41 import com.sun.org.apache.xerces.internal.util.DatatypeMessageFormatter;
42 import com.sun.org.apache.xerces.internal.utils.SecuritySupport;
43
44 /**
45 * <p>Representation for W3C XML Schema 1.0 date/time datatypes.
46 * Specifically, these date/time datatypes are
47 * {@link DatatypeConstants#DATETIME dateTime},
48 * {@link DatatypeConstants#TIME time},
49 * {@link DatatypeConstants#DATE date},
50 * {@link DatatypeConstants#GYEARMONTH gYearMonth},
51 * {@link DatatypeConstants#GMONTHDAY gMonthDay},
52 * {@link DatatypeConstants#GYEAR gYear},
53 * {@link DatatypeConstants#GMONTH gMonth} and
54 * {@link DatatypeConstants#GDAY gDay}
55 * defined in the XML Namespace
56 * <code>"http://www.w3.org/2001/XMLSchema"</code>.
57 * These datatypes are normatively defined in
58 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p>
59 *
60 * <p>The table below defines the mapping between XML Schema 1.0
61 * date/time datatype fields and this class' fields. It also summarizes
62 * the value constraints for the date and time fields defined in
63 * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
64 * <i>ISO 8601 Date and Time Formats</i></a>.</p>
65 *
66 * <a name="datetimefieldsmapping"/>
67 * <table border="2" rules="all" cellpadding="2">
68 * <thead>
69 * <tr>
70 * <th align="center" colspan="3">
71 * Date/time datatype field mapping between XML Schema 1.0 and Java representation
72 * </th>
73 * </tr>
74 * </thead>
75 * <tbody>
76 * <tr>
77 * <th>XML Schema 1.0<br/>
78 * datatype<br/>
79 * field</th>
80 * <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th>
81 * <th>Value Range</th>
82 * </tr>
83 * <a name="datetimefield-year"/>
84 * <tr>
85 * <td> year </td>
86 * <td> {@link #getYear()} + {@link #getEon()} or<br/>
87 * {@link #getEonAndYear}
88 * </td>
89 * <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1
90 * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
91 * {@link #getEon()} is high order year value in billion of years.<br/>
92 * <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9).
93 * A value of null indicates field is undefined.</br>
94 * 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
95 * will be a valid lexical value in a future version of XML Schema,
96 * this class allows the year field to be set to zero. Otherwise,
97 * the year field value is handled exactly as described
98 * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
99 * validation does not allow for the year field to have a value of zero.
100 * </td>
101 * </tr>
102 * <a name="datetimefield-month"/>
103 * <tr>
104 * <td> month </td>
105 * <td> {@link #getMonth()} </td>
106 * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
107 * </tr>
108 * <a name="datetimefield-day"/>
109 * <tr>
110 * <td> day </td>
111 * <td> {@link #getDay()} </td>
112 * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
113 * The normative value constraint stated relative to month
114 * 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>.
115 * </td>
116 * </tr>
117 * <a name="datetimefield-hour"/>
118 * <tr>
119 * <td> hour </td>
120 * <td> {@link #getHour()} </td>
121 * <td>
122 * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
123 * An hour value of 24 is allowed to be set in the lexical space provided the minute and second
124 * field values are zero. However, an hour value of 24 is not allowed in value space and will be
125 * transformed to represent the value of the first instance of the following day as per
126 * <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes">
127 * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>.
128 * </td>
129 * </tr>
130 * <a name="datetimefield-minute"/>
131 * <tr>
132 * <td> minute </td>
133 * <td> {@link #getMinute()} </td>
134 * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
135 * </tr>
136 * <a name="datetimefield-second"/>
137 * <tr>
138 * <td>second</td>
139 * <td>
140 * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/>
141 * {@link #getSecond()} + {@link #getFractionalSecond()}
142 * </td>
143 * <td>
144 * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
145 * <i>(Note: 60 only allowable for leap second.)</i><br/>
146 * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
147 * the {@link #getSecond()} is defined.<br/>
148 * <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br />
149 * {@link #getMillisecond()} is the convenience
150 * millisecond precision of value of {@link #getFractionalSecond()}.
151 * </td>
152 * </tr>
153 * <tr id="datetimefield-timezone">
154 * <td> timezone </td>
155 * <td> {@link #getTimezone()} </td>
156 * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
157 * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
158 * </td>
159 * </tr>
160 * </tbody>
161 * </table>
162 *
163 * <p>All maximum value space constraints listed for the fields in the table
164 * above are checked by factory methods, setter methods and parse methods of
165 * this class. <code>IllegalArgumentException</code> is thrown when
166 * parameter's value is outside the maximum value constraint for the field.
167 * Validation checks, for example, whether days in month should be
168 * limited to 29, 30 or 31 days, that are dependent on the values of other
169 * fields are not checked by these methods.
170 * </p>
171 *
172 * <p>The following operations are defined for this class:
173 * <ul>
174 * <li>factory methods to create instances</li>
175 * <li>accessors/mutators for independent date/time fields</li>
176 * <li>conversion between this class and W3C XML Schema 1.0 lexical representation</li>
177 * <li>conversion between this class and <code>java.util.GregorianCalendar</code></li>
178 * <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar)}</li>
179 * <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar)}.</li>
180 * <li> addition operation with {@link javax.xml.datatype.Duration}.
181 * instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">
182 * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.</li>
183 * </ul>
184 * </p>
185 *
186 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
187 * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>
188 * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a>
189 * @version $Revision: 1.14 $, $Date: 2010-11-10 07:41:41 $
190 * @see javax.xml.datatype.Duration
191 * @since 1.5
192 */
193
194 public class XMLGregorianCalendarImpl
195 extends XMLGregorianCalendar
196 implements Serializable, Cloneable {
197
198 /**
199 * <p>Eon of this <code>XMLGregorianCalendar</code>.</p>
200 */
201 private BigInteger eon = null;
202
203 /**
204 * <p>Year of this <code>XMLGregorianCalendar</code>.</p>
205 */
206 private int year = DatatypeConstants.FIELD_UNDEFINED;
207
208 /**
209 * <p>Month of this <code>XMLGregorianCalendar</code>.</p>
210 */
211 private int month = DatatypeConstants.FIELD_UNDEFINED;
212
213 /**
214 * <p>Day of this <code>XMLGregorianCalendar</code>.</p>
215 */
216 private int day = DatatypeConstants.FIELD_UNDEFINED;
217
218 /**
219 * <p>Timezone of this <code>XMLGregorianCalendar</code> in minutes.</p>
220 */
221 private int timezone = DatatypeConstants.FIELD_UNDEFINED;
222
223 /**
224 * <p>Hour of this <code>XMLGregorianCalendar</code>.</p>
225 */
226 private int hour = DatatypeConstants.FIELD_UNDEFINED;
227
228 /**
229 * <p>Minute of this <code>XMLGregorianCalendar</code>.</p>
230 */
231 private int minute = DatatypeConstants.FIELD_UNDEFINED;
232
233 /**
234 * <p>Second of this <code>XMLGregorianCalendar</code>.</p>
235 */
236 private int second = DatatypeConstants.FIELD_UNDEFINED ;
237
238 /**
239 * <p>Fractional second of this <code>XMLGregorianCalendar</code>.</p>
240 */
241 private BigDecimal fractionalSecond = null;
242
243 /**
244 * <p>Constant to represent a billion.</p>
245 */
246 private static final BigInteger BILLION = new BigInteger("1000000000");
247
248 /**
249 * <p>Obtain a pure Gregorian Calendar by calling
250 * GregorianCalendar.setChange(PURE_GREGORIAN_CHANGE). </p>
251 */
252 private static final Date PURE_GREGORIAN_CHANGE =
253 new Date(Long.MIN_VALUE);
254
255 /**
256 * Year index for MIN_ and MAX_FIELD_VALUES.
257 */
258 private static final int YEAR = 0;
259
260 /**
261 * Month index for MIN_ and MAX_FIELD_VALUES.
262 */
263 private static final int MONTH = 1;
264
265 /**
266 * Day index for MIN_ and MAX_FIELD_VALUES.
267 */
268 private static final int DAY = 2;
269
270 /**
271 * Hour index for MIN_ and MAX_FIELD_VALUES.
272 */
273 private static final int HOUR = 3;
274
275 /**
276 * Minute index for MIN_ and MAX_FIELD_VALUES.
277 */
278 private static final int MINUTE = 4;
279
280 /**
281 * Second index for MIN_ and MAX_FIELD_VALUES.
282 */
283 private static final int SECOND = 5;
284
285 /**
286 * Second index for MIN_ and MAX_FIELD_VALUES.
287 */
288 private static final int MILLISECOND = 6;
289
290 /**
291 * Timezone index for MIN_ and MAX_FIELD_VALUES
292 */
293 private static final int TIMEZONE = 7;
294
295
296 /**
297 * field names indexed by YEAR..TIMEZONE.
298 */
299 private static final String FIELD_NAME[] = {
300 "Year",
301 "Month",
302 "Day",
303 "Hour",
304 "Minute",
305 "Second",
306 "Millisecond",
307 "Timezone"
308 };
309
310 /**
311 * <p>Stream Unique Identifier.</p>
312 *
313 * <p>TODO: Serialization should use the XML string representation as
314 * the serialization format to ensure future compatibility.</p>
315 */
316 private static final long serialVersionUID = 1L;
317
318 /**
319 * <p>Use as a template for default field values when
320 * converting to a {@link GregorianCalendar}, set to a leap
321 * year date of January 1, 0400 at midnight.</p>
322 *
323 * <p>Fields that are optional for an <code>xsd:dateTime</code> instances are defaulted to not being set to any value.
324 * <code>XMLGregorianCalendar</code> fields millisecond, fractional second and timezone return the value indicating
325 * that the field is not set, {@link DatatypeConstants#FIELD_UNDEFINED} for millisecond and timezone
326 * and <code>null</code> for fractional second.</p>
327 *
328 * @see #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)
329 */
330 public static final XMLGregorianCalendar LEAP_YEAR_DEFAULT =
331 createDateTime(
332 400, //year
333 DatatypeConstants.JANUARY, //month
334 1, // day
335 0, // hour
336 0, // minute
337 0, // second
338 DatatypeConstants.FIELD_UNDEFINED, // milliseconds
339 DatatypeConstants.FIELD_UNDEFINED // timezone
340 );
341
342 // Constructors
343
344 /**
345 * Constructs a new XMLGregorianCalendar object.
346 *
347 * String parsing documented by {@link #parse(String)}.
348 *
349 * Returns a non-null valid XMLGregorianCalendar object that holds the
350 * value indicated by the lexicalRepresentation parameter.
351 *
352 * @param lexicalRepresentation
353 * Lexical representation of one the eight
354 * XML Schema date/time datatypes.
355 * @throws IllegalArgumentException
356 * If the given string does not conform as documented in
357 * {@link #parse(String)}.
358 * @throws NullPointerException
359 * If the given string is null.
360 */
361 protected XMLGregorianCalendarImpl(String lexicalRepresentation)
362 throws IllegalArgumentException {
363
364 // compute format string for this lexical representation.
365 String format = null;
366 String lexRep = lexicalRepresentation;
367 final int NOT_FOUND = -1;
368 int lexRepLength = lexRep.length();
369
370 // current parser needs a format string,
371 // use following heuristics to figure out what xml schema date/time
372 // datatype this lexical string could represent.
373 // Fix 4971612: invalid SCCS macro substitution in data string,
374 // no %{alpha}% to avoid SCCS maco substitution
375 if (lexRep.indexOf('T') != NOT_FOUND) {
376 // found Date Time separater, must be xsd:DateTime
377 format = "%Y-%M-%DT%h:%m:%s" + "%z";
378 } else if (lexRepLength >= 3 && lexRep.charAt(2) == ':') {
379 // found ":", must be xsd:Time
380 format = "%h:%m:%s" + "%z";
381 } else if (lexRep.startsWith("--")) {
382 // check for gDay || gMonth || gMonthDay
383 if (lexRepLength >= 3 && lexRep.charAt(2) == '-') {
384 // gDay, ---DD(z?)
385 format = "---%D" + "%z";
386 } else if (lexRepLength == 4 // --MM
387 || lexRepLength == 5 // --MMZ
388 || lexRepLength == 10) { // --MMSHH:MM
389 // gMonth, --MM(z?),
390 // per XML Schema Errata, used to be --MM--(z?)
391 format = "--%M" + "%z";
392 } else {
393 // gMonthDay, --MM-DD(z?), (or invalid lexicalRepresentation)
394 // length should be:
395 // 7: --MM-DD
396 // 8: --MM-DDZ
397 // 13: --MM-DDSHH:MM
398 format = "--%M-%D" + "%z";
399 }
400 } else {
401 // check for Date || GYear | GYearMonth
402 int countSeparator = 0;
403
404 // start at index 1 to skip potential negative sign for year.
405
406
407 int timezoneOffset = lexRep.indexOf(':');
408 if (timezoneOffset != NOT_FOUND) {
409
410 // found timezone, strip it off for distinguishing
411 // between Date, GYear and GYearMonth so possible
412 // negative sign in timezone is not mistaken as
413 // a separator.
414 lexRepLength -= 6;
415 }
416
417 for (int i = 1; i < lexRepLength; i++) {
418 if (lexRep.charAt(i) == '-') {
419 countSeparator++;
420 }
421 }
422 if (countSeparator == 0) {
423 // GYear
424 format = "%Y" + "%z";
425 } else if (countSeparator == 1) {
426 // GYearMonth
427 format = "%Y-%M" + "%z";
428 } else {
429 // Date or invalid lexicalRepresentation
430 // Fix 4971612: invalid SCCS macro substitution in data string
431 format = "%Y-%M-%D" + "%z";
432 }
433 }
434 Parser p = new Parser(format, lexRep);
435 p.parse();
436
437 // check for validity
438 if (!isValid()) {
439 throw new IllegalArgumentException(
440 DatatypeMessageFormatter.formatMessage(null, "InvalidXGCRepresentation", new Object[]{lexicalRepresentation})
441 //"\"" + lexicalRepresentation + "\" is not a valid representation of an XML Gregorian Calendar value."
442 );
443 }
444 }
445
446 /**
447 * <p>Create an instance with all date/time datatype fields set to
448 * {@link DatatypeConstants#FIELD_UNDEFINED} or null respectively.</p>
449 */
450 public XMLGregorianCalendarImpl() {
451
452 // field initializers already do the correct initialization.
453 }
454
455 /**
456 * <p>Private constructor allowing for complete value spaces allowed by
457 * W3C XML Schema 1.0 recommendation for xsd:dateTime and related
458 * builtin datatypes. Note that <code>year</code> parameter supports
459 * arbitrarily large numbers and fractionalSecond has infinite
460 * precision.</p>
461 *
462 * @param year of <code>XMLGregorianCalendar</code> to be created.
463 * @param month of <code>XMLGregorianCalendar</code> to be created.
464 * @param day of <code>XMLGregorianCalendar</code> to be created.
465 * @param hour of <code>XMLGregorianCalendar</code> to be created.
466 * @param minute of <code>XMLGregorianCalendar</code> to be created.
467 * @param second of <code>XMLGregorianCalendar</code> to be created.
468 * @param fractionalSecond of <code>XMLGregorianCalendar</code> to be created.
469 * @param timezone of <code>XMLGregorianCalendar</code> to be created.
470 *
471 */
472 protected XMLGregorianCalendarImpl(
473 BigInteger year,
474 int month,
475 int day,
476 int hour,
477 int minute,
478 int second,
479 BigDecimal fractionalSecond,
480 int timezone) {
481
482 setYear(year);
483 setMonth(month);
484 setDay(day);
485 setTime(hour, minute, second, fractionalSecond);
486 setTimezone(timezone);
487
488 // check for validity
489 if (!isValid()) {
490
491 throw new IllegalArgumentException(
492 DatatypeMessageFormatter.formatMessage(null,
493 "InvalidXGCValue-fractional",
494 new Object[] { year, new Integer(month), new Integer(day),
495 new Integer(hour), new Integer(minute), new Integer(second),
496 fractionalSecond, new Integer(timezone)})
497 );
498
499 /**
500 String yearString = "null";
501 if (year != null) {
502 yearString = year.toString();
503 }
504 String fractionalSecondString = "null";
505 if (fractionalSecond != null) {
506 fractionalSecondString = fractionalSecond.toString();
507 }
508
509 throw new IllegalArgumentException(
510 "year = " + yearString
511 + ", month = " + month
512 + ", day = " + day
513 + ", hour = " + hour
514 + ", minute = " + minute
515 + ", second = " + second
516 + ", fractionalSecond = " + fractionalSecondString
517 + ", timezone = " + timezone
518 + ", is not a valid representation of an XML Gregorian Calendar value."
519 );
520 */
521
522 }
523
524 }
525
526 /**
527 * <p>Private constructor of value spaces that a
528 * <code>java.util.GregorianCalendar</code> instance would need to convert to an
529 * <code>XMLGregorianCalendar</code> instance.</p>
530 *
531 * <p><code>XMLGregorianCalendar eon</code> and
532 * <code>fractionalSecond</code> are set to <code>null</code></p>
533 *
534 * @param year of <code>XMLGregorianCalendar</code> to be created.
535 * @param month of <code>XMLGregorianCalendar</code> to be created.
536 * @param day of <code>XMLGregorianCalendar</code> to be created.
537 * @param hour of <code>XMLGregorianCalendar</code> to be created.
538 * @param minute of <code>XMLGregorianCalendar</code> to be created.
539 * @param second of <code>XMLGregorianCalendar</code> to be created.
540 * @param millisecond of <code>XMLGregorianCalendar</code> to be created.
541 * @param timezone of <code>XMLGregorianCalendar</code> to be created.
542 */
543 private XMLGregorianCalendarImpl(
544 int year,
545 int month,
546 int day,
547 int hour,
548 int minute,
549 int second,
550 int millisecond,
551 int timezone) {
552
553 setYear(year);
554 setMonth(month);
555 setDay(day);
556 setTime(hour, minute, second);
557 setTimezone(timezone);
558 setMillisecond(millisecond);
559
560 if (!isValid()) {
561
562 throw new IllegalArgumentException(
563 DatatypeMessageFormatter.formatMessage(null,
564 "InvalidXGCValue-milli",
565 new Object[] { new Integer(year), new Integer(month), new Integer(day),
566 new Integer(hour), new Integer(minute), new Integer(second),
567 new Integer(millisecond), new Integer(timezone)})
568 );
569 /*
570 throw new IllegalArgumentException(
571 "year = " + year
572 + ", month = " + month
573 + ", day = " + day
574 + ", hour = " + hour
575 + ", minute = " + minute
576 + ", second = " + second
577 + ", millisecond = " + millisecond
578 + ", timezone = " + timezone
579 + ", is not a valid representation of an XML Gregorian Calendar value."
580 );
581 */
582
583 }
584 }
585
586 /**
587 * <p>Convert a <code>java.util.GregorianCalendar</code> to XML Schema 1.0
588 * representation.</p>
589 *
590 * <table border="2" rules="all" cellpadding="2">
591 * <thead>
592 * <tr>
593 * <th align="center" colspan="2">
594 * Field by Field Conversion from
595 * <code>java.util.GregorianCalendar</code> to this class
596 * </th>
597 * </tr>
598 * </thead>
599 * <tbody>
600 * <tr>
601 * <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th>
602 * <th><code>java.util.GregorianCalendar</code> field</th>
603 * </tr>
604 * <tr>
605 * <th>{@link #setYear(int)}</th>
606 * <th><code>ERA == GregorianCalendar.BC ? -YEAR : YEAR</code></th>
607 * </tr>
608 * <tr>
609 * <th>{@link #setMonth(int)}</th>
610 * <th><code>MONTH + 1</code></th>
611 * </tr>
612 * <tr>
613 * <th>{@link #setDay(int)}</th>
614 * <th><code>DAY_OF_MONTH</code></th>
615 * </tr>
616 * <tr>
617 * <th>{@link #setTime(int,int,int, BigDecimal)}</th>
618 * <th><code>HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND</code></th>
619 * </tr>
620 * <tr>
621 * <th>{@link #setTimezone(int)}<i>*</i></th>
622 * <th><code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/>
623 * <i>(in minutes)</i>
624 * </th>
625 * </tr>
626 * </tbody>
627 * </table>
628 * <p><i>*</i>conversion loss of information. It is not possible to represent
629 * a <code>java.util.GregorianCalendar</code> daylight savings timezone id in the
630 * XML Schema 1.0 date/time datatype representation.</p>
631 *
632 * <p>To compute the return value's <code>TimeZone</code> field,
633 * <ul>
634 * <li>when <code>this.getTimezone() != DatatypeConstants.FIELD_UNDEFINED</code>,
635 * create a <code>java.util.TimeZone</code> with a custom timezone id
636 * using the <code>this.getTimezone()</code>.</li>
637 * <li>else use the <code>GregorianCalendar</code> default timezone value
638 * for the host is defined as specified by
639 * <code>java.util.TimeZone.getDefault()</code>.</li></p>
640 *
641 * @param cal <code>java.util.GregorianCalendar</code> used to create <code>XMLGregorianCalendar</code>
642 */
643 public XMLGregorianCalendarImpl(GregorianCalendar cal) {
644
645 int year = cal.get(Calendar.YEAR);
646 if (cal.get(Calendar.ERA) == GregorianCalendar.BC) {
647 year = -year;
648 }
649 this.setYear(year);
650
651 // Calendar.MONTH is zero based, XSD Date datatype's month field starts
652 // with JANUARY as 1.
653 this.setMonth(cal.get(Calendar.MONTH) + 1);
654 this.setDay(cal.get(Calendar.DAY_OF_MONTH));
655 this.setTime(
656 cal.get(Calendar.HOUR_OF_DAY),
657 cal.get(Calendar.MINUTE),
658 cal.get(Calendar.SECOND),
659 cal.get(Calendar.MILLISECOND));
660
661 // Calendar ZONE_OFFSET and DST_OFFSET fields are in milliseconds.
662 int offsetInMinutes = (cal.get(Calendar.ZONE_OFFSET) + cal.get(Calendar.DST_OFFSET)) / (60 * 1000);
663 this.setTimezone(offsetInMinutes);
664 }
665
666 // Factories
667
668 /**
669 * <p>Create a Java representation of XML Schema builtin datatype <code>dateTime</code>.
670 * All possible fields are specified for this factory method.</p>
671 *
672 * @param year represents both high-order eons and low-order year.
673 * @param month of <code>dateTime</code>
674 * @param day of <code>dateTime</code>
675 * @param hours of <code>dateTime</code>
676 * @param minutes of <code>dateTime</code>
677 * @param seconds of <code>dateTime</code>
678 * @param fractionalSecond value of null indicates optional field is absent.
679 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
680 *
681 * @return <code>XMLGregorianCalendar</code> created from parameter values.
682 *
683 * @see DatatypeConstants#FIELD_UNDEFINED
684 *
685 * @throws IllegalArgumentException if any parameter is outside value
686 * constraints for the field as specified in
687 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
688 */
689 public static XMLGregorianCalendar createDateTime(
690 BigInteger year,
691 int month,
692 int day,
693 int hours,
694 int minutes,
695 int seconds,
696 BigDecimal fractionalSecond,
697 int timezone) {
698
699 return new XMLGregorianCalendarImpl(
700 year,
701 month,
702 day,
703 hours,
704 minutes,
705 seconds,
706 fractionalSecond,
707 timezone);
708 }
709
710 /**
711 * <p>Create a Java instance of XML Schema builtin datatype dateTime.</p>
712 *
713 * @param year represents both high-order eons and low-order year.
714 * @param month of <code>dateTime</code>
715 * @param day of <code>dateTime</code>
716 * @param hour of <code>dateTime</code>
717 * @param minute of <code>dateTime</code>
718 * @param second of <code>dateTime</code>
719 *
720 * @return <code>XMLGregorianCalendar</code> created from parameter values.
721 *
722 * @throws IllegalArgumentException if any parameter is outside value constraints for the field as specified in
723 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
724 *
725 * @see DatatypeConstants#FIELD_UNDEFINED
726 */
727 public static XMLGregorianCalendar createDateTime(
728 int year,
729 int month,
730 int day,
731 int hour,
732 int minute,
733 int second) {
734
735 return new XMLGregorianCalendarImpl(
736 year,
737 month,
738 day,
739 hour,
740 minute,
741 second,
742 DatatypeConstants.FIELD_UNDEFINED, //millisecond
743 DatatypeConstants.FIELD_UNDEFINED //timezone
744 );
745 }
746
747 /**
748 * <p>Create a Java representation of XML Schema builtin datatype <code>dateTime</code>.
749 * All possible fields are specified for this factory method.</p>
750 *
751 * @param year represents low-order year.
752 * @param month of <code>dateTime</code>
753 * @param day of <code>dateTime</code>
754 * @param hours of <code>dateTime</code>
755 * @param minutes of <code>dateTime</code>
756 * @param seconds of <code>dateTime</code>
757 * @param milliseconds of <code>dateTime</code>. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
758 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
759 *
760 * @return <code>XMLGregorianCalendar</code> created from parameter values.
761 *
762 * @throws IllegalArgumentException if any parameter is outside value constraints for the field as specified in
763 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
764 *
765 * @see DatatypeConstants#FIELD_UNDEFINED
766 */
767 public static XMLGregorianCalendar createDateTime(
768 int year,
769 int month,
770 int day,
771 int hours,
772 int minutes,
773 int seconds,
774 int milliseconds,
775 int timezone) {
776
777 return new XMLGregorianCalendarImpl(
778 year,
779 month,
780 day,
781 hours,
782 minutes,
783 seconds,
784 milliseconds,
785 timezone);
786 }
787
788 /**
789 * <p>Create a Java representation of XML Schema builtin datatype <code>date</code> or <code>g*</code>.</p>
790 *
791 * <p>For example, an instance of <code>gYear</code> can be created invoking this factory
792 * with <code>month</code> and <code>day</code> parameters set to
793 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
794 *
795 * @param year of <code>XMLGregorianCalendar</code> to be created.
796 * @param month of <code>XMLGregorianCalendar</code> to be created.
797 * @param day of <code>XMLGregorianCalendar</code> to be created.
798 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
799 *
800 * @return <code>XMLGregorianCalendar</code> created from parameter values.
801 *
802 * @see DatatypeConstants#FIELD_UNDEFINED
803 *
804 * @throws IllegalArgumentException if any parameter is outside value
805 * constraints for the field as specified in
806 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
807 */
808 public static XMLGregorianCalendar createDate(
809 int year,
810 int month,
811 int day,
812 int timezone) {
813
814 return new XMLGregorianCalendarImpl(
815 year,
816 month,
817 day,
818 DatatypeConstants.FIELD_UNDEFINED, // hour
819 DatatypeConstants.FIELD_UNDEFINED, // minute
820 DatatypeConstants.FIELD_UNDEFINED, // second
821 DatatypeConstants.FIELD_UNDEFINED, // millisecond
822 timezone);
823 }
824
825 /**
826 * Create a Java instance of XML Schema builtin datatype <code>time</code>.
827 * @param hours number of hours
828 * @param minutes number of minutes
829 * @param seconds number of seconds
830 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
831 *
832 * @return <code>XMLGregorianCalendar</code> created from parameter values.
833 *
834 * @see DatatypeConstants#FIELD_UNDEFINED
835 *
836 * @throws IllegalArgumentException if any parameter is outside value
837 * constraints for the field as specified in
838 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
839 */
840 public static XMLGregorianCalendar createTime(
841 int hours,
842 int minutes,
843 int seconds,
844 int timezone) {
845
846 return new XMLGregorianCalendarImpl(
847 DatatypeConstants.FIELD_UNDEFINED, // Year
848 DatatypeConstants.FIELD_UNDEFINED, // Month
849 DatatypeConstants.FIELD_UNDEFINED, // Day
850 hours,
851 minutes,
852 seconds,
853 DatatypeConstants.FIELD_UNDEFINED, //Millisecond
854 timezone);
855 }
856
857 /**
858 * <p>Create a Java instance of XML Schema builtin datatype time.</p>
859 *
860 * @param hours number of hours
861 * @param minutes number of minutes
862 * @param seconds number of seconds
863 * @param fractionalSecond value of <code>null</code> indicates that this optional field is not set.
864 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
865 *
866 * @return <code>XMLGregorianCalendar</code> created from parameter values.
867 *
868 * @see DatatypeConstants#FIELD_UNDEFINED
869 *
870 * @throws IllegalArgumentException if any parameter is outside value
871 * constraints for the field as specified in
872 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
873 */
874 public static XMLGregorianCalendar createTime(
875 int hours,
876 int minutes,
877 int seconds,
878 BigDecimal fractionalSecond,
879 int timezone) {
880
881 return new XMLGregorianCalendarImpl(
882 null, // Year
883 DatatypeConstants.FIELD_UNDEFINED, // month
884 DatatypeConstants.FIELD_UNDEFINED, // day
885 hours,
886 minutes,
887 seconds,
888 fractionalSecond,
889 timezone);
890 }
891
892 /**
893 * <p>Create a Java instance of XML Schema builtin datatype time.</p>
894 *
895 * @param hours number of hours
896 * @param minutes number of minutes
897 * @param seconds number of seconds
898 * @param milliseconds number of milliseconds
899 * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
900 *
901 * @return <code>XMLGregorianCalendar</code> created from parameter values.
902 *
903 * @see DatatypeConstants#FIELD_UNDEFINED
904 *
905 * @throws IllegalArgumentException if any parameter is outside value
906 * constraints for the field as specified in
907 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
908 */
909 public static XMLGregorianCalendar createTime(
910 int hours,
911 int minutes,
912 int seconds,
913 int milliseconds,
914 int timezone) {
915
916 return new XMLGregorianCalendarImpl(
917 DatatypeConstants.FIELD_UNDEFINED, // year
918 DatatypeConstants.FIELD_UNDEFINED, // month
919 DatatypeConstants.FIELD_UNDEFINED, // day
920 hours,
921 minutes,
922 seconds,
923 milliseconds,
924 timezone);
925 }
926
927 // Accessors
928
929 /**
930 * <p>Return high order component for XML Schema 1.0 dateTime datatype field for
931 * <code>year</code>.
932 * <code>null</code> if this optional part of the year field is not defined.</p>
933 *
934 * <p>Value constraints for this value are summarized in
935 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
936 * @return eon of this <code>XMLGregorianCalendar</code>. The value
937 * returned is an integer multiple of 10^9.
938 *
939 * @see #getYear()
940 * @see #getEonAndYear()
941 */
942 public BigInteger getEon() {
943 return eon;
944 }
945
946 /**
947 * <p>Return low order component for XML Schema 1.0 dateTime datatype field for
948 * <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
949 *
950 * <p>Value constraints for this value are summarized in
951 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
952 *
953 * @return year of this <code>XMLGregorianCalendar</code>.
954 *
955 * @see #getEon()
956 * @see #getEonAndYear()
957 */
958 public int getYear() {
959 return year;
960 }
961
962 /**
963 * <p>Return XML Schema 1.0 dateTime datatype field for
964 * <code>year</code>.</p>
965 *
966 * <p>Value constraints for this value are summarized in
967 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
968 *
969 * @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code>
970 * when both fields are defined. When only <code>year</code> is defined,
971 * return it. When both <code>eon</code> and <code>year</code> are not
972 * defined, return <code>null</code>.
973 *
974 * @see #getEon()
975 * @see #getYear()
976 */
977 public BigInteger getEonAndYear() {
978
979 // both are defined
980 if (year != DatatypeConstants.FIELD_UNDEFINED
981 && eon != null) {
982
983 return eon.add(BigInteger.valueOf((long) year));
984 }
985
986 // only year is defined
987 if (year != DatatypeConstants.FIELD_UNDEFINED
988 && eon == null) {
989
990 return BigInteger.valueOf((long) year);
991 }
992
993 // neither are defined
994 // or only eon is defined which is not valid without a year
995 return null;
996 }
997
998 /**
999 * <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1000 *
1001 * <p>Value constraints for this value are summarized in
1002 * <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p>
1003 *
1004 * @return year of this <code>XMLGregorianCalendar</code>.
1005 *
1006 */
1007 public int getMonth() {
1008 return month;
1009 }
1010
1011 /**
1012 * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1013 *
1014 * <p>Value constraints for this value are summarized in
1015 * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p>
1016 *
1017 * @see #setDay(int)
1018 */
1019 public int getDay() {
1020 return day;
1021 }
1022
1023 /**
1024 * Return timezone offset in minutes or
1025 * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
1026 *
1027 * <p>Value constraints for this value are summarized in
1028 * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p>
1029 *
1030 * @see #setTimezone(int)
1031 */
1032 public int getTimezone() {
1033 return timezone;
1034 }
1035
1036 /**
1037 * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.
1038 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
1039 *
1040 * <p>Value constraints for this value are summarized in
1041 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p>
1042 * @see #setTime(int, int, int)
1043 */
1044 public int getHour() {
1045 return hour;
1046 }
1047
1048 /**
1049 * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.<\p>
1050 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
1051 *
1052 * <p>Value constraints for this value are summarized in
1053 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p>
1054 * @see #setTime(int, int, int)
1055 */
1056 public int getMinute() {
1057 return minute;
1058 }
1059
1060 /**
1061 * <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.<\p>
1062 *
1063 * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
1064 * When this field is not defined, the optional xs:dateTime
1065 * fractional seconds field, represented by
1066 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
1067 * must not be defined.</p>
1068 *
1069 * <p>Value constraints for this value are summarized in
1070 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
1071 *
1072 * @return Second of this <code>XMLGregorianCalendar</code>.
1073 *
1074 * @see #getFractionalSecond()
1075 * @see #getMillisecond()
1076 * @see #setTime(int, int, int)
1077 */
1078 public int getSecond() {
1079 return second;
1080 }
1081
1082 /**
1083 * @return result of adding second and fractional second field
1084 */
1085 private BigDecimal getSeconds() {
1086 if (second == DatatypeConstants.FIELD_UNDEFINED) {
1087 return DECIMAL_ZERO;
1088 }
1089 BigDecimal result = BigDecimal.valueOf((long) second);
1090 if (fractionalSecond != null) {
1091 return result.add(fractionalSecond);
1092 } else {
1093 return result;
1094 }
1095 }
1096
1097
1098 /**
1099 * <p>Return millisecond precision of {@link #getFractionalSecond()}.<\p>
1100 *
1101 * <p>This method represents a convenience accessor to infinite
1102 * precision fractional second value returned by
1103 * {@link #getFractionalSecond()}. The returned value is the rounded
1104 * down to milliseconds value of
1105 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
1106 * returns <code>null</code>, this method must return
1107 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1108 *
1109 * <p>Value constraints for this value are summarized in
1110 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
1111 *
1112 * @return Millisecond of this <code>XMLGregorianCalendar</code>.
1113 *
1114 * @see #getFractionalSecond()
1115 * @see #setTime(int, int, int)
1116 */
1117 public int getMillisecond() {
1118 if (fractionalSecond == null) {
1119 return DatatypeConstants.FIELD_UNDEFINED;
1120 } else {
1121 // TODO: Non-optimal solution for now.
1122 // Efficient implementation would only store as BigDecimal
1123 // when needed and millisecond otherwise.
1124 return fractionalSecond.movePointRight(3).intValue();
1125 }
1126 }
1127
1128 /**
1129 * <p>Return fractional seconds.</p>
1130 *
1131 * <p><code>null</code> is returned when this optional field is not defined.</p>
1132 *
1133 * <p>Value constraints are detailed in
1134 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
1135 *
1136 * <p>This optional field can only have a defined value when the
1137 * xs:dateTime second field, represented by ({@link #getSecond()},
1138 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}).</p>
1139 *
1140 * @return fractional seconds of this <code>XMLGregorianCalendar</code>.
1141 *
1142 * @see #getSecond()
1143 * @see #setTime(int, int, int, BigDecimal)
1144 */
1145 public BigDecimal getFractionalSecond() {
1146 return fractionalSecond;
1147 }
1148
1149 // setters
1150
1151 /**
1152 * <p>Set low and high order component of XSD <code>dateTime</code> year field.</p>
1153 *
1154 * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p>
1155 *
1156 * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
1157 *
1158 * @throws IllegalArgumentException if <code>year</code> parameter is
1159 * outside value constraints for the field as specified in
1160 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1161 */
1162 public void setYear(BigInteger year) {
1163 if (year == null) {
1164 this.eon = null;
1165 this.year = DatatypeConstants.FIELD_UNDEFINED;
1166 } else {
1167 BigInteger temp = year.remainder(BILLION);
1168 this.year = temp.intValue();
1169 setEon(year.subtract(temp));
1170 }
1171 }
1172
1173 /**
1174 * <p>Set year of XSD <code>dateTime</code> year field.</p>
1175 *
1176 * <p>Unset this field by invoking the setter with a parameter value of
1177 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1178 *
1179 * <p>Note: if the absolute value of the <code>year</code> parameter
1180 * is less than 10^9, the eon component of the XSD year field is set to
1181 * <code>null</code> by this method.</p>
1182 *
1183 * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
1184 * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>.
1185 */
1186 public void setYear(int year) {
1187 if (year == DatatypeConstants.FIELD_UNDEFINED) {
1188 this.year = DatatypeConstants.FIELD_UNDEFINED;
1189 this.eon = null;
1190 } else if (Math.abs(year) < BILLION.intValue()) {
1191 this.year = year;
1192 this.eon = null;
1193 } else {
1194 BigInteger theYear = BigInteger.valueOf((long) year);
1195 BigInteger remainder = theYear.remainder(BILLION);
1196 this.year = remainder.intValue();
1197 setEon(theYear.subtract(remainder));
1198 }
1199 }
1200
1201 /**
1202 * <p>Set high order part of XSD <code>dateTime</code> year field.</p>
1203 *
1204 * <p>Unset this field by invoking the setter with a parameter value of
1205 * <code>null</code>.</p>
1206 *
1207 * @param eon value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
1208 */
1209 private void setEon(BigInteger eon) {
1210 if (eon != null && eon.compareTo(BigInteger.ZERO) == 0) {
1211 // Treat ZERO as field being undefined.
1212 this.eon = null;
1213 } else {
1214 this.eon = eon;
1215 }
1216 }
1217
1218 /**
1219 * <p>Set month.</p>
1220 *
1221 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1222 *
1223 * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.
1224 *
1225 * @throws IllegalArgumentException if <code>month</code> parameter is
1226 * outside value constraints for the field as specified in
1227 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1228 */
1229 public void setMonth(int month) {
1230 if(month<DatatypeConstants.JANUARY || DatatypeConstants.DECEMBER<month)
1231 if(month!=DatatypeConstants.FIELD_UNDEFINED)
1232 invalidFieldValue(MONTH, month);
1233 this.month = month;
1234 }
1235
1236 /**
1237 * <p>Set days in month.</p>
1238 *
1239 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1240 *
1241 * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.
1242 *
1243 * @throws IllegalArgumentException if <code>day</code> parameter is
1244 * outside value constraints for the field as specified in
1245 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1246 */
1247 public void setDay(int day) {
1248 if(day<1 || 31<day)
1249 if(day!=DatatypeConstants.FIELD_UNDEFINED)
1250 invalidFieldValue(DAY,day);
1251 this.day = day;
1252 }
1253
1254 /**
1255 * <p>Set the number of minutes in the timezone offset.</p>
1256 *
1257 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
1258 *
1259 * @param offset value constraints summarized in <a href="#datetimefield-timezone">
1260 * timezone field of date/time field mapping table</a>.
1261 *
1262 * @throws IllegalArgumentException if <code>offset</code> parameter is
1263 * outside value constraints for the field as specified in
1264 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1265 */
1266 public void setTimezone(int offset) {
1267 if(offset<-14*60 || 14*60<offset)
1268 if(offset!=DatatypeConstants.FIELD_UNDEFINED)
1269 invalidFieldValue(TIMEZONE,offset);
1270 this.timezone = offset;
1271 }
1272
1273 /**
1274 * <p>Set time as one unit.</p>
1275 *
1276 * @param hour value constraints are summarized in
1277 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
1278 * @param minute value constraints are summarized in
1279 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
1280 * @param second value constraints are summarized in
1281 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
1282 *
1283 * @see #setTime(int, int, int, BigDecimal)
1284 *
1285 * @throws IllegalArgumentException if any parameter is
1286 * outside value constraints for the field as specified in
1287 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1288 */
1289 public void setTime(int hour, int minute, int second) {
1290 setTime(hour, minute, second, null);
1291 }
1292
1293 private void invalidFieldValue(int field, int value) {
1294 throw new IllegalArgumentException(
1295 DatatypeMessageFormatter.formatMessage(null, "InvalidFieldValue",
1296 new Object[]{ new Integer(value), FIELD_NAME[field]})
1297 );
1298 }
1299
1300 private void testHour() {
1301
1302 // http://www.w3.org/2001/05/xmlschema-errata#e2-45
1303 if (getHour() == 24) {
1304 if (getMinute() != 0
1305 || getSecond() != 0) {
1306 invalidFieldValue(HOUR, getHour());
1307 }
1308 // while 0-24 is acceptable in the lexical space, 24 is not valid in value space
1309 // W3C XML Schema Part 2, Section 3.2.7.1
1310 setHour(0, false);
1311 add(new DurationImpl(true, 0, 0, 1, 0, 0, 0));
1312 }
1313 }
1314
1315 public void setHour(int hour) {
1316
1317 setHour(hour, true);
1318 }
1319
1320 private void setHour(int hour, boolean validate) {
1321
1322 if (hour < 0 || hour > 24) {
1323 if (hour != DatatypeConstants.FIELD_UNDEFINED) {
1324 invalidFieldValue(HOUR, hour);
1325 }
1326 }
1327
1328 this.hour = hour;
1329
1330 if (validate) {
1331 testHour();
1332 }
1333 }
1334
1335 public void setMinute(int minute) {
1336 if(minute<0 || 59<minute)
1337 if(minute!=DatatypeConstants.FIELD_UNDEFINED)
1338 invalidFieldValue(MINUTE, minute);
1339 this.minute = minute;
1340 }
1341
1342 public void setSecond(int second) {
1343 if(second<0 || 60<second) // leap second allows for 60
1344 if(second!=DatatypeConstants.FIELD_UNDEFINED)
1345 invalidFieldValue(SECOND, second);
1346 this.second = second;
1347 }
1348
1349 /**
1350 * <p>Set time as one unit, including the optional infinite precison
1351 * fractional seconds.</p>
1352 *
1353 * @param hour value constraints are summarized in
1354 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
1355 * @param minute value constraints are summarized in
1356 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
1357 * @param second value constraints are summarized in
1358 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
1359 * @param fractional value of <code>null</code> indicates this optional
1360 * field is not set.
1361 *
1362 * @throws IllegalArgumentException if any parameter is
1363 * outside value constraints for the field as specified in
1364 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1365 */
1366 public void setTime(
1367 int hour,
1368 int minute,
1369 int second,
1370 BigDecimal fractional) {
1371
1372 setHour(hour, false);
1373
1374 setMinute(minute);
1375 if (second != 60) {
1376 setSecond(second);
1377 } else if ((hour == 23 && minute == 59) || (hour == 0 && minute == 0)) {
1378 setSecond(second);
1379 } else {
1380 invalidFieldValue(SECOND, second);
1381 }
1382
1383 setFractionalSecond(fractional);
1384
1385 // must test hour after setting seconds
1386 testHour();
1387 }
1388
1389
1390 /**
1391 * <p>Set time as one unit, including optional milliseconds.</p>
1392 *
1393 * @param hour value constraints are summarized in
1394 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
1395 * @param minute value constraints are summarized in
1396 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
1397 * @param second value constraints are summarized in
1398 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
1399 * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this
1400 * optional field is not set.
1401 *
1402 * @throws IllegalArgumentException if any parameter is
1403 * outside value constraints for the field as specified in
1404 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
1405 */
1406 public void setTime(int hour, int minute, int second, int millisecond) {
1407
1408 setHour(hour, false);
1409
1410 setMinute(minute);
1411 if (second != 60) {
1412 setSecond(second);
1413 } else if ((hour == 23 && minute == 59) || (hour == 0 && minute == 0)) {
1414 setSecond(second);
1415 } else {
1416 invalidFieldValue(SECOND, second);
1417 }
1418 setMillisecond(millisecond);
1419
1420 // must test hour after setting seconds
1421 testHour();
1422 }
1423
1424 // comparisons
1425 /**
1426 * <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes
1427 * according to partial order relation defined in
1428 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
1429 * <i>Order relation on dateTime</i></a>.</p>
1430 *
1431 * <p><code>xsd:dateTime</code> datatype field mapping to accessors of
1432 * this class are defined in
1433 * <a href="#datetimefieldmapping">date/time field mapping table</a>.</p>
1434 *
1435 * @param rhs instance of <code>XMLGregorianCalendar</code> to compare
1436 *
1437 * @return the relationship between <code>lhs</code> and <code>rhs</code> as
1438 * {@link DatatypeConstants#LESSER},
1439 * {@link DatatypeConstants#EQUAL},
1440 * {@link DatatypeConstants#GREATER} or
1441 * {@link DatatypeConstants#INDETERMINATE}.
1442 *
1443 * @throws NullPointerException if <code>lhs</code> or <code>rhs</code>
1444 * parameters are null.
1445 */
1446 public int compare(XMLGregorianCalendar rhs) {
1447
1448 XMLGregorianCalendar lhs = this;
1449
1450 int result = DatatypeConstants.INDETERMINATE;
1451 XMLGregorianCalendarImpl P = (XMLGregorianCalendarImpl) lhs;
1452 XMLGregorianCalendarImpl Q = (XMLGregorianCalendarImpl) rhs;
1453
1454 if (P.getTimezone() == Q.getTimezone()) {
1455 // Optimization:
1456 // both instances are in same timezone or
1457 // both are FIELD_UNDEFINED.
1458 // Avoid costly normalization of timezone to 'Z' time.
1459 return internalCompare(P, Q);
1460
1461 } else if (P.getTimezone() != DatatypeConstants.FIELD_UNDEFINED &&
1462 Q.getTimezone() != DatatypeConstants.FIELD_UNDEFINED) {
1463
1464 // Both instances have different timezones.
1465 // Normalize to UTC time and compare.
1466 P = (XMLGregorianCalendarImpl) P.normalize();
1467 Q = (XMLGregorianCalendarImpl) Q.normalize();
1468 return internalCompare(P, Q);
1469 } else if (P.getTimezone() != DatatypeConstants.FIELD_UNDEFINED) {
1470
1471 if (P.getTimezone() != 0) {
1472 P = (XMLGregorianCalendarImpl) P.normalize();
1473 }
1474
1475 // C. step 1
1476 XMLGregorianCalendar MinQ = Q.normalizeToTimezone(DatatypeConstants.MIN_TIMEZONE_OFFSET);
1477 result = internalCompare(P, MinQ);
1478 if (result == DatatypeConstants.LESSER) {
1479 return result;
1480 }
1481
1482 // C. step 2
1483 XMLGregorianCalendar MaxQ = Q.normalizeToTimezone(DatatypeConstants.MAX_TIMEZONE_OFFSET);
1484 result = internalCompare(P, MaxQ);
1485 if (result == DatatypeConstants.GREATER) {
1486 return result;
1487 } else {
1488 // C. step 3
1489 return DatatypeConstants.INDETERMINATE;
1490 }
1491 } else { // Q.getTimezone() != DatatypeConstants.FIELD_UNDEFINED
1492 // P has no timezone and Q does.
1493 if (Q.getTimezone() != 0) {
1494 Q = (XMLGregorianCalendarImpl) Q.normalizeToTimezone(Q.getTimezone());
1495 }
1496
1497 // D. step 1
1498 XMLGregorianCalendar MaxP = P.normalizeToTimezone(DatatypeConstants.MAX_TIMEZONE_OFFSET);
1499 result = internalCompare(MaxP, Q);
1500 if (result == DatatypeConstants.LESSER) {
1501 return result;
1502 }
1503
1504 // D. step 2
1505 XMLGregorianCalendar MinP = P.normalizeToTimezone(DatatypeConstants.MIN_TIMEZONE_OFFSET);
1506 result = internalCompare(MinP, Q);
1507 if (result == DatatypeConstants.GREATER) {
1508 return result;
1509 } else {
1510 // D. step 3
1511 return DatatypeConstants.INDETERMINATE;
1512 }
1513 }
1514 }
1515
1516 /**
1517 * <p>Normalize this instance to UTC.</p>
1518 *
1519 * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p>
1520 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p>
1521 */
1522 public XMLGregorianCalendar normalize() {
1523
1524 XMLGregorianCalendar normalized = normalizeToTimezone(timezone);
1525
1526 // if timezone was undefined, leave it undefined
1527 if (getTimezone() == DatatypeConstants.FIELD_UNDEFINED) {
1528 normalized.setTimezone(DatatypeConstants.FIELD_UNDEFINED);
1529 }
1530
1531 // if milliseconds was undefined, leave it undefined
1532 if (getMillisecond() == DatatypeConstants.FIELD_UNDEFINED) {
1533 normalized.setMillisecond(DatatypeConstants.FIELD_UNDEFINED);
1534 }
1535
1536 return normalized;
1537 }
1538
1539 /**
1540 * <p>Normalize this instance to UTC.</p>
1541 *
1542 * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p>
1543 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p>
1544 */
1545 private XMLGregorianCalendar normalizeToTimezone(int timezone) {
1546
1547 int minutes = timezone;
1548 XMLGregorianCalendar result = (XMLGregorianCalendar) this.clone();
1549
1550 // normalizing to UTC time negates the timezone offset before
1551 // addition.
1552 minutes = -minutes;
1553 Duration d = new DurationImpl(minutes >= 0, // isPositive
1554 0, //years
1555 0, //months
1556 0, //days
1557 0, //hours
1558 minutes < 0 ? -minutes : minutes, // absolute
1559 0 //seconds
1560 );
1561 result.add(d);
1562
1563 // set to zulu UTC time.
1564 result.setTimezone(0);
1565 return result;
1566 }
1567
1568 /**
1569 *
1570 * <p>Implements Step B from http://www.w3.org/TR/xmlschema-2/#dateTime-order </p>
1571 * @param P calendar instance with normalized timezone offset or
1572 * having same timezone as Q
1573 * @param Q calendar instance with normalized timezone offset or
1574 * having same timezone as P
1575 *
1576 * @return result of comparing P and Q, value of
1577 * {@link DatatypeConstants#EQUAL},
1578 * {@link DatatypeConstants#LESSER},
1579 * {@link DatatypeConstants#GREATER} or
1580 * {@link DatatypeConstants#INDETERMINATE}.
1581 */
1582 private static int internalCompare(XMLGregorianCalendar P,
1583 XMLGregorianCalendar Q) {
1584
1585 int result;
1586
1587 // compare Year.
1588 if (P.getEon() == Q.getEon()) {
1589
1590 // Eon field is only equal when null.
1591 // optimized case for comparing year not requiring eon field.
1592 result = compareField(P.getYear(), Q.getYear());
1593 if (result != DatatypeConstants.EQUAL) {
1594 return result;
1595 }
1596 } else {
1597 result = compareField(P.getEonAndYear(), Q.getEonAndYear());
1598 if (result != DatatypeConstants.EQUAL) {
1599 return result;
1600 }
1601 }
1602
1603 result = compareField(P.getMonth(), Q.getMonth());
1604 if (result != DatatypeConstants.EQUAL) {
1605 return result;
1606 }
1607
1608 result = compareField(P.getDay(), Q.getDay());
1609 if (result != DatatypeConstants.EQUAL) {
1610 return result;
1611 }
1612
1613 result = compareField(P.getHour(), Q.getHour());
1614 if (result != DatatypeConstants.EQUAL) {
1615 return result;
1616 }
1617
1618 result = compareField(P.getMinute(), Q.getMinute());
1619 if (result != DatatypeConstants.EQUAL) {
1620 return result;
1621 }
1622 result = compareField(P.getSecond(), Q.getSecond());
1623 if (result != DatatypeConstants.EQUAL) {
1624 return result;
1625 }
1626
1627 result = compareField(P.getFractionalSecond(), Q.getFractionalSecond());
1628 return result;
1629 }
1630
1631 /**
1632 * <p>Implement Step B from
1633 * http://www.w3.org/TR/xmlschema-2/#dateTime-order.</p>
1634 */
1635 private static int compareField(int Pfield, int Qfield) {
1636 if (Pfield == Qfield) {
1637
1638 //fields are either equal in value or both undefined.
1639 // Step B. 1.1 AND optimized result of performing 1.1-1.4.
1640 return DatatypeConstants.EQUAL;
1641 } else {
1642 if (Pfield == DatatypeConstants.FIELD_UNDEFINED || Qfield == DatatypeConstants.FIELD_UNDEFINED) {
1643 // Step B. 1.2
1644 return DatatypeConstants.INDETERMINATE;
1645 } else {
1646 // Step B. 1.3-4.
1647 return (Pfield < Qfield ? DatatypeConstants.LESSER : DatatypeConstants.GREATER);
1648 }
1649 }
1650 }
1651
1652 private static int compareField(BigInteger Pfield, BigInteger Qfield) {
1653 if (Pfield == null) {
1654 return (Qfield == null ? DatatypeConstants.EQUAL : DatatypeConstants.INDETERMINATE);
1655 }
1656 if (Qfield == null) {
1657 return DatatypeConstants.INDETERMINATE;
1658 }
1659 return Pfield.compareTo(Qfield);
1660 }
1661
1662 private static int compareField(BigDecimal Pfield, BigDecimal Qfield) {
1663 // optimization. especially when both arguments are null.
1664 if (Pfield == Qfield) {
1665 return DatatypeConstants.EQUAL;
1666 }
1667
1668 if (Pfield == null) {
1669 Pfield = DECIMAL_ZERO;
1670 }
1671
1672 if (Qfield == null) {
1673 Qfield = DECIMAL_ZERO;
1674 }
1675
1676 return Pfield.compareTo(Qfield);
1677 }
1678
1679 /**
1680 * <p>Indicates whether parameter <code>obj</code> is "equal to" this one.</p>
1681 *
1682 * @param obj to compare.
1683 *
1684 * @return <code>true</code> when <code>compare(this,(XMLGregorianCalendar)obj) == EQUAL.</code>.
1685 */
1686 public boolean equals(Object obj) {
1687
1688 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
1689 return false;
1690 }
1691 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
1692 }
1693
1694 /**
1695 * <p>Returns a hash code consistent with the definition of the equals method.</p>
1696 *
1697 * @return hash code of this object.
1698 */
1699 public int hashCode() {
1700
1701 // Following two dates compare to EQUALS since in different timezones.
1702 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
1703 //
1704 // Must ensure both instances generate same hashcode by normalizing
1705 // this to UTC timezone.
1706 int timezone = getTimezone();
1707 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
1708 timezone = 0;
1709 }
1710 XMLGregorianCalendar gc = this;
1711 if (timezone != 0) {
1712 gc = this.normalizeToTimezone(getTimezone());
1713 }
1714 return gc.getYear() + gc.getMonth() + gc.getDay() +
1715 gc.getHour() + gc.getMinute() + gc.getSecond();
1716 }
1717
1718
1719 /**
1720 * <p>Constructs a new XMLGregorianCalendar object by
1721 * parsing its lexical string representation as defined in
1722 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
1723 * <i>Lexical Representation</i>.</a></p>
1724 *
1725 * <p>The string representation may not have any leading and trailing whitespaces.</p>
1726 *
1727 * <p>The parsing is done field by field so that
1728 * the following holds for any lexically correct string x:</p>
1729 * <pre>
1730 * new XMLGregorianCalendar(x).toXMLFormat().equals(x)
1731 * </pre>
1732 * Except for the noted lexical/canonical representation mismatches
1733 * listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">
1734 * XML Schema 1.0 errata, Section 3.2.7.2</a>.
1735 *
1736 * <p>Returns a non-null valid XMLGregorianCalendar object that holds the value
1737 * indicated by the lexicalRepresentation parameter.</p>
1738 *
1739 * @param lexicalRepresentation Lexical representation of one the 8 XML Schema calendar datatypes.
1740 *
1741 * @return <code>XMLGregorianCalendar</code> created from parsing <code>lexicalRepresentation</code> parameter.
1742 *
1743 * @throws IllegalArgumentException
1744 * If the given string does not conform to the aforementioned
1745 * specification.
1746 * @throws NullPointerException
1747 * If the given string is null.
1748 */
1749 public static XMLGregorianCalendar parse(String lexicalRepresentation) {
1750
1751 return new XMLGregorianCalendarImpl(lexicalRepresentation);
1752 }
1753
1754 /**
1755 * <p>Return the lexical representation of <code>this</code> instance.
1756 * The format is specified in
1757 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
1758 * <i>Lexical Representation</i>".</a></p>
1759 *
1760 * <p>Specific target lexical representation format is determined by
1761 * {@link #getXMLSchemaType()}.</p>
1762 *
1763 * @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code>
1764 *
1765 * @throws java.lang.IllegalStateException if the combination of set fields
1766 * does not match one of the eight defined XML Schema builtin date/time datatypes.
1767 */
1768 public String toXMLFormat() {
1769
1770 QName typekind = getXMLSchemaType();
1771
1772 String formatString = null;
1773 // Fix 4971612: invalid SCCS macro substitution in data string
1774 // no %{alpha}% to avoid SCCS macro substitution
1775 if (typekind == DatatypeConstants.DATETIME) {
1776 formatString = "%Y-%M-%DT%h:%m:%s" + "%z";
1777 } else if (typekind == DatatypeConstants.DATE) {
1778 formatString = "%Y-%M-%D" + "%z";
1779 } else if (typekind == DatatypeConstants.TIME) {
1780 formatString = "%h:%m:%s" + "%z";
1781 } else if (typekind == DatatypeConstants.GMONTH) {
1782 formatString = "--%M" + "%z";
1783 } else if (typekind == DatatypeConstants.GDAY) {
1784 formatString = "---%D" + "%z";
1785 } else if (typekind == DatatypeConstants.GYEAR) {
1786 formatString = "%Y" + "%z";
1787 } else if (typekind == DatatypeConstants.GYEARMONTH) {
1788 formatString = "%Y-%M" + "%z";
1789 } else if (typekind == DatatypeConstants.GMONTHDAY) {
1790 formatString = "--%M-%D" + "%z";
1791 }
1792 return format(formatString);
1793 }
1794
1795 /**
1796 * <p>Return the name of the XML Schema date/time type that this instance
1797 * maps to. Type is computed based on fields that are set.</p>
1798 *
1799 * <table border="2" rules="all" cellpadding="2">
1800 * <thead>
1801 * <tr>
1802 * <th align="center" colspan="7">
1803 * Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
1804 * <i>(timezone is optional for all date/time datatypes)</i>
1805 * </th>
1806 * </tr>
1807 * </thead>
1808 * <tbody>
1809 * <tr>
1810 * <td>Datatype</td>
1811 * <td>year</td>
1812 * <td>month</td>
1813 * <td>day</td>
1814 * <td>hour</td>
1815 * <td>minute</td>
1816 * <td>second</td>
1817 * </tr>
1818 * <tr>
1819 * <td>{@link DatatypeConstants#DATETIME}</td>
1820 * <td>X</td>
1821 * <td>X</td>
1822 * <td>X</td>
1823 * <td>X</td>
1824 * <td>X</td>
1825 * <td>X</td>
1826 * </tr>
1827 * <tr>
1828 * <td>{@link DatatypeConstants#DATE}</td>
1829 * <td>X</td>
1830 * <td>X</td>
1831 * <td>X</td>
1832 * <td></td>
1833 * <td></td>
1834 * <td></td>
1835 * </tr>
1836 * <tr>
1837 * <td>{@link DatatypeConstants#TIME}</td>
1838 * <td></td>
1839 * <td></td>
1840 * <td></td>
1841 * <td>X</td>
1842 * <td>X</td>
1843 * <td>X</td>
1844 * </tr>
1845 * <tr>
1846 * <td>{@link DatatypeConstants#GYEARMONTH}</td>
1847 * <td>X</td>
1848 * <td>X</td>
1849 * <td></td>
1850 * <td></td>
1851 * <td></td>
1852 * <td></td>
1853 * </tr>
1854 * <tr>
1855 * <td>{@link DatatypeConstants#GMONTHDAY}</td>
1856 * <td></td>
1857 * <td>X</td>
1858 * <td>X</td>
1859 * <td></td>
1860 * <td></td>
1861 * <td></td>
1862 * </tr>
1863 * <tr>
1864 * <td>{@link DatatypeConstants#GYEAR}</td>
1865 * <td>X</td>
1866 * <td></td>
1867 * <td></td>
1868 * <td></td>
1869 * <td></td>
1870 * <td></td>
1871 * </tr>
1872 * <tr>
1873 * <td>{@link DatatypeConstants#GMONTH}</td>
1874 * <td></td>
1875 * <td>X</td>
1876 * <td></td>
1877 * <td></td>
1878 * <td></td>
1879 * <td></td>
1880 * </tr>
1881 * <tr>
1882 * <td>{@link DatatypeConstants#GDAY}</td>
1883 * <td></td>
1884 * <td></td>
1885 * <td>X</td>
1886 * <td></td>
1887 * <td></td>
1888 * <td></td>
1889 * </tr>
1890 * </tbody>
1891 * </table>
1892 *
1893 * @throws java.lang.IllegalStateException if the combination of set fields
1894 * does not match one of the eight defined XML Schema builtin
1895 * date/time datatypes.
1896 * @return One of the following class constants:
1897 * {@link DatatypeConstants#DATETIME},
1898 * {@link DatatypeConstants#TIME},
1899 * {@link DatatypeConstants#DATE},
1900 * {@link DatatypeConstants#GYEARMONTH},
1901 * {@link DatatypeConstants#GMONTHDAY},
1902 * {@link DatatypeConstants#GYEAR},
1903 * {@link DatatypeConstants#GMONTH} or
1904 * {@link DatatypeConstants#GDAY}.
1905 */
1906 public QName getXMLSchemaType() {
1907
1908 int mask =
1909 (year != DatatypeConstants.FIELD_UNDEFINED ? 0x20 : 0 )|
1910 (month != DatatypeConstants.FIELD_UNDEFINED ? 0x10 : 0 )|
1911 (day != DatatypeConstants.FIELD_UNDEFINED ? 0x08 : 0 )|
1912 (hour != DatatypeConstants.FIELD_UNDEFINED ? 0x04 : 0 )|
1913 (minute != DatatypeConstants.FIELD_UNDEFINED ? 0x02 : 0 )|
1914 (second != DatatypeConstants.FIELD_UNDEFINED ? 0x01 : 0 );
1915
1916 switch(mask) {
1917 case 0x3F:
1918 return DatatypeConstants.DATETIME;
1919 case 0x38:
1920 return DatatypeConstants.DATE;
1921 case 0x07:
1922 return DatatypeConstants.TIME;
1923 case 0x30:
1924 return DatatypeConstants.GYEARMONTH;
1925 case 0x18:
1926 return DatatypeConstants.GMONTHDAY;
1927 case 0x20:
1928 return DatatypeConstants.GYEAR;
1929 case 0x10:
1930 return DatatypeConstants.GMONTH;
1931 case 0x08:
1932 return DatatypeConstants.GDAY;
1933 default:
1934 throw new IllegalStateException(
1935 this.getClass().getName()
1936 + "#getXMLSchemaType() :"
1937 + DatatypeMessageFormatter.formatMessage(null, "InvalidXGCFields", null)
1938 );
1939 }
1940 }
1941
1942
1943 /**
1944 * Validate instance by <code>getXMLSchemaType()</code> constraints.
1945 * @return true if data values are valid.
1946 */
1947 public boolean isValid() {
1948 // since setters do not allow for invalid values,
1949 // (except for exceptional case of year field of zero),
1950 // no need to check for anything except for constraints
1951 // between fields.
1952
1953 //check if days in month is valid. Can be dependent on leap year.
1954 if (getMonth() == DatatypeConstants.FEBRUARY) {
1955 // years could not be set
1956 int maxDays = 29;
1957
1958 if (eon == null) {
1959 if(year!=DatatypeConstants.FIELD_UNDEFINED)
1960 maxDays = maximumDayInMonthFor(year,getMonth());
1961 } else {
1962 BigInteger years = getEonAndYear();
1963 if (years != null) {
1964 maxDays = maximumDayInMonthFor(getEonAndYear(), DatatypeConstants.FEBRUARY);
1965 }
1966 }
1967 if (getDay() > maxDays) {
1968 return false;
1969 }
1970 }
1971
1972 // http://www.w3.org/2001/05/xmlschema-errata#e2-45
1973 if (getHour() == 24) {
1974 if(getMinute() != 0) {
1975 return false;
1976 } else if (getSecond() != 0) {
1977 return false;
1978 }
1979 }
1980
1981 // XML Schema 1.0 specification defines year value of zero as
1982 // invalid. Allow this class to set year field to zero
1983 // since XML Schema 1.0 errata states that lexical zero will
1984 // be allowed in next version and treated as 1 B.C.E.
1985 if (eon == null) {
1986 // optimize check.
1987 if (year == 0) {
1988 return false;
1989 }
1990 } else {
1991 BigInteger yearField = getEonAndYear();
1992 if (yearField != null) {
1993 int result = compareField(yearField, BigInteger.ZERO);
1994 if (result == DatatypeConstants.EQUAL) {
1995 return false;
1996 }
1997 }
1998 }
1999 return true;
2000 }
2001
2002 /**
2003 * <p>Add <code>duration</code> to this instance.<\p>
2004 *
2005 * <p>The computation is specified in
2006 * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
2007 * <i>Adding durations to dateTimes</i>></a>.
2008 * <a href="#datetimefieldsmapping">date/time field mapping table</a>
2009 * defines the mapping from XML Schema 1.0 <code>dateTime</code> fields
2010 * to this class' representation of those fields.</p>
2011 *
2012 * @param duration Duration to add to this <code>XMLGregorianCalendar</code>.
2013 *
2014 * @throws NullPointerException when <code>duration</code> parameter is <code>null</code>.
2015 */
2016 public void add(Duration duration) {
2017
2018 /*
2019 * Extracted from
2020 * http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes
2021 * to ensure implemented properly. See spec for definitions of methods
2022 * used in algorithm.
2023 *
2024 * Given a dateTime S and a duration D, specifies how to compute a
2025 * dateTime E where E is the end of the time period with start S and
2026 * duration D i.e. E = S + D.
2027 *
2028 * The following is the precise specification.
2029 * These steps must be followed in the same order.
2030 * If a field in D is not specified, it is treated as if it were zero.
2031 * If a field in S is not specified, it is treated in the calculation
2032 * as if it were the minimum allowed value in that field, however,
2033 * after the calculation is concluded, the corresponding field in
2034 * E is removed (set to unspecified).
2035 *
2036 * Months (may be modified additionally below)
2037 * temp := S[month] + D[month]
2038 * E[month] := modulo(temp, 1, 13)
2039 * carry := fQuotient(temp, 1, 13)
2040 */
2041
2042 boolean fieldUndefined[] = {
2043 false,
2044 false,
2045 false,
2046 false,
2047 false,
2048 false
2049 };
2050
2051 int signum = duration.getSign();
2052
2053 int startMonth = getMonth();
2054 if (startMonth == DatatypeConstants.FIELD_UNDEFINED) {
2055 startMonth = DatatypeConstants.JANUARY;
2056 fieldUndefined[MONTH] = true;
2057 }
2058
2059 BigInteger dMonths = sanitize(duration.getField(DatatypeConstants.MONTHS), signum);
2060 BigInteger temp = BigInteger.valueOf((long) startMonth).add(dMonths);
2061 setMonth(temp.subtract(BigInteger.ONE).mod(TWELVE).intValue() + 1);
2062 BigInteger carry =
2063 new BigDecimal(temp.subtract(BigInteger.ONE)).divide(new BigDecimal(TWELVE), BigDecimal.ROUND_FLOOR).toBigInteger();
2064
2065 /* Years (may be modified additionally below)
2066 * E[year] := S[year] + D[year] + carry
2067 */
2068 BigInteger startYear = getEonAndYear();
2069 if (startYear == null) {
2070 fieldUndefined[YEAR] = true;
2071 startYear = BigInteger.ZERO;
2072 }
2073 BigInteger dYears = sanitize(duration.getField(DatatypeConstants.YEARS), signum);
2074 BigInteger endYear = startYear.add(dYears).add(carry);
2075 setYear(endYear);
2076
2077 /* Zone
2078 * E[zone] := S[zone]
2079 *
2080 * no-op since adding to this, not to a new end point.
2081 */
2082
2083 /* Seconds
2084 * temp := S[second] + D[second]
2085 * E[second] := modulo(temp, 60)
2086 * carry := fQuotient(temp, 60)
2087 */
2088 BigDecimal startSeconds;
2089 if (getSecond() == DatatypeConstants.FIELD_UNDEFINED) {
2090 fieldUndefined[SECOND] = true;
2091 startSeconds = DECIMAL_ZERO;
2092 } else {
2093 // seconds + fractionalSeconds
2094 startSeconds = getSeconds();
2095 }
2096
2097 // Duration seconds is SECONDS + FRACTIONALSECONDS.
2098 BigDecimal dSeconds = DurationImpl.sanitize((BigDecimal) duration.getField(DatatypeConstants.SECONDS), signum);
2099 BigDecimal tempBD = startSeconds.add(dSeconds);
2100 BigDecimal fQuotient =
2101 new BigDecimal(new BigDecimal(tempBD.toBigInteger()).divide(DECIMAL_SIXTY, BigDecimal.ROUND_FLOOR).toBigInteger());
2102 BigDecimal endSeconds = tempBD.subtract(fQuotient.multiply(DECIMAL_SIXTY));
2103
2104 carry = fQuotient.toBigInteger();
2105 setSecond(endSeconds.intValue());
2106 BigDecimal tempFracSeconds = endSeconds.subtract(new BigDecimal(BigInteger.valueOf((long) getSecond())));
2107 if (tempFracSeconds.compareTo(DECIMAL_ZERO) < 0) {
2108 setFractionalSecond(DECIMAL_ONE.add(tempFracSeconds));
2109 if (getSecond() == 0) {
2110 setSecond(59);
2111 carry = carry.subtract(BigInteger.ONE);
2112 } else {
2113 setSecond(getSecond() - 1);
2114 }
2115 } else {
2116 setFractionalSecond(tempFracSeconds);
2117 }
2118
2119 /* Minutes
2120 * temp := S[minute] + D[minute] + carry
2121 * E[minute] := modulo(temp, 60)
2122 * carry := fQuotient(temp, 60)
2123 */
2124 int startMinutes = getMinute();
2125 if (startMinutes == DatatypeConstants.FIELD_UNDEFINED) {
2126 fieldUndefined[MINUTE] = true;
2127 startMinutes = 0;
2128 }
2129 BigInteger dMinutes = sanitize(duration.getField(DatatypeConstants.MINUTES), signum);
2130
2131 temp = BigInteger.valueOf(startMinutes).add(dMinutes).add(carry);
2132 setMinute(temp.mod(SIXTY).intValue());
2133 carry = new BigDecimal(temp).divide(DECIMAL_SIXTY, BigDecimal.ROUND_FLOOR).toBigInteger();
2134
2135 /* Hours
2136 * temp := S[hour] + D[hour] + carry
2137 * E[hour] := modulo(temp, 24)
2138 * carry := fQuotient(temp, 24)
2139 */
2140 int startHours = getHour();
2141 if (startHours == DatatypeConstants.FIELD_UNDEFINED) {
2142 fieldUndefined[HOUR] = true;
2143 startHours = 0;
2144 }
2145 BigInteger dHours = sanitize(duration.getField(DatatypeConstants.HOURS), signum);
2146
2147 temp = BigInteger.valueOf(startHours).add(dHours).add(carry);
2148 setHour(temp.mod(TWENTY_FOUR).intValue(), false);
2149 carry = new BigDecimal(temp).divide(new BigDecimal(TWENTY_FOUR), BigDecimal.ROUND_FLOOR).toBigInteger();
2150
2151 /* Days
2152 * if S[day] > maximumDayInMonthFor(E[year], E[month])
2153 * + tempDays := maximumDayInMonthFor(E[year], E[month])
2154 * else if S[day] < 1
2155 * + tempDays := 1
2156 * else
2157 * + tempDays := S[day]
2158 * E[day] := tempDays + D[day] + carry
2159 * START LOOP
2160 * + IF E[day] < 1
2161 * # E[day] := E[day] +
2162 * maximumDayInMonthFor(E[year], E[month] - 1)
2163 * # carry := -1
2164 * + ELSE IF E[day] > maximumDayInMonthFor(E[year], E[month])
2165 * # E[day] :=
2166 * E[day] - maximumDayInMonthFor(E[year], E[month])
2167 * # carry := 1
2168 * + ELSE EXIT LOOP
2169 * + temp := E[month] + carry
2170 * + E[month] := modulo(temp, 1, 13)
2171 * + E[year] := E[year] + fQuotient(temp, 1, 13)
2172 * + GOTO START LOOP
2173 */
2174 BigInteger tempDays;
2175 int startDay = getDay();
2176 if (startDay == DatatypeConstants.FIELD_UNDEFINED) {
2177 fieldUndefined[DAY] = true;
2178 startDay = 1;
2179 }
2180 BigInteger dDays = sanitize(duration.getField(DatatypeConstants.DAYS), signum);
2181 int maxDayInMonth = maximumDayInMonthFor(getEonAndYear(), getMonth());
2182 if (startDay > maxDayInMonth) {
2183 tempDays = BigInteger.valueOf(maxDayInMonth);
2184 } else if (startDay < 1) {
2185 tempDays = BigInteger.ONE;
2186 } else {
2187 tempDays = BigInteger.valueOf(startDay);
2188 }
2189 BigInteger endDays = tempDays.add(dDays).add(carry);
2190 int monthCarry;
2191 int intTemp;
2192 while (true) {
2193 if (endDays.compareTo(BigInteger.ONE) < 0) {
2194 // calculate days in previous month, watch for month roll over
2195 BigInteger mdimf = null;
2196 if (month >= 2) {
2197 mdimf = BigInteger.valueOf(maximumDayInMonthFor(getEonAndYear(), getMonth() - 1));
2198 } else {
2199 // roll over to December of previous year
2200 mdimf = BigInteger.valueOf(maximumDayInMonthFor(getEonAndYear().subtract(BigInteger.valueOf((long) 1)), 12));
2201 }
2202 endDays = endDays.add(mdimf);
2203 monthCarry = -1;
2204 } else if (endDays.compareTo(BigInteger.valueOf(maximumDayInMonthFor(getEonAndYear(), getMonth()))) > 0) {
2205 endDays = endDays.add(BigInteger.valueOf(-maximumDayInMonthFor(getEonAndYear(), getMonth())));
2206 monthCarry = 1;
2207 } else {
2208 break;
2209 }
2210
2211 intTemp = getMonth() + monthCarry;
2212 int endMonth = (intTemp - 1) % (13 - 1);
2213 int quotient;
2214 if (endMonth < 0) {
2215 endMonth = (13 - 1) + endMonth + 1;
2216 quotient = new BigDecimal(intTemp - 1).divide(new BigDecimal(TWELVE), BigDecimal.ROUND_UP).intValue();
2217 } else {
2218 quotient = (intTemp - 1) / (13 - 1);
2219 endMonth += 1;
2220 }
2221 setMonth(endMonth);
2222 if (quotient != 0) {
2223 setYear(getEonAndYear().add(BigInteger.valueOf(quotient)));
2224 }
2225 }
2226 setDay(endDays.intValue());
2227
2228 // set fields that where undefined before this addition, back to undefined.
2229 for (int i = YEAR; i <= SECOND; i++) {
2230 if (fieldUndefined[i]) {
2231 switch (i) {
2232 case YEAR:
2233 setYear(DatatypeConstants.FIELD_UNDEFINED);
2234 break;
2235 case MONTH:
2236 setMonth(DatatypeConstants.FIELD_UNDEFINED);
2237 break;
2238 case DAY:
2239 setDay(DatatypeConstants.FIELD_UNDEFINED);
2240 break;
2241 case HOUR:
2242 setHour(DatatypeConstants.FIELD_UNDEFINED, false);
2243 break;
2244 case MINUTE:
2245 setMinute(DatatypeConstants.FIELD_UNDEFINED);
2246 break;
2247 case SECOND:
2248 setSecond(DatatypeConstants.FIELD_UNDEFINED);
2249 setFractionalSecond(null);
2250 break;
2251 }
2252 }
2253 }
2254 }
2255
2256 private static final BigInteger FOUR = BigInteger.valueOf(4);
2257 private static final BigInteger HUNDRED = BigInteger.valueOf(100);
2258 private static final BigInteger FOUR_HUNDRED = BigInteger.valueOf(400);
2259 private static final BigInteger SIXTY = BigInteger.valueOf(60);
2260 private static final BigInteger TWENTY_FOUR = BigInteger.valueOf(24);
2261 private static final BigInteger TWELVE = BigInteger.valueOf(12);
2262 private static final BigDecimal DECIMAL_ZERO = new BigDecimal("0");
2263 private static final BigDecimal DECIMAL_ONE = new BigDecimal("1");
2264 private static final BigDecimal DECIMAL_SIXTY = new BigDecimal("60");
2265
2266
2267 private static int daysInMonth[] = { 0, // XML Schema months start at 1.
2268 31, 28, 31, 30, 31, 30,
2269 31, 31, 30, 31, 30, 31};
2270
2271 private static int maximumDayInMonthFor(BigInteger year, int month) {
2272 if (month != DatatypeConstants.FEBRUARY) {
2273 return daysInMonth[month];
2274 } else {
2275 if (year.mod(FOUR_HUNDRED).equals(BigInteger.ZERO) ||
2276 (!year.mod(HUNDRED).equals(BigInteger.ZERO) &&
2277 year.mod(FOUR).equals(BigInteger.ZERO))) {
2278 // is a leap year.
2279 return 29;
2280 } else {
2281 return daysInMonth[month];
2282 }
2283 }
2284 }
2285
2286 private static int maximumDayInMonthFor(int year, int month) {
2287 if (month != DatatypeConstants.FEBRUARY) {
2288 return daysInMonth[month];
2289 } else {
2290 if (((year % 400) == 0) ||
2291 (((year % 100) != 0) && ((year % 4) == 0))) {
2292 // is a leap year.
2293 return 29;
2294 } else {
2295 return daysInMonth[DatatypeConstants.FEBRUARY];
2296 }
2297 }
2298 }
2299
2300 /**
2301 * <p>Convert <code>this</code> to <code>java.util.GregorianCalendar</code>.</p>
2302 *
2303 * <p>When <code>this</code> instance has an undefined field, this
2304 * conversion relies on the <code>java.util.GregorianCalendar</code> default
2305 * for its corresponding field. A notable difference between
2306 * XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code>
2307 * is that Timezone value is optional for date/time datatypes and it is
2308 * a required field for <code>java.util.GregorianCalendar</code>. See javadoc
2309 * for <code>java.util.TimeZone.getDefault()</code> on how the default
2310 * is determined. To explicitly specify the <code>TimeZone</code>
2311 * instance, see
2312 * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p>
2313 *
2314 * <table border="2" rules="all" cellpadding="2">
2315 * <thead>
2316 * <tr>
2317 * <th align="center" colspan="2">
2318 * Field by Field Conversion from this class to
2319 * <code>java.util.GregorianCalendar</code>
2320 * </th>
2321 * </tr>
2322 * </thead>
2323 * <tbody>
2324 * <tr>
2325 * <th><code>java.util.GregorianCalendar</code> field</th>
2326 * <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th>
2327 * </tr>
2328 * <tr>
2329 * <th><code>ERA</code></th>
2330 * <th>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></th>
2331 * </tr>
2332 * <tr>
2333 * <th><code>YEAR</code></th>
2334 * <th>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></th>
2335 * </tr>
2336 * <tr>
2337 * <th><code>MONTH</code></th>
2338 * <th>{@link #getMonth()}<code> - 1</code></th>
2339 * </tr>
2340 * <tr>
2341 * <th><code>DAY_OF_MONTH</code></th>
2342 * <th>{@link #getDay()}</th>
2343 * </tr>
2344 * <tr>
2345 * <th><code>AM_PM</code></th>
2346 * <th>{@link #getHour()} < 12 : Calendar.AM : Calendar.PM</th>
2347 * </tr>
2348 * <tr>
2349 * <th><code>HOUR_OF_DAY</code></th>
2350 * <th>{@link #getHour()}</th>
2351 * </tr>
2352 * <tr>
2353 * <th><code>MINUTE</code></th>
2354 * <th>{@link #getMinute()}</th>
2355 * </tr>
2356 * <tr>
2357 * <th><code>SECOND</code></th>
2358 * <th>{@link #getSecond()}</th>
2359 * </tr>
2360 * <tr>
2361 * <th><code>MILLISECOND</code></th>
2362 * <th>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </th>
2363 * </tr>
2364 * <tr>
2365 * <th><code>GregorianCalendar.setTimeZone(TimeZone)</code></th>
2366 * <th>{@link #getTimezone()} formatted into Custom timezone id</th>
2367 * </tr>
2368 * </tbody>
2369 * </table>
2370 * <i>*</i> designates possible loss of precision during the conversion due
2371 * to source datatype having higer precison than target datatype.
2372 *
2373 * <p>To ensure consistency in conversion implementations, the new
2374 * <code>GregorianCalendar</code> should be instantiated in following
2375 * manner.
2376 * <ul>
2377 * <li>Using <code>timeZone</code> value as defined above, create a new
2378 * <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>.
2379 * </li>
2380 * <li>Initialize all GregorianCalendar fields by calling {(@link GegorianCalendar#clear()}.</li>
2381 * <li>Obtain a pure Gregorian Calendar by invoking
2382 * <code>GregorianCalendar.setGregorianChange(
2383 * new Date(Long.MIN_VALUE))</code>.</li>
2384 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
2385 * MINUTE, SECOND and MILLISECOND are set using the method
2386 * <code>Calendar.set(int,int)</code></li>
2387 * </ul>
2388 * </p>
2389 *
2390 * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
2391 */
2392 public java.util.GregorianCalendar toGregorianCalendar() {
2393
2394 GregorianCalendar result = null;
2395 final int DEFAULT_TIMEZONE_OFFSET = DatatypeConstants.FIELD_UNDEFINED;
2396 TimeZone tz = getTimeZone(DEFAULT_TIMEZONE_OFFSET);
2397 /** Use the following instead for JDK7 only:
2398 * Locale locale = Locale.getDefault(Locale.Category.FORMAT);
2399 */
2400 Locale locale = getDefaultLocale();
2401
2402 result = new GregorianCalendar(tz, locale);
2403 result.clear();
2404 result.setGregorianChange(PURE_GREGORIAN_CHANGE);
2405
2406 // if year( and eon) are undefined, leave default Calendar values
2407 BigInteger year = getEonAndYear();
2408 if (year != null) {
2409 result.set(Calendar.ERA, year.signum() == -1 ? GregorianCalendar.BC : GregorianCalendar.AD);
2410 result.set(Calendar.YEAR, year.abs().intValue());
2411 }
2412
2413 // only set month if it is set
2414 if (month != DatatypeConstants.FIELD_UNDEFINED) {
2415 // Calendar.MONTH is zero based while XMLGregorianCalendar month field is not.
2416 result.set(Calendar.MONTH, month - 1);
2417 }
2418
2419 // only set day if it is set
2420 if (day != DatatypeConstants.FIELD_UNDEFINED) {
2421 result.set(Calendar.DAY_OF_MONTH, day);
2422 }
2423
2424 // only set hour if it is set
2425 if (hour != DatatypeConstants.FIELD_UNDEFINED) {
2426 result.set(Calendar.HOUR_OF_DAY, hour);
2427 }
2428
2429 // only set minute if it is set
2430 if (minute != DatatypeConstants.FIELD_UNDEFINED) {
2431 result.set(Calendar.MINUTE, minute);
2432 }
2433
2434 // only set second if it is set
2435 if (second != DatatypeConstants.FIELD_UNDEFINED) {
2436 result.set(Calendar.SECOND, second);
2437 }
2438
2439 // only set millisend if it is set
2440 if (fractionalSecond != null) {
2441 result.set(Calendar.MILLISECOND, getMillisecond());
2442 }
2443
2444 return result;
2445 }
2446
2447 /**
2448 *
2449 * @return default locale
2450 */
2451 private Locale getDefaultLocale() {
2452
2453 String lang = SecuritySupport.getSystemProperty("user.language.format");
2454 String country = SecuritySupport.getSystemProperty("user.country.format");
2455 String variant = SecuritySupport.getSystemProperty("user.variant.format");
2456 Locale locale = null;
2457 if (lang != null) {
2458 if (country != null) {
2459 if (variant != null) {
2460 locale = new Locale(lang, country, variant);
2461 } else {
2462 locale = new Locale(lang, country);
2463 }
2464 } else {
2465 locale = new Locale(lang);
2466 }
2467 }
2468 if (locale == null) {
2469 locale = Locale.getDefault();
2470 }
2471 return locale;
2472 }
2473
2474 /**
2475 * <p>Convert <code>this</code> along with provided parameters
2476 * to <code>java.util.GregorianCalendar</code> instance.</p>
2477 *
2478 * <p> Since XML Schema 1.0 date/time datetypes has no concept of
2479 * timezone ids or daylight savings timezone ids, this conversion operation
2480 * allows the user to explicitly specify one with
2481 * <code>timezone</code> parameter.</p>
2482 *
2483 * <p>To compute the return value's <code>TimeZone</code> field,
2484 * <ul>
2485 * <li>when parameter <code>timeZone</code> is non-null,
2486 * it is the timezone field.</li>
2487 * <li>else when <code>this.getTimezone() != DatatypeConstants.FIELD_UNDEFINED</code>,
2488 * create a <code>java.util.TimeZone</code> with a custom timezone id
2489 * using the <code>this.getTimezone()</code>.</li>
2490 * <li>else when <code>defaults.getTimezone() != DatatypeConstants.FIELD_UNDEFINED</code>,
2491 * create a <code>java.util.TimeZone</code> with a custom timezone id
2492 * using <code>defaults.getTimezone()</code>.</li>
2493 * <li>else use the <code>GregorianCalendar</code> default timezone value
2494 * for the host is definedas specified by
2495 * <code>java.util.TimeZone.getDefault()</code>.</li></p>
2496 *
2497 * <p>To ensure consistency in conversion implementations, the new
2498 * <code>GregorianCalendar</code> should be instantiated in following
2499 * manner.
2500 * <ul>
2501 * <li>Create a new <code>java.util.GregorianCalendar(TimeZone,
2502 * Locale)</code> with TimeZone set as specified above and the
2503 * <code>Locale</code> parameter.
2504 * </li>
2505 * <li>Initialize all GregorianCalendar fields by calling {(@link GegorianCalendar#clear()}.</li>
2506 * <li>Obtain a pure Gregorian Calendar by invoking
2507 * <code>GregorianCalendar.setGregorianChange(
2508 * new Date(Long.MIN_VALUE))</code>.</li>
2509 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
2510 * MINUTE, SECOND and MILLISECOND are set using the method
2511 * <code>Calendar.set(int,int)</code></li>
2512 * </ul>
2513 *
2514 * @param timezone provide Timezone. <code>null</code> is a legal value.
2515 * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if
2516 * value is <code>null</code>.
2517 * @param defaults provide default field values to use when corresponding
2518 * field for this instance is DatatypeConstants.FIELD_UNDEFINED or null.
2519 * If <code>defaults</code>is <code>null</code> or a field
2520 * within the specified <code>defaults</code> is undefined,
2521 * just use <code>java.util.GregorianCalendar</code> defaults.
2522 * @return a java.util.GregorianCalendar conversion of this instance.
2523 *
2524 * @see #LEAP_YEAR_DEFAULT
2525 */
2526 public GregorianCalendar toGregorianCalendar(TimeZone timezone,
2527 Locale aLocale,
2528 XMLGregorianCalendar defaults) {
2529 GregorianCalendar result = null;
2530 TimeZone tz = timezone;
2531 if (tz == null) {
2532 int defaultZoneoffset = DatatypeConstants.FIELD_UNDEFINED;
2533 if (defaults != null) {
2534 defaultZoneoffset = defaults.getTimezone();
2535 }
2536 tz = getTimeZone(defaultZoneoffset);
2537 }
2538 if (aLocale == null) {
2539 aLocale = Locale.getDefault();
2540 }
2541 result = new GregorianCalendar(tz, aLocale);
2542 result.clear();
2543 result.setGregorianChange(PURE_GREGORIAN_CHANGE);
2544
2545 // if year( and eon) are undefined, leave default Calendar values
2546 BigInteger year = getEonAndYear();
2547 if (year != null) {
2548 result.set(Calendar.ERA, year.signum() == -1 ? GregorianCalendar.BC : GregorianCalendar.AD);
2549 result.set(Calendar.YEAR, year.abs().intValue());
2550 } else {
2551 // use default if set
2552 BigInteger defaultYear = (defaults != null) ? defaults.getEonAndYear() : null;
2553 if (defaultYear != null) {
2554 result.set(Calendar.ERA, defaultYear.signum() == -1 ? GregorianCalendar.BC : GregorianCalendar.AD);
2555 result.set(Calendar.YEAR, defaultYear.abs().intValue());
2556 }
2557 }
2558
2559 // only set month if it is set
2560 if (month != DatatypeConstants.FIELD_UNDEFINED) {
2561 // Calendar.MONTH is zero based while XMLGregorianCalendar month field is not.
2562 result.set(Calendar.MONTH, month - 1);
2563 } else {
2564 // use default if set
2565 int defaultMonth = (defaults != null) ? defaults.getMonth() : DatatypeConstants.FIELD_UNDEFINED;
2566 if (defaultMonth != DatatypeConstants.FIELD_UNDEFINED) {
2567 // Calendar.MONTH is zero based while XMLGregorianCalendar month field is not.
2568 result.set(Calendar.MONTH, defaultMonth - 1);
2569 }
2570 }
2571
2572 // only set day if it is set
2573 if (day != DatatypeConstants.FIELD_UNDEFINED) {
2574 result.set(Calendar.DAY_OF_MONTH, day);
2575 } else {
2576 // use default if set
2577 int defaultDay = (defaults != null) ? defaults.getDay() : DatatypeConstants.FIELD_UNDEFINED;
2578 if (defaultDay != DatatypeConstants.FIELD_UNDEFINED) {
2579 result.set(Calendar.DAY_OF_MONTH, defaultDay);
2580 }
2581 }
2582
2583 // only set hour if it is set
2584 if (hour != DatatypeConstants.FIELD_UNDEFINED) {
2585 result.set(Calendar.HOUR_OF_DAY, hour);
2586 } else {
2587 // use default if set
2588 int defaultHour = (defaults != null) ? defaults.getHour() : DatatypeConstants.FIELD_UNDEFINED;
2589 if (defaultHour != DatatypeConstants.FIELD_UNDEFINED) {
2590 result.set(Calendar.HOUR_OF_DAY, defaultHour);
2591 }
2592 }
2593
2594 // only set minute if it is set
2595 if (minute != DatatypeConstants.FIELD_UNDEFINED) {
2596 result.set(Calendar.MINUTE, minute);
2597 } else {
2598 // use default if set
2599 int defaultMinute = (defaults != null) ? defaults.getMinute() : DatatypeConstants.FIELD_UNDEFINED;
2600 if (defaultMinute != DatatypeConstants.FIELD_UNDEFINED) {
2601 result.set(Calendar.MINUTE, defaultMinute);
2602 }
2603 }
2604
2605 // only set second if it is set
2606 if (second != DatatypeConstants.FIELD_UNDEFINED) {
2607 result.set(Calendar.SECOND, second);
2608 } else {
2609 // use default if set
2610 int defaultSecond = (defaults != null) ? defaults.getSecond() : DatatypeConstants.FIELD_UNDEFINED;
2611 if (defaultSecond != DatatypeConstants.FIELD_UNDEFINED) {
2612 result.set(Calendar.SECOND, defaultSecond);
2613 }
2614 }
2615
2616 // only set millisend if it is set
2617 if (fractionalSecond != null) {
2618 result.set(Calendar.MILLISECOND, getMillisecond());
2619 } else {
2620 // use default if set
2621 BigDecimal defaultFractionalSecond = (defaults != null) ? defaults.getFractionalSecond() : null;
2622 if (defaultFractionalSecond != null) {
2623 result.set(Calendar.MILLISECOND, defaults.getMillisecond());
2624 }
2625 }
2626
2627 return result;
2628 }
2629
2630 /**
2631 * <p>Returns a <code>java.util.TimeZone</code> for this class.</p>
2632 *
2633 * <p>If timezone field is defined for this instance,
2634 * returns TimeZone initialized with custom timezone id
2635 * of zoneoffset. If timezone field is undefined,
2636 * try the defaultZoneoffset that was passed in.
2637 * If defaultZoneoffset is DatatypeConstants.FIELD_UNDEFINED, return
2638 * default timezone for this host.
2639 * (Same default as java.util.GregorianCalendar).</p>
2640 *
2641 * @param defaultZoneoffset default zoneoffset if this zoneoffset is
2642 * {@link DatatypeConstants#FIELD_UNDEFINED}.
2643 *
2644 * @return TimeZone for this.
2645 */
2646 public TimeZone getTimeZone(int defaultZoneoffset) {
2647 TimeZone result = null;
2648 int zoneoffset = getTimezone();
2649
2650 if (zoneoffset == DatatypeConstants.FIELD_UNDEFINED) {
2651 zoneoffset = defaultZoneoffset;
2652 }
2653 if (zoneoffset == DatatypeConstants.FIELD_UNDEFINED) {
2654 result = TimeZone.getDefault();
2655 } else {
2656 // zoneoffset is in minutes. Convert to custom timezone id format.
2657 char sign = zoneoffset < 0 ? '-' : '+';
2658 if (sign == '-') {
2659 zoneoffset = -zoneoffset;
2660 }
2661 int hour = zoneoffset / 60;
2662 int minutes = zoneoffset - (hour * 60);
2663
2664 // Javadoc for java.util.TimeZone documents max length
2665 // for customTimezoneId is 8 when optional ':' is not used.
2666 // Format is
2667 // "GMT" ('-'|''+') (digit digit?) (digit digit)?
2668 // hour minutes
2669 StringBuffer customTimezoneId = new StringBuffer(8);
2670 customTimezoneId.append("GMT");
2671 customTimezoneId.append(sign);
2672 customTimezoneId.append(hour);
2673 if (minutes != 0) {
2674 customTimezoneId.append(minutes);
2675 }
2676 result = TimeZone.getTimeZone(customTimezoneId.toString());
2677 }
2678 return result;
2679 }
2680
2681 /**
2682 * <p>Creates and returns a copy of this object.</p>
2683 *
2684 * @return copy of this <code>Object</code>
2685 */
2686 public Object clone() {
2687 // Both this.eon and this.fractionalSecond are instances
2688 // of immutable classes, so they do not need to be cloned.
2689 return new XMLGregorianCalendarImpl(getEonAndYear(),
2690 this.month, this.day,
2691 this.hour, this.minute, this.second,
2692 this.fractionalSecond,
2693 this.timezone);
2694 }
2695
2696 /**
2697 * <p>Unset all fields to undefined.</p>
2698 *
2699 * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields
2700 * to null.</p>
2701 */
2702 public void clear() {
2703 eon = null;
2704 year = DatatypeConstants.FIELD_UNDEFINED;
2705 month = DatatypeConstants.FIELD_UNDEFINED;
2706 day = DatatypeConstants.FIELD_UNDEFINED;
2707 timezone = DatatypeConstants.FIELD_UNDEFINED; // in minutes
2708 hour = DatatypeConstants.FIELD_UNDEFINED;
2709 minute = DatatypeConstants.FIELD_UNDEFINED;
2710 second = DatatypeConstants.FIELD_UNDEFINED;
2711 fractionalSecond = null;
2712 }
2713
2714 public void setMillisecond(int millisecond) {
2715 if (millisecond == DatatypeConstants.FIELD_UNDEFINED) {
2716 fractionalSecond = null;
2717 } else {
2718 if(millisecond<0 || 999<millisecond)
2719 if(millisecond!=DatatypeConstants.FIELD_UNDEFINED)
2720 invalidFieldValue(MILLISECOND, millisecond);
2721 fractionalSecond = new BigDecimal((long) millisecond).movePointLeft(3);
2722 }
2723 }
2724
2725 public void setFractionalSecond(BigDecimal fractional) {
2726 if (fractional != null) {
2727 if ((fractional.compareTo(DECIMAL_ZERO) < 0) ||
2728 (fractional.compareTo(DECIMAL_ONE) > 0)) {
2729 throw new IllegalArgumentException(DatatypeMessageFormatter.formatMessage(null,
2730 "InvalidFractional", new Object[]{fractional}));
2731 }
2732 }
2733 this.fractionalSecond = fractional;
2734 }
2735
2736 private final class Parser {
2737 private final String format;
2738 private final String value;
2739
2740 private final int flen;
2741 private final int vlen;
2742
2743 private int fidx;
2744 private int vidx;
2745
2746 private Parser(String format, String value) {
2747 this.format = format;
2748 this.value = value;
2749 this.flen = format.length();
2750 this.vlen = value.length();
2751 }
2752
2753 /**
2754 * <p>Parse a formated <code>String</code> into an <code>XMLGregorianCalendar</code>.</p>
2755 *
2756 * <p>If <code>String</code> is not formated as a legal <code>XMLGregorianCalendar</code> value,
2757 * an <code>IllegalArgumentException</code> is thrown.</p>
2758 *
2759 * @throws IllegalArgumentException If <code>String</code> is not formated as a legal <code>XMLGregorianCalendar</code> value.
2760 */
2761 public void parse() throws IllegalArgumentException {
2762 while (fidx < flen) {
2763 char fch = format.charAt(fidx++);
2764
2765 if (fch != '%') { // not a meta character
2766 skip(fch);
2767 continue;
2768 }
2769
2770 // seen meta character. we don't do error check against the format
2771 switch (format.charAt(fidx++)) {
2772 case 'Y' : // year
2773 parseAndSetYear(4);
2774 break;
2775
2776 case 'M' : // month
2777 setMonth(parseInt(2, 2));
2778 break;
2779
2780 case 'D' : // days
2781 setDay(parseInt(2, 2));
2782 break;
2783
2784 case 'h' : // hours
2785 setHour(parseInt(2, 2), false);
2786 break;
2787
2788 case 'm' : // minutes
2789 setMinute(parseInt(2, 2));
2790 break;
2791
2792 case 's' : // parse seconds.
2793 setSecond(parseInt(2, 2));
2794
2795 if (peek() == '.') {
2796 setFractionalSecond(parseBigDecimal());
2797 }
2798 break;
2799
2800 case 'z' : // time zone. missing, 'Z', or [+-]nn:nn
2801 char vch = peek();
2802 if (vch == 'Z') {
2803 vidx++;
2804 setTimezone(0);
2805 } else if (vch == '+' || vch == '-') {
2806 vidx++;
2807 int h = parseInt(2, 2);
2808 skip(':');
2809 int m = parseInt(2, 2);
2810 setTimezone((h * 60 + m) * (vch == '+' ? 1 : -1));
2811 }
2812
2813 break;
2814
2815 default :
2816 // illegal meta character. impossible.
2817 throw new InternalError();
2818 }
2819 }
2820
2821 if (vidx != vlen) {
2822 // some tokens are left in the input
2823 throw new IllegalArgumentException(value); //,vidx);
2824 }
2825 testHour();
2826 }
2827
2828 private char peek() throws IllegalArgumentException {
2829 if (vidx == vlen) {
2830 return (char) -1;
2831 }
2832 return value.charAt(vidx);
2833 }
2834
2835 private char read() throws IllegalArgumentException {
2836 if (vidx == vlen) {
2837 throw new IllegalArgumentException(value); //,vidx);
2838 }
2839 return value.charAt(vidx++);
2840 }
2841
2842 private void skip(char ch) throws IllegalArgumentException {
2843 if (read() != ch) {
2844 throw new IllegalArgumentException(value); //,vidx-1);
2845 }
2846 }
2847
2848 private int parseInt(int minDigits, int maxDigits)
2849 throws IllegalArgumentException {
2850
2851 int n = 0;
2852 char ch;
2853 int vstart = vidx;
2854 while (isDigit(ch=peek()) && (vidx - vstart) <= maxDigits) {
2855 vidx++;
2856 n = n*10 + ch-'0';
2857 }
2858 if ((vidx - vstart) < minDigits) {
2859 // we are expecting more digits
2860 throw new IllegalArgumentException(value); //,vidx);
2861 }
2862
2863 return n;
2864 }
2865
2866 private void parseAndSetYear(int minDigits)
2867 throws IllegalArgumentException {
2868 int vstart = vidx;
2869 int n = 0;
2870 boolean neg = false;
2871
2872 // skip leading negative, if it exists
2873 if (peek() == '-') {
2874 vidx++;
2875 neg = true;
2876 }
2877 while(true) {
2878 char ch = peek();
2879 if(!isDigit(ch))
2880 break;
2881 vidx++;
2882 n = n*10 + ch-'0';
2883 }
2884
2885 if ((vidx - vstart) < minDigits) {
2886 // we are expecting more digits
2887 throw new IllegalArgumentException(value); //,vidx);
2888 }
2889
2890 if(vidx-vstart<7) {
2891 // definitely int only. I don't know the exact # of digits that can be in int,
2892 // but as long as we can catch (0-9999) range, that should be enough.
2893 if(neg) n = -n;
2894 year = n;
2895 eon = null;
2896 } else {
2897 setYear(new BigInteger(value.substring(vstart, vidx)));
2898 }
2899 }
2900
2901 private BigDecimal parseBigDecimal()
2902 throws IllegalArgumentException {
2903 int vstart = vidx;
2904
2905 if (peek() == '.') {
2906 vidx++;
2907 } else {
2908 throw new IllegalArgumentException(value);
2909 }
2910 while (isDigit(peek())) {
2911 vidx++;
2912 }
2913 return new BigDecimal(value.substring(vstart, vidx));
2914 }
2915 }
2916
2917 private static boolean isDigit(char ch) {
2918 return '0' <= ch && ch <= '9';
2919 }
2920
2921 /**
2922 * Prints this object according to the format specification.
2923 *
2924 * <p>
2925 * I wrote a custom format method for a particular format string to
2926 * see if it improves the performance, but it didn't. So this interpreting
2927 * approach isn't too bad.
2928 *
2929 * <p>
2930 * StringBuffer -> StringBuilder change had a very visible impact.
2931 * It almost cut the execution time to half, but unfortunately we can't use it
2932 * because we need to run on JDK 1.3
2933 */
2934 private String format( String format ) {
2935 char[] buf = new char[32];
2936 int bufPtr = 0;
2937
2938 int fidx=0,flen=format.length();
2939
2940 while(fidx<flen) {
2941 char fch = format.charAt(fidx++);
2942 if(fch!='%') {// not a meta char
2943 buf[bufPtr++] = fch;
2944 continue;
2945 }
2946
2947 switch(format.charAt(fidx++)) {
2948 case 'Y':
2949 if(eon==null) {
2950 // optimized path
2951 int y = getYear();
2952 if(y<0) {
2953 buf[bufPtr++] = '-';
2954 y = -y;
2955 }
2956 bufPtr = print4Number(buf,bufPtr,y);
2957 } else {
2958 String s = getEonAndYear().toString();
2959 // reallocate the buffer now so that it has enough space
2960 char[] n = new char[buf.length+s.length()];
2961 System.arraycopy(buf,0,n,0,bufPtr);
2962 buf = n;
2963 for(int i=s.length();i<4;i++)
2964 buf[bufPtr++] = '0';
2965 s.getChars(0,s.length(),buf,bufPtr);
2966 bufPtr += s.length();
2967 }
2968 break;
2969 case 'M':
2970 bufPtr = print2Number(buf,bufPtr,getMonth());
2971 break;
2972 case 'D':
2973 bufPtr = print2Number(buf,bufPtr,getDay());
2974 break;
2975 case 'h':
2976 bufPtr = print2Number(buf,bufPtr,getHour());
2977 break;
2978 case 'm':
2979 bufPtr = print2Number(buf,bufPtr,getMinute());
2980 break;
2981 case 's':
2982 bufPtr = print2Number(buf,bufPtr,getSecond());
2983 if (getFractionalSecond() != null) {
2984 // Note: toPlainString() isn't available before Java 1.5
2985 String frac = getFractionalSecond().toString();
2986
2987 int pos = frac.indexOf("E-");
2988 if (pos >= 0) {
2989 String zeros = frac.substring(pos+2);
2990 frac = frac.substring(0,pos);
2991 pos = frac.indexOf(".");
2992 if (pos >= 0) {
2993 frac = frac.substring(0,pos) + frac.substring(pos+1);
2994 }
2995 int count = Integer.parseInt(zeros);
2996 if (count < 40) {
2997 frac = "00000000000000000000000000000000000000000".substring(0,count-1) + frac;
2998 } else {
2999 // do it the hard way
3000 while (count > 1) {
3001 frac = "0" + frac;
3002 count--;
3003 }
3004 }
3005 frac = "0." + frac;
3006 }
3007
3008 // reallocate the buffer now so that it has enough space
3009 char[] n = new char[buf.length+frac.length()];
3010 System.arraycopy(buf,0,n,0,bufPtr);
3011 buf = n;
3012 //skip leading zero.
3013 frac.getChars(1, frac.length(), buf, bufPtr);
3014 bufPtr += frac.length()-1;
3015 }
3016 break;
3017 case 'z':
3018 int offset = getTimezone();
3019 if (offset == 0) {
3020 buf[bufPtr++] = 'Z';
3021 } else
3022 if (offset != DatatypeConstants.FIELD_UNDEFINED) {
3023 if (offset < 0) {
3024 buf[bufPtr++] = '-';
3025 offset *= -1;
3026 } else {
3027 buf[bufPtr++] = '+';
3028 }
3029 bufPtr = print2Number(buf, bufPtr, offset / 60);
3030 buf[bufPtr++] = ':';
3031 bufPtr = print2Number(buf, bufPtr, offset % 60);
3032 }
3033 break;
3034 default:
3035 throw new InternalError(); // impossible
3036 }
3037 }
3038
3039 return new String(buf,0,bufPtr);
3040 }
3041
3042 /**
3043 * Prints an int as two digits into the buffer.
3044 *
3045 * @param number
3046 * Number to be printed. Must be positive.
3047 */
3048 private int print2Number( char[] out, int bufptr, int number ) {
3049 out[bufptr++] = (char) ('0'+(number/10));
3050 out[bufptr++] = (char) ('0'+(number%10));
3051 return bufptr;
3052 }
3053
3054 /**
3055 * Prints an int as four digits into the buffer.
3056 *
3057 * @param number
3058 * Number to be printed. Must be positive.
3059 */
3060 private int print4Number( char[] out, int bufptr, int number ) {
3061 out[bufptr+3] = (char) ('0'+(number%10));
3062 number /= 10;
3063 out[bufptr+2] = (char) ('0'+(number%10));
3064 number /= 10;
3065 out[bufptr+1] = (char) ('0'+(number%10));
3066 number /= 10;
3067 out[bufptr ] = (char) ('0'+(number%10));
3068 return bufptr+4;
3069 }
3070
3071 /**
3072 * Compute <code>value*signum</code> where value==null is treated as
3073 * value==0.
3074 * @return non-null {@link BigInteger}.
3075 */
3076 static BigInteger sanitize(Number value, int signum) {
3077 if (signum == 0 || value == null) {
3078 return BigInteger.ZERO;
3079 }
3080 return (signum < 0)? ((BigInteger)value).negate() : (BigInteger)value;
3081 }
3082
3083 /** <p><code>reset()</code> is designed to allow the reuse of existing
3084 * <code>XMLGregorianCalendar</code>s thus saving resources associated
3085 * with the creation of new <code>XMLGregorianCalendar</code>s.</p>
3086 */
3087 public void reset() {
3088 //PENDING : Implementation of reset method
3089 }
3090 }