* A new instance of the {@code DatatypeFactory} is created through the {@link #newInstance()} method * that uses the following implementation resolution mechanisms to determine an implementation: *
* Use the configuration file "jaxp.properties". The file is in standard * {@link java.util.Properties} format and typically located in the * {@code conf} directory of the Java installation. It contains the fully qualified * name of the implementation class with the key being the system property * defined above. *
* The jaxp.properties file is read only once by the JAXP implementation * and its values are then cached for future use. If the file does not exist * when the first attempt is made to read from it, no further attempts are * made to check for its existence. It is not possible to change the value * of any property in jaxp.properties after it has been read for the first time. *
* Use the service-provider loading facility, 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. *
* The final mechanism is to attempt to instantiate the {@code Class} specified by * {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}. * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. *
Default value is {@code 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 {@code DatatypeFactory}. */ protected DatatypeFactory() { } /** * Creates a new instance of the {@code DatatypeFactory} {@linkplain * #DATATYPEFACTORY_IMPLEMENTATION_CLASS builtin system-default * implementation}. * * @return A new instance of the {@code DatatypeFactory} builtin * system-default implementation. * * @since 9 */ public static DatatypeFactory newDefaultInstance() { return new DatatypeFactoryImpl(); } /** * Obtain a new instance of a {@code DatatypeFactory}. * *
The implementation resolution mechanisms are defined in this * {@code Class}'s documentation. * * @return New instance of a {@code 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 {@code 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 {@code DatatypeFactory} * it can use the factory to configure and obtain datatype instances. * * *
Setting the {@code jaxp.debug} system property will cause * this method to print a lot of debug messages * to {@code 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 {@code javax.xml.datatype.DatatypeFactory}.
*
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current {@code Thread}'s context classLoader is used to load the factory class.
*
* @return New instance of a {@code DatatypeFactory}
*
* @throws DatatypeConfigurationException if {@code factoryClassName} is {@code 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 {@code Duration}
* specifying the {@code 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 {@code 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 {@code String} representation of a {@code Duration}. * * @return New {@code Duration} created from parsing the {@code lexicalRepresentation}. * * @throws IllegalArgumentException If {@code lexicalRepresentation} is not a valid representation of a {@code Duration}. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException if {@code lexicalRepresentation} is {@code null}. */ public abstract Duration newDuration(final String lexicalRepresentation); /** * Obtain a new instance of a {@code Duration} * specifying the {@code Duration} as milliseconds. * *
XML Schema Part 2: Datatypes, 3.2.6 duration, defines {@code 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 {@code 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 {@code Duration} representing {@code durationInMilliSeconds}. */ public abstract Duration newDuration(final long durationInMilliSeconds); /** * Obtain a new instance of a {@code Duration} * specifying the {@code 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 {@code null} value indicates that field is not set. * * @param isPositive Set to {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param years of this {@code Duration} * @param months of this {@code Duration} * @param days of this {@code Duration} * @param hours of this {@code Duration} * @param minutes of this {@code Duration} * @param seconds of this {@code Duration} * * @return New {@code Duration} created from the specified values. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code Duration} * specifying the {@code 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 {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param years of this {@code Duration} * @param months of this {@code Duration} * @param days of this {@code Duration} * @param hours of this {@code Duration} * @param minutes of this {@code Duration} * @param seconds of this {@code Duration} * * @return New {@code Duration} created from the specified values. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code Duration} of type {@code xdt:dayTimeDuration} * by parsing its {@code String} representation, * "PnDTnHnMnS", * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration. * *
The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration} * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace {@code 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 {@code Duration} created using the specified {@code lexicalRepresentation}. * * @throws IllegalArgumentException If {@code lexicalRepresentation} is * not a valid representation of a {@code Duration} expressed only in terms of days and time. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException If {@code lexicalRepresentation} is {@code 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 {@code Duration} of type {@code xdt:dayTimeDuration} * using the specified milliseconds as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration. * *
The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration} * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace {@code 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 {@code 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 {@code Duration} to create. * * @return New {@code Duration} created with the specified {@code durationInMilliseconds}. * * @see * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration */ public Duration newDurationDayTime(final long durationInMilliseconds) { return newDuration(durationInMilliseconds); } /** * Create a {@code Duration} of type {@code xdt:dayTimeDuration} using the specified * {@code day}, {@code hour}, {@code minute} and {@code second} as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration. * *
The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration} * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace {@code 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 {@code null} value indicates that field is not set. * * @param isPositive Set to {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param day Day of {@code Duration}. * @param hour Hour of {@code Duration}. * @param minute Minute of {@code Duration}. * @param second Second of {@code Duration}. * * @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute} * and {@code second}. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code Duration} of type {@code xdt:dayTimeDuration} using the specified * {@code day}, {@code hour}, {@code minute} and {@code second} as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration. * *
The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration} * whose lexical representation contains only day, hour, minute, and second components. * This datatype resides in the namespace {@code http://www.w3.org/2003/11/xpath-datatypes}. * *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param isPositive Set to {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param day Day of {@code Duration}. * @param hour Hour of {@code Duration}. * @param minute Minute of {@code Duration}. * @param second Second of {@code Duration}. * * @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute} * and {@code second}. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code Duration} of type {@code xdt:yearMonthDuration} * by parsing its {@code String} representation, * "PnYnM", * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration. * *
The datatype {@code xdt:yearMonthDuration} is a subtype of {@code 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 {@code Duration} created using the specified {@code lexicalRepresentation}. * * @throws IllegalArgumentException If {@code lexicalRepresentation} is not a valid representation of a {@code Duration} expressed only in terms of years and months. * @throws UnsupportedOperationException If implementation cannot support requested values. * @throws NullPointerException If {@code lexicalRepresentation} is {@code 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 {@code Duration} of type {@code xdt:yearMonthDuration} * using the specified milliseconds as defined in * * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration. * *
The datatype {@code xdt:yearMonthDuration} is a subtype of {@code 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 {@code 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 {@code Duration} to create. * * @return New {@code Duration} created using the specified {@code 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 {@code Duration} of type {@code xdt:yearMonthDuration} using the specified * {@code year} and {@code 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 {@code null} value indicates that field is not set. * * @param isPositive Set to {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param year Year of {@code Duration}. * @param month Month of {@code Duration}. * * @return New {@code Duration} created using the specified {@code year} and {@code month}. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code Duration} of type {@code xdt:yearMonthDuration} using the specified * {@code year} and {@code 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 {@code false} to create a negative duration. When the length * of the duration is zero, this parameter will be ignored. * @param year Year of {@code Duration}. * @param month Month of {@code Duration}. * * @return New {@code Duration} created using the specified {@code year} and {@code month}. * * @throws IllegalArgumentException If the values are not a valid representation of a * {@code 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 {@code XMLGregorianCalendar}. * *
All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null. * * @return New {@code 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 {@code XMLGregorianCalendar} created from the {@code lexicalRepresentation}. * * @throws IllegalArgumentException If the {@code lexicalRepresentation} is not a valid {@code XMLGregorianCalendar}. * @throws NullPointerException If {@code lexicalRepresentation} is {@code null}. */ public abstract XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation); /** * Create an {@code XMLGregorianCalendar} from a {@link GregorianCalendar}. * *
| {@code java.util.GregorianCalendar} field | *{@code javax.xml.datatype.XMLGregorianCalendar} field | *
|---|---|
| {@code ERA == GregorianCalendar.BC ? -YEAR : YEAR} | *{@link XMLGregorianCalendar#setYear(int year)} | *
| {@code MONTH + 1} | *{@link XMLGregorianCalendar#setMonth(int month)} | *
| {@code DAY_OF_MONTH} | *{@link XMLGregorianCalendar#setDay(int day)} | *
| {@code HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND} | *{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)} | *
|
* {@code (ZONE_OFFSET + DST_OFFSET) / (60*1000)} * (in minutes) * |
* {@link XMLGregorianCalendar#setTimezone(int offset)}* * | *
*conversion loss of information. It is not possible to represent * a {@code java.util.GregorianCalendar} daylight savings timezone id in the * XML Schema 1.0 date/time datatype representation. * *
To compute the return value's {@code TimeZone} field, *
A {@code null} value indicates that field is not set. * * @param year of {@code XMLGregorianCalendar} to be created. * @param month of {@code XMLGregorianCalendar} to be created. * @param day of {@code XMLGregorianCalendar} to be created. * @param hour of {@code XMLGregorianCalendar} to be created. * @param minute of {@code XMLGregorianCalendar} to be created. * @param second of {@code XMLGregorianCalendar} to be created. * @param fractionalSecond of {@code XMLGregorianCalendar} to be created. * @param timezone of {@code XMLGregorianCalendar} to be created. * * @return {@code XMLGregorianCalendar} created from specified values. * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. */ public abstract XMLGregorianCalendar newXMLGregorianCalendar( final BigInteger year, final int month, final int day, final int hour, final int minute, final int second, final BigDecimal fractionalSecond, final int timezone); /** * Constructor of value spaces that a * {@code java.util.GregorianCalendar} instance would need to convert to an * {@code XMLGregorianCalendar} instance. * *
{@code XMLGregorianCalendar eon} and * {@code fractionalSecond} are set to {@code null} * *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param year of {@code XMLGregorianCalendar} to be created. * @param month of {@code XMLGregorianCalendar} to be created. * @param day of {@code XMLGregorianCalendar} to be created. * @param hour of {@code XMLGregorianCalendar} to be created. * @param minute of {@code XMLGregorianCalendar} to be created. * @param second of {@code XMLGregorianCalendar} to be created. * @param millisecond of {@code XMLGregorianCalendar} to be created. * @param timezone of {@code XMLGregorianCalendar} to be created. * * @return {@code XMLGregorianCalendar} created from specified values. * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. */ public XMLGregorianCalendar newXMLGregorianCalendar( final int year, final int month, final int day, final int hour, final int minute, final int second, final int millisecond, final int timezone) { // year may be undefined BigInteger realYear = (year != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) year) : null; // millisecond may be undefined // millisecond must be >= 0 millisecond <= 1000 BigDecimal realMillisecond = null; // undefined value if (millisecond != DatatypeConstants.FIELD_UNDEFINED) { if (millisecond < 0 || millisecond > 1000) { throw new IllegalArgumentException( "javax.xml.datatype.DatatypeFactory#newXMLGregorianCalendar(" + "int year, int month, int day, int hour, int minute, int second, int millisecond, int timezone)" + "with invalid millisecond: " + millisecond ); } realMillisecond = BigDecimal.valueOf((long) millisecond).movePointLeft(3); } return newXMLGregorianCalendar( realYear, month, day, hour, minute, second, realMillisecond, timezone ); } /** * Create a Java representation of XML Schema builtin datatype {@code date} or {@code g*}. * *
For example, an instance of {@code gYear} can be created invoking this factory * with {@code month} and {@code day} parameters set to * {@link DatatypeConstants#FIELD_UNDEFINED}. * *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param year of {@code XMLGregorianCalendar} to be created. * @param month of {@code XMLGregorianCalendar} to be created. * @param day of {@code XMLGregorianCalendar} to be created. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * * @return {@code XMLGregorianCalendar} created from parameter values. * * @see DatatypeConstants#FIELD_UNDEFINED * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. */ public XMLGregorianCalendar newXMLGregorianCalendarDate( final int year, final int month, final int day, final int timezone) { return newXMLGregorianCalendar( year, month, day, DatatypeConstants.FIELD_UNDEFINED, // hour DatatypeConstants.FIELD_UNDEFINED, // minute DatatypeConstants.FIELD_UNDEFINED, // second DatatypeConstants.FIELD_UNDEFINED, // millisecond timezone); } /** * Create a Java instance of XML Schema builtin datatype {@code time}. * *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param hours number of hours * @param minutes number of minutes * @param seconds number of seconds * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * * @return {@code XMLGregorianCalendar} created from parameter values. * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. * * @see DatatypeConstants#FIELD_UNDEFINED */ public XMLGregorianCalendar newXMLGregorianCalendarTime( final int hours, final int minutes, final int seconds, final int timezone) { return newXMLGregorianCalendar( DatatypeConstants.FIELD_UNDEFINED, // Year DatatypeConstants.FIELD_UNDEFINED, // Month DatatypeConstants.FIELD_UNDEFINED, // Day hours, minutes, seconds, DatatypeConstants.FIELD_UNDEFINED, //Millisecond timezone); } /** * Create a Java instance of XML Schema builtin datatype time. * *
A {@code null} value indicates that field is not set. *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param hours number of hours * @param minutes number of minutes * @param seconds number of seconds * @param fractionalSecond value of {@code null} indicates that this optional field is not set. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * * @return {@code XMLGregorianCalendar} created from parameter values. * * @see DatatypeConstants#FIELD_UNDEFINED * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. */ public XMLGregorianCalendar newXMLGregorianCalendarTime( final int hours, final int minutes, final int seconds, final BigDecimal fractionalSecond, final int timezone) { return newXMLGregorianCalendar( null, // year DatatypeConstants.FIELD_UNDEFINED, // month DatatypeConstants.FIELD_UNDEFINED, // day hours, minutes, seconds, fractionalSecond, timezone); } /** * Create a Java instance of XML Schema builtin datatype time. * *
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set. * * @param hours number of hours * @param minutes number of minutes * @param seconds number of seconds * @param milliseconds number of milliseconds * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * * @return {@code XMLGregorianCalendar} created from parameter values. * * @see DatatypeConstants#FIELD_UNDEFINED * * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance * as determined by {@link XMLGregorianCalendar#isValid()}. */ public XMLGregorianCalendar newXMLGregorianCalendarTime( final int hours, final int minutes, final int seconds, final int milliseconds, final int timezone) { // millisecond may be undefined // millisecond must be >= 0 millisecond <= 1000 BigDecimal realMilliseconds = null; // undefined value if (milliseconds != DatatypeConstants.FIELD_UNDEFINED) { if (milliseconds < 0 || milliseconds > 1000) { throw new IllegalArgumentException( "javax.xml.datatype.DatatypeFactory#newXMLGregorianCalendarTime(" + "int hours, int minutes, int seconds, int milliseconds, int timezone)" + "with invalid milliseconds: " + milliseconds ); } realMilliseconds = BigDecimal.valueOf((long) milliseconds).movePointLeft(3); } return newXMLGregorianCalendarTime( hours, minutes, seconds, realMilliseconds, timezone ); } }