src/javax/xml/datatype/DatatypeFactory.java

Print this page




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.datatype;
  27 
  28 import java.math.BigInteger;
  29 import java.math.BigDecimal;

  30 import java.util.GregorianCalendar;
  31 import java.util.regex.Matcher;
  32 import java.util.regex.Pattern;
  33 
  34 /**
  35  * <p>Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.</p>
  36  *
  37  * <p><a name="DatatypeFactory.newInstance"/>{@link #newInstance()} is used to create a new <code>DatatypeFactory</code>.
  38  * The following implementation resolution mechanisms are used in the following order:</p>
  39  * <ol>
  40  *    <li>
  41  *      If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
  42  *      exists, a class with the name of the property's value is instantiated.
  43  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  44  *    </li>
  45  *    <li>
  46  *      If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
  47  *      The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
  48  *      and processed as documented in the prior step.
  49  *    </li>
  50  *    <li>
  51  *      The services resolution mechanism is used, e.g. <code>META-INF/services/java.xml.datatype.DatatypeFactory</code>.
  52  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.





  53  *    </li>
  54  *    <li>
  55  *      The final mechanism is to attempt to instantiate the <code>Class</code> specified by
  56  *      {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
  57  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  58  *    </li>
  59  * </ol>
  60  *
  61  * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
  62  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  63  * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
  64  *
  65  * @version $Revision: 1.13 $, $Date: 2010/03/11 23:10:53 $
  66  * @since 1.5
  67  */
  68 public abstract class DatatypeFactory {
  69 
  70         /**
  71          * <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
  72          *
  73          * <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
  74          */
  75         public static final String DATATYPEFACTORY_PROPERTY = "javax.xml.datatype.DatatypeFactory";
  76 
  77         /**
  78          * <p>Default implementation class name as defined in
  79          * <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p>
  80          *
  81          * <p>Implementers should specify the name of an appropriate class
  82          * to be instantiated if no other implementation resolution mechanism
  83          * succeeds.</p>
  84          *
  85          * <p>Users should not refer to this field; it is intended only to


 108          */
 109         protected DatatypeFactory() {
 110         }
 111 
 112         /**
 113          * <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
 114          *
 115      * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
 116      * <code>Class</code>'s documentation.</p>
 117          *
 118          * @return New instance of a <code>DatatypeFactory</code>
 119          *
 120          * @throws DatatypeConfigurationException If the implementation is not
 121          *   available or cannot be instantiated.
 122      *
 123      * @see #newInstance(String factoryClassName, ClassLoader classLoader)
 124          */
 125         public static DatatypeFactory newInstance()
 126                 throws DatatypeConfigurationException {
 127 
 128                 try {
 129                         return (DatatypeFactory) FactoryFinder.find(
 130                                 /* The default property name according to the JAXP spec */
 131                                  DATATYPEFACTORY_PROPERTY,
 132                                 /* The fallback implementation class name */
 133                                 DATATYPEFACTORY_IMPLEMENTATION_CLASS);
 134                 } catch (FactoryFinder.ConfigurationError e) {
 135                         throw new DatatypeConfigurationException(e.getMessage(), e.getException());
 136                 }
 137         }
 138 
 139     /**
 140      * <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name.
 141      * This function is useful when there are multiple providers in the classpath.
 142      * It gives more control to the application as it can specify which provider
 143      * should be loaded.</p>
 144      *
 145      * <p>Once an application has obtained a reference to a <code>DatatypeFactory</code>
 146      * it can use the factory to configure and obtain datatype instances.</P>
 147      *
 148      *
 149      * <h2>Tip for Trouble-shooting</h2>
 150      * <p>Setting the <code>jaxp.debug</code> system property will cause
 151      * this method to print a lot of debug messages
 152      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 153      *
 154      * <p> If you have problems try:</p>
 155      * <pre>
 156      * java -Djaxp.debug=1 YourProgram ....
 157      * </pre>
 158      *
 159      * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>.
 160      *
 161      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 162      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
 163      *
 164      * @return New instance of a <code>DatatypeFactory</code>
 165      *
 166      * @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
 167      *                                   the factory class cannot be loaded, instantiated.
 168      *
 169      * @see #newInstance()
 170      *
 171      * @since 1.6
 172      */
 173     public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader)
 174         throws DatatypeConfigurationException {
 175         try {
 176             return (DatatypeFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
 177         } catch (FactoryFinder.ConfigurationError e) {
 178             throw new DatatypeConfigurationException(e.getMessage(), e.getException());
 179         }
 180     }
 181 
 182         /**
 183          * <p>Obtain a new instance of a <code>Duration</code>
 184          * specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
 185          * as defined in XML Schema 1.0 section 3.2.6.1.</p>
 186          *
 187          * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
 188          * <blockquote>
 189          * duration represents a duration of time.
 190          * The value space of duration is a six-dimensional space where the coordinates designate the
 191          * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
 192          * These components are ordered in their significance by their order of appearance i.e. as
 193          * year, month, day, hour, minute, and second.
 194          * </blockquote>
 195      * <p>All six values are set and availabe from the created {@link Duration}</p>
 196      *
 197      * <p>The XML Schema specification states that values can be of an arbitrary size.
 198      * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
 199      * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.datatype;
  27 

  28 import java.math.BigDecimal;
  29 import java.math.BigInteger;
  30 import java.util.GregorianCalendar;
  31 import java.util.regex.Matcher;
  32 import java.util.regex.Pattern;
  33 
  34 /**
  35  * <p>Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.</p>
  36  *
  37  * <p>A new instance of the <code>DatatypeFactory</code> is created through the {@link #newInstance()} method 
  38  * that uses the following implementation resolution mechanisms to determine an implementation:</p>
  39  * <ol>
  40  *    <li>
  41  *      If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
  42  *      exists, a class with the name of the property's value is instantiated.
  43  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  44  *    </li>
  45  *    <li>
  46  *      If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
  47  *      The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
  48  *      and processed as documented in the prior step.
  49  *    </li>
  50  *    <li>
  51  *     <p>Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt 
  52  *     to locate and load an implementation of the service. In case of multiple providers, the first non-default implementation
  53  *     shall be instantiated and returned.  The default implementation is returned if it is the only one
  54  *     found by the service loader.</p>
  55  *     <p>
  56  *     If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped 
  57  *     in a {@link javax.xml.datatype.DatatypeConfigurationException}.</p>
  58  *    </li>
  59  *    <li>
  60  *      The final mechanism is to attempt to instantiate the <code>Class</code> specified by
  61  *      {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
  62  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  63  *    </li>
  64  * </ol>
  65  *
  66  * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
  67  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  68  * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
  69  *
  70  * @version $Revision: 1.14 $, $Date: 2010-11-01 04:36:08 $
  71  * @since 1.5
  72  */
  73 public abstract class DatatypeFactory {
  74 
  75         /**
  76      *     <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
  77          *
  78      *     <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
  79          */
  80         public static final String DATATYPEFACTORY_PROPERTY = "javax.xml.datatype.DatatypeFactory";
  81 
  82         /**
  83      *     <p>Default implementation class name as defined in
  84      *     <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p>
  85          *
  86      *     <p>Implementers should specify the name of an appropriate class
  87      *     to be instantiated if no other implementation resolution mechanism
  88      *     succeeds.</p>
  89          *
  90      *     <p>Users should not refer to this field; it is intended only to


 113          */
 114         protected DatatypeFactory() {
 115         }
 116 
 117         /**
 118      *     <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
 119          *
 120  *     <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
 121  *     <code>Class</code>'s documentation.</p>
 122          *
 123      *     @return New instance of a <code>DatatypeFactory</code>
 124          *
 125      *     @throws DatatypeConfigurationException If the implementation is not
 126      *       available or cannot be instantiated.
 127      *
 128  *     @see #newInstance(String factoryClassName, ClassLoader classLoader)
 129          */
 130     public static DatatypeFactory newInstance()
 131         throws DatatypeConfigurationException {
 132 
 133         return (DatatypeFactory) FactoryFinder.find(DatatypeFactory.class,

 134                 /* The default property name according to the JAXP spec */
 135                  DATATYPEFACTORY_PROPERTY,
 136                 /* The fallback implementation class name */
 137                 DATATYPEFACTORY_IMPLEMENTATION_CLASS);
 138 }



 139 
 140     /**
 141  *     <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name.
 142  *     This function is useful when there are multiple providers in the classpath.
 143  *     It gives more control to the application as it can specify which provider
 144  *     should be loaded.</p>
 145      *
 146  *     <p>Once an application has obtained a reference to a <code>DatatypeFactory</code>
 147  *     it can use the factory to configure and obtain datatype instances.</P>
 148      *
 149      *
 150  *     <h2>Tip for Trouble-shooting</h2>
 151  *     <p>Setting the <code>jaxp.debug</code> system property will cause
 152  *     this method to print a lot of debug messages
 153  *     to <code>System.err</code> about what it is doing and where it is looking at.</p>
 154      *
 155  *     <p> If you have problems try:</p>
 156  *     <pre>
 157  *     java -Djaxp.debug=1 YourProgram ....
 158  *     </pre>
 159      *
 160  *     @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>.
 161      *
 162  *     @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 163  *                         current <code>Thread</code>'s context classLoader is used to load the factory class.
 164      *
 165  *     @return New instance of a <code>DatatypeFactory</code>
 166      *
 167  *     @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
 168  *                                       the factory class cannot be loaded, instantiated.
 169      *
 170  *     @see #newInstance()
 171      *
 172  *     @since 1.6
 173      */
 174     public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader)
 175         throws DatatypeConfigurationException {

 176             return (DatatypeFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);



 177         }
 178 
 179         /**
 180      *     <p>Obtain a new instance of a <code>Duration</code>
 181      *     specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
 182      *     as defined in XML Schema 1.0 section 3.2.6.1.</p>
 183          *
 184      *     <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
 185      *     <blockquote>
 186      *     duration represents a duration of time.
 187      *     The value space of duration is a six-dimensional space where the coordinates designate the
 188      *     Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
 189      *     These components are ordered in their significance by their order of appearance i.e. as
 190      *     year, month, day, hour, minute, and second.
 191      *     </blockquote>
 192  *     <p>All six values are set and availabe from the created {@link Duration}</p>
 193      *
 194  *     <p>The XML Schema specification states that values can be of an arbitrary size.
 195  *     Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
 196  *     An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits