/* * Copyright (c) 2000, 2013, 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.transform; /** *

A TransformerFactory instance can be used to create * {@link javax.xml.transform.Transformer} and * {@link javax.xml.transform.Templates} objects.

* *

The system property that determines which Factory implementation * to create is named "javax.xml.transform.TransformerFactory". * This property names a concrete subclass of the * TransformerFactory abstract class. If the property is not * defined, a platform default is be used.

* * @author Jeff Suttor * @author Neeraj Bajaj * * @since 1.5 */ public abstract class TransformerFactory { /** * Default constructor is protected on purpose. */ protected TransformerFactory() { } /** *

Obtain a new instance of a TransformerFactory. * This static method creates a new factory instance.

*

This method uses the following ordered lookup procedure to determine * the TransformerFactory implementation class to * load:

* * *

Once an application has obtained a reference to a * TransformerFactory it can use the factory to configure * and obtain transformer instances.

* * @return new TransformerFactory instance, never null. * * @throws TransformerFactoryConfigurationError Thrown in case of {@linkplain * java.util.ServiceConfigurationError service configuration error} or if * the implementation is not available or cannot be instantiated. */ public static TransformerFactory newInstance() throws TransformerFactoryConfigurationError { return FactoryFinder.find( /* The default property name according to the JAXP spec */ TransformerFactory.class, /* The fallback implementation class name, XSLTC */ "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"); } /** *

Obtain a new instance of a TransformerFactory from factory 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.

* *

Once an application has obtained a reference to a * TransformerFactory it can use the factory to configure * and obtain transformer instances.

* *

Tip for Trouble-shooting

*

Setting the jaxp.debug system property will cause * this method to print a lot of debug messages * to System.err about what it is doing and where it is looking at.

* *

If you have problems try:

* 
     * java -Djaxp.debug=1 YourProgram ....
     *
* * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.transform.TransformerFactory. * * @param classLoader ClassLoader used to load the factory class. If null * current Thread's context classLoader is used to load the factory class. * * @return new TransformerFactory instance, never null. * * @throws TransformerFactoryConfigurationError * if factoryClassName is null, or * the factory class cannot be loaded, instantiated. * * @see #newInstance() * * @since 1.6 */ public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader) throws TransformerFactoryConfigurationError{ //do not fallback if given classloader can't find the class, throw exception return FactoryFinder.newInstance(TransformerFactory.class, factoryClassName, classLoader, false, false); } /** *

Process the Source into a Transformer * Object. The Source is an XSLT document that * conforms to * XSL Transformations (XSLT) Version 1.0. Care must * be taken not to use this Transformer in multiple * Threads running concurrently. * Different TransformerFactories can be used concurrently by * different Threads.

* * @param source Source of XSLT document used to create * Transformer. * Examples of XML Sources include * {@link javax.xml.transform.dom.DOMSource DOMSource}, * {@link javax.xml.transform.sax.SAXSource SAXSource}, and * {@link javax.xml.transform.stream.StreamSource StreamSource}. * * @return A Transformer object that may be used to perform * a transformation in a single Thread, never * null. * * @throws TransformerConfigurationException Thrown if there are errors when * parsing the Source or it is not possible to create a * Transformer instance. * * @see * XSL Transformations (XSLT) Version 1.0 */ public abstract Transformer newTransformer(Source source) throws TransformerConfigurationException; /** *

Create a new Transformer that performs a copy * of the Source to the Result. * i.e. the "identity transform".

* * @return A Transformer object that may be used to perform a transformation * in a single thread, never null. * * @throws TransformerConfigurationException When it is not * possible to create a Transformer instance. */ public abstract Transformer newTransformer() throws TransformerConfigurationException; /** * Process the Source into a Templates object, which is a * a compiled representation of the source. This Templates object * may then be used concurrently across multiple threads. Creating * a Templates object allows the TransformerFactory to do detailed * performance optimization of transformation instructions, without * penalizing runtime transformation. * * @param source An object that holds a URL, input stream, etc. * * @return A Templates object capable of being used for transformation * purposes, never null. * * @throws TransformerConfigurationException When parsing to * construct the Templates object fails. */ public abstract Templates newTemplates(Source source) throws TransformerConfigurationException; /** *

Get the stylesheet specification(s) associated with the * XML Source document via the * * xml-stylesheet processing instruction that match the given criteria. * Note that it is possible to return several stylesheets, in which case * they are applied as if they were a list of imports or cascades in a * single stylesheet.

* * @param source The XML source document. * @param media The media attribute to be matched. May be null, in which * case the prefered templates will be used (i.e. alternate = no). * @param title The value of the title attribute to match. May be null. * @param charset The value of the charset attribute to match. May be null. * * @return A Source Object suitable for passing * to the TransformerFactory. * * @throws TransformerConfigurationException An Exception * is thrown if an error occurings during parsing of the * source. * * @see * Associating Style Sheets with XML documents Version 1.0 */ public abstract Source getAssociatedStylesheet( Source source, String media, String title, String charset) throws TransformerConfigurationException; /** * Set an object that is used by default during the transformation * to resolve URIs used in document(), xsl:import, or xsl:include. * * @param resolver An object that implements the URIResolver interface, * or null. */ public abstract void setURIResolver(URIResolver resolver); /** * Get the object that is used by default during the transformation * to resolve URIs used in document(), xsl:import, or xsl:include. * * @return The URIResolver that was set with setURIResolver. */ public abstract URIResolver getURIResolver(); //======= CONFIGURATION METHODS ======= /** *

Set a feature for this TransformerFactory and Transformers * or Templates created by this factory.

* *

* Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * An {@link TransformerConfigurationException} is thrown if this TransformerFactory or the * Transformers or Templates it creates cannot support the feature. * It is possible for an TransformerFactory to expose a feature value but be unable to change its state. *

* *

All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * When the feature is:

* * * @param name Feature name. * @param value Is feature state true or false. * * @throws TransformerConfigurationException if this TransformerFactory * or the Transformers or Templates it creates cannot support this feature. * @throws NullPointerException If the name parameter is null. */ public abstract void setFeature(String name, boolean value) throws TransformerConfigurationException; /** * Look up the value of a feature. * *

* Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * false is returned if this TransformerFactory or the * Transformers or Templates it creates cannot support the feature. * It is possible for an TransformerFactory to expose a feature value but be unable to change its state. *

* * @param name Feature name. * * @return The current state of the feature, true or false. * * @throws NullPointerException If the name parameter is null. */ public abstract boolean getFeature(String name); /** * Allows the user to set specific attributes on the underlying * implementation. An attribute in this context is defined to * be an option that the implementation provides. * An IllegalArgumentException is thrown if the underlying * implementation doesn't recognize the attribute. *

* All implementations that implement JAXP 1.5 or newer are required to * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} properties. *

* * * @param name The name of the attribute. * @param value The value of the attribute. * * @throws IllegalArgumentException When implementation does not * recognize the attribute. */ public abstract void setAttribute(String name, Object value); /** * Allows the user to retrieve specific attributes on the underlying * implementation. * An IllegalArgumentException is thrown if the underlying * implementation doesn't recognize the attribute. * * @param name The name of the attribute. * * @return value The value of the attribute. * * @throws IllegalArgumentException When implementation does not * recognize the attribute. */ public abstract Object getAttribute(String name); /** * Set the error event listener for the TransformerFactory, which * is used for the processing of transformation instructions, * and not for the transformation itself. * An IllegalArgumentException is thrown if the * ErrorListener listener is null. * * @param listener The new error listener. * * @throws IllegalArgumentException When listener is * null */ public abstract void setErrorListener(ErrorListener listener); /** * Get the error event handler for the TransformerFactory. * * @return The current error handler, which should never be null. */ public abstract ErrorListener getErrorListener(); }