javax.xml.transform.TransformerFactory Maven / Gradle / Ivy
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ // $Id: TransformerFactory.java 446598 2006-09-15 12:55:40Z jeremias $ package javax.xml.transform; /** *false. * * @param state of canonicalization */ /* public void setCanonicalization(boolean state) { canonicalState = state; } */ /** * Obtain a new instance of aA 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
* * @author Jeff Suttor */ public abstract class TransformerFactory { /** * Default constructor is protected on purpose. */ protected TransformerFactory() { } /** *"javax.xml.transform.TransformerFactory". * This property names a concrete subclass of the *TransformerFactoryabstract class. If the property is not * defined, a platform default is be used.Get current state of canonicalization.
* * @return current state canonicalization control */ /* public boolean getCanonicalization() { return canonicalState; } */ /** *Set canonicalization control to
trueor *TransformerFactory. * This static method creates a new factory instance * This method uses the following ordered lookup procedure to determine * theTransformerFactoryimplementation class to * load: *
-
*
-
* Use the
javax.xml.transform.TransformerFactorysystem * property. *
* -
* Use the properties file "lib/jaxp.properties" in the JRE directory.
* This configuration file is in standard
java.util.Properties *format and contains the fully qualified name of the * implementation class with the key being the system property defined * above. * * The jaxp.properties file is read only once by the JAXP implementation * and it's 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. *
* -
* Use the Services API (as detailed in the JAR specification), if
* available, to determine the classname. The Services API will look
* for a classname in the file
*
META-INF/services/javax.xml.transform.TransformerFactory* in jars available to the runtime. *
* -
* Platform default
TransformerFactoryinstance. *
*
* TransformerFactory it can use the factory to configure
* and obtain parser instances.
*
* @return new TransformerFactory instance, never null.
*
* @throws TransformerFactoryConfigurationError Thrown if the implementation
* is not available or cannot be instantiated.
*/
public static TransformerFactory newInstance()
throws TransformerFactoryConfigurationError {
try {
return (TransformerFactory) FactoryFinder.find(
/* The default property name according to the JAXP spec */
"javax.xml.transform.TransformerFactory",
/* The fallback implementation class name */
"org.apache.xalan.processor.TransformerFactoryImpl");
} catch (FactoryFinder.ConfigurationError e) {
throw new TransformerFactoryConfigurationError(
e.getException(),
e.getMessage());
}
}
/**
* 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.
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".
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.
*
* @exception TransformerConfigurationException May throw this during the
* parse when it is constructing the Templates object and 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.
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:
*-
*
-
*
true: the implementation will limit XML processing to conform to implementation limits * and behave in a secure fashion as defined by the implementation. * Examples include resolving user defined style sheets and functions. * If XML processing is limited for security reasons, it will be reported via a call to the registered * {@link ErrorListener#fatalError(TransformerException exception)}. * See {@link #setErrorListener(ErrorListener listener)}. *
* -
*
false: the implementation will processing XML according to the XML specifications without * regard to possible implementation limits. *
*
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.
*
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.
*
* @param name The name of the attribute.
* @param value The value of 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.
*/
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.
*/
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();
}