javax.xml.datatype.XMLGregorianCalendar Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id: XMLGregorianCalendar.java 759822 2009-03-30 01:15:11Z mrglavas $
package javax.xml.datatype;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.GregorianCalendar;
import java.util.TimeZone;
import javax.xml.namespace.QName;
/**
* 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
* {@link #getYear()} + {@link #getEon()} or
* {@link #getEonAndYear}
*
* 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.
* 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 24 or {@link DatatypeConstants#FIELD_UNDEFINED}.
* For a value of 24, the minute and second field must be zero per
* XML Schema Errata.
*
*
*
*
* 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.
* FractionalSecond is optional and has a value of 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. 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:
*
* - accessors/mutators for independent date/time fields
* - conversion between this class and W3C XML Schema 1.0 lexical representation,
* {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}
* - conversion between this class and {@link GregorianCalendar},
* {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)},
* {@link DatatypeFactory}
* - partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}
* - {@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.
* - addition operation with {@link Duration}
* instance as defined in
* W3C XML Schema 1.0 Part 2, Appendix E, Adding durations to dateTimes.
*
*
*
*
* @author Joseph Fialli
* @author Kohsuke Kawaguchi
* @author Jeff Suttor
* @version $Revision: 759822 $, $Date: 2009-03-29 18:15:11 -0700 (Sun, 29 Mar 2009) $
* @see Duration
* @see DatatypeFactory
* @since 1.5
*/
public abstract class XMLGregorianCalendar
implements Cloneable {
/**
* 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 XMLGregorianCalendar to its original values.
*
* 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)}.
*
*
* reset() is designed to allow the reuse of existing XMLGregorianCalendars
* thus saving resources associated with the creation of new XMLGregorianCalendars.
*/
public abstract void reset();
/**
* Set low and high order component of XSD dateTime year field.
*
* Unset this field by invoking the setter with a parameter value of null.
*
* @param year value constraints summarized in year field of date/time field mapping table.
*
* @throws IllegalArgumentException if 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 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 year parameter
* is less than 10^9, the eon component of the XSD year field is set to
* 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 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 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 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 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 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 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 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
* millisecond field of date/time field mapping table.
*
* @throws IllegalArgumentException if 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 null.
*
* @param fractional value constraints summarized in
* fractional field of date/time field mapping table.
*
* @throws IllegalArgumentException if 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 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
* year.
* 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 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
* 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 XMLGregorianCalendar.
*
* @see #getEon()
* @see #getEonAndYear()
*/
public abstract int getYear();
/**
* Return XML Schema 1.0 dateTime datatype field for
* year.
*
* Value constraints for this value are summarized in
* year field of date/time field mapping table.
*
* @return sum of eon and BigInteger.valueOf(year)
* when both fields are defined. When only year is defined,
* return it. When both eon and year are not
* defined, return 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 year of this 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 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 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 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.
*
* 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 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.
*
* xsd:dateTime datatype field mapping to accessors of
* this class are defined in
* date/time field mapping table.
*
* @param xmlGregorianCalendar Instance of XMLGregorianCalendar to compare
*
* @return The relationship between this XMLGregorianCalendar and
* the specified xmlGregorianCalendar as
* {@link DatatypeConstants#LESSER},
* {@link DatatypeConstants#EQUAL},
* {@link DatatypeConstants#GREATER} or
* {@link DatatypeConstants#INDETERMINATE}.
*
* @throws NullPointerException if 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 this XMLGregorianCalendar normalized to UTC.
*/
public abstract XMLGregorianCalendar normalize();
/**
* Indicates whether parameter obj is "equal to" this one.
*
* @param obj to compare.
*
* @return true when obj is an instance of XMLGregorianCalendar
* and {@link #compare(XMLGregorianCalendar obj)} returns {@link DatatypeConstants#EQUAL}, otherwise false.
*/
public boolean equals(Object obj) {
if (obj == this) {
return true;
}
if (obj instanceof XMLGregorianCalendar) {
return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
}
return false;
}
/**
* 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 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 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();
/**
* 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
*
*
*
*
* @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();
/**
* Returns a String representation of this XMLGregorianCalendar Object.
*
* The result is a lexical representation generated by {@link #toXMLFormat()}.
*
* @return A non-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 getXMLSchemaType() constraints.
* @return true if data values are valid.
*/
public abstract boolean isValid();
/**
* Add 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 dateTime fields
* to this class' representation of those fields.
*
* @param duration Duration to add to this XMLGregorianCalendar.
*
* @throws NullPointerException when duration parameter is null.
*/
public abstract void add(Duration duration);
/**
* Convert this XMLGregorianCalendar to a {@link GregorianCalendar}.
*
* When this instance has an undefined field, this
* conversion relies on the java.util.GregorianCalendar default
* for its corresponding field. A notable difference between
* XML Schema 1.0 date/time datatypes and java.util.GregorianCalendar
* is that Timezone value is optional for date/time datatypes and it is
* a required field for java.util.GregorianCalendar. See javadoc
* for java.util.TimeZone.getDefault() on how the default
* is determined. To explicitly specify the TimeZone
* instance, see
* {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
*
*
*
*
*
* Field by Field Conversion from this class to
* java.util.GregorianCalendar
*
*
*
*
*
* java.util.GregorianCalendar fieldjavax.xml.datatype.XMLGregorianCalendar field
*
* ERA{@link #getEonAndYear()}.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD
*
*
* YEAR{@link #getEonAndYear()}.abs().intValue()*
*
*
* MONTH{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}
*
*
* DAY_OF_MONTH{@link #getDay()}
*
*
* HOUR_OF_DAY{@link #getHour()}
*
*
* MINUTE{@link #getMinute()}
*
*
* SECOND{@link #getSecond()}
*
*
* MILLISECONDget millisecond order from {@link #getFractionalSecond()}*
*
*
* GregorianCalendar.setTimeZone(TimeZone){@link #getTimezone()} formatted into Custom timezone id
*
*
*
* * designates possible loss of precision during the conversion due
* to source datatype having higher precision than target datatype.
*
* To ensure consistency in conversion implementations, the new
* GregorianCalendar should be instantiated in following
* manner.
*
* - Using
timeZone value as defined above, create a new
* java.util.GregorianCalendar(timeZone,Locale.getDefault()).
*
* - Initialize all GregorianCalendar fields by calling {(@link GegorianCalendar#clear()}.
* - Obtain a pure Gregorian Calendar by invoking
*
GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE)).
* - Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method
*
Calendar.set(int,int)
*
*
*
* @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
*/
public abstract GregorianCalendar toGregorianCalendar();
/**
* Convert this XMLGregorianCalendar along with provided parameters
* to a {@link GregorianCalendar} instance.
*
* 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
* timezone parameter.
*
* To compute the return value's TimeZone field,
*
* - when parameter
timeZone is non-null,
* it is the timezone field.
* - else when
this.getTimezone() != FIELD_UNDEFINED,
* create a java.util.TimeZone with a custom timezone id
* using the this.getTimezone().
* - else when
defaults.getTimezone() != FIELD_UNDEFINED,
* create a java.util.TimeZone with a custom timezone id
* using defaults.getTimezone().
* - else use the
GregorianCalendar default timezone value
* for the host is defined as specified by
* java.util.TimeZone.getDefault().
*
* To ensure consistency in conversion implementations, the new
* GregorianCalendar should be instantiated in following
* manner.
*
* - Create a new
java.util.GregorianCalendar(TimeZone,
* Locale) with TimeZone set as specified above and the
* Locale parameter.
*
* - Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}
* - Obtain a pure Gregorian Calendar by invoking
*
GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE)).
* - Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method
*
Calendar.set(int,int)
*
*
* @param timezone provide Timezone. null is a legal value.
* @param aLocale provide explicit Locale. Use default GregorianCalendar locale if
* value is null.
* @param defaults provide default field values to use when corresponding
* field for this instance is FIELD_UNDEFINED or null.
* If defaultsis null or a field
* within the specified defaults is undefined,
* just use 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);
/**
* Returns a java.util.TimeZone for this class.
*
* 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 Object
*/
public abstract Object clone();
}