286N/A * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * An instance of this abstract class can transform a 286N/A * source tree into a result tree. 286N/A * <p>An instance of this class can be obtained with the 286N/A * {@link TransformerFactory#newTransformer TransformerFactory.newTransformer} 286N/A * method. This instance may then be used to process XML from a 286N/A * variety of sources and write the transformation output to a 286N/A * variety of sinks.</p> 286N/A * <p>An object of this class may not be used in multiple threads 286N/A * running concurrently. Different Transformers may be used 286N/A * concurrently by different threads.</p> 286N/A * <p>A <code>Transformer</code> may be used multiple times. Parameters and 286N/A * output properties are preserved across transformations.</p> 286N/A * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> 286N/A * Default constructor is protected on purpose. 286N/A * <p>Reset this <code>Transformer</code> to its original configuration.</p> 286N/A * <p><code>Transformer</code> is reset to the same state as when it was created with 286N/A * {@link TransformerFactory#newTransformer()}, 286N/A * {@link TransformerFactory#newTransformer(Source source)} or 286N/A * {@link Templates#newTransformer()}. 286N/A * <code>reset()</code> is designed to allow the reuse of existing <code>Transformer</code>s 286N/A * thus saving resources associated with the creation of new <code>Transformer</code>s.</p> 286N/A * <p>The reset <code>Transformer</code> is not guaranteed to have the same {@link URIResolver} 286N/A * or {@link ErrorListener} <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. 286N/A * It is guaranteed to have a functionally equal <code>URIResolver</code> 286N/A * and <code>ErrorListener</code>.</p> 286N/A * @throws UnsupportedOperationException When implementation does not 286N/A * override this method. 286N/A // implementors should override this method 286N/A "This Transformer, \"" +
this.
getClass().
getName() +
"\", does not support the reset functionality." 286N/A * <p>Transform the XML <code>Source</code> to a <code>Result</code>. 286N/A * Specific transformation behavior is determined by the settings of the 286N/A * <code>TransformerFactory</code> in effect when the 286N/A * <code>Transformer</code> was instantiated and any modifications made to 286N/A * the <code>Transformer</code> instance.</p> 286N/A * <p>An empty <code>Source</code> is represented as an empty document 286N/A * as constructed by {@link javax.xml.parsers.DocumentBuilder#newDocument()}. 286N/A * The result of transforming an empty <code>Source</code> depends on 286N/A * the transformation behavior; it is not always an empty 286N/A * <code>Result</code>.</p> 286N/A * @param xmlSource The XML input to transform. 286N/A * @param outputTarget The <code>Result</code> of transforming the 286N/A * <code>xmlSource</code>. 286N/A * @throws TransformerException If an unrecoverable error occurs 286N/A * during the course of the transformation. 286N/A * Add a parameter for the transformation. 286N/A * <p>Pass a qualified name as a two-part string, the namespace URI 286N/A * enclosed in curly braces ({}), followed by the local name. If the 286N/A * name has a null URL, the String only contain the local name. An 286N/A * application can safely check for a non-null URI by testing to see if the 286N/A * first character of the name is a '{' character.</p> 286N/A * <p>For example, if a URI and local name were obtained from an element 286N/A * defined with <xyz:foo 286N/A * Note that no prefix is used.</p> 286N/A * @param name The name of the parameter, which may begin with a 286N/A * namespace URI in curly braces ({}). 286N/A * @param value The value object. This can be any valid Java object. It is 286N/A * up to the processor to provide the proper object coersion or to simply 286N/A * pass the object on for use in an extension. 286N/A * @throws NullPointerException If value is null. 286N/A * Get a parameter that was explicitly set with setParameter. 286N/A * <p>This method does not return a default parameter value, which 286N/A * cannot be determined until the node context is evaluated during 286N/A * the transformation process. 286N/A * @param name of <code>Object</code> to get 286N/A * @return A parameter that has been set with setParameter. 286N/A * <p>Set a list of parameters.</p> 286N/A * <p>Note that the list of parameters is specified as a 286N/A * <code>Properties</code> <code>Object</code> which limits the parameter 286N/A * values to <code>String</code>s. Multiple calls to 286N/A * {@link #setParameter(String name, Object value)} should be used when the 286N/A * desired values are non-<code>String</code> <code>Object</code>s. 286N/A * The parameter names should conform as specified in 286N/A * {@link #setParameter(String name, Object value)}. 286N/A * An <code>IllegalArgumentException</code> is thrown if any names do not 286N/A * <p>New parameters in the list are added to any existing parameters. 286N/A * If the name of a new parameter is equal to the name of an existing 286N/A * parameter as determined by {@link java.lang.Object#equals(Object obj)}, 286N/A * the existing parameter is set to the new value.</p> 286N/A * @param params Parameters to set. 286N/A * @throws IllegalArgumentException If any parameter names do not conform 286N/A * Clear all parameters set with setParameter. 286N/A * Set an object that will be used to resolve URIs used in 286N/A * <p>If the resolver argument is null, the URIResolver value will 286N/A * be cleared and the transformer will no longer have a resolver.</p> 286N/A * @param resolver An object that implements the URIResolver interface, 286N/A * Get an object that will be used to resolve URIs used in 286N/A * @return An object that implements the URIResolver interface, 286N/A * Set the output properties for the transformation. These 286N/A * properties will override properties set in the Templates 286N/A * <p>If argument to this function is null, any properties 286N/A * previously set are removed, and the value will revert to the value 286N/A * defined in the templates object.</p> 286N/A * <p>Pass a qualified property key name as a two-part string, the namespace 286N/A * URI enclosed in curly braces ({}), followed by the local name. If the 286N/A * name has a null URL, the String only contain the local name. An 286N/A * application can safely check for a non-null URI by testing to see if the 286N/A * first character of the name is a '{' character.</p> 286N/A * <p>For example, if a URI and local name were obtained from an element 286N/A * defined with <xyz:foo 286N/A * Note that no prefix is used.</p> 286N/A * An <code>IllegalArgumentException</code> is thrown if any of the 286N/A * argument keys are not recognized and are not namespace qualified. 286N/A * @param oformat A set of output properties that will be 286N/A * used to override any of the same properties in affect 286N/A * for the transformation. 286N/A * @throws IllegalArgumentException When keys are not recognized and 286N/A * are not namespace qualified. 286N/A * <p>Get a copy of the output properties for the transformation.</p> 286N/A * <p>The properties returned should contain properties set by the user, 286N/A * and properties set by the stylesheet, and these properties 286N/A * are "defaulted" by default properties specified by 286N/A * XSL Transformations (XSLT) W3C Recommendation</a>. The properties that 286N/A * were specifically set by the user or the stylesheet should be in the base 286N/A * Properties list, while the XSLT default properties that were not 286N/A * specifically set should be the default Properties list. Thus, 286N/A * getOutputProperties().getProperty(String key) will obtain any 286N/A * property in that was set by {@link #setOutputProperty}, 286N/A * {@link #setOutputProperties}, in the stylesheet, <em>or</em> the default 286N/A * getOutputProperties().get(String key) will only retrieve properties 286N/A * that were explicitly set by {@link #setOutputProperty}, 286N/A * {@link #setOutputProperties}, or in the stylesheet.</p> 286N/A * <p>Note that mutation of the Properties object returned will not 286N/A * effect the properties that the transformer contains.</p> 286N/A * <p>If any of the argument keys are not recognized and are not 286N/A * namespace qualified, the property will be ignored and not returned. 286N/A * In other words the behaviour is not orthogonal with 286N/A * {@link #setOutputProperties setOutputProperties}.</p> 286N/A * @return A copy of the set of output properties in effect for 286N/A * the next transformation. 286N/A * XSL Transformations (XSLT) Version 1.0</a> 286N/A * Set an output property that will be in effect for the 286N/A * <p>Pass a qualified property name as a two-part string, the namespace URI 286N/A * enclosed in curly braces ({}), followed by the local name. If the 286N/A * name has a null URL, the String only contain the local name. An 286N/A * application can safely check for a non-null URI by testing to see if the 286N/A * first character of the name is a '{' character.</p> 286N/A * <p>For example, if a URI and local name were obtained from an element 286N/A * defined with <xyz:foo 286N/A * Note that no prefix is used.</p> 286N/A * <p>The Properties object that was passed to {@link #setOutputProperties} 286N/A * won't be effected by calling this method.</p> 286N/A * @param name A non-null String that specifies an output 286N/A * property name, which may be namespace qualified. 286N/A * @param value The non-null string value of the output property. 286N/A * @throws IllegalArgumentException If the property is not supported, and is 286N/A * not qualified with a namespace. 286N/A * <p>Get an output property that is in effect for the transformer.</p> 286N/A * <p>If a property has been set using {@link #setOutputProperty}, 286N/A * that value will be returned. Otherwise, if a property is explicitly 286N/A * specified in the stylesheet, that value will be returned. If 286N/A * the value of the property has been defaulted, that is, if no 286N/A * value has been set explicitly either with {@link #setOutputProperty} or 286N/A * in the stylesheet, the result may vary depending on 286N/A * implementation and input stylesheet.</p> 286N/A * @param name A non-null String that specifies an output 286N/A * property name, which may be namespace qualified. 286N/A * @return The string value of the output property, or null 286N/A * if no property was found. 286N/A * @throws IllegalArgumentException If the property is not supported. 286N/A * Set the error event listener in effect for the transformation. 286N/A * @param listener The new error listener. 286N/A * @throws IllegalArgumentException if listener is null. 286N/A * Get the error event handler in effect for the transformation. 286N/A * Implementations must provide a default error listener. 286N/A * @return The current error handler, which should never be null.