286N/A * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * <p>Representation for W3C XML Schema 1.0 date/time datatypes. 286N/A * {@link DatatypeConstants#DATETIME}, 286N/A * {@link DatatypeConstants#TIME}, 286N/A * {@link DatatypeConstants#DATE}, 286N/A * {@link DatatypeConstants#GYEARMONTH}, 286N/A * {@link DatatypeConstants#GMONTHDAY}, 286N/A * {@link DatatypeConstants#GYEAR}, 286N/A * {@link DatatypeConstants#GMONTH}, and 286N/A * {@link DatatypeConstants#GDAY} 286N/A * defined in the XML Namespace 286N/A * These datatypes are normatively defined in 286N/A * <p>The table below defines the mapping between XML Schema 1.0 286N/A * date/time datatype fields and this class' fields. It also summarizes 286N/A * the value constraints for the date and time fields defined in 286N/A * <i>ISO 8601 Date and Time Formats</i></a>.</p> 286N/A * <a name="datetimefieldmapping"/> 286N/A * <table border="2" rules="all" cellpadding="2"> 286N/A * <th align="center" colspan="3"> 286N/A * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation 286N/A * <th>XML Schema 1.0<br/> 286N/A * <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th> 286N/A * <td><a name="datetimefield-year"/>year</td> 286N/A * <td> {@link #getYear()} + {@link #getEon()} or<br/> 286N/A * {@link #getEonAndYear} 286N/A * <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1 286N/A * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> 286N/A * {@link #getEon()} is high order year value in billion of years.<br/> 286N/A * <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9). 286N/A * A value of null indicates field is undefined.</br> 286N/A * will be a valid lexical value in a future version of XML Schema, 286N/A * this class allows the year field to be set to zero. Otherwise, 286N/A * the year field value is handled exactly as described 286N/A * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0 286N/A * validation does not allow for the year field to have a value of zero. 286N/A * <td><a name="datetimefield-month"/>month</td> 286N/A * <td> {@link #getMonth()} </td> 286N/A * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> 286N/A * <td><a name="datetimefield-day"/>day</td> 286N/A * <td> {@link #getDay()} </td> 286N/A * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> 286N/A * The normative value constraint stated relative to month 286N/A * <td><a name="datetimefield-hour"/>hour</td> 286N/A * <td>{@link #getHour()}</td> 286N/A * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}. 286N/A * An hour value of 24 is allowed to be set in the lexical space provided the minute and second 286N/A * field values are zero. However, an hour value of 24 is not allowed in value space and will be 286N/A * transformed to represent the value of the first instance of the following day as per 286N/A * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>. 286N/A * <td><a name="datetimefield-minute"/>minute</td> 286N/A * <td> {@link #getMinute()} </td> 286N/A * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> 286N/A * <td><a name="datetimefield-second"/>second</td> 286N/A * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/> 286N/A * {@link #getSecond()} + {@link #getFractionalSecond()} 286N/A * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> 286N/A * <i>(Note: 60 only allowable for leap second.)</i><br/> 286N/A * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when 286N/A * the {@link #getSecond()} is defined.<br/> 286N/A * <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br /> 286N/A * {@link #getMillisecond()} is the convenience 286N/A * millisecond precision of value of {@link #getFractionalSecond()}. 286N/A * <td><a name="datetimefield-timezone"/>timezone</td> 286N/A * <td> {@link #getTimezone()} </td> 286N/A * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. 286N/A * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes). 286N/A * <p>All maximum value space constraints listed for the fields in the table 286N/A * above are checked by factory methods, @{link DatatypeFactory}, 286N/A * setter methods and parse methods of 286N/A * this class. <code>IllegalArgumentException</code> is thrown when a 286N/A * parameter's value is outside the value constraint for the field or 286N/A * values constitute an invalid XMLGregorianCalendar instance (for example, if 286N/A * the 31st of June is specified). 286N/A * <p>The following operations are defined for this class: 286N/A * <li>conversion between this class and W3C XML Schema 1.0 lexical representation, 286N/A * {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li> 286N/A * <li>conversion between this class and {@link GregorianCalendar}, 286N/A * {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)}, 286N/A * {@link DatatypeFactory}</li> 286N/A * <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li> 286N/A * <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li> 286N/A * <li>addition operation with {@link Duration} 286N/A * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>. 286N/A * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a> 286N/A * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> 286N/A * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 286N/A * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a> 286N/A * Default no-arg constructor. 286N/A * <p>Note: Always use the {@link DatatypeFactory} to 286N/A * construct an instance of <code>XMLGregorianCalendar</code>. 286N/A * The constructor on this class cannot be guaranteed to 286N/A * produce an object with a consistent state and may be 286N/A * removed in the future.</p> 286N/A * <p>Unset all fields to undefined.</p> 286N/A * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields 286N/A * <p>Reset this <code>XMLGregorianCalendar</code> to its original values.</p> 286N/A * <p><code>XMLGregorianCalendar</code> is reset to the same values as when it was created with 286N/A * {@link DatatypeFactory#newXMLGregorianCalendar()}, 286N/A * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}, 286N/A * {@link DatatypeFactory#newXMLGregorianCalendar( 286N/A * BigDecimal fractionalSecond, 286N/A * {@link DatatypeFactory#newXMLGregorianCalendar( 286N/A * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)}, 286N/A * {@link DatatypeFactory#newXMLGregorianCalendarDate( 286N/A * {@link DatatypeFactory#newXMLGregorianCalendarTime( 286N/A * {@link DatatypeFactory#newXMLGregorianCalendarTime( 286N/A * BigDecimal fractionalSecond, 286N/A * {@link DatatypeFactory#newXMLGregorianCalendarTime( 286N/A * <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s 286N/A * thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p> 286N/A * <p>Set low and high order component of XSD <code>dateTime</code> year field.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> 286N/A * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>year</code> parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set year of XSD <code>dateTime</code> year field.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of 286N/A * {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Note: if the absolute value of the <code>year</code> parameter 286N/A * is less than 10^9, the eon component of the XSD year field is set to 286N/A * <code>null</code> by this method.</p> 286N/A * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. 286N/A * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>. 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>month</code> parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set days in month.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>day</code> parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set the number of minutes in the timezone offset.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param offset value constraints summarized in <a href="#datetimefield-timezone"> 286N/A * @throws IllegalArgumentException if <code>offset</code> parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set time as one unit.</p> 286N/A * @param hour value constraints are summarized in 286N/A * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. 286N/A * @param minute value constraints are summarized in 286N/A * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. 286N/A * @param second value constraints are summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @see #setTime(int, int, int, BigDecimal) 286N/A * @throws IllegalArgumentException if any parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>hour</code> parameter is outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>minute</code> parameter is outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>second</code> parameter is outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set milliseconds.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @param millisecond value constraints summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>millisecond</code> parameter is outside value constraints for the field as specified 286N/A * in <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set fractional seconds.</p> 286N/A * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> 286N/A * @param fractional value constraints summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @throws IllegalArgumentException if <code>fractional</code> parameter is outside value constraints for the field as specified 286N/A * in <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set time as one unit, including the optional infinite precision 286N/A * fractional seconds.</p> 286N/A * @param hour value constraints are summarized in 286N/A * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. 286N/A * @param minute value constraints are summarized in 286N/A * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. 286N/A * @param second value constraints are summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @param fractional value of <code>null</code> indicates this optional 286N/A * @throws IllegalArgumentException if any parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Set time as one unit, including optional milliseconds.</p> 286N/A * @param hour value constraints are summarized in 286N/A * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. 286N/A * @param minute value constraints are summarized in 286N/A * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. 286N/A * @param second value constraints are summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>. 286N/A * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this 286N/A * optional field is not set. 286N/A * @throws IllegalArgumentException if any parameter is 286N/A * outside value constraints for the field as specified in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>. 286N/A * <p>Return high order component for XML Schema 1.0 dateTime datatype field for 286N/A * <code>null</code> if this optional part of the year field is not defined.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> 286N/A * @return eon of this <code>XMLGregorianCalendar</code>. The value 286N/A * returned is an integer multiple of 10^9. 286N/A * @see #getEonAndYear() 286N/A * <p>Return low order component for XML Schema 1.0 dateTime datatype field for 286N/A * <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> 286N/A * @return year of this <code>XMLGregorianCalendar</code>. 286N/A * @see #getEonAndYear() 286N/A * <p>Return XML Schema 1.0 dateTime datatype field for 286N/A * <code>year</code>.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> 286N/A * @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code> 286N/A * when both fields are defined. When only <code>year</code> is defined, 286N/A * return it. When both <code>eon</code> and <code>year</code> are not 286N/A * defined, return <code>null</code>. 286N/A * <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p> 286N/A * @return year of this <code>XMLGregorianCalendar</code>. 286N/A * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p> 286N/A * Return timezone offset in minutes or 286N/A * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined. 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p> 286N/A * @see #setTimezone(int) 286N/A * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}. 286N/A * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p> 286N/A * @see #setTime(int, int, int) 286N/A * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p> 286N/A * @see #setTime(int, int, int) 286N/A * <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. 286N/A * When this field is not defined, the optional xs:dateTime 286N/A * fractional seconds field, represented by 286N/A * {@link #getFractionalSecond()} and {@link #getMillisecond()}, 286N/A * must not be defined.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> 286N/A * @return Second of this <code>XMLGregorianCalendar</code>. 286N/A * @see #getFractionalSecond() 286N/A * @see #getMillisecond() 286N/A * @see #setTime(int, int, int) 286N/A * <p>Return millisecond precision of {@link #getFractionalSecond()}.</p> 286N/A * <p>This method represents a convenience accessor to infinite 286N/A * precision fractional second value returned by 286N/A * {@link #getFractionalSecond()}. The returned value is the rounded 286N/A * down to milliseconds value of 286N/A * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()} 286N/A * returns <code>null</code>, this method must return 286N/A * {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * <p>Value constraints for this value are summarized in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> 286N/A * @return Millisecond of this <code>XMLGregorianCalendar</code>. 286N/A * @see #getFractionalSecond() 286N/A * @see #setTime(int, int, int) 286N/A * <p>Return fractional seconds.</p> 286N/A * <p><code>null</code> is returned when this optional field is not defined.</p> 286N/A * <p>Value constraints are detailed in 286N/A * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> 286N/A * <p>This optional field can only have a defined value when the 286N/A * xs:dateTime second field, represented by {@link #getSecond()}, 286N/A * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.</p> 286N/A * @return fractional seconds of this <code>XMLGregorianCalendar</code>. 286N/A * @see #setTime(int, int, int, BigDecimal) 286N/A * <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes 286N/A * according to partial order relation defined in 286N/A * <i>Order relation on dateTime</i></a>.</p> 286N/A * <p><code>xsd:dateTime</code> datatype field mapping to accessors of 286N/A * this class are defined in 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a>.</p> 286N/A * @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar</code> to compare 286N/A * @return The relationship between <code>this</code> <code>XMLGregorianCalendar</code> and 286N/A * the specified <code>xmlGregorianCalendar</code> as 286N/A * {@link DatatypeConstants#LESSER}, 286N/A * {@link DatatypeConstants#EQUAL}, 286N/A * {@link DatatypeConstants#GREATER} or 286N/A * {@link DatatypeConstants#INDETERMINATE}. 286N/A * @throws NullPointerException if <code>xmlGregorianCalendar</code> is null. 286N/A * <p>Normalize this instance to UTC.</p> 286N/A * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p> 286N/A * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p> 286N/A * @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC. 286N/A * <p>Compares this calendar to the specified object. The result is 286N/A * <code>true</code> if and only if the argument is not null and is an 286N/A * <code>XMLGregorianCalendar</code> object that represents the same 286N/A * instant in time as this object.</p> 286N/A * @param obj to compare. 286N/A * @return <code>true</code> when <code>obj</code> is an instance of 286N/A * <code>XMLGregorianCalendar</code> and 286N/A * {@link #compare(XMLGregorianCalendar obj)} 286N/A * returns {@link DatatypeConstants#EQUAL}, 286N/A * otherwise <code>false</code>. 286N/A * <p>Returns a hash code consistent with the definition of the equals method.</p> 286N/A * @return hash code of this object. 286N/A // Following two dates compare to EQUALS since in different timezones. 286N/A // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00 286N/A // Must ensure both instances generate same hashcode by normalizing 286N/A // this to UTC timezone. 286N/A * <p>Return the lexical representation of <code>this</code> instance. 286N/A * The format is specified in 286N/A * <i>Lexical Representation</i>".</a></p> 286N/A * <p>Specific target lexical representation format is determined by 286N/A * {@link #getXMLSchemaType()}.</p> 286N/A * @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code> 286N/A * @throws IllegalStateException if the combination of set fields 286N/A * does not match one of the eight defined XML Schema builtin date/time datatypes. 286N/A * <p>Return the name of the XML Schema date/time type that this instance 286N/A * maps to. Type is computed based on fields that are set.</p> 286N/A * <table border="2" rules="all" cellpadding="2"> 286N/A * <th align="center" colspan="7"> 286N/A * <td>{@link DatatypeConstants#DATETIME}</td> 286N/A * <td>{@link DatatypeConstants#DATE}</td> 286N/A * <td>{@link DatatypeConstants#TIME}</td> 286N/A * <td>{@link DatatypeConstants#GYEARMONTH}</td> 286N/A * <td>{@link DatatypeConstants#GMONTHDAY}</td> 286N/A * <td>{@link DatatypeConstants#GYEAR}</td> 286N/A * <td>{@link DatatypeConstants#GMONTH}</td> 286N/A * <td>{@link DatatypeConstants#GDAY}</td> 286N/A * @throws java.lang.IllegalStateException if the combination of set fields 286N/A * does not match one of the eight defined XML Schema builtin 286N/A * @return One of the following class constants: 286N/A * {@link DatatypeConstants#DATETIME}, 286N/A * {@link DatatypeConstants#TIME}, 286N/A * {@link DatatypeConstants#DATE}, 286N/A * {@link DatatypeConstants#GYEARMONTH}, 286N/A * {@link DatatypeConstants#GMONTHDAY}, 286N/A * {@link DatatypeConstants#GYEAR}, 286N/A * {@link DatatypeConstants#GMONTH} or 286N/A * {@link DatatypeConstants#GDAY}. 286N/A * <p>Returns a <code>String</code> representation of this <code>XMLGregorianCalendar</code> <code>Object</code>.</p> 286N/A * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.</p> 286N/A * @return A non-<code>null</code> valid <code>String</code> representation of this <code>XMLGregorianCalendar</code>. 286N/A * @throws IllegalStateException if the combination of set fields 286N/A * does not match one of the eight defined XML Schema builtin date/time datatypes. 286N/A * Validate instance by <code>getXMLSchemaType()</code> constraints. 286N/A * @return true if data values are valid. 286N/A * <p>Add <code>duration</code> to this instance.</p> 286N/A * <p>The computation is specified in 286N/A * <i>Adding durations to dateTimes</i>></a>. 286N/A * <a href="#datetimefieldmapping">date/time field mapping table</a> 286N/A * defines the mapping from XML Schema 1.0 <code>dateTime</code> fields 286N/A * to this class' representation of those fields.</p> 286N/A * @param duration Duration to add to this <code>XMLGregorianCalendar</code>. 286N/A * @throws NullPointerException when <code>duration</code> parameter is <code>null</code>. 286N/A * <p>Convert this <code>XMLGregorianCalendar</code> to a {@link GregorianCalendar}.</p> 286N/A * <p>When <code>this</code> instance has an undefined field, this 286N/A * conversion relies on the <code>java.util.GregorianCalendar</code> default 286N/A * for its corresponding field. A notable difference between 286N/A * XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code> 286N/A * is that Timezone value is optional for date/time datatypes and it is 286N/A * a required field for <code>java.util.GregorianCalendar</code>. See javadoc 286N/A * for <code>java.util.TimeZone.getDefault()</code> on how the default 286N/A * is determined. To explicitly specify the <code>TimeZone</code> 286N/A * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p> 286N/A * <table border="2" rules="all" cellpadding="2"> 286N/A * <th align="center" colspan="2"> 286N/A * Field by Field Conversion from this class to 286N/A * <code>java.util.GregorianCalendar</code> 286N/A * <td><code>java.util.GregorianCalendar</code> field</td> 286N/A * <td><code>ERA</code></td> 286N/A * <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td> 286N/A * <td><code>YEAR</code></td> 286N/A * <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td> 286N/A * <td><code>MONTH</code></td> 286N/A * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td> 286N/A * <td><code>DAY_OF_MONTH</code></td> 286N/A * <td>{@link #getDay()}</td> 286N/A * <td><code>HOUR_OF_DAY</code></td> 286N/A * <td>{@link #getHour()}</td> 286N/A * <td><code>MINUTE</code></td> 286N/A * <td>{@link #getMinute()}</td> 286N/A * <td><code>SECOND</code></td> 286N/A * <td>{@link #getSecond()}</td> 286N/A * <td><code>MILLISECOND</code></td> 286N/A * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td> 286N/A * <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td> 286N/A * <td>{@link #getTimezone()} formatted into Custom timezone id</td> 286N/A * <i>*</i> designates possible loss of precision during the conversion due 286N/A * to source datatype having higher precision than target datatype. 286N/A * <p>To ensure consistency in conversion implementations, the new 286N/A * <code>GregorianCalendar</code> should be instantiated in following 286N/A * <li>Using <code>timeZone</code> value as defined above, create a new 286N/A * <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>. 286N/A * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li> 286N/A * <li>Obtain a pure Gregorian Calendar by invoking 286N/A * <code>GregorianCalendar.setGregorianChange( 286N/A * new Date(Long.MIN_VALUE))</code>.</li> 286N/A * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 286N/A * MINUTE, SECOND and MILLISECOND are set using the method 286N/A * <code>Calendar.set(int,int)</code></li> 286N/A * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) 286N/A * <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters 286N/A * to a {@link GregorianCalendar} instance.</p> 286N/A * <p> Since XML Schema 1.0 date/time datetypes has no concept of 286N/A * timezone ids or daylight savings timezone ids, this conversion operation 286N/A * allows the user to explicitly specify one with 286N/A * <code>timezone</code> parameter.</p> 286N/A * <p>To compute the return value's <code>TimeZone</code> field, 286N/A * <li>when parameter <code>timeZone</code> is non-null, 286N/A * it is the timezone field.</li> 286N/A * <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>, 286N/A * create a <code>java.util.TimeZone</code> with a custom timezone id 286N/A * using the <code>this.getTimezone()</code>.</li> 286N/A * <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>, 286N/A * create a <code>java.util.TimeZone</code> with a custom timezone id 286N/A * using <code>defaults.getTimezone()</code>.</li> 286N/A * <li>else use the <code>GregorianCalendar</code> default timezone value 286N/A * for the host is defined as specified by 286N/A * <code>java.util.TimeZone.getDefault()</code>.</li></p> 286N/A * <p>To ensure consistency in conversion implementations, the new 286N/A * <code>GregorianCalendar</code> should be instantiated in following 286N/A * <li>Create a new <code>java.util.GregorianCalendar(TimeZone, 286N/A * Locale)</code> with TimeZone set as specified above and the 286N/A * <code>Locale</code> parameter. 286N/A * <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li> 286N/A * <li>Obtain a pure Gregorian Calendar by invoking 286N/A * <code>GregorianCalendar.setGregorianChange( 286N/A * new Date(Long.MIN_VALUE))</code>.</li> 286N/A * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 286N/A * MINUTE, SECOND and MILLISECOND are set using the method 286N/A * <code>Calendar.set(int,int)</code></li> 286N/A * @param timezone provide Timezone. <code>null</code> is a legal value. 286N/A * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if 286N/A * value is <code>null</code>. 286N/A * @param defaults provide default field values to use when corresponding 286N/A * field for this instance is FIELD_UNDEFINED or null. 286N/A * If <code>defaults</code>is <code>null</code> or a field 286N/A * within the specified <code>defaults</code> is undefined, 286N/A * just use <code>java.util.GregorianCalendar</code> defaults. 286N/A * @return a java.util.GregorianCalendar conversion of this instance. 286N/A * <p>Returns a <code>java.util.TimeZone</code> for this class.</p> 286N/A * <p>If timezone field is defined for this instance, 286N/A * returns TimeZone initialized with custom timezone id 286N/A * of zoneoffset. If timezone field is undefined, 286N/A * try the defaultZoneoffset that was passed in. 286N/A * If defaultZoneoffset is FIELD_UNDEFINED, return 286N/A * default timezone for this host. 286N/A * (Same default as java.util.GregorianCalendar).</p> 286N/A * @param defaultZoneoffset default zoneoffset if this zoneoffset is 286N/A * {@link DatatypeConstants#FIELD_UNDEFINED}. 286N/A * @return TimeZone for this. 286N/A * <p>Creates and returns a copy of this object.</p> 286N/A * @return copy of this <code>Object</code>