xml/datatype/DatatypeFactory.java

/*
 * Copyright (c) 2004, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.xml.datatype;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.GregorianCalendar;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl;

/**
 * Factory that creates new {@code javax.xml.datatype} {@code Object}s that map XML to/from Java {@code Object}s.
 * <p id="DatatypeFactory.newInstance">
 * 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:
 * <ol>
 *    <li>
 *      If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "{@code javax.xml.datatype.DatatypeFactory}",
 *      exists, a class with the name of the property value is instantiated.
 *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
 *    </li>
 *    <li>
 *      <p>
 *      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.
 *      <p>
 *      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.
 *    </li>
 *    <li>
 *     <p>
 *     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.
 *     <p>
 *     In case of {@link java.util.ServiceConfigurationError service
 *     configuration error}, a {@link javax.xml.datatype.DatatypeConfigurationException}
 *     will be thrown.
 *    </li>
 *    <li>
 *      <p>
 *      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}.
 *    </li>
 * </ol>
 *
 * @author Joseph Fialli
 * @author Jeff Suttor
 * @author Neeraj Bajaj
 *
 * @since 1.5
 */
public abstract class DatatypeFactory {

    /**
     * Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
     *
     * <p>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
     * <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.
     *
     * <p>Implementers should specify the name of an appropriate class
     * to be instantiated if no other implementation resolution mechanism
     * succeeds.
     *
     * <p>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.
     *
     * <p>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}.
     *
     * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> 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.
     *
     * <p>Once an application has obtained a reference to a {@code DatatypeFactory}
     * it can use the factory to configure and obtain datatype instances.
     *
     *
     * <h4>Tip for Trouble-shooting</h4>
     * <p>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.
     *
     * <p> If you have problems try:
     * <pre>
     * java -Djaxp.debug=1 YourProgram ....
     * </pre>
     *
     * @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.
     *
     * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines {@code duration} as:
     * <blockquote>
     * 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.
     * </blockquote>
     * <p>All six values are set and available from the created {@link Duration}
     *
     * <p>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.
     *
     * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines {@code duration} as:
     * <blockquote>
     * 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.
     * </blockquote>
     * <p>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:
     * <ul>
     *   <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
     *   <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
     *     W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
     *   </li>
     *   <li>{@link XMLGregorianCalendar}  Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
     * </ul>
     *
     * <p>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.
     *
     * <p>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.
     *
     * <p>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.
     *
     * <p>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,
     * "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
     *
     * <p>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}.
     *
     * <p>All four values are set and available from the created {@link Duration}
     *
     * <p>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
     * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
     *
     * <p>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}.
     *
     * <p>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:
     * <ul>
     *   <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
     *   <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
     *     W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
     *   </li>
     *   <li>{@link XMLGregorianCalendar}  Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
     * </ul>
     *
     * <p>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.
     *
     * <p>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 <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>
     */
    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
     * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
     *
     * <p>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}.
     *
     * <p>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.
     *
     * <p>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
     * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
     *
     * <p>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}.
     *
     * <p>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,
     * "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
     *
     * <p>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}.
     *
     * <p>Both values are set and available from the created {@link Duration}
     *
     * <p>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
     * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
     *
     * <p>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}.
     *
     * <p>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:
     * <ul>
     *   <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
     *   <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
     *     W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
     *   </li>
     *   <li>{@link XMLGregorianCalendar}  Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
     * </ul>
     *
     * <p>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.
     *
     * <p>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
     * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
     *
     * <p>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.
     *
     * <p>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
     * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
     *   XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
     *
     * <p>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}.
     *
     * <p>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.
     *
     * <p>Parsing the lexical string representation is defined in
     * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
     * <em>Lexical Representation</em>.</a>
     *
     * <p>The string representation may not have any leading and trailing whitespaces.
     *
     * <p>The parsing is done field by field so that
     * the following holds for any lexically correct String x:
     * <pre>
     * newXMLGregorianCalendar(x).toXMLFormat().equals(x)
     * </pre>
     * <p>Except for the noted lexical/canonical representation mismatches
     * listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">
     * XML Schema 1.0 errata, Section 3.2.7.2</a>.
     *
     * @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}.
     *
     * <table class="striped">
     *   <caption>Field by Field Conversion from
     *          {@link GregorianCalendar} to an {@link XMLGregorianCalendar}</caption>
     *   <thead>
     *     <tr>
     *        <th scope="col">{@code java.util.GregorianCalendar} field</th>
     *        <th scope="col">{@code javax.xml.datatype.XMLGregorianCalendar} field</th>
     *     </tr>
     *   </thead>
     *   <tbody>
     *     <tr>
     *       <th scope="row">{@code ERA == GregorianCalendar.BC ? -YEAR : YEAR}</th>
     *       <td>{@link XMLGregorianCalendar#setYear(int year)}</td>
     *     </tr>
     *     <tr>
     *       <th scope="row">{@code MONTH + 1}</th>
     *       <td>{@link XMLGregorianCalendar#setMonth(int month)}</td>
     *     </tr>
     *     <tr>
     *       <th scope="row">{@code DAY_OF_MONTH}</th>
     *       <td>{@link XMLGregorianCalendar#setDay(int day)}</td>
     *     </tr>
     *     <tr>
     *       <th scope="row">{@code HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND}</th>
     *       <td>{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}</td>
     *     </tr>
     *     <tr>
     *       <th scope="row">
     *         {@code (ZONE_OFFSET + DST_OFFSET) / (60*1000)}<br>
     *         <em>(in minutes)</em>
     *       </th>
     *       <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup>
     *       </td>
     *     </tr>
     *   </tbody>
     * </table>
     * <p><em>*</em>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.
     *
     * <p>To compute the return value's {@code TimeZone} field,
     * <ul>
     * <li>when {@code this.getTimezone() != FIELD_UNDEFINED},
     * create a {@code java.util.TimeZone} with a custom timezone id
     * using the {@code this.getTimezone()}.</li>
     * <li>else use the {@code GregorianCalendar} default timezone value
     * for the host is defined as specified by
     * {@code java.util.TimeZone.getDefault()}.</li>
     * </ul>
     *
     * @param cal {@code java.util.GregorianCalendar} used to create {@code XMLGregorianCalendar}
     *
     * @return {@code XMLGregorianCalendar} created from {@code java.util.GregorianCalendar}
     *
     * @throws NullPointerException If {@code cal} is {@code 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 {@code year} parameter supports
     * arbitrarily large numbers and fractionalSecond has infinite
     * precision.
     *
     * <p>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.
     *
     * <p>{@code XMLGregorianCalendar eon} and
     * {@code fractionalSecond} are set to {@code null}
     *
     * <p>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*}.
     *
     * <p>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}.
     *
     * <p>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}.
     *
     * <p>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.
     *
     * <p>A {@code null} value indicates that field is not set.
     * <p>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.
     *
     * <p>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
            );
    }
}