public abstract class XMLGregorianCalendar extends Object
implements Cloneable

Representation for W3C XML Schema 1.0 date/time datatypes. Specifically, these date/time datatypes are dateTime, time, date, gYearMonth, gMonthDay, gYear gMonth and gDay defined in the XML Namespace "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
Value Range
year getYear() + getEon() or
getYear() is a value between -(10^9-1) to (10^9)-1 or FIELD_UNDEFINED.
getEon() is high order year value in billion of years.
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 getMonth() 1 to 12 or FIELD_UNDEFINED
day getDay() Independent of month, max range is 1 to 31 or 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 getHour() 0 to 24 or FIELD_UNDEFINED. For a value of 24, the minute and second field must be zero per XML Schema Errata.
minute getMinute() 0 to 59 or FIELD_UNDEFINED
second getSecond() + getMillisecond()/1000 or
getSecond() + getFractionalSecond()
getSecond() from 0 to 60 or FIELD_UNDEFINED.
(Note: 60 only allowable for leap second.)
getFractionalSecond() allows for infinite precision over the range from 0.0 to 1.0 when the getSecond() is defined.
FractionalSecond is optional and has a value of null when it is undefined.
getMillisecond() is the convenience millisecond precision of value of getFractionalSecond().
timezone getTimezone() Number of minutes or 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. 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:

Public Constructor Summary

Public Method Summary

abstract void
add(Duration duration)

Add duration to this instance.

abstract void

Unset all fields to undefined.

abstract Object

Creates and returns a copy of this object.

abstract int
compare(XMLGregorianCalendar xmlGregorianCalendar)

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, Order relation on dateTime.

equals(Object obj)

Indicates whether parameter obj is "equal to" this one.

abstract int
Return day in month or FIELD_UNDEFINED.
abstract BigInteger

Return high order component for XML Schema 1.0 dateTime datatype field for year.

abstract BigInteger

Return XML Schema 1.0 dateTime datatype field for year.

abstract BigDecimal

Return fractional seconds.

abstract int
Return hours or FIELD_UNDEFINED.

Return millisecond precision of getFractionalSecond().

abstract int
Return minutes or FIELD_UNDEFINED.
abstract int

Return number of month or FIELD_UNDEFINED.

abstract int

Return seconds or FIELD_UNDEFINED.

abstract TimeZone
getTimeZone(int defaultZoneoffset)

Returns a java.util.TimeZone for this class.

abstract int
Return timezone offset in minutes or FIELD_UNDEFINED if this optional field is not defined.
abstract QName

Return the name of the XML Schema date/time type that this instance maps to.

abstract int

Return low order component for XML Schema 1.0 dateTime datatype field for year or FIELD_UNDEFINED.


Returns a hash code consistent with the definition of the equals method.

abstract boolean
Validate instance by getXMLSchemaType() constraints.
abstract XMLGregorianCalendar

Normalize this instance to UTC.

abstract void

Reset this XMLGregorianCalendar to its original values.

abstract void
setDay(int day)

Set days in month.

abstract void
setFractionalSecond(BigDecimal fractional)

Set fractional seconds.