/* * Copyright (c) 2004, 2013, 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 java.math.BigDecimal; import java.math.BigInteger; import java.util.GregorianCalendar; import java.util.regex.Matcher; import java.util.regex.Pattern; /** *

Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.

* *

A new instance of the DatatypeFactory is created through the {@link #newInstance()} method * that uses the following implementation resolution mechanisms to determine an implementation:

*
    *
  1. * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "javax.xml.datatype.DatatypeFactory", * exists, a class with the name of the property value is instantiated. * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. *
    2. *
  2. * If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} Object. * The Properties Object is then queried for the property as documented in the prior step * and processed as documented in the prior step. *
    3. *
  3. * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt * to locate and load an implementation of the service using the {@linkplain * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * the service-provider loading facility will use the {@linkplain * java.lang.Thread#getContextClassLoader() current thread's context class loader} * to attempt to load the service. If the context class * loader is null, the {@linkplain * ClassLoader#getSystemClassLoader() system class loader} will be used. *
    * In case of {@link java.util.ServiceConfigurationError service * configuration error} a {@link javax.xml.datatype.DatatypeConfigurationException} * will be thrown. *
    4. *
  4. * The final mechanism is to attempt to instantiate the Class specified by * {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}. * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. *
    5. *
* * @author Joseph Fialli * @author Jeff Suttor * @author Neeraj Bajaj * * @version $Revision: 1.13 $, $Date: 2010/03/11 23:10:53 $ * @since 1.5 */ public abstract class DatatypeFactory { /** *

Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.

* *

Default value is javax.xml.datatype.DatatypeFactory.

*/ public static final String DATATYPEFACTORY_PROPERTY = // We use a String constant here, rather than calling // DatatypeFactory.class.getName() - in order to make javadoc // generate a See Also: Constant Field Value link. "javax.xml.datatype.DatatypeFactory"; /** *

Default implementation class name as defined in * JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.

* *

Implementers should specify the name of an appropriate class * to be instantiated if no other implementation resolution mechanism * succeeds.

* *

Users should not refer to this field; it is intended only to * document a factory implementation detail. *

*/ public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS = // We use new String() here to prevent javadoc from generating // a See Also: Constant Field Value link. new String("com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl"); /** * http://www.w3.org/TR/xpath-datamodel/#xdtschema defines two regexps * to constrain the value space of dayTimeDuration ([^YM]*[DT].*) * and yearMonthDuration ([^DT]*). Note that these expressions rely on * the fact that the value must be an xs:Duration, they simply exclude * some Durations. */ private static final Pattern XDTSCHEMA_YMD = Pattern.compile("[^DT]*"); private static final Pattern XDTSCHEMA_DTD = Pattern.compile("[^YM]*[DT].*"); /** *

Protected constructor to prevent instantiation outside of package.

* *

Use {@link #newInstance()} to create a DatatypeFactory.

*/ protected DatatypeFactory() { } /** *

Obtain a new instance of a DatatypeFactory.

* *

The implementation resolution mechanisms are defined in this * Class's documentation.

* * @return New instance of a DatatypeFactory * * @throws DatatypeConfigurationException If the implementation is not * available or cannot be instantiated. * * @see #newInstance(String factoryClassName, ClassLoader classLoader) */ public static DatatypeFactory newInstance() throws DatatypeConfigurationException { return FactoryFinder.find( /* The default property name according to the JAXP spec */ DatatypeFactory.class, /* The fallback implementation class name */ DATATYPEFACTORY_IMPLEMENTATION_CLASS); } /** *

Obtain a new instance of a DatatypeFactory from class name. * This function is useful when there are multiple providers in the classpath. * It gives more control to the application as it can specify which provider * should be loaded.

* *

Once an application has obtained a reference to a DatatypeFactory * it can use the factory to configure and obtain datatype instances.

* * *

Tip for Trouble-shooting

*

Setting the jaxp.debug system property will cause * this method to print a lot of debug messages * to System.err about what it is doing and where it is looking at.

* *

If you have problems try:

* 
     * java -Djaxp.debug=1 YourProgram ....
     *
* * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.datatype.DatatypeFactory. * * @param classLoader ClassLoader used to load the factory class. If null * current Thread's context classLoader is used to load the factory class. * * @return New instance of a DatatypeFactory * * @throws DatatypeConfigurationException if factoryClassName is null, or * the factory class cannot be loaded, instantiated. * * @see #newInstance() * * @since 1.6 */ public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader) throws DatatypeConfigurationException { return FactoryFinder.newInstance(DatatypeFactory.class, factoryClassName, classLoader, false); } /** *

Obtain a new instance of a Duration * specifying the Duration as its string representation, "PnYnMnDTnHnMnS", * as defined in XML Schema 1.0 section 3.2.6.1.

* *

XML Schema Part 2: Datatypes, 3.2.6 duration, defines duration as:

*
* duration represents a duration of time. * The value space of duration is a six-dimensional space where the coordinates designate the * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. * These components are ordered in their significance by their order of appearance i.e. as * year, month, day, hour, minute, and second. *
*

All six values are set and available from the created {@link Duration}

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* * @param lexicalRepresentation String representation of a Duration. * * @return New Duration created from parsing the lexicalRepresentation. * * @throws IllegalArgumentException If lexicalRepresentation is not a valid representation of a Duration. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException if lexicalRepresentation is null. */ public abstract Duration newDuration(final String lexicalRepresentation); /** *

Obtain a new instance of a Duration * specifying the Duration as milliseconds.

* *

XML Schema Part 2: Datatypes, 3.2.6 duration, defines duration as:

*
* duration represents a duration of time. * The value space of duration is a six-dimensional space where the coordinates designate the * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. * These components are ordered in their significance by their order of appearance i.e. as * year, month, day, hour, minute, and second. *
*

All six values are set by computing their values from the specified milliseconds * and are available using the get methods of the created {@link Duration}. * The values conform to and are defined by:

* * *

The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., * {@link java.util.Calendar#YEAR} = 1970, * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, * {@link java.util.Calendar#DATE} = 1, etc. * This is important as there are variations in the Gregorian Calendar, * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.

* * @param durationInMilliSeconds Duration in milliseconds to create. * * @return New Duration representing durationInMilliSeconds. */ public abstract Duration newDuration(final long durationInMilliSeconds); /** *

Obtain a new instance of a Duration * specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* *

A null value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param years of this Duration * @param months of this Duration * @param days of this Duration * @param hours of this Duration * @param minutes of this Duration * @param seconds of this Duration * * @return New Duration created from the specified values. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if all the fields (years, months, ...) are null or * if any of the fields is negative. * @throws UnsupportedOperationException If implementation cannot support requested values. */ public abstract Duration newDuration( final boolean isPositive, final BigInteger years, final BigInteger months, final BigInteger days, final BigInteger hours, final BigInteger minutes, final BigDecimal seconds); /** *

Obtain a new instance of a Duration * specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.

* *

A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param years of this Duration * @param months of this Duration * @param days of this Duration * @param hours of this Duration * @param minutes of this Duration * @param seconds of this Duration * * @return New Duration created from the specified values. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if any of the fields is negative. * * @see #newDuration( * boolean isPositive, * BigInteger years, * BigInteger months, * BigInteger days, * BigInteger hours, * BigInteger minutes, * BigDecimal seconds) */ public Duration newDuration( final boolean isPositive, final int years, final int months, final int days, final int hours, final int minutes, final int seconds) { // years may not be set BigInteger realYears = (years != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) years) : null; // months may not be set BigInteger realMonths = (months != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) months) : null; // days may not be set BigInteger realDays = (days != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) days) : null; // hours may not be set BigInteger realHours = (hours != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) hours) : null; // minutes may not be set BigInteger realMinutes = (minutes != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) minutes) : null; // seconds may not be set BigDecimal realSeconds = (seconds != DatatypeConstants.FIELD_UNDEFINED) ? BigDecimal.valueOf((long) seconds) : null; return newDuration( isPositive, realYears, realMonths, realDays, realHours, realMinutes, realSeconds ); } /** *

Create a Duration of type xdt:dayTimeDuration by parsing its String representation, * "PnDTnHnMnS", * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

* *

The datatype xdt:dayTimeDuration is a subtype of xs:duration * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

* *

All four values are set and available from the created {@link Duration}

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* * @param lexicalRepresentation Lexical representation of a duration. * * @return New Duration created using the specified lexicalRepresentation. * * @throws IllegalArgumentException If lexicalRepresentation is not a valid representation of a Duration expressed only in terms of days and time. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException If lexicalRepresentation is null. */ public Duration newDurationDayTime(final String lexicalRepresentation) { // lexicalRepresentation must be non-null if (lexicalRepresentation == null) { throw new NullPointerException( "Trying to create an xdt:dayTimeDuration with an invalid" + " lexical representation of \"null\""); } // test lexicalRepresentation against spec regex Matcher matcher = XDTSCHEMA_DTD.matcher(lexicalRepresentation); if (!matcher.matches()) { throw new IllegalArgumentException( "Trying to create an xdt:dayTimeDuration with an invalid" + " lexical representation of \"" + lexicalRepresentation + "\", data model requires years and months only."); } return newDuration(lexicalRepresentation); } /** *

Create a Duration of type xdt:dayTimeDuration using the specified milliseconds as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

* *

The datatype xdt:dayTimeDuration is a subtype of xs:duration * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

* *

All four values are set by computing their values from the specified milliseconds * and are available using the get methods of the created {@link Duration}. * The values conform to and are defined by:

* * *

The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., * {@link java.util.Calendar#YEAR} = 1970, * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, * {@link java.util.Calendar#DATE} = 1, etc. * This is important as there are variations in the Gregorian Calendar, * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * so the result of {@link Duration#getDays()} can be influenced.

* *

Any remaining milliseconds after determining the day, hour, minute and second are discarded.

* * @param durationInMilliseconds Milliseconds of Duration to create. * * @return New Duration created with the specified durationInMilliseconds. * * @see * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration */ public Duration newDurationDayTime(final long durationInMilliseconds) { return newDuration(durationInMilliseconds); } /** *

Create a Duration of type xdt:dayTimeDuration using the specified * day, hour, minute and second as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

* *

The datatype xdt:dayTimeDuration is a subtype of xs:duration * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* *

A null value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param day Day of Duration. * @param hour Hour of Duration. * @param minute Minute of Duration. * @param second Second of Duration. * * @return New Duration created with the specified day, hour, minute * and second. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if all the fields (day, hour, ...) are null or * if any of the fields is negative. * @throws UnsupportedOperationException If implementation cannot support requested values. */ public Duration newDurationDayTime( final boolean isPositive, final BigInteger day, final BigInteger hour, final BigInteger minute, final BigInteger second) { return newDuration( isPositive, null, // years null, // months day, hour, minute, (second != null)? new BigDecimal(second):null ); } /** *

Create a Duration of type xdt:dayTimeDuration using the specified * day, hour, minute and second as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

* *

The datatype xdt:dayTimeDuration is a subtype of xs:duration * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

* *

A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param day Day of Duration. * @param hour Hour of Duration. * @param minute Minute of Duration. * @param second Second of Duration. * * @return New Duration created with the specified day, hour, minute * and second. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if any of the fields (day, hour, ...) is negative. */ public Duration newDurationDayTime( final boolean isPositive, final int day, final int hour, final int minute, final int second) { return newDurationDayTime( isPositive, BigInteger.valueOf((long) day), BigInteger.valueOf((long) hour), BigInteger.valueOf((long) minute), BigInteger.valueOf((long) second) ); } /** *

Create a Duration of type xdt:yearMonthDuration by parsing its String representation, * "PnYnM", * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

* *

The datatype xdt:yearMonthDuration is a subtype of xs:duration * whose lexical representation contains only year and month components. * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.

* *

Both values are set and available from the created {@link Duration}

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* * @param lexicalRepresentation Lexical representation of a duration. * * @return New Duration created using the specified lexicalRepresentation. * * @throws IllegalArgumentException If lexicalRepresentation is not a valid representation of a Duration expressed only in terms of years and months. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException If lexicalRepresentation is null. */ public Duration newDurationYearMonth( final String lexicalRepresentation) { // lexicalRepresentation must be non-null if (lexicalRepresentation == null) { throw new NullPointerException( "Trying to create an xdt:yearMonthDuration with an invalid" + " lexical representation of \"null\""); } // test lexicalRepresentation against spec regex Matcher matcher = XDTSCHEMA_YMD.matcher(lexicalRepresentation); if (!matcher.matches()) { throw new IllegalArgumentException( "Trying to create an xdt:yearMonthDuration with an invalid" + " lexical representation of \"" + lexicalRepresentation + "\", data model requires days and times only."); } return newDuration(lexicalRepresentation); } /** *

Create a Duration of type xdt:yearMonthDuration using the specified milliseconds as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

* *

The datatype xdt:yearMonthDuration is a subtype of xs:duration * whose lexical representation contains only year and month components. * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.

* *

Both values are set by computing their values from the specified milliseconds * and are available using the get methods of the created {@link Duration}. * The values conform to and are defined by:

* * *

The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., * {@link java.util.Calendar#YEAR} = 1970, * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, * {@link java.util.Calendar#DATE} = 1, etc. * This is important as there are variations in the Gregorian Calendar, * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * so the result of {@link Duration#getMonths()} can be influenced.

* *

Any remaining milliseconds after determining the year and month are discarded.

* * @param durationInMilliseconds Milliseconds of Duration to create. * * @return New Duration created using the specified durationInMilliseconds. */ public Duration newDurationYearMonth( final long durationInMilliseconds) { // create a Duration that only has sign, year & month // Duration is immutable, so need to create a new Duration // implementations may override this method in a more efficient way Duration fullDuration = newDuration(durationInMilliseconds); boolean isPositive = (fullDuration.getSign() == -1) ? false : true; BigInteger years = (BigInteger) fullDuration.getField(DatatypeConstants.YEARS); if (years == null) { years = BigInteger.ZERO; } BigInteger months = (BigInteger) fullDuration.getField(DatatypeConstants.MONTHS); if (months == null) { months = BigInteger.ZERO; } return newDurationYearMonth(isPositive, years, months); } /** *

Create a Duration of type xdt:yearMonthDuration using the specified * year and month as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

* *

The XML Schema specification states that values can be of an arbitrary size. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * if implementation capacities are exceeded.

* *

A null value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param year Year of Duration. * @param month Month of Duration. * * @return New Duration created using the specified year and month. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if all of the fields (year, month) are null or * if any of the fields is negative. * @throws UnsupportedOperationException If implementation cannot support requested values. */ public Duration newDurationYearMonth( final boolean isPositive, final BigInteger year, final BigInteger month) { return newDuration( isPositive, year, month, null, // days null, // hours null, // minutes null // seconds ); } /** *

Create a Duration of type xdt:yearMonthDuration using the specified * year and month as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

* *

A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.

* * @param isPositive Set to false to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param year Year of Duration. * @param month Month of Duration. * * @return New Duration created using the specified year and month. * * @throws IllegalArgumentException If the values are not a valid representation of a * Duration: if any of the fields (year, month) is negative. */ public Duration newDurationYearMonth( final boolean isPositive, final int year, final int month) { return newDurationYearMonth( isPositive, BigInteger.valueOf((long) year), BigInteger.valueOf((long) month)); } /** *

Create a new instance of an XMLGregorianCalendar.

* *

All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null.

* * @return New XMLGregorianCalendar with all date/time datatype fields set to * {@link DatatypeConstants#FIELD_UNDEFINED} or null. */ public abstract XMLGregorianCalendar newXMLGregorianCalendar(); /** *

Create a new XMLGregorianCalendar by parsing the String as a lexical representation.

* *

Parsing the lexical string representation is defined in * XML Schema 1.0 Part 2, Section 3.2.[7-14].1, * Lexical Representation.

* *

The string representation may not have any leading and trailing whitespaces.

* *

The parsing is done field by field so that * the following holds for any lexically correct String x:

* 
     * newXMLGregorianCalendar(x).toXMLFormat().equals(x)
     *
*

Except for the noted lexical/canonical representation mismatches * listed in * XML Schema 1.0 errata, Section 3.2.7.2.

* * @param lexicalRepresentation Lexical representation of one the eight XML Schema date/time datatypes. * * @return XMLGregorianCalendar created from the lexicalRepresentation. * * @throws IllegalArgumentException If the lexicalRepresentation is not a valid XMLGregorianCalendar. * @throws NullPointerException If lexicalRepresentation is null. */ public abstract XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation); /** *

Create an XMLGregorianCalendar from a {@link GregorianCalendar}.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Field by Field Conversion from * {@link GregorianCalendar} to an {@link XMLGregorianCalendar} *
java.util.GregorianCalendar fieldjavax.xml.datatype.XMLGregorianCalendar field
ERA == GregorianCalendar.BC ? -YEAR : YEAR{@link XMLGregorianCalendar#setYear(int year)}
MONTH + 1{@link XMLGregorianCalendar#setMonth(int month)}
DAY_OF_MONTH{@link XMLGregorianCalendar#setDay(int day)}
HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}
* (ZONE_OFFSET + DST_OFFSET) / (60*1000)
* (in minutes) * 		{@link XMLGregorianCalendar#setTimezone(int offset)}* *
*

*conversion loss of information. It is not possible to represent * a java.util.GregorianCalendar daylight savings timezone id in the * XML Schema 1.0 date/time datatype representation.

* *

To compute the return value's TimeZone field, *