Class XMLGregorianCalendar

java.lang.Object
javax.xml.datatype.XMLGregorianCalendar
All Implemented Interfaces:
java.lang.Cloneable

public abstract class XMLGregorianCalendar extends java.lang.Object implements java.lang.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
datatype
field
Related
XMLGregorianCalendar
Accessor(s)
Value Range
year getYear() + getEon() or
getEonAndYear()
getYear() is a value between -(10^9-1) to (10^9)-1 or DatatypeConstants.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 DatatypeConstants.FIELD_UNDEFINED
day getDay() Independent of month, max range is 1 to 31 or 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 getHour() 0 to 24 or DatatypeConstants.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 DatatypeConstants.FIELD_UNDEFINED
second getSecond() + getMillisecond()/1000 or
getSecond() + getFractionalSecond()
getSecond() from 0 to 60 or DatatypeConstants.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 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. 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:

Since:
1.5
Version:
$Revision: 759822 $, $Date: 2009-03-30 04:15:11 +0300 (Mon, 30 Mar 2009) $
Author:
Joseph Fialli, Kohsuke Kawaguchi, Jeff Suttor
See Also:
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    add(Duration duration)
    Add duration to this instance.
    abstract void
    Unset all fields to undefined.
    abstract java.lang.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 3.2.7.3, Order relation on dateTime.
    boolean
    equals(java.lang.Object obj)
    Indicates whether parameter obj is "equal to" this one.
    abstract int
    Return day in month or DatatypeConstants.FIELD_UNDEFINED.
    abstract java.math.BigInteger
    Return high order component for XML Schema 1.0 dateTime datatype field for year.
    abstract java.math.BigInteger
    Return XML Schema 1.0 dateTime datatype field for year.
    abstract java.math.BigDecimal
    Return fractional seconds.
    abstract int
    int
    Return millisecond precision of getFractionalSecond().
    abstract int
    abstract int
    Return number of month or DatatypeConstants.FIELD_UNDEFINED.
    abstract int
    abstract int
    Return timezone offset in minutes or DatatypeConstants.FIELD_UNDEFINED if this optional field is not defined.
    abstract java.util.TimeZone
    getTimeZone(int defaultZoneoffset)
    Returns a java.util.TimeZone for this class.
    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 DatatypeConstants.FIELD_UNDEFINED.
    int
    Returns a hash code consistent with the definition of the equals method.
    abstract boolean
    Validate instance by getXMLSchemaType() constraints.
    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(java.math.BigDecimal fractional)
    Set fractional seconds.
    abstract void
    setHour(int hour)
    Set hours.
    abstract void
    setMillisecond(int millisecond)
    Set milliseconds.
    abstract void
    setMinute(int minute)
    Set minutes.
    abstract void
    setMonth(int month)
    Set month.
    abstract void
    setSecond(int second)
    Set seconds.
    void
    setTime(int hour, int minute, int second)
    Set time as one unit.
    void
    setTime(int hour, int minute, int second, int millisecond)
    Set time as one unit, including optional milliseconds.
    void
    setTime(int hour, int minute, int second, java.math.BigDecimal fractional)
    Set time as one unit, including the optional infinite precision fractional seconds.
    abstract void
    setTimezone(int offset)
    Set the number of minutes in the timezone offset.
    abstract void
    setYear(int year)
    Set year of XSD dateTime year field.
    abstract void
    setYear(java.math.BigInteger year)
    Set low and high order component of XSD dateTime year field.
    abstract java.util.GregorianCalendar
    Convert this XMLGregorianCalendar to a GregorianCalendar.
    abstract java.util.GregorianCalendar
    toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)
    Convert this XMLGregorianCalendar along with provided parameters to a GregorianCalendar instance.
    java.lang.String
    Returns a String representation of this XMLGregorianCalendar Object.
    abstract java.lang.String
    Return the lexical representation of this instance.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait