// $Id: DatatypeFactory.java,v 1.1.6.2.4.3 2004/06/18 08:40:14 rameshm Exp $ /* * @(#)DatatypeFactory.java 1.4 04/07/26 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package javax.xml.datatype; import java.math.BigInteger; import java.math.BigDecimal; import java.util.GregorianCalendar; /** *
Factory that creates new javax.xml.datatype
Object
s that map XML to/from Java Object
s.
{@link #newInstance()} is used to create a new DatatypeFactory
.
* The following implementation resolution mechanisms are used in the following order:
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}.
* Object
.
* The Properties
Object
is then queried for the property as documented in the prior step
* and processed as documented in the prior step.
* META-INF/services/java.xml.datatype.DatatypeFactory
.
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
* Class
specified by
* {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}, "javax.xml.datatype.DatatypeFactoryImpl
".
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
* Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
* *Default value is 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 com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl
.
Protected constructor to prevent instaniation outside of package.
* *Use {@link #newInstance()} to create a DatatypeFactory
.
Obtain a new instance of a DatatypeFactory
.
The implementation resolution mechanisms are defined in this
* Class
's documentation.
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());
}
}
/**
* 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 availabe 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 lexicalRepresentationString
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 availabe 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 NewDuration
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 isnot set.
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 isnot set.
* * @param isPositive Set tofalse
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 availabe 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 NewDuration
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) {
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 availabe 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 ofDuration
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 isnot set.
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 isnot set.
* * @param isPositive Set tofalse
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 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 availabe 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 NewDuration
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) {
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 availabe 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 ofDuration
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 isnot set.
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 isnot set.
* * @param isPositive Set tofalse
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 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 NewXMLGregorianCalendar
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. * * @returnXMLGregorianCalendar
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 field |
* javax.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,
*
this.getTimezone() != FIELD_UNDEFINED
,
* create a java.util.TimeZone
with a custom timezone id
* using the this.getTimezone()
.GregorianCalendar
default timezone value
* for the host is defined as specified by
* java.util.TimeZone.getDefault()
.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 isnot set.
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 isnot set.
* * @param year ofXMLGregorianCalendar
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).movePointLeft(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 isnot set.
* * @param year ofXMLGregorianCalendar
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 isnot 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. * * @returnXMLGregorianCalendar
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 isnot set.
A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.
* * @param hours number of hours * @param minutes number of minutes * @param seconds number of seconds * @param fractionalSecond value ofnull
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 isnot 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. * * @returnXMLGregorianCalendar
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).movePointLeft(3);
}
return newXMLGregorianCalendarTime(
hours,
minutes,
seconds,
realMilliseconds,
timezone
);
}
}