javax.xml.datatype.DatatypeFactory 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: DatatypeFactory.java 884950 2009-11-27 18:46:18Z mrglavas $
package javax.xml.datatype;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.GregorianCalendar;
/**
* Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.
*
* {@link #newInstance()} is used to create a new DatatypeFactory.
* The following implementation resolution mechanisms are used in the following order:
*
* -
* If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "
javax.xml.datatype.DatatypeFactory",
* exists, a class with the name of the property's value is instantiated.
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
*
* -
* 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.
*
* -
* The services resolution mechanism is used, e.g.
META-INF/services/java.xml.datatype.DatatypeFactory.
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
*
* -
* The final mechanism is to attempt to instantiate the
Class specified by
* {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}, "javax.xml.datatype.DatatypeFactoryImpl".
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
*
*
*
* Note that you must supply your own implementation (such as Xerces); Android does not ship with a default implementation.
*
* @author Joseph Fialli
* @author Jeff Suttor
* @version $Revision: 884950 $, $Date: 2009-11-27 10:46:18 -0800 (Fri, 27 Nov 2009) $
* @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 = "javax.xml.datatype.DatatypeFactory";
/**
* Default implementation class name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
*
* Default value is org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl.
*/
// This uses "new String" to avoid being inlined as a constant.
public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS = new String("org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl");
/**
* 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.
* Note that you must supply your own implementation (such as Xerces); Android does not ship with a default implementation.
*
* @return New instance of a DocumentBuilderFactory
*
* @throws DatatypeConfigurationException If the implementation is not
* available or cannot be instantiated.
*/
public static DatatypeFactory newInstance()
throws DatatypeConfigurationException {
try {
return (DatatypeFactory) FactoryFinder.find(
/* The default property name according to the JAXP spec */
DATATYPEFACTORY_PROPERTY,
/* The fallback implementation class name */
DATATYPEFACTORY_IMPLEMENTATION_CLASS);
}
catch (FactoryFinder.ConfigurationError e) {
throw new DatatypeConfigurationException(e.getMessage(), e.getException());
}
}
/**
* Returns an instance of the named implementation of {@code DatatypeFactory}.
*
* @throws DatatypeConfigurationException if {@code factoryClassName} is not available or cannot
* be instantiated.
* @since 1.6
*/
public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader)
throws DatatypeConfigurationException {
if (factoryClassName == null) {
throw new DatatypeConfigurationException("factoryClassName == null");
}
if (classLoader == null) {
classLoader = Thread.currentThread().getContextClassLoader();
}
try {
Class type = classLoader != null
? classLoader.loadClass(factoryClassName)
: Class.forName(factoryClassName);
return (DatatypeFactory) type.newInstance();
} catch (ClassNotFoundException e) {
throw new DatatypeConfigurationException(e);
} catch (InstantiationException e) {
throw new DatatypeConfigurationException(e);
} catch (IllegalAccessException e) {
throw new DatatypeConfigurationException(e);
}
}
/**
*
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:
*
* - ISO 8601:2000(E) Section 5.5.3.2 Alternative format
* -
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
*
* - {@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
*
*
* 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 values are not a valid representation of a Duration.
* @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 values are not a valid representation of a Duration.
*
* @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 the given string does not conform to the aforementioned specification.
* @throws UnsupportedOperationException If implementation cannot support requested values.
* @throws NullPointerException If lexicalRepresentation is null.
*/
public Duration newDurationDayTime(final String lexicalRepresentation) {
if (lexicalRepresentation == null) {
throw new NullPointerException("lexicalRepresentation == null");
}
// The lexical representation must match the pattern [^YM]*(T.*)?
int pos = lexicalRepresentation.indexOf('T');
int length = (pos >= 0) ? pos : lexicalRepresentation.length();
for (int i = 0; i < length; ++i) {
char c = lexicalRepresentation.charAt(i);
if (c == 'Y' || c == 'M') {
throw new IllegalArgumentException("Invalid dayTimeDuration value: " + lexicalRepresentation);
}
}
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:
*
* - ISO 8601:2000(E) Section 5.5.3.2 Alternative format
* -
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
*
* - {@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
*
*
* 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) {
long _durationInMilliseconds = durationInMilliseconds;
if (_durationInMilliseconds == 0) {
return newDuration(true, DatatypeConstants.FIELD_UNDEFINED,
DatatypeConstants.FIELD_UNDEFINED, 0, 0, 0, 0);
}
boolean tooLong = false;
final boolean isPositive;
if (_durationInMilliseconds < 0) {
isPositive = false;
if (_durationInMilliseconds == Long.MIN_VALUE) {
_durationInMilliseconds++;
tooLong = true;
}
_durationInMilliseconds *= -1;
}
else {
isPositive = true;
}
long val = _durationInMilliseconds;
int milliseconds = (int) (val % 60000L); // 60000 milliseconds per minute
if (tooLong) {
++milliseconds;
}
if (milliseconds % 1000 == 0) {
int seconds = milliseconds / 1000;
val = val / 60000L;
int minutes = (int) (val % 60L); // 60 minutes per hour
val = val / 60L;
int hours = (int) (val % 24L); // 24 hours per day
long days = val / 24L;
if (days <= ((long) Integer.MAX_VALUE)) {
return newDuration(isPositive, DatatypeConstants.FIELD_UNDEFINED,
DatatypeConstants.FIELD_UNDEFINED, (int) days, hours, minutes, seconds);
}
else {
return newDuration(isPositive, null, null,
BigInteger.valueOf(days), BigInteger.valueOf(hours),
BigInteger.valueOf(minutes), BigDecimal.valueOf(milliseconds, 3));
}
}
BigDecimal seconds = BigDecimal.valueOf(milliseconds, 3);
val = val / 60000L;
BigInteger minutes = BigInteger.valueOf(val % 60L); // 60 minutes per hour
val = val / 60L;
BigInteger hours = BigInteger.valueOf(val % 24L); // 24 hours per day
val = val / 24L;
BigInteger days = BigInteger.valueOf(val);
return newDuration(isPositive, null, null, days, hours, minutes, seconds);
}
/**
* 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 any values would create an invalid Duration.
* @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 any values would create an invalid Duration.
*/
public Duration newDurationDayTime(
final boolean isPositive,
final int day,
final int hour,
final int minute,
final int second) {
return newDuration(isPositive,
DatatypeConstants.FIELD_UNDEFINED, DatatypeConstants.FIELD_UNDEFINED,
day, hour, minute, 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 the lexicalRepresentation does not conform to the specification.
* @throws UnsupportedOperationException If implementation cannot support requested values.
* @throws NullPointerException If lexicalRepresentation is null.
*/
public Duration newDurationYearMonth(final String lexicalRepresentation) {
if (lexicalRepresentation == null) {
throw new NullPointerException("lexicalRepresentation == null");
}
// The lexical representation must match the pattern [^DT]*.
int length = lexicalRepresentation.length();
for (int i = 0; i < length; ++i) {
char c = lexicalRepresentation.charAt(i);
if (c == 'D' || c == 'T') {
throw new IllegalArgumentException("Invalid yearMonthDuration value: " + lexicalRepresentation);
}
}
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:
*
* - ISO 8601:2000(E) Section 5.5.3.2 Alternative format
* -
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
*
* - {@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
*
*
* 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) {
return newDuration(durationInMilliseconds);
}
/**
* 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 any values would create an invalid Duration.
* @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 any values would create an invalid Duration.
*/
public Duration newDurationYearMonth(
final boolean isPositive,
final int year,
final int month) {
return newDuration(isPositive, year, month,
DatatypeConstants.FIELD_UNDEFINED, DatatypeConstants.FIELD_UNDEFINED,
DatatypeConstants.FIELD_UNDEFINED, DatatypeConstants.FIELD_UNDEFINED);
}
/**
* 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,
*
* - when
this.getTimezone() != FIELD_UNDEFINED,
* create a java.util.TimeZone with a custom timezone id
* using the this.getTimezone().
* - else use the
GregorianCalendar default timezone value
* for the host is defined as specified by
* java.util.TimeZone.getDefault().
*
* @param cal java.util.GregorianCalendar used to create XMLGregorianCalendar
*
* @return XMLGregorianCalendar created from java.util.GregorianCalendar
*
* @throws NullPointerException If cal is null.
*/
public abstract XMLGregorianCalendar newXMLGregorianCalendar(final GregorianCalendar cal);
/**
* Constructor allowing for complete value spaces allowed by
* W3C XML Schema 1.0 recommendation for xsd:dateTime and related
* builtin datatypes. Note that year parameter supports
* arbitrarily large numbers and fractionalSecond has infinite
* precision.
*
* A null value indicates that field is not set.
*
* @param year of XMLGregorianCalendar to be created.
* @param month of XMLGregorianCalendar to be created.
* @param day of XMLGregorianCalendar to be created.
* @param hour of XMLGregorianCalendar to be created.
* @param minute of XMLGregorianCalendar to be created.
* @param second of XMLGregorianCalendar to be created.
* @param fractionalSecond of XMLGregorianCalendar to be created.
* @param timezone of XMLGregorianCalendar to be created.
*
* @return 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 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
* java.util.GregorianCalendar instance would need to convert to an
* XMLGregorianCalendar instance.
*
* XMLGregorianCalendar eon and
* fractionalSecond are set to null
*
* A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
*
* @param year of XMLGregorianCalendar to be created.
* @param month of XMLGregorianCalendar to be created.
* @param day of XMLGregorianCalendar to be created.
* @param hour of XMLGregorianCalendar to be created.
* @param minute of XMLGregorianCalendar to be created.
* @param second of XMLGregorianCalendar to be created.
* @param millisecond of XMLGregorianCalendar to be created.
* @param timezone of XMLGregorianCalendar to be created.
*
* @return 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 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, 3);
}
return newXMLGregorianCalendar(
realYear,
month,
day,
hour,
minute,
second,
realMillisecond,
timezone
);
}
/**
* Create a Java representation of XML Schema builtin datatype date or g*.
*
* For example, an instance of gYear can be created invoking this factory
* with month and day parameters set to
* {@link DatatypeConstants#FIELD_UNDEFINED}.
*
* A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
*
* @param year of XMLGregorianCalendar to be created.
* @param month of XMLGregorianCalendar to be created.
* @param day of XMLGregorianCalendar to be created.
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
*
* @return 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 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 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 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 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 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 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 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 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 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 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, 3);
}
return newXMLGregorianCalendarTime(
hours,
minutes,
seconds,
realMilliseconds,
timezone
);
}
}