// $Id: TransformerFactory.java,v 1.14.14.1 2004/05/05 20:04:52 jsuttor Exp $ /* * @(#)TransformerFactory.java 1.36 04/07/26 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ 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.
Get current state of canonicalization.
* * @return current state canonicalization control */ /* public boolean getCanonicalization() { return canonicalState; } */ /** *Set canonicalization control to true
or
* false.
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:
* javax.xml.transform.TransformerFactory
system
* property.
* 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.
* META-INF/services/javax.xml.transform.TransformerFactory
* in jars available to the runtime.
* TransformerFactory
instance.
*
* 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, XSLTC */
"com.sun.org.apache.xalan.internal.xsltc.trax.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
* Thread
s running concurrently.
* Different TransformerFactories
can be used concurrently by
* different Thread
s.
Source
of XSLT document used to create
* Transformer
.
* Examples of XML Source
s 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 Transformer
s
* or Template
s 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
* Transformer
s or Template
s 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 Transformer
s or Template
s 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
* Transformer
s or Template
s 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();
}