Java tutorial
/* * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.datatype; import javax.xml.namespace.QName; import java.math.BigDecimal; import java.math.BigInteger; import java.util.TimeZone; import java.util.GregorianCalendar; /** * <p>Representation for W3C XML Schema 1.0 date/time datatypes. * Specifically, these date/time datatypes are * {@link DatatypeConstants#DATETIME}, * {@link DatatypeConstants#TIME}, * {@link DatatypeConstants#DATE}, * {@link DatatypeConstants#GYEARMONTH}, * {@link DatatypeConstants#GMONTHDAY}, * {@link DatatypeConstants#GYEAR}, * {@link DatatypeConstants#GMONTH}, and * {@link DatatypeConstants#GDAY} * defined in the XML Namespace * {@code "http://www.w3.org/2001/XMLSchema"}. * 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>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>. * * <a id="datetimefieldmapping"></a> * <table class="striped"> * <caption>Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</caption> * <thead> * <tr> * <th scope="col">XML Schema 1.0<br> * datatype<br> * field</th> * <th scope="col">Related<br>XMLGregorianCalendar<br>Accessor(s)</th> * <th scope="col">Value Range</th> * </tr> * </thead> * <tbody> * <tr> * <th scope="row"><a id="datetimefield-year">year</a></th> * <td> {@link #getYear()} + {@link #getEon()} or<br> * {@link #getEonAndYear} * </td> * <td> {@code getYear()} 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()} 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> * <tr> * <th scope="row"><a id="datetimefield-month">month</a></th> * <td> {@link #getMonth()} </td> * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> * </tr> * <tr> * <th scope="row"><a id="datetimefield-day">day</a></th> * <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> * <th scope="row"><a id="datetimefield-hour">hour</a></th> * <td>{@link #getHour()}</td> * <td> * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}. * An hour value of 24 is allowed to be set in the lexical space provided the minute and second * field values are zero. However, an hour value of 24 is not allowed in value space and will be * transformed to represent the value of the first instance of the following day as per * <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes"> * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>. * </td> * </tr> * <tr> * <th scope="row"><a id="datetimefield-minute">minute</a></th> * <td> {@link #getMinute()} </td> * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> * </tr> * <tr> * <th scope="row"><a id="datetimefield-second">second</a></th> * <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} is optional and has a value of {@code null} when it is undefined.<br> * {@link #getMillisecond()} is the convenience * millisecond precision of value of {@link #getFractionalSecond()}. * </td> * </tr> * <tr> * <th scope="row"><a id="datetimefield-timezone">timezone</a></th> * <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} 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>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> * * @author Joseph Fialli * @author Kohsuke Kawaguchi * @author Jeff Suttor * @author Sunitha Reddy * @see Duration * @see DatatypeFactory * @since 1.5 */ public abstract class XMLGregorianCalendar implements Cloneable { /** * Default no-arg constructor. * * <p>Note: Always use the {@link DatatypeFactory} to * construct an instance of {@code XMLGregorianCalendar}. * The constructor on this class cannot be guaranteed to * produce an object with a consistent state and may be * removed in the future. */ public XMLGregorianCalendar() { } /** * Unset all fields to undefined. * * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields * to null. */ public abstract void clear(); /** * Reset this {@code XMLGregorianCalendar} to its original values. * * <p>{@code XMLGregorianCalendar} 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>{@code reset()} is designed to allow the reuse of existing {@code XMLGregorianCalendar}s * thus saving resources associated with the creation of new {@code XMLGregorianCalendar}s. */ public abstract void reset(); /** * Set low and high order component of XSD {@code dateTime} year field. * * <p>Unset this field by invoking the setter with a parameter value of {@code null}. * * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code year} 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); /** * Set year of XSD {@code dateTime} year field. * * <p>Unset this field by invoking the setter with a parameter value of * {@link DatatypeConstants#FIELD_UNDEFINED}. * * <p>Note: if the absolute value of the {@code year} parameter * is less than 10^9, the eon component of the XSD year field is set to * {@code null} by this method. * * @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}. */ public abstract void setYear(int year); /** * Set month. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code month} 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); /** * Set days in month. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code day} 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); /** * Set the number of minutes in the timezone offset. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param offset value constraints summarized in <a href="#datetimefield-timezone"> * timezone field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code offset} 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); /** * Set time as one unit. * * @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 ); } /** * Set hours. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code hour} 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); /** * Set minutes. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code minute} 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); /** * Set seconds. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code second} 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); /** * Set milliseconds. * * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param millisecond value constraints summarized in * <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code millisecond} 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); /** * Set fractional seconds. * * <p>Unset this field by invoking the setter with a parameter value of {@code null}. * * @param fractional value constraints summarized in * <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * @throws IllegalArgumentException if {@code fractional} 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); /** * Set time as one unit, including the optional infinite precision * fractional seconds. * * @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} 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); } /** * Set time as one unit, including optional milliseconds. * * @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); } /** * Returns the high order component for XML Schema 1.0 dateTime datatype field for * {@code year}. * {@code null} if this optional part of the year field is not defined. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-year">year field of date/time field mapping table</a>. * @return The eon of this {@code XMLGregorianCalendar}. The value * returned is an integer multiple of 10^9. * * @see #getYear() * @see #getEonAndYear() */ public abstract BigInteger getEon(); /** * Returns the low order component for XML Schema 1.0 dateTime datatype field for * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-year">year field of date/time field mapping table</a>. * * @return The year of this {@code XMLGregorianCalendar}. * * @see #getEon() * @see #getEonAndYear() */ public abstract int getYear(); /** * Returns the XML Schema 1.0 dateTime datatype field for * {@code year}. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-year">year field of date/time field mapping table</a>. * * @return sum of {@code eon} and {@code BigInteger.valueOf(year)} * when both fields are defined. When only {@code year} is defined, * return it. When both {@code eon} and {@code year} are not * defined, return {@code null}. * * @see #getEon() * @see #getYear() */ public abstract BigInteger getEonAndYear(); /** * Returns the month of this calendar or {@link DatatypeConstants#FIELD_UNDEFINED}. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-month">month field of date/time field mapping table</a>. * * @return The month of this {@code XMLGregorianCalendar}, from 1 to 12. * */ public abstract int getMonth(); /** * Returns the day of month or {@link DatatypeConstants#FIELD_UNDEFINED}. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-day">day field of date/time field mapping table</a>. * * @return The day of month of this {@code XMLGregorianCalendar}, from 1 to 31. * * @see #setDay(int) */ public abstract int getDay(); /** * Returns the 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>. * * @return The Timezone offset in minutes of this {@code XMLGregorianCalendar}. * * @see #setTimezone(int) */ public abstract int getTimezone(); /** * Returns the hour of day or * {@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>. * * @return The hour of day of this {@code XMLGregorianCalendar}, from 0 to 23. * * @see #setTime(int, int, int) */ public abstract int getHour(); /** * Returns the minute of hour or * {@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>. * * @return The minute of hour of this {@code XMLGregorianCalendar}, from 0 to 59. * * @see #setTime(int, int, int) */ public abstract int getMinute(); /** * Returns the second of minute or * {@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>Value constraints for this value are summarized in * <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * @return The second of minute of this {@code XMLGregorianCalendar}, from 0 to 59. * * @see #getFractionalSecond() * @see #getMillisecond() * @see #setTime(int, int, int) */ public abstract int getSecond(); /** * Returns the millisecond precision of {@link #getFractionalSecond()}. * * <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}, this method must return * {@link DatatypeConstants#FIELD_UNDEFINED}. * * <p>Value constraints for this value are summarized in * <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * @return The millisecond precision of this {@code XMLGregorianCalendar}. * * @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(); } /** * Returns fractional seconds. * * <p>{@code null} is returned when this optional field is not defined. * * <p>Value constraints are detailed in * <a href="#datetimefield-second">second field of date/time field mapping table</a>. * * <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}. * * @return Fractional seconds of this {@code XMLGregorianCalendar}. * * @see #getSecond() * @see #setTime(int, int, int, BigDecimal) */ public abstract BigDecimal getFractionalSecond(); // comparisons /** * 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>{@code xsd:dateTime} datatype field mapping to accessors of * this class are defined in * <a href="#datetimefieldmapping">date/time field mapping table</a>. * * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare * * @return The relationship between {@code this} {@code XMLGregorianCalendar} and * the specified {@code xmlGregorianCalendar} as * {@link DatatypeConstants#LESSER}, * {@link DatatypeConstants#EQUAL}, * {@link DatatypeConstants#GREATER} or * {@link DatatypeConstants#INDETERMINATE}. * * @throws NullPointerException if {@code xmlGregorianCalendar} is null. */ public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar); /** * Normalize this instance to UTC. * * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A). * * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC. */ public abstract XMLGregorianCalendar normalize(); /** * Compares this calendar to the specified object. The result is * {@code true} if and only if the argument is not null and is an * {@code XMLGregorianCalendar} object that represents the same * instant in time as this object. * * @param obj to compare. * * @return {@code true} when {@code obj} is an instance of * {@code XMLGregorianCalendar} and * {@link #compare(XMLGregorianCalendar obj)} * returns {@link DatatypeConstants#EQUAL}, * otherwise {@code false}. */ @Override public boolean equals(Object obj) { if (obj == null || !(obj instanceof XMLGregorianCalendar)) { return false; } return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL; } /** * Returns a hash code consistent with the definition of the equals method. * * @return hash code of this object. */ @Override 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(); } /** * Return the lexical representation of {@code this} 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>Specific target lexical representation format is determined by * {@link #getXMLSchemaType()}. * * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar} * * @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(); /** * Return the name of the XML Schema date/time type that this instance * maps to. Type is computed based on fields that are set. * * <table class="striped"> * <caption>Required fields for XML Schema 1.0 Date/Time Datatypes.<br> * <i>(timezone is optional for all date/time datatypes)</i></caption> * <thead> * <tr> * <th scope="col">Datatype</th> * <th scope="col">year</th> * <th scope="col">month</th> * <th scope="col">day</th> * <th scope="col">hour</th> * <th scope="col">minute</th> * <th scope="col">second</th> * </tr> * </thead> * <tbody> * <tr> * <th scope="row">{@link DatatypeConstants#DATETIME}</th> * <td>X</td> * <td>X</td> * <td>X</td> * <td>X</td> * <td>X</td> * <td>X</td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#DATE}</th> * <td>X</td> * <td>X</td> * <td>X</td> * <td></td> * <td></td> * <td></td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#TIME}</th> * <td></td> * <td></td> * <td></td> * <td>X</td> * <td>X</td> * <td>X</td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#GYEARMONTH}</th> * <td>X</td> * <td>X</td> * <td></td> * <td></td> * <td></td> * <td></td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#GMONTHDAY}</th> * <td></td> * <td>X</td> * <td>X</td> * <td></td> * <td></td> * <td></td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#GYEAR}</th> * <td>X</td> * <td></td> * <td></td> * <td></td> * <td></td> * <td></td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#GMONTH}</th> * <td></td> * <td>X</td> * <td></td> * <td></td> * <td></td> * <td></td> * </tr> * <tr> * <th scope="row">{@link DatatypeConstants#GDAY}</th> * <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(); /** * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}. * * <p>The result is a lexical representation generated by {@link #toXMLFormat()}. * * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}. * * @throws IllegalStateException if the combination of set fields * does not match one of the eight defined XML Schema builtin date/time datatypes. * * @see #toXMLFormat() */ @Override public String toString() { return toXMLFormat(); } /** * Validate instance by {@code getXMLSchemaType()} constraints. * @return true if data values are valid. */ public abstract boolean isValid(); /** * Add {@code duration} to this instance. * * <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="#datetimefieldmapping">date/time field mapping table</a> * defines the mapping from XML Schema 1.0 {@code dateTime} fields * to this class' representation of those fields. * * @param duration Duration to add to this {@code XMLGregorianCalendar}. * * @throws NullPointerException when {@code duration} parameter is {@code null}. */ public abstract void add(Duration duration); /** * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}. * * <p>When {@code this} instance has an undefined field, this * conversion relies on the {@code java.util.GregorianCalendar} default * for its corresponding field. A notable difference between * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar} * is that Timezone value is optional for date/time datatypes and it is * a required field for {@code java.util.GregorianCalendar}. See javadoc * for {@code java.util.TimeZone.getDefault()} on how the default * is determined. To explicitly specify the {@code TimeZone} * instance, see * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}. * * <table class="striped"> * <caption>Field by Field Conversion from this class to * {@code java.util.GregorianCalendar}</caption> * <thead> * <tr> * <th scope="col">{@code java.util.GregorianCalendar} field</th> * <th scope="col">{@code javax.xml.datatype.XMLGregorianCalendar} field</th> * </tr> * </thead> * <tbody> * <tr> * <th scope="row">{@code ERA}</th> * <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td> * </tr> * <tr> * <th scope="row">{@code YEAR}</th> * <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td> * </tr> * <tr> * <th scope="row">{@code MONTH}</th> * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td> * </tr> * <tr> * <th scope="row">{@code DAY_OF_MONTH}</th> * <td>{@link #getDay()}</td> * </tr> * <tr> * <th scope="row">{@code HOUR_OF_DAY}</th> * <td>{@link #getHour()}</td> * </tr> * <tr> * <th scope="row">{@code MINUTE}</th> * <td>{@link #getMinute()}</td> * </tr> * <tr> * <th scope="row">{@code SECOND}</th> * <td>{@link #getSecond()}</td> * </tr> * <tr> * <th scope="row">{@code MILLISECOND}</th> * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td> * </tr> * <tr> * <th scope="row">{@code GregorianCalendar.setTimeZone(TimeZone)}</th> * <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} should be instantiated in following * manner. * <ul> * <li>Using {@code timeZone} value as defined above, create a new * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}. * </li> * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li> * <li>Obtain a pure Gregorian Calendar by invoking * {@code GregorianCalendar.setGregorianChange( * new Date(Long.MIN_VALUE))}.</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)}</li> * </ul> * * @return An instance of {@link java.util.GregorianCalendar}. * * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) */ public abstract GregorianCalendar toGregorianCalendar(); /** * Convert this {@code XMLGregorianCalendar} along with provided parameters * to a {@link GregorianCalendar} instance. * * <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} parameter. * * <p>To compute the return value's {@code TimeZone} field, * <ul> * <li>when parameter {@code timeZone} is non-null, * it is the timezone field.</li> * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED}, * create a {@code java.util.TimeZone} with a custom timezone id * using the {@code this.getTimezone()}.</li> * <li>else when {@code defaults.getTimezone() != FIELD_UNDEFINED}, * create a {@code java.util.TimeZone} with a custom timezone id * using {@code defaults.getTimezone()}.</li> * <li>else use the {@code GregorianCalendar} default timezone value * for the host is defined as specified by * {@code java.util.TimeZone.getDefault()}.</li> * </ul> * * <p>To ensure consistency in conversion implementations, the new * {@code GregorianCalendar} should be instantiated in following * manner. * <ul> * <li>Create a new {@code java.util.GregorianCalendar(TimeZone, * Locale)} with TimeZone set as specified above and the * {@code Locale} 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))}.</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)}</li> * </ul> * * @param timezone provide Timezone. {@code null} is a legal value. * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if * value is {@code null}. * @param defaults provide default field values to use when corresponding * field for this instance is FIELD_UNDEFINED or null. * If {@code defaults}is {@code null} or a field * within the specified {@code defaults} is undefined, * just use {@code java.util.GregorianCalendar} defaults. * @return a java.util.GregorianCalendar conversion of this instance. */ public abstract GregorianCalendar toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults); /** * Returns a {@code java.util.TimeZone} for this class. * * <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). * * @param defaultZoneoffset default zoneoffset if this zoneoffset is * {@link DatatypeConstants#FIELD_UNDEFINED}. * * @return TimeZone for this. */ public abstract TimeZone getTimeZone(int defaultZoneoffset); /** * Creates and returns a copy of this object. * * @return copy of this {@code Object} */ @Override public abstract Object clone(); }