Source Home >> Java Source 1.6.0 >> javax.xml.transform.Transformer V 0.09

001/*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License").  You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * https://jaxp.dev.java.net/CDDLv1.0.html.
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 *
012 * When distributing Covered Code, include this CDDL
013 * HEADER in each file and include the License file at
014 * https://jaxp.dev.java.net/CDDLv1.0.html
015 * If applicable add the following below this CDDL HEADER
016 * with the fields enclosed by brackets "[]" replaced with
017 * your own identifying information: Portions Copyright
018 * [year] [name of copyright owner]
019 */
020
021/*
022 * $Id: XMLEntityReader.java,v 1.3 2005/11/03 17:02:21 jeffsuttor Exp $
023 * @(#)Transformer.java	1.34 05/11/17
024 *
025 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
026 */
027
028package javax.xml.transform;
029
030import java.util.Properties;
031
032/**
033 * An instance of this abstract class can transform a
034 * source tree into a result tree.
035 *
036 * <p>An instance of this class can be obtained with the
037 * {@link TransformerFactory#newTransformer TransformerFactory.newTransformer}
038 * method. This instance may then be used to process XML from a
039 * variety of sources and write the transformation output to a
040 * variety of sinks.</p>
041 *
042 * <p>An object of this class may not be used in multiple threads
043 * running concurrently.  Different Transformers may be used
044 * concurrently by different threads.</p>
045 *
046 * <p>A <code>Transformer</code> may be used multiple times.  Parameters and
047 * output properties are preserved across transformations.</p>
048 * 
049 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
050 * @version $Revision: 1.3 $, $Date: 2005/10/12 17:14:20 $
051 */
052public abstract class Transformer {
053
054    /**
055     * Default constructor is protected on purpose.
056     */
057    protected Transformer() { }
058    
059	/**
060	 * <p>Reset this <code>Transformer</code> to its original configuration.</p>
061	 * 
062	 * <p><code>Transformer</code> is reset to the same state as when it was created with
063	 * {@link TransformerFactory#newTransformer()},
064	 * {@link TransformerFactory#newTransformer(Source source)} or
065	 * {@link Templates#newTransformer()}.
066	 * <code>reset()</code> is designed to allow the reuse of existing <code>Transformer</code>s
067	 * thus saving resources associated with the creation of new <code>Transformer</code>s.</p>
068	 * 
069	 * <p>The reset <code>Transformer</code> is not guaranteed to have the same {@link URIResolver}
070	 * or {@link ErrorListener} <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.
071	 * It is guaranteed to have a functionally equal <code>URIResolver</code>
072	 * and <code>ErrorListener</code>.</p>
073     * 
074     * @throws UnsupportedOperationException When implementation does not
075     *   override this method.
076	 * 
077	 * @since 1.5
078	 */
079	public void reset() {
080
081		// implementors should override this method
082		throw new UnsupportedOperationException(
083			"This Transformer, \"" + this.getClass().getName() + "\", does not support the reset functionality."
084			+ "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
085			+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
086			);
087	}
088
089    /**
090     * <p>Transform the XML <code>Source</code> to a <code>Result</code>.
091     * Specific transformation behavior is determined by the settings of the
092     * <code>TransformerFactory</code> in effect when the
093     * <code>Transformer</code> was instantiated and any modifications made to
094     * the <code>Transformer</code> instance.</p>
095     *
096     * <p>An empty <code>Source</code> is represented as an empty document
097     * as constructed by {@link javax.xml.parsers.DocumentBuilder#newDocument()}.
098     * The result of transforming an empty <code>Source</code> depends on
099     * the transformation behavior; it is not always an empty
100     * <code>Result</code>.</p>
101     *
102     * @param xmlSource The XML input to transform.
103     * @param outputTarget The <code>Result</code> of transforming the
104     *   <code>xmlSource</code>.
105     *
106     * @throws TransformerException If an unrecoverable error occurs
107     *   during the course of the transformation.
108     */
109    public abstract void transform(Source xmlSource, Result outputTarget)
110        throws TransformerException;
111
112    /**
113     * Add a parameter for the transformation.
114     *
115     * <p>Pass a qualified name as a two-part string, the namespace URI
116     * enclosed in curly braces ({}), followed by the local name. If the
117     * name has a null URL, the String only contain the local name. An
118     * application can safely check for a non-null URI by testing to see if the
119     * first character of the name is a '{' character.</p>
120     * <p>For example, if a URI and local name were obtained from an element
121     * defined with <xyz:foo
122     * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
123     * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
124     * Note that no prefix is used.</p>
125     *
126     * @param name The name of the parameter, which may begin with a
127     * namespace URI in curly braces ({}).
128     * @param value The value object.  This can be any valid Java object. It is
129     * up to the processor to provide the proper object coersion or to simply
130     * pass the object on for use in an extension.
131     *
132     * @throws NullPointerException If value is null.
133     */
134     public abstract void setParameter(String name, Object value);
135
136    /**
137     * Get a parameter that was explicitly set with setParameter.
138     *
139     * <p>This method does not return a default parameter value, which
140     * cannot be determined until the node context is evaluated during
141     * the transformation process.
142     *
143     * @param name of <code>Object</code> to get
144     *
145     * @return A parameter that has been set with setParameter.
146     */
147    public abstract Object getParameter(String name);
148    
149    /**
150     * <p>Set a list of parameters.</p>
151     * 
152     * <p>Note that the list of parameters is specified as a
153     * <code>Properties</code> <code>Object</code> which limits the parameter
154     * values to <code>String</code>s.  Multiple calls to
155     * {@link #setParameter(String name, Object value)} should be used when the
156     * desired values are non-<code>String</code> <code>Object</code>s.
157     * The parameter names should conform as specified in
158     * {@link #setParameter(String name, Object value)}.
159     * An <code>IllegalArgumentException</code> is thrown if any names do not
160     * conform.</p>
161     * 
162     * <p>New parameters in the list are added to any existing parameters.
163     * If the name of a new parameter is equal to the name of an existing
164     * parameter as determined by {@link java.lang.Object#equals(Object obj)},
165     *  the existing parameter is set to the new value.</p>
166     * 
167     * @param params Parameters to set.
168     * 
169     * @throws IllegalArgumentException If any parameter names do not conform
170     *   to the naming rules.
171     */
172
173    /**
174     * Clear all parameters set with setParameter.
175     */
176    public abstract void clearParameters();
177
178    /**
179     * Set an object that will be used to resolve URIs used in
180     * document().
181     *
182     * <p>If the resolver argument is null, the URIResolver value will
183     * be cleared and the transformer will no longer have a resolver.</p>
184     *
185     * @param resolver An object that implements the URIResolver interface,
186     * or null.
187     */
188    public abstract void setURIResolver(URIResolver resolver);
189
190    /**
191     * Get an object that will be used to resolve URIs used in
192     * document().
193     *
194     * @return An object that implements the URIResolver interface,
195     * or null.
196     */
197    public abstract URIResolver getURIResolver();
198
199    /**
200     * Set the output properties for the transformation.  These
201     * properties will override properties set in the Templates
202     * with xsl:output.
203     *
204     * <p>If argument to this function is null, any properties
205     * previously set are removed, and the value will revert to the value
206     * defined in the templates object.</p>
207     *
208     * <p>Pass a qualified property key name as a two-part string, the namespace
209     * URI enclosed in curly braces ({}), followed by the local name. If the
210     * name has a null URL, the String only contain the local name. An
211     * application can safely check for a non-null URI by testing to see if the
212     * first character of the name is a '{' character.</p>
213     * <p>For example, if a URI and local name were obtained from an element
214     * defined with <xyz:foo
215     * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
216     * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
217     * Note that no prefix is used.</p>
218     * An <code>IllegalArgumentException</code> is thrown  if any of the
219     * argument keys are not recognized and are not namespace qualified.
220     *
221     * @param oformat A set of output properties that will be
222     *   used to override any of the same properties in affect
223     *   for the transformation.
224     *
225     * @throws IllegalArgumentException When keys are not recognized and
226     *   are not namespace qualified.
227     *
228     * @see javax.xml.transform.OutputKeys
229     * @see java.util.Properties
230     *
231     */
232    public abstract void setOutputProperties(Properties oformat);
233
234    /**
235     * <p>Get a copy of the output properties for the transformation.</p>
236     *
237     * <p>The properties returned should contain properties set by the user,
238     * and properties set by the stylesheet, and these properties
239     * are "defaulted" by default properties specified by
240     * <a href="http://www.w3.org/TR/xslt#output">section 16 of the
241     * XSL Transformations (XSLT) W3C Recommendation</a>.  The properties that
242     * were specifically set by the user or the stylesheet should be in the base
243     * Properties list, while the XSLT default properties that were not
244     * specifically set should be the default Properties list.  Thus,
245     * getOutputProperties().getProperty(String key) will obtain any
246     * property in that was set by {@link #setOutputProperty},
247     * {@link #setOutputProperties}, in the stylesheet, <em>or</em> the default
248     * properties, while
249     * getOutputProperties().get(String key) will only retrieve properties
250     * that were explicitly set by {@link #setOutputProperty},
251     * {@link #setOutputProperties}, or in the stylesheet.</p>
252     *
253     * <p>Note that mutation of the Properties object returned will not
254     * effect the properties that the transformer contains.</p>
255     *
256     * <p>If any of the argument keys are not recognized and are not
257     * namespace qualified, the property will be ignored and not returned.
258     * In other words the behaviour is not orthogonal with
259     * {@link #setOutputProperties setOutputProperties}.</p>
260     *
261     * @return A copy of the set of output properties in effect for
262     *   the next transformation.
263     *
264     * @see javax.xml.transform.OutputKeys
265     * @see java.util.Properties
266     * @see <a href="http://www.w3.org/TR/xslt#output">
267     *   XSL Transformations (XSLT) Version 1.0</a>
268     */
269    public abstract Properties getOutputProperties();
270
271    /**
272     * Set an output property that will be in effect for the
273     * transformation.
274     *
275     * <p>Pass a qualified property name as a two-part string, the namespace URI
276     * enclosed in curly braces ({}), followed by the local name. If the
277     * name has a null URL, the String only contain the local name. An
278     * application can safely check for a non-null URI by testing to see if the
279     * first character of the name is a '{' character.</p>
280     * <p>For example, if a URI and local name were obtained from an element
281     * defined with <xyz:foo
282     * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
283     * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
284     * Note that no prefix is used.</p>
285     *
286     * <p>The Properties object that was passed to {@link #setOutputProperties}
287     * won't be effected by calling this method.</p>
288     *
289     * @param name A non-null String that specifies an output
290     * property name, which may be namespace qualified.
291     * @param value The non-null string value of the output property.
292     *
293     * @throws IllegalArgumentException If the property is not supported, and is
294     * not qualified with a namespace.
295     *
296     * @see javax.xml.transform.OutputKeys
297     */
298    public abstract void setOutputProperty(String name, String value)
299        throws IllegalArgumentException;
300
301    /**
302     * <p>Get an output property that is in effect for the transformer.</p>
303     *
304     * <p>If a property has been set using {@link #setOutputProperty},
305     * that value will be returned. Otherwise, if a property is explicitly
306     * specified in the stylesheet, that value will be returned. If
307     * the value of the property has been defaulted, that is, if no
308     * value has been set explicitly either with {@link #setOutputProperty} or
309     * in the stylesheet, the result may vary depending on
310     * implementation and input stylesheet.</p>
311     *
312     * @param name A non-null String that specifies an output
313     * property name, which may be namespace qualified.
314     *
315     * @return The string value of the output property, or null
316     * if no property was found.
317     *
318     * @throws IllegalArgumentException If the property is not supported.
319     *
320     * @see javax.xml.transform.OutputKeys
321     */
322    public abstract String getOutputProperty(String name)
323        throws IllegalArgumentException;
324
325    /**
326     * Set the error event listener in effect for the transformation.
327     *
328     * @param listener The new error listener.
329     *
330     * @throws IllegalArgumentException if listener is null.
331     */
332    public abstract void setErrorListener(ErrorListener listener)
333        throws IllegalArgumentException;
334
335    /**
336     * Get the error event handler in effect for the transformation.
337     * Implementations must provide a default error listener.
338     *
339     * @return The current error handler, which should never be null.
340     */
341    public abstract ErrorListener getErrorListener();
342}