// 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/>Convert this <code>XMLGregorianCalendar</code> 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</code> parameter.
*
* <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/>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>
*
* @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 java.util.GregorianCalendar toGregorianCalendar(
java.util.TimeZone timezone,
java.util.Locale aLocale,
XMLGregorianCalendar defaults);
