|
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 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>
* <td>month
* <td> {@link #getMonth()}
* <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED}
* </tr>
* <tr>
* <td>day
* <td> {@link #getDay()}
* <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.null
when it is undefined.XMLGregorianCalendar
to its original values.
*
* <p>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>
*
* <p>reset()
is designed to allow the reuse of existing XMLGregorianCalendar
s
* thus saving resources associated with the creation of new <code>XMLGregorianCalendars.
*/
public abstract void reset();
/**
* <p>Set low and high order component of XSD dateTime
year field.
*
* <p>Unset this field by invoking the setter with a parameter value of null
.
*
* @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table.
*
* @throws IllegalArgumentException if <code>year parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setYear(BigInteger year);
/**
* <p>Set year of XSD dateTime
year field.
*
* <p>Unset this field by invoking the setter with a parameter value of
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
*
* <p>Note: if the absolute value of the 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.
* If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null.
*/
public abstract void setYear(int year);
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>month parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setMonth(int month);
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>day parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setDay(int day);
/**
* <p>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.
*/
public abstract void setTimezone(int offset);
/**
* <p>Set time as one unit.
*
* @param hour value constraints are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table.
* @param minute value constraints are summarized in
* <a href="#datetimefield-minute">minute field of date/time field mapping table.
* @param second value constraints are summarized in
* <a href="#datetimefield-second">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
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public void setTime(int hour, int minute, int second) {
setTime(
hour,
minute,
second,
null // fractional
);
}
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>hour parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setHour(int hour);
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>minute parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setMinute(int minute);
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>second parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setSecond(int second);
/**
* <p>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.
*
* @throws IllegalArgumentException if <code>millisecond parameter is outside value constraints for the field as specified
* in <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setMillisecond(int millisecond);
/**
* <p>Set fractional seconds.
*
* <p>Unset this field by invoking the setter with a parameter value of null
.
*
* @param fractional value constraints summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table.
*
* @throws IllegalArgumentException if <code>fractional parameter is outside value constraints for the field as specified
* in <a href="#datetimefieldmapping">date/time field mapping table.
*/
public abstract void setFractionalSecond(BigDecimal fractional);
/**
* <p>Set time as one unit, including the optional infinite precision
* fractional seconds.</p>
*
* @param hour value constraints are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table.
* @param minute value constraints are summarized in
* <a href="#datetimefield-minute">minute field of date/time field mapping table.
* @param second value constraints are summarized in
* <a href="#datetimefield-second">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
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public void setTime(
int hour,
int minute,
int second,
BigDecimal fractional) {
setHour(hour);
setMinute(minute);
setSecond(second);
setFractionalSecond(fractional);
}
/**
* <p>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.
* @param minute value constraints are summarized in
* <a href="#datetimefield-minute">minute field of date/time field mapping table.
* @param second value constraints are summarized in
* <a href="#datetimefield-second">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
* <a href="#datetimefieldmapping">date/time field mapping table.
*/
public void setTime(int hour, int minute, int second, int millisecond) {
setHour(hour);
setMinute(minute);
setSecond(second);
setMillisecond(millisecond);
}
/**
* <p>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.
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-year">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();
/**
* <p>Return 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.
*
* @return year of this <code>XMLGregorianCalendar.
*
* @see #getEon()
* @see #getEonAndYear()
*/
public abstract int getYear();
/**
* <p>Return 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.
*
* @return sum of <code>eon and BigInteger.valueOf(year)
* when both fields are defined. When only <code>year is defined,
* return it. When both <code>eon and year
are not
* defined, return <code>null.
*
* @see #getEon()
* @see #getYear()
*/
public abstract BigInteger getEonAndYear();
/**
* <p>Return number of month 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.
*
* @return year of this <code>XMLGregorianCalendar.
*
*/
public abstract int getMonth();
/**
* Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-day">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.
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-timezone">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.
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table.
* @see #setTime(int, int, int)
*/
public abstract int getHour();
/**
* Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
* Returns {@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.
* @see #setTime(int, int, int)
*/
public abstract int getMinute();
/**
* <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.
*
* <p>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.</p>
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-second">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();
/**
* <p>Return 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>
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-second">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();
}
/**
* <p>Return fractional seconds.
*
* <p>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.
*
* <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}.</p>
*
* @return fractional seconds of this <code>XMLGregorianCalendar.
*
* @see #getSecond()
* @see #setTime(int, int, int, BigDecimal)
*/
public abstract BigDecimal getFractionalSecond();
// 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.
*
* <p>xsd:dateTime
datatype field mapping to accessors of
* this class are defined in
* <a href="#datetimefieldmapping">date/time field mapping table.
*
* @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar to compare
*
* @return The relationship between <code>thisXMLGregorianCalendar
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);
/**
* <p>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>thisXMLGregorianCalendar
normalized to UTC.
*/
public abstract XMLGregorianCalendar normalize();
/**
* <p>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.</p>
*
* @param obj to compare.
*
* @return <code>true when 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;
}
/**
* <p>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();
}
/**
* <p>Return the lexical representation of 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".
*
* <p>Specific target lexical representation format is determined by
* {@link #getXMLSchemaType()}.</p>
*
* @return XML, as <code>String, representation of this 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();
/**
* <p>Return the name of the XML Schema date/time type that this instance
* maps to. Type is computed based on fields that are set.</p>
*
* <table border="2" rules="all" cellpadding="2">
* <thead>
* <tr>
* <th align="center" colspan="7">
* Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
* <i>(timezone is optional for all date/time datatypes)
* </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <td>Datatype
* <td>year
* <td>month
* <td>day
* <td>hour
* <td>minute
* <td>second
* </tr>
* <tr>
* <td>{@link DatatypeConstants#DATETIME}
* <td>X
* <td>X
* <td>X
* <td>X
* <td>X
* <td>X
* </tr>
* <tr>
* <td>{@link DatatypeConstants#DATE}
* <td>X
* <td>X
* <td>X
* <td>
* <td>
* <td>
* </tr>
* <tr>
* <td>{@link DatatypeConstants#TIME}
* <td>
* <td>
* <td>
* <td>X
* <td>X
* <td>X
* </tr>
* <tr>
* <td>{@link DatatypeConstants#GYEARMONTH}
* <td>X
* <td>X
* <td>
* <td>
* <td>
* <td>
* </tr>
* <tr>
* <td>{@link DatatypeConstants#GMONTHDAY}
* <td>
* <td>X
* <td>X
* <td>
* <td>
* <td>
* </tr>
* <tr>
* <td>{@link DatatypeConstants#GYEAR}
* <td>X
* <td>
* <td>
* <td>
* <td>
* <td>
* </tr>
* <tr>
* <td>{@link DatatypeConstants#GMONTH}
* <td>
* <td>X
* <td>
* <td>
* <td>
* <td>
* </tr>
* <tr>
* <td>{@link DatatypeConstants#GDAY}
* <td>
* <td>
* <td>X
* <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();
/**
* <p>Returns a String
representation of this XMLGregorianCalendar
Object
.
*
* <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
*
* @return A non-<code>null valid String
representation of this 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();
/**
* <p>Add 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>.
* <a href="#datetimefieldmapping">date/time field mapping table
* defines the mapping from XML Schema 1.0 <code>dateTime fields
* to this class' representation of those fields.</p>
*
* @param duration Duration to add to this <code>XMLGregorianCalendar.
*
* @throws NullPointerException when <code>duration parameter is null
.
*/
public abstract void add(Duration duration);
/**
* <p>Convert this XMLGregorianCalendar
to a {@link GregorianCalendar}.
*
* <p>When 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)}.</p>
*
* <table border="2" rules="all" cellpadding="2">
* <thead>
* <tr>
* <th align="center" colspan="2">
* Field by Field Conversion from this class to
* <code>java.util.GregorianCalendar
* </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <td>java.util.GregorianCalendar
field
* <td>javax.xml.datatype.XMLGregorianCalendar
field
* </tr>
* <tr>
* <td>ERA
* <td>{@link #getEonAndYear()}.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD
* </tr>
* <tr>
* <td>YEAR
* <td>{@link #getEonAndYear()}.abs().intValue()
*
* </tr>
* <tr>
* <td>MONTH
* <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}
* </tr>
* <tr>
* <td>DAY_OF_MONTH
* <td>{@link #getDay()}
* </tr>
* <tr>
* <td>HOUR_OF_DAY
* <td>{@link #getHour()}
* </tr>
* <tr>
* <td>MINUTE
* <td>{@link #getMinute()}
* </tr>
* <tr>
* <td>SECOND
* <td>{@link #getSecond()}
* </tr>
* <tr>
* <td>MILLISECOND
* <td>get millisecond order from {@link #getFractionalSecond()}*
* </tr>
* <tr>
* <td>GregorianCalendar.setTimeZone(TimeZone)
* <td>{@link #getTimezone()} formatted into Custom timezone id
* </tr>
* </tbody>
* </table>
* <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 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>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.
* <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)
* </ul>
* </p>
*
* @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
*/
public abstract GregorianCalendar toGregorianCalendar();
/**
* <p>Convert this XMLGregorianCalendar
along with provided parameters
* to a {@link GregorianCalendar} instance.</p>
*
* <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 TimeZone
field,
* <ul>
* <li>when parameter timeZone
is non-null,
* it is the timezone field.</li>
* <li>else when this.getTimezone() != FIELD_UNDEFINED
,
* create a <code>java.util.TimeZone with a custom timezone id
* using the <code>this.getTimezone().
* <li>else when defaults.getTimezone() != FIELD_UNDEFINED
,
* create a <code>java.util.TimeZone with a custom timezone id
* using <code>defaults.getTimezone().
* <li>else use the GregorianCalendar
default timezone value
* for the host is defined as specified by
* <code>java.util.TimeZone.getDefault().
*
* <p>To ensure consistency in conversion implementations, the new
* <code>GregorianCalendar should be instantiated in following
* manner.
* <ul>
* <li>Create a new java.util.GregorianCalendar(TimeZone,
* Locale)</code> with TimeZone set as specified above and the
* <code>Locale
parameter.
* </li>
* <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}
* <li>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.
* <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)
* </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>defaultsis 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);
/**
* <p>Returns a 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).</p>
*
* @param defaultZoneoffset default zoneoffset if this zoneoffset is
* {@link DatatypeConstants#FIELD_UNDEFINED}.
*
* @return TimeZone for this.
*/
public abstract TimeZone getTimeZone(int defaultZoneoffset);
/**
* <p>Creates and returns a copy of this object.
*
* @return copy of this <code>Object
*/
public abstract Object clone();
}
Here is a short list of links related to this Java XMLGregorianCalendar.java source code file:
Java example source code file (XMLGregorianCalendar.java)
The XMLGregorianCalendar.java Java example source code/* * Copyright (c) 2003, 2006, 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. * * <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. * * <a name="datetimefieldmapping"/> * <table border="2" rules="all" cellpadding="2"> * <thead> * <tr> * <th align="center" colspan="3"> * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation * </th> * </tr> * </thead> * <tbody> * <tr> * <th>XML Schema 1.0 |
... this post is sponsored by my books ... | |
#1 New Release! |
FP Best Seller |
Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.
A percentage of advertising revenue from
pages under the /java/jwarehouse
URI on this website is
paid back to open source projects.