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 * W3C XML Schema 1.0 Part 2, Section 3.2.7-14. * *
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 * W3C XML Schema 1.0 Part 2, Appendix D, * ISO 8601 Date and Time Formats. * * *
| * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation * | *||
|---|---|---|
| XML Schema 1.0 * datatype * field |
* Related XMLGregorianCalendar Accessor(s) |
* Value Range | *
| year | * {@link #getYear()} + {@link #getEon()} or * {@link #getEonAndYear} * |
* {@code getYear()} is a value between -(10^9-1) to (10^9)-1
* or {@link DatatypeConstants#FIELD_UNDEFINED}. * {@link #getEon()} is high order year value in billion of years. * {@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. * Given that XML Schema 1.0 errata 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. * |
*
| month | *{@link #getMonth()} | *1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} | *
| day | *{@link #getDay()} | * Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}. * The normative value constraint stated relative to month * field's value is in W3C XML Schema 1.0 Part 2, Appendix D. * |
*
| hour | *{@link #getHour()} | ** 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 * * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes. * | *
| minute | *{@link #getMinute()} | *0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} | *
| second | *
* {@link #getSecond()} + {@link #getMillisecond()}/1000 or * {@link #getSecond()} + {@link #getFractionalSecond()} * |
*
* {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}. * (Note: 60 only allowable for leap second.) * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when * the {@link #getSecond()} is defined. * {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined. * {@link #getMillisecond()} is the convenience * millisecond precision of value of {@link #getFractionalSecond()}. * |
*
| timezone | *{@link #getTimezone()} | *Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes). * | *
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). * *
The following operations are defined for this class: *
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. * *
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. * *
{@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)}. * *
{@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. * *
Unset this field by invoking the setter with a parameter value of {@code null}. * * @param year value constraints summarized in year field of date/time field mapping table. * * @throws IllegalArgumentException if {@code year} parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setYear(BigInteger year); /** * Set year of XSD {@code dateTime} year field. * *
Unset this field by invoking the setter with a parameter value of * {@link DatatypeConstants#FIELD_UNDEFINED}. * *
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 year field of date/time field mapping table. * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to {@code null}. */ public abstract void setYear(int year); /** * Set month. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param month value constraints summarized in month field of date/time field mapping table. * * @throws IllegalArgumentException if {@code month} parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setMonth(int month); /** * Set days in month. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param day value constraints summarized in day field of date/time field mapping table. * * @throws IllegalArgumentException if {@code day} parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setDay(int day); /** * Set the number of minutes in the timezone offset. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param offset value constraints summarized in * timezone field of date/time field mapping table. * * @throws IllegalArgumentException if {@code offset} parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setTimezone(int offset); /** * Set time as one unit. * * @param hour value constraints are summarized in * hour field of date/time field mapping table. * @param minute value constraints are summarized in * minute field of date/time field mapping table. * @param second value constraints are summarized in * second field of date/time field mapping table. * * @see #setTime(int, int, int, BigDecimal) * * @throws IllegalArgumentException if any parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public void setTime(int hour, int minute, int second) { setTime( hour, minute, second, null // fractional ); } /** * Set hours. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param hour value constraints summarized in hour field of date/time field mapping table. * * @throws IllegalArgumentException if {@code hour} parameter is outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setHour(int hour); /** * Set minutes. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param minute value constraints summarized in minute field of date/time field mapping table. * * @throws IllegalArgumentException if {@code minute} parameter is outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setMinute(int minute); /** * Set seconds. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param second value constraints summarized in second field of date/time field mapping table. * * @throws IllegalArgumentException if {@code second} parameter is outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setSecond(int second); /** * Set milliseconds. * *
Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}. * * @param millisecond value constraints summarized in * second field of date/time field mapping table. * * @throws IllegalArgumentException if {@code millisecond} parameter is outside value constraints for the field as specified * in date/time field mapping table. */ public abstract void setMillisecond(int millisecond); /** * Set fractional seconds. * *
Unset this field by invoking the setter with a parameter value of {@code null}. * * @param fractional value constraints summarized in * second field of date/time field mapping table. * * @throws IllegalArgumentException if {@code fractional} parameter is outside value constraints for the field as specified * in date/time field mapping table. */ 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 * hour field of date/time field mapping table. * @param minute value constraints are summarized in * minute field of date/time field mapping table. * @param second value constraints are summarized in * second field of date/time field mapping table. * @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 * date/time field mapping table. */ 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 * hour field of date/time field mapping table. * @param minute value constraints are summarized in * minute field of date/time field mapping table. * @param second value constraints are summarized in * second field of date/time field mapping table. * @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 * date/time field mapping table. */ public void setTime(int hour, int minute, int second, int millisecond) { setHour(hour); setMinute(minute); setSecond(second); setMillisecond(millisecond); } /** * Return 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. * *
Value constraints for this value are summarized in * year field of date/time field mapping table. * @return eon of this {@code XMLGregorianCalendar}. The value * returned is an integer multiple of 10^9. * * @see #getYear() * @see #getEonAndYear() */ public abstract BigInteger getEon(); /** * Return low order component for XML Schema 1.0 dateTime datatype field for * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}. * *
Value constraints for this value are summarized in * year field of date/time field mapping table. * * @return year of this {@code XMLGregorianCalendar}. * * @see #getEon() * @see #getEonAndYear() */ public abstract int getYear(); /** * Return XML Schema 1.0 dateTime datatype field for * {@code year}. * *
Value constraints for this value are summarized in * year field of date/time field mapping table. * * @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(); /** * Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}. * *
Value constraints for this value are summarized in * month field of date/time field mapping table. * * @return month of this {@code XMLGregorianCalendar}. * */ public abstract int getMonth(); /** * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}. * *
Value constraints for this value are summarized in * day field of date/time field mapping table. * * @see #setDay(int) */ public abstract int getDay(); /** * Return timezone offset in minutes or * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined. * *
Value constraints for this value are summarized in * timezone field of date/time field mapping table. * * @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. * *
Value constraints for this value are summarized in * hour field of date/time field mapping table. * @see #setTime(int, int, int) */ public abstract int getHour(); /** * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. * *
Value constraints for this value are summarized in * minute field of date/time field mapping table. * @see #setTime(int, int, int) */ public abstract int getMinute(); /** * Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}. * *
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. * *
Value constraints for this value are summarized in * second field of date/time field mapping table. * * @return Second of this {@code XMLGregorianCalendar}. * * @see #getFractionalSecond() * @see #getMillisecond() * @see #setTime(int, int, int) */ public abstract int getSecond(); /** * Return millisecond precision of {@link #getFractionalSecond()}. * *
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}. * *
Value constraints for this value are summarized in * second field of date/time field mapping table. * * @return Millisecond 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(); } /** * Return fractional seconds. * *
{@code null} is returned when this optional field is not defined. * *
Value constraints are detailed in * second field of date/time field mapping table. * *
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 * W3C XML Schema 1.0 Part 2, Section 3.2.7.3, * Order relation on dateTime. * *
{@code xsd:dateTime} datatype field mapping to accessors of * this class are defined in * date/time field mapping table. * * @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. * *
2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z *
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}. */ 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. */ 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 * XML Schema 1.0 Part 2, Section 3.2.[7-14].1, * Lexical Representation". * *
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. * *
|
* Required fields for XML Schema 1.0 Date/Time Datatypes. * (timezone is optional for all date/time datatypes) * |
* ||||||
|---|---|---|---|---|---|---|
| Datatype | *year | *month | *day | *hour | *minute | *second | *
| {@link DatatypeConstants#DATETIME} | *X | *X | *X | *X | *X | *X | *
| {@link DatatypeConstants#DATE} | *X | *X | *X | ** | * | * |
| {@link DatatypeConstants#TIME} | ** | * | * | X | *X | *X | *
| {@link DatatypeConstants#GYEARMONTH} | *X | *X | ** | * | * | * |
| {@link DatatypeConstants#GMONTHDAY} | ** | X | *X | ** | * | * |
| {@link DatatypeConstants#GYEAR} | *X | ** | * | * | * | * |
| {@link DatatypeConstants#GMONTH} | ** | X | ** | * | * | * |
| {@link DatatypeConstants#GDAY} | ** | * | X | ** | * | * |
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() */ 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. * *
The computation is specified in * XML Schema 1.0 Part 2, Appendix E, * Adding durations to dateTimes. * date/time field mapping table * 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}. * *
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)}. * *
| * Field by Field Conversion from this class to * {@code java.util.GregorianCalendar} * | *|
|---|---|
| {@code java.util.GregorianCalendar} field | *{@code javax.xml.datatype.XMLGregorianCalendar} field | *
| {@code ERA} | *{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD} | *
| {@code YEAR} | *{@link #getEonAndYear()}{@code .abs().intValue()}* | *
| {@code MONTH} | *{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY} | *
| {@code DAY_OF_MONTH} | *{@link #getDay()} | *
| {@code HOUR_OF_DAY} | *{@link #getHour()} | *
| {@code MINUTE} | *{@link #getMinute()} | *
| {@code SECOND} | *{@link #getSecond()} | *
| {@code MILLISECOND} | *get millisecond order from {@link #getFractionalSecond()}* | *
| {@code GregorianCalendar.setTimeZone(TimeZone)} | *{@link #getTimezone()} formatted into Custom timezone id | *
To ensure consistency in conversion implementations, the new * {@code GregorianCalendar} should be instantiated in following * manner. *
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. * *
To compute the return value's {@code TimeZone} field, *
To ensure consistency in conversion implementations, the new * {@code GregorianCalendar} should be instantiated in following * manner. *
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} */ public abstract Object clone(); }