/*
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the "License").  You may not use this file except
 * in compliance with the License.
 *
 * You can obtain a copy of the license at
 * https://jaxp.dev.java.net/CDDLv1.0.html.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * HEADER in each file and include the License file at
 * https://jaxp.dev.java.net/CDDLv1.0.html
 * If applicable add the following below this CDDL HEADER
 * with the fields enclosed by brackets "[]" replaced with
 * your own identifying information: Portions Copyright
 * [year] [name of copyright owner]
 */

/*
 * $Id: XMLEntityReader.java,v 1.3 2005/11/03 17:02:21 jeffsuttor Exp $
 * @(#)Transformer.java	1.34 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
 */

package javax.xml.transform;

import java.util.Properties;

/**
 * An instance of this abstract class can transform a
 * source tree into a result tree.
 *
 * <p>An instance of this class can be obtained with the
 * {@link TransformerFactory#newTransformer TransformerFactory.newTransformer}
 * method. This instance may then be used to process XML from a
 * variety of sources and write the transformation output to a
 * variety of sinks.</p>
 *
 * <p>An object of this class may not be used in multiple threads
 * running concurrently.  Different Transformers may be used
 * concurrently by different threads.</p>
 *
 * <p>A <code>Transformer</code> may be used multiple times.  Parameters and
 * output properties are preserved across transformations.</p>
 * 
 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
 * @version $Revision: 1.3 $, $Date: 2005/10/12 17:14:20 $
 */
public abstract class Transformer {

    /**
     * Default constructor is protected on purpose.
     */
    protected Transformer() { }
    
	/**
	 * <p>Reset this <code>Transformer</code> to its original configuration.</p>
	 * 
	 * <p><code>Transformer</code> is reset to the same state as when it was created with
	 * {@link TransformerFactory#newTransformer()},
	 * {@link TransformerFactory#newTransformer(Source source)} or
	 * {@link Templates#newTransformer()}.
	 * <code>reset()</code> is designed to allow the reuse of existing <code>Transformer</code>s
	 * thus saving resources associated with the creation of new <code>Transformer</code>s.</p>
	 * 
	 * <p>The reset <code>Transformer</code> is not guaranteed to have the same {@link URIResolver}
	 * or {@link ErrorListener} <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.
	 * It is guaranteed to have a functionally equal <code>URIResolver</code>
	 * and <code>ErrorListener</code>.</p>
     * 
     * @throws UnsupportedOperationException When implementation does not
     *   override this method.
	 * 
	 * @since 1.5
	 */
	public void reset() {

		// implementors should override this method
		throw new UnsupportedOperationException(
			"This Transformer, \"" + this.getClass().getName() + "\", does not support the reset functionality."
			+ "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
			+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
			);
	}

    /**
     * <p>Transform the XML <code>Source</code> to a <code>Result</code>.
     * Specific transformation behavior is determined by the settings of the
     * <code>TransformerFactory</code> in effect when the
     * <code>Transformer</code> was instantiated and any modifications made to
     * the <code>Transformer</code> instance.</p>
     *
     * <p>An empty <code>Source</code> is represented as an empty document
     * as constructed by {@link javax.xml.parsers.DocumentBuilder#newDocument()}.
     * The result of transforming an empty <code>Source</code> depends on
     * the transformation behavior; it is not always an empty
     * <code>Result</code>.</p>