| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| // $Id: XMLGregorianCalendar.java 759822 2009-03-30 01:15:11Z mrglavas $ |
| |
| package javax.xml.datatype; |
| |
| import java.math.BigDecimal; |
| import java.math.BigInteger; |
| import java.util.GregorianCalendar; |
| import java.util.TimeZone; |
| import javax.xml.namespace.QName; |
| |
| /** |
| * <p>Representation for W3C XML Schema 1.0 date/time datatypes. |
| * Specifically, these date/time datatypes are |
| * <a href="#DATETIME"><code>dateTime</code></a>, |
| * <a href="#TIME"><code>time</code></a>, |
| * <a href="#DATE"><code>date</code></a>, |
| * <a href="#GYEARMONTH"><code>gYearMonth</code></a>, |
| * <a href="#GMONTHDAY"><code>gMonthDay</code></a>, |
| * <a href="#GYEAR"><code>gYear</code></a> |
| * <a href="#GMONTH"><code>gMonth</code></a> and |
| * <a href="#GDAY"><code>gDay</code></a> defined in the XML Namespace |
| * <code>"http://www.w3.org/2001/XMLSchema"</code>. |
| * These datatypes are normatively defined in |
| * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p> |
| * |
| * <p>The table below defines the mapping between XML Schema 1.0 |
| * date/time datatype fields and this class' fields. It also summarizes |
| * the value constraints for the date and time fields defined in |
| * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D, |
| * <i>ISO 8601 Date and Time Formats</i></a>.</p> |
| * |
| * <a name="datetimefieldsmapping"/> |
| * <table border="2" rules="all" cellpadding="2"> |
| * <thead> |
| * <tr> |
| * <th align="center" colspan="3"> |
| * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation |
| * </th> |
| * </tr> |
| * </thead> |
| * <tbody> |
| * <tr> |
| * <th>XML Schema 1.0<br/> |
| * datatype<br/> |
| * field</th> |
| * <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th> |
| * <th>Value Range</th> |
| * </tr> |
| * <a name="datetimefield-year"/> |
| * <tr> |
| * <td> year </td> |
| * <td> {@link #getYear()} + {@link #getEon()} or<br/> |
| * {@link #getEonAndYear} |
| * </td> |
| * <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1 |
| * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> |
| * {@link #getEon()} is high order year value in billion of years.<br/> |
| * <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9). |
| * A value of null indicates field is undefined.</br> |
| * 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 |
| * will be a valid lexical value in a future version of XML Schema, |
| * this class allows the year field to be set to zero. Otherwise, |
| * the year field value is handled exactly as described |
| * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0 |
| * validation does not allow for the year field to have a value of zero. |
| * </td> |
| * </tr> |
| * <a name="datetimefield-month"/> |
| * <tr> |
| * <td> month </td> |
| * <td> {@link #getMonth()} </td> |
| * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> |
| * </tr> |
| * <a name="datetimefield-day"/> |
| * <tr> |
| * <td> day </td> |
| * <td> {@link #getDay()} </td> |
| * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> |
| * The normative value constraint stated relative to month |
| * 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>. |
| * </td> |
| * </tr> |
| * <tr id="datetimefield-hour"> |
| * <td>hour</td> |
| * <td>{@link #getHour()}</td> |
| * <td> |
| * 0 to 24 or {@link DatatypeConstants#FIELD_UNDEFINED}. |
| * For a value of 24, the minute and second field must be zero per |
| * <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">XML Schema Errata</a>. |
| * </td> |
| * </tr> |
| * <a name="datetimefield-minute"/> |
| * <tr> |
| * <td> minute </td> |
| * <td> {@link #getMinute()} </td> |
| * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> |
| * </tr> |
| * <a name="datetimefield-second"/> |
| * <tr> |
| * <td>second</td> |
| * <td> |
| * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/> |
| * {@link #getSecond()} + {@link #getFractionalSecond()} |
| * </td> |
| * <td> |
| * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> |
| * <i>(Note: 60 only allowable for leap second.)</i><br/> |
| * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when |
| * the {@link #getSecond()} is defined.<br/> |
| * <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br /> |
| * {@link #getMillisecond()} is the convenience |
| * millisecond precision of value of {@link #getFractionalSecond()}. |
| * </td> |
| * </tr> |
| * <tr id="datetimefield-timezone"> |
| * <td> timezone </td> |
| * <td> {@link #getTimezone()} </td> |
| * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. |
| * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes). |
| * </td> |
| * </tr> |
| * </tbody> |
| * </table> |
| * |
| * <p>All maximum value space constraints listed for the fields in the table |
| * above are checked by factory methods, @{link DatatypeFactory}, |
| * setter methods and parse methods of |
| * this class. <code>IllegalArgumentException</code> is thrown when a |
| * parameter's value is outside the value constraint for the field or |
| * if the composite |
| * values constitute an invalid XMLGregorianCalendar instance (for example, if |
| * the 31st of June is specified). |
| * </p> |
| * |
| * <p>The following operations are defined for this class: |
| * <ul> |
| * <li>accessors/mutators for independent date/time fields</li> |
| * <li>conversion between this class and W3C XML Schema 1.0 lexical representation, |
| * {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li> |
| * <li>conversion between this class and {@link GregorianCalendar}, |
| * {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)}, |
| * {@link DatatypeFactory}</li> |
| * <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li> |
| * <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li> |
| * <li>addition operation with {@link Duration} |
| * instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes"> |
| * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>. |
| * </li> |
| * </ul> |
| * </p> |
| * |
| * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a> |
| * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> |
| * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> |
| * @version $Revision: 759822 $, $Date: 2009-03-29 18:15:11 -0700 (Sun, 29 Mar 2009) $ |
| * @see Duration |
| * @see DatatypeFactory |
| * @since 1.5 |
| */ |
| |
| public abstract class XMLGregorianCalendar |
| implements Cloneable { |
| |
| /** |
| * <p>Unset all fields to undefined.</p> |
| * |
| * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields |
| * to null.</p> |
| */ |
| public abstract void clear(); |
| |
| /** |
| * <p>Reset this <code>XMLGregorianCalendar</code> to its original values.</p> |
| * |
| * <p><code>XMLGregorianCalendar</code> is reset to the same values as when it was created with |
| * {@link DatatypeFactory#newXMLGregorianCalendar()}, |
| * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendar( |
| * BigInteger year, |
| * int month, |
| * int day, |
| * int hour, |
| * int minute, |
| * int second, |
| * BigDecimal fractionalSecond, |
| * int timezone)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendar( |
| * int year, |
| * int month, |
| * int day, |
| * int hour, |
| * int minute, |
| * int second, |
| * int millisecond, |
| * int timezone)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendarDate( |
| * int year, |
| * int month, |
| * int day, |
| * int timezone)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendarTime( |
| * int hours, |
| * int minutes, |
| * int seconds, |
| * int timezone)}, |
| * {@link DatatypeFactory#newXMLGregorianCalendarTime( |
| * int hours, |
| * int minutes, |
| * int seconds, |
| * BigDecimal fractionalSecond, |
| * int timezone)} or |
| * {@link DatatypeFactory#newXMLGregorianCalendarTime( |
| * int hours, |
| * int minutes, |
| * int seconds, |
| * int milliseconds, |
| * int timezone)}. |
| * </p> |
| * |
| * <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s |
| * thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p> |
| */ |
| public abstract void reset(); |
| |
| /** |
| * <p>Set low and high order component of XSD <code>dateTime</code> year field.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> |
| * |
| * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>year</code> parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setYear(BigInteger year); |
| |
| /** |
| * <p>Set year of XSD <code>dateTime</code> year field.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of |
| * {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Note: if the absolute value of the <code>year</code> parameter |
| * is less than 10^9, the eon component of the XSD year field is set to |
| * <code>null</code> by this method.</p> |
| * |
| * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. |
| * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>. |
| */ |
| public abstract void setYear(int year); |
| |
| /** |
| * <p>Set month.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>month</code> parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setMonth(int month); |
| |
| /** |
| * <p>Set days in month.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>day</code> parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setDay(int day); |
| |
| /** |
| * <p>Set the number of minutes in the timezone offset.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param offset value constraints summarized in <a href="#datetimefield-timezone"> |
| * timezone field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>offset</code> parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setTimezone(int offset); |
| |
| /** |
| * <p>Set time as one unit.</p> |
| * |
| * @param hour value constraints are summarized in |
| * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. |
| * @param minute value constraints are summarized in |
| * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. |
| * @param second value constraints are summarized in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>. |
| * |
| * @see #setTime(int, int, int, BigDecimal) |
| * |
| * @throws IllegalArgumentException if any parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public void setTime(int hour, int minute, int second) { |
| |
| setTime( |
| hour, |
| minute, |
| second, |
| null // fractional |
| ); |
| } |
| |
| /** |
| * <p>Set hours.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>hour</code> parameter is outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setHour(int hour); |
| |
| /** |
| * <p>Set minutes.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>minute</code> parameter is outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setMinute(int minute); |
| |
| /** |
| * <p>Set seconds.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>second</code> parameter is outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setSecond(int second); |
| |
| /** |
| * <p>Set milliseconds.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @param millisecond value constraints summarized in |
| * <a href="#datetimefield-millisecond">millisecond field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>millisecond</code> parameter is outside value constraints for the field as specified |
| * in <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setMillisecond(int millisecond); |
| |
| /** |
| * <p>Set fractional seconds.</p> |
| * |
| * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> |
| * |
| * @param fractional value constraints summarized in |
| * <a href="#datetimefield-fractional">fractional field of date/time field mapping table</a>. |
| * |
| * @throws IllegalArgumentException if <code>fractional</code> parameter is outside value constraints for the field as specified |
| * in <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public abstract void setFractionalSecond(BigDecimal fractional); |
| |
| /** |
| * <p>Set time as one unit, including the optional infinite precision |
| * fractional seconds.</p> |
| * |
| * @param hour value constraints are summarized in |
| * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. |
| * @param minute value constraints are summarized in |
| * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. |
| * @param second value constraints are summarized in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>. |
| * @param fractional value of <code>null</code> indicates this optional |
| * field is not set. |
| * |
| * @throws IllegalArgumentException if any parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public void setTime( |
| int hour, |
| int minute, |
| int second, |
| BigDecimal fractional) { |
| |
| setHour(hour); |
| setMinute(minute); |
| setSecond(second); |
| setFractionalSecond(fractional); |
| } |
| |
| /** |
| * <p>Set time as one unit, including optional milliseconds.</p> |
| * |
| * @param hour value constraints are summarized in |
| * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. |
| * @param minute value constraints are summarized in |
| * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. |
| * @param second value constraints are summarized in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>. |
| * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this |
| * optional field is not set. |
| * |
| * @throws IllegalArgumentException if any parameter is |
| * outside value constraints for the field as specified in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>. |
| */ |
| public void setTime(int hour, int minute, int second, int millisecond) { |
| |
| setHour(hour); |
| setMinute(minute); |
| setSecond(second); |
| setMillisecond(millisecond); |
| } |
| |
| /** |
| * <p>Return high order component for XML Schema 1.0 dateTime datatype field for |
| * <code>year</code>. |
| * <code>null</code> if this optional part of the year field is not defined.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> |
| * @return eon of this <code>XMLGregorianCalendar</code>. The value |
| * returned is an integer multiple of 10^9. |
| * |
| * @see #getYear() |
| * @see #getEonAndYear() |
| */ |
| public abstract BigInteger getEon(); |
| |
| /** |
| * <p>Return low order component for XML Schema 1.0 dateTime datatype field for |
| * <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> |
| * |
| * @return year of this <code>XMLGregorianCalendar</code>. |
| * |
| * @see #getEon() |
| * @see #getEonAndYear() |
| */ |
| public abstract int getYear(); |
| |
| /** |
| * <p>Return XML Schema 1.0 dateTime datatype field for |
| * <code>year</code>.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> |
| * |
| * @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code> |
| * when both fields are defined. When only <code>year</code> is defined, |
| * return it. When both <code>eon</code> and <code>year</code> are not |
| * defined, return <code>null</code>. |
| * |
| * @see #getEon() |
| * @see #getYear() |
| */ |
| public abstract BigInteger getEonAndYear(); |
| |
| /** |
| * <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p> |
| * |
| * @return year of this <code>XMLGregorianCalendar</code>. |
| * |
| */ |
| public abstract int getMonth(); |
| |
| /** |
| * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p> |
| * |
| * @see #setDay(int) |
| */ |
| public abstract int getDay(); |
| |
| /** |
| * Return timezone offset in minutes or |
| * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined. |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p> |
| * |
| * @see #setTimezone(int) |
| */ |
| public abstract int getTimezone(); |
| |
| /** |
| * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}. |
| * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p> |
| * @see #setTime(int, int, int) |
| */ |
| public abstract int getHour(); |
| |
| /** |
| * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p> |
| * @see #setTime(int, int, int) |
| */ |
| public abstract int getMinute(); |
| |
| /** |
| * <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. |
| * When this field is not defined, the optional xs:dateTime |
| * fractional seconds field, represented by |
| * {@link #getFractionalSecond()} and {@link #getMillisecond()}, |
| * must not be defined.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> |
| * |
| * @return Second of this <code>XMLGregorianCalendar</code>. |
| * |
| * @see #getFractionalSecond() |
| * @see #getMillisecond() |
| * @see #setTime(int, int, int) |
| */ |
| public abstract int getSecond(); |
| |
| /** |
| * <p>Return millisecond precision of {@link #getFractionalSecond()}.</p> |
| * |
| * <p>This method represents a convenience accessor to infinite |
| * precision fractional second value returned by |
| * {@link #getFractionalSecond()}. The returned value is the rounded |
| * down to milliseconds value of |
| * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()} |
| * returns <code>null</code>, this method must return |
| * {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * <p>Value constraints for this value are summarized in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> |
| * |
| * @return Millisecond of this <code>XMLGregorianCalendar</code>. |
| * |
| * @see #getFractionalSecond() |
| * @see #setTime(int, int, int) |
| */ |
| public int getMillisecond() { |
| |
| BigDecimal fractionalSeconds = getFractionalSecond(); |
| |
| // is field undefined? |
| if (fractionalSeconds == null) { |
| return DatatypeConstants.FIELD_UNDEFINED; |
| } |
| |
| return getFractionalSecond().movePointRight(3).intValue(); |
| } |
| |
| /** |
| * <p>Return fractional seconds.</p> |
| * |
| * <p><code>null</code> is returned when this optional field is not defined.</p> |
| * |
| * <p>Value constraints are detailed in |
| * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> |
| * |
| * <p>This optional field can only have a defined value when the |
| * xs:dateTime second field, represented by {@link #getSecond()}, |
| * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.</p> |
| * |
| * @return fractional seconds of this <code>XMLGregorianCalendar</code>. |
| * |
| * @see #getSecond() |
| * @see #setTime(int, int, int, BigDecimal) |
| */ |
| public abstract BigDecimal getFractionalSecond(); |
| |
| // comparisons |
| /** |
| * <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes |
| * according to partial order relation defined in |
| * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3, |
| * <i>Order relation on dateTime</i></a>.</p> |
| * |
| * <p><code>xsd:dateTime</code> datatype field mapping to accessors of |
| * this class are defined in |
| * <a href="#datetimefieldmapping">date/time field mapping table</a>.</p> |
| * |
| * @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar</code> to compare |
| * |
| * @return The relationship between <code>this</code> <code>XMLGregorianCalendar</code> and |
| * the specified <code>xmlGregorianCalendar</code> as |
| * {@link DatatypeConstants#LESSER}, |
| * {@link DatatypeConstants#EQUAL}, |
| * {@link DatatypeConstants#GREATER} or |
| * {@link DatatypeConstants#INDETERMINATE}. |
| * |
| * @throws NullPointerException if <code>xmlGregorianCalendar</code> is null. |
| */ |
| public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar); |
| |
| /** |
| * <p>Normalize this instance to UTC.</p> |
| * |
| * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p> |
| * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p> |
| * |
| * @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC. |
| */ |
| public abstract XMLGregorianCalendar normalize(); |
| |
| /** |
| * <p>Indicates whether parameter <code>obj</code> is "equal to" this one.</p> |
| * |
| * @param obj to compare. |
| * |
| * @return <code>true</code> when <code>obj</code> is an instance of <code>XMLGregorianCalendar</code> |
| * and {@link #compare(XMLGregorianCalendar obj)} returns {@link DatatypeConstants#EQUAL}, otherwise <code>false</code>. |
| */ |
| public boolean equals(Object obj) { |
| if (obj == this) { |
| return true; |
| } |
| if (obj instanceof XMLGregorianCalendar) { |
| return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL; |
| } |
| return false; |
| } |
| |
| /** |
| * <p>Returns a hash code consistent with the definition of the equals method.</p> |
| * |
| * @return hash code of this object. |
| */ |
| public int hashCode() { |
| |
| // Following two dates compare to EQUALS since in different timezones. |
| // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00 |
| // |
| // Must ensure both instances generate same hashcode by normalizing |
| // this to UTC timezone. |
| int timezone = getTimezone(); |
| if (timezone == DatatypeConstants.FIELD_UNDEFINED) { |
| timezone = 0; |
| } |
| XMLGregorianCalendar gc = this; |
| if (timezone != 0) { |
| gc = this.normalize(); |
| } |
| return gc.getYear() |
| + gc.getMonth() |
| + gc.getDay() |
| + gc.getHour() |
| + gc.getMinute() |
| + gc.getSecond(); |
| } |
| |
| /** |
| * <p>Return the lexical representation of <code>this</code> instance. |
| * The format is specified in |
| * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1, |
| * <i>Lexical Representation</i>".</a></p> |
| * |
| * <p>Specific target lexical representation format is determined by |
| * {@link #getXMLSchemaType()}.</p> |
| * |
| * @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code> |
| * |
| * @throws IllegalStateException if the combination of set fields |
| * does not match one of the eight defined XML Schema builtin date/time datatypes. |
| */ |
| public abstract String toXMLFormat(); |
| |
| /** |
| * <p>Return the name of the XML Schema date/time type that this instance |
| * maps to. Type is computed based on fields that are set.</p> |
| * |
| * <table border="2" rules="all" cellpadding="2"> |
| * <thead> |
| * <tr> |
| * <th align="center" colspan="7"> |
| * Required fields for XML Schema 1.0 Date/Time Datatypes.<br/> |
| * <i>(timezone is optional for all date/time datatypes)</i> |
| * </th> |
| * </tr> |
| * </thead> |
| * <tbody> |
| * <tr> |
| * <td>Datatype</td> |
| * <td>year</td> |
| * <td>month</td> |
| * <td>day</td> |
| * <td>hour</td> |
| * <td>minute</td> |
| * <td>second</td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#DATETIME}</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#DATE}</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#TIME}</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td>X</td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#GYEARMONTH}</td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#GMONTHDAY}</td> |
| * <td></td> |
| * <td>X</td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#GYEAR}</td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#GMONTH}</td> |
| * <td></td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * <tr> |
| * <td>{@link DatatypeConstants#GDAY}</td> |
| * <td></td> |
| * <td></td> |
| * <td>X</td> |
| * <td></td> |
| * <td></td> |
| * <td></td> |
| * </tr> |
| * </tbody> |
| * </table> |
| * |
| * @throws java.lang.IllegalStateException if the combination of set fields |
| * does not match one of the eight defined XML Schema builtin |
| * date/time datatypes. |
| * @return One of the following class constants: |
| * {@link DatatypeConstants#DATETIME}, |
| * {@link DatatypeConstants#TIME}, |
| * {@link DatatypeConstants#DATE}, |
| * {@link DatatypeConstants#GYEARMONTH}, |
| * {@link DatatypeConstants#GMONTHDAY}, |
| * {@link DatatypeConstants#GYEAR}, |
| * {@link DatatypeConstants#GMONTH} or |
| * {@link DatatypeConstants#GDAY}. |
| */ |
| public abstract QName getXMLSchemaType(); |
| |
| /** |
| * <p>Returns a <code>String</code> representation of this <code>XMLGregorianCalendar</code> <code>Object</code>.</p> |
| * |
| * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.</p> |
| * |
| * @return A non-<code>null</code> valid <code>String</code> representation of this <code>XMLGregorianCalendar</code>. |
| * |
| * @throws IllegalStateException if the combination of set fields |
| * does not match one of the eight defined XML Schema builtin date/time datatypes. |
| * |
| * @see #toXMLFormat() |
| */ |
| public String toString() { |
| |
| return toXMLFormat(); |
| } |
| |
| /** |
| * Validate instance by <code>getXMLSchemaType()</code> constraints. |
| * @return true if data values are valid. |
| */ |
| public abstract boolean isValid(); |
| |
| /** |
| * <p>Add <code>duration</code> to this instance.</p> |
| * |
| * <p>The computation is specified in |
| * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E, |
| * <i>Adding durations to dateTimes</i>></a>. |
| * <a href="#datetimefieldsmapping">date/time field mapping table</a> |
| * defines the mapping from XML Schema 1.0 <code>dateTime</code> fields |
| * to this class' representation of those fields.</p> |
| * |
| * @param duration Duration to add to this <code>XMLGregorianCalendar</code>. |
| * |
| * @throws NullPointerException when <code>duration</code> parameter is <code>null</code>. |
| */ |
| public abstract void add(Duration duration); |
| |
| /** |
| * <p>Convert this <code>XMLGregorianCalendar</code> to a {@link GregorianCalendar}.</p> |
| * |
| * <p>When <code>this</code> instance has an undefined field, this |
| * conversion relies on the <code>java.util.GregorianCalendar</code> default |
| * for its corresponding field. A notable difference between |
| * XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code> |
| * is that Timezone value is optional for date/time datatypes and it is |
| * a required field for <code>java.util.GregorianCalendar</code>. See javadoc |
| * for <code>java.util.TimeZone.getDefault()</code> on how the default |
| * is determined. To explicitly specify the <code>TimeZone</code> |
| * instance, see |
| * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p> |
| * |
| * <table border="2" rules="all" cellpadding="2"> |
| * <thead> |
| * <tr> |
| * <th align="center" colspan="2"> |
| * Field by Field Conversion from this class to |
| * <code>java.util.GregorianCalendar</code> |
| * </th> |
| * </tr> |
| * </thead> |
| * <tbody> |
| * <tr> |
| * <td><code>java.util.GregorianCalendar</code> field</td> |
| * <td><code>javax.xml.datatype.XMLGregorianCalendar</code> field</td> |
| * </tr> |
| * <tr> |
| * <td><code>ERA</code></td> |
| * <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td> |
| * </tr> |
| * <tr> |
| * <td><code>YEAR</code></td> |
| * <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td> |
| * </tr> |
| * <tr> |
| * <td><code>MONTH</code></td> |
| * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td> |
| * </tr> |
| * <tr> |
| * <td><code>DAY_OF_MONTH</code></td> |
| * <td>{@link #getDay()}</td> |
| * </tr> |
| * <tr> |
| * <td><code>HOUR_OF_DAY</code></td> |
| * <td>{@link #getHour()}</td> |
| * </tr> |
| * <tr> |
| * <td><code>MINUTE</code></td> |
| * <td>{@link #getMinute()}</td> |
| * </tr> |
| * <tr> |
| * <td><code>SECOND</code></td> |
| * <td>{@link #getSecond()}</td> |
| * </tr> |
| * <tr> |
| * <td><code>MILLISECOND</code></td> |
| * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td> |
| * </tr> |
| * <tr> |
| * <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td> |
| * <td>{@link #getTimezone()} formatted into Custom timezone id</td> |
| * </tr> |
| * </tbody> |
| * </table> |
| * <i>*</i> designates possible loss of precision during the conversion due |
| * to source datatype having higher precision than target datatype. |
| * |
| * <p>To ensure consistency in conversion implementations, the new |
| * <code>GregorianCalendar</code> should be instantiated in following |
| * manner. |
| * <ul> |
| * <li>Using <code>timeZone</code> value as defined above, create a new |
| * <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>. |
| * </li> |
| * <li>Initialize all GregorianCalendar fields by calling {(@link GegorianCalendar#clear()}.</li> |
| * <li>Obtain a pure Gregorian Calendar by invoking |
| * <code>GregorianCalendar.setGregorianChange( |
| * new Date(Long.MIN_VALUE))</code>.</li> |
| * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, |
| * MINUTE, SECOND and MILLISECOND are set using the method |
| * <code>Calendar.set(int,int)</code></li> |
| * </ul> |
| * </p> |
| * |
| * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) |
| */ |
| public abstract GregorianCalendar toGregorianCalendar(); |
| |
| /** |
| * <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters |
| * to a {@link GregorianCalendar} instance.</p> |
| * |
| * <p> Since XML Schema 1.0 date/time datetypes has no concept of |
| * timezone ids or daylight savings timezone ids, this conversion operation |
| * allows the user to explicitly specify one with |
| * <code>timezone</code> parameter.</p> |
| * |
| * <p>To compute the return value's <code>TimeZone</code> field, |
| * <ul> |
| * <li>when parameter <code>timeZone</code> is non-null, |
| * it is the timezone field.</li> |
| * <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>, |
| * create a <code>java.util.TimeZone</code> with a custom timezone id |
| * using the <code>this.getTimezone()</code>.</li> |
| * <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>, |
| * create a <code>java.util.TimeZone</code> with a custom timezone id |
| * using <code>defaults.getTimezone()</code>.</li> |
| * <li>else use the <code>GregorianCalendar</code> default timezone value |
| * for the host is defined as specified by |
| * <code>java.util.TimeZone.getDefault()</code>.</li></ul></p> |
| * |
| * <p>To ensure consistency in conversion implementations, the new |
| * <code>GregorianCalendar</code> should be instantiated in following |
| * manner. |
| * <ul> |
| * <li>Create a new <code>java.util.GregorianCalendar(TimeZone, |
| * Locale)</code> with TimeZone set as specified above and the |
| * <code>Locale</code> parameter. |
| * </li> |
| * <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li> |
| * <li>Obtain a pure Gregorian Calendar by invoking |
| * <code>GregorianCalendar.setGregorianChange( |
| * new Date(Long.MIN_VALUE))</code>.</li> |
| * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, |
| * MINUTE, SECOND and MILLISECOND are set using the method |
| * <code>Calendar.set(int,int)</code></li> |
| * </ul></p> |
| * |
| * @param timezone provide Timezone. <code>null</code> is a legal value. |
| * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if |
| * value is <code>null</code>. |
| * @param defaults provide default field values to use when corresponding |
| * field for this instance is FIELD_UNDEFINED or null. |
| * If <code>defaults</code>is <code>null</code> or a field |
| * within the specified <code>defaults</code> is undefined, |
| * just use <code>java.util.GregorianCalendar</code> defaults. |
| * @return a java.util.GregorianCalendar conversion of this instance. |
| */ |
| public abstract GregorianCalendar toGregorianCalendar( |
| java.util.TimeZone timezone, |
| java.util.Locale aLocale, |
| XMLGregorianCalendar defaults); |
| |
| /** |
| * <p>Returns a <code>java.util.TimeZone</code> for this class.</p> |
| * |
| * <p>If timezone field is defined for this instance, |
| * returns TimeZone initialized with custom timezone id |
| * of zoneoffset. If timezone field is undefined, |
| * try the defaultZoneoffset that was passed in. |
| * If defaultZoneoffset is FIELD_UNDEFINED, return |
| * default timezone for this host. |
| * (Same default as java.util.GregorianCalendar).</p> |
| * |
| * @param defaultZoneoffset default zoneoffset if this zoneoffset is |
| * {@link DatatypeConstants#FIELD_UNDEFINED}. |
| * |
| * @return TimeZone for this. |
| */ |
| public abstract TimeZone getTimeZone(int defaultZoneoffset); |
| |
| /** |
| * <p>Creates and returns a copy of this object.</p> |
| * |
| * @return copy of this <code>Object</code> |
| */ |
| public abstract Object clone(); |
| } |
