src/javax/xml/transform/TransformerFactory.java

Print this page




  58      * load:</p>
  59      * <ul>
  60      * <li>
  61      * Use the <code>javax.xml.transform.TransformerFactory</code> system
  62      * property.
  63      * </li>
  64      * <li>
  65      * Use the properties file "lib/jaxp.properties" in the JRE directory.
  66      * This configuration file is in standard <code>java.util.Properties
  67      * </code> format and contains the fully qualified name of the
  68      * implementation class with the key being the system property defined
  69      * above.
  70      *
  71      * The jaxp.properties file is read only once by the JAXP implementation
  72      * and it's values are then cached for future use.  If the file does not exist
  73      * when the first attempt is made to read from it, no further attempts are
  74      * made to check for its existence.  It is not possible to change the value
  75      * of any property in jaxp.properties after it has been read for the first time.
  76      * </li>
  77      * <li>
  78      * Use the Services API (as detailed in the JAR specification), if
  79      * available, to determine the classname. The Services API will look
  80      * for a classname in the file
  81      * <code>META-INF/services/javax.xml.transform.TransformerFactory</code>
  82      * in jars available to the runtime.


  83      * </li>
  84      * <li>
  85      * Platform default <code>TransformerFactory</code> instance.
  86      * </li>
  87      * </ul>
  88      *
  89      * <p>Once an application has obtained a reference to a <code>
  90      * TransformerFactory</code> it can use the factory to configure
  91      * and obtain transformer instances.</p>
  92      *
  93      * @return new TransformerFactory instance, never null.
  94      *
  95      * @throws TransformerFactoryConfigurationError Thrown if the implementation
  96      *    is not available or cannot be instantiated.
  97      */
  98     public static TransformerFactory newInstance()
  99         throws TransformerFactoryConfigurationError {
 100         try {
 101             return (TransformerFactory) FactoryFinder.find(
 102             /* The default property name according to the JAXP spec */
 103             "javax.xml.transform.TransformerFactory",
 104             /* The fallback implementation class name, XSLTC */
 105             "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl");
 106         } catch (FactoryFinder.ConfigurationError e) {
 107             throw new TransformerFactoryConfigurationError(
 108                 e.getException(),
 109                 e.getMessage());
 110         }
 111     }
 112 
 113     /**
 114      * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
 115      * This function is useful when there are multiple providers in the classpath.
 116      * It gives more control to the application as it can specify which provider
 117      * should be loaded.</p>
 118      *
 119      * <p>Once an application has obtained a reference to a <code>
 120      * TransformerFactory</code> it can use the factory to configure
 121      * and obtain transformer instances.</p>
 122      *
 123      * <h2>Tip for Trouble-shooting</h2>
 124      * <p>Setting the <code>jaxp.debug</code> system property will cause
 125      * this method to print a lot of debug messages
 126      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 127      *
 128      * <p> If you have problems try:</p>
 129      * <pre>
 130      * java -Djaxp.debug=1 YourProgram ....
 131      * </pre>
 132      *
 133      * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
 134      *
 135      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 136      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
 137      *
 138      * @return new TransformerFactory instance, never null.
 139      *
 140      * @throws TransformerFactoryConfigurationError
 141      *                    if <code>factoryClassName</code> is <code>null</code>, or
 142      *                   the factory class cannot be loaded, instantiated.
 143      *
 144      * @see #newInstance()
 145      *
 146      * @since 1.6
 147      */
 148     public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
 149         throws TransformerFactoryConfigurationError{
 150         try {
 151             //do not fallback if given classloader can't find the class, throw exception
 152             return (TransformerFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
 153         } catch (FactoryFinder.ConfigurationError e) {
 154             throw new TransformerFactoryConfigurationError(
 155                 e.getException(),
 156                 e.getMessage());
 157         }
 158     }
 159     /**
 160      * <p>Process the <code>Source</code> into a <code>Transformer</code>
 161      * <code>Object</code>.  The <code>Source</code> is an XSLT document that
 162      * conforms to <a href="http://www.w3.org/TR/xslt">
 163      * XSL Transformations (XSLT) Version 1.0</a>.  Care must
 164      * be taken not to use this <code>Transformer</code> in multiple
 165      * <code>Thread</code>s running concurrently.
 166      * Different <code>TransformerFactories</code> can be used concurrently by
 167      * different <code>Thread</code>s.</p>
 168      *
 169      * @param source <code>Source </code> of XSLT document used to create
 170      *   <code>Transformer</code>.
 171      *   Examples of XML <code>Source</code>s include
 172      *   {@link javax.xml.transform.dom.DOMSource DOMSource},
 173      *   {@link javax.xml.transform.sax.SAXSource SAXSource}, and
 174      *   {@link javax.xml.transform.stream.StreamSource StreamSource}.
 175      *
 176      * @return A <code>Transformer</code> object that may be used to perform
 177      *   a transformation in a single <code>Thread</code>, never




  58      * load:</p>
  59      * <ul>
  60      * <li>
  61      * Use the <code>javax.xml.transform.TransformerFactory</code> system
  62      * property.
  63      * </li>
  64      * <li>
  65      * Use the properties file "lib/jaxp.properties" in the JRE directory.
  66      * This configuration file is in standard <code>java.util.Properties
  67      * </code> format and contains the fully qualified name of the
  68      * implementation class with the key being the system property defined
  69      * above.
  70      *
  71      * The jaxp.properties file is read only once by the JAXP implementation
  72      * and it's values are then cached for future use.  If the file does not exist
  73      * when the first attempt is made to read from it, no further attempts are
  74      * made to check for its existence.  It is not possible to change the value
  75      * of any property in jaxp.properties after it has been read for the first time.
  76      * </li>
  77      * <li>
  78      * <p>Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt 
  79      * to locate and load an implementation of the service. In case of multiple providers, the first non-default implementation
  80      * shall be instantiated and returned.  The default implementation is returned if it is the only one
  81      * found by the service loader.</p>
  82      * <p>
  83      * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped 
  84      * in a {@link javax.xml.transform.TransformerFactoryConfigurationError}.</p>
  85      * </li>
  86      * <li>
  87      * Platform default <code>TransformerFactory</code> instance.
  88      * </li>
  89      * </ul>
  90      *
  91      * <p>Once an application has obtained a reference to a <code>
  92      * TransformerFactory</code> it can use the factory to configure
  93      * and obtain transformer instances.</p>
  94      *
  95      * @return new TransformerFactory instance, never null.
  96      *
  97      * @throws TransformerFactoryConfigurationError Thrown if the implementation
  98      *    is not available or cannot be instantiated.
  99      */
 100     public static TransformerFactory newInstance()
 101         throws TransformerFactoryConfigurationError {
 102         return (TransformerFactory) FactoryFinder.find(TransformerFactory.class,

 103             /* The default property name according to the JAXP spec */
 104             "javax.xml.transform.TransformerFactory",
 105             /* The fallback implementation class name, XSLTC */
 106             "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl");





 107         }
 108 
 109     /**
 110      * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
 111      * This function is useful when there are multiple providers in the classpath.
 112      * It gives more control to the application as it can specify which provider
 113      * should be loaded.</p>
 114      *
 115      * <p>Once an application has obtained a reference to a <code>
 116      * TransformerFactory</code> it can use the factory to configure
 117      * and obtain transformer instances.</p>
 118      *
 119      * <h2>Tip for Trouble-shooting</h2>
 120      * <p>Setting the <code>jaxp.debug</code> system property will cause
 121      * this method to print a lot of debug messages
 122      * to <code>System.err</code> about what it is doing and where it is looking at.</p>
 123      *
 124      * <p> If you have problems try:</p>
 125      * <pre>
 126      * java -Djaxp.debug=1 YourProgram ....
 127      * </pre>
 128      *
 129      * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
 130      *
 131      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
 132      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
 133      *
 134      * @return new TransformerFactory instance, never null.
 135      *
 136      * @throws TransformerFactoryConfigurationError
 137      *                    if <code>factoryClassName</code> is <code>null</code>, or
 138      *                   the factory class cannot be loaded, instantiated.
 139      *
 140      * @see #newInstance()
 141      *
 142      * @since 1.6
 143      */
 144     public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
 145         throws TransformerFactoryConfigurationError{

 146             //do not fallback if given classloader can't find the class, throw exception
 147             return (TransformerFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);





 148         }
 149     /**
 150      * <p>Process the <code>Source</code> into a <code>Transformer</code>
 151      * <code>Object</code>.  The <code>Source</code> is an XSLT document that
 152      * conforms to <a href="http://www.w3.org/TR/xslt">
 153      * XSL Transformations (XSLT) Version 1.0</a>.  Care must
 154      * be taken not to use this <code>Transformer</code> in multiple
 155      * <code>Thread</code>s running concurrently.
 156      * Different <code>TransformerFactories</code> can be used concurrently by
 157      * different <code>Thread</code>s.</p>
 158      *
 159      * @param source <code>Source </code> of XSLT document used to create
 160      *   <code>Transformer</code>.
 161      *   Examples of XML <code>Source</code>s include
 162      *   {@link javax.xml.transform.dom.DOMSource DOMSource},
 163      *   {@link javax.xml.transform.sax.SAXSource SAXSource}, and
 164      *   {@link javax.xml.transform.stream.StreamSource StreamSource}.
 165      *
 166      * @return A <code>Transformer</code> object that may be used to perform
 167      *   a transformation in a single <code>Thread</code>, never