Transformer


1   // $Id: Transformer.java,v 1.9.14.1.2.4 2004/06/28 18:45:41 ndw Exp $
2   
3   /*
4    * @(#)Transformer.java 1.25 04/07/26
5    * 
6    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
7    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
8    */
9   
10  package javax.xml.transform;
11  
12  import java.util.Properties  ;
13  
14  /**
15   * An instance of this abstract class can transform a
16   * source tree into a result tree.
17   *
18   * <p>An instance of this class can be obtained with the
19   * {@link TransformerFactory#newTransformer TransformerFactory.newTransformer}
20   * method. This instance may then be used to process XML from a
21   * variety of sources and write the transformation output to a
22   * variety of sinks.</p>
23   *
24   * <p>An object of this class may not be used in multiple threads
25   * running concurrently.  Different Transformers may be used
26   * concurrently by different threads.</p>
27   *
28   * <p>A <code>Transformer</code> may be used multiple times.  Parameters and
29   * output properties are preserved across transformations.</p>
30   * 
31   * @author <a HREF="Jeff.Suttor@Sun.com">Jeff Suttor</a>
32   * @version $Revision: 1.9.14.1.2.4 $, $Date: 2004/06/28 18:45:41 $
33   */
34  public abstract class Transformer {
35  
36      /**
37       * Default constructor is protected on purpose.
38       */
39      protected Transformer() { }
40      
41      /**
42       * <p>Reset this <code>Transformer</code> to its original configuration.</p>
43       * 
44       * <p><code>Transformer</code> is reset to the same state as when it was created with
45       * {@link TransformerFactory#newTransformer()},
46       * {@link TransformerFactory#newTransformer(Source source)} or
47       * {@link Templates#newTransformer()}.
48       * <code>reset()</code> is designed to allow the reuse of existing <code>Transformer</code>s
49       * thus saving resources associated with the creation of new <code>Transformer</code>s.</p>
50       * 
51       * <p>The reset <code>Transformer</code> is not guaranteed to have the same {@link URIResolver}
52       * or {@link ErrorListener} <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.
53       * It is guaranteed to have a functionally equal <code>URIResolver</code>
54       * and <code>ErrorListener</code>.</p>
55       * 
56       * @since 1.5
57       */
58      public void reset() {
59  
60          // implementors should override this method
61          throw new UnsupportedOperationException  (
62              "This Transformer, \"" + this.getClass().getName() + "\", does not support the reset functionality."
63              + "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
64              + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
65              );
66      }
67  
68      /**
69       * <p>Transform the XML <code>Source</code> to a <code>Result</code>.
70       * Specific transformation behavior is determined by the settings of the
71       * <code>TransformerFactory</code> in effect when the
72       * <code>Transformer</code> was instantiated and any modifications made to
73       * the <code>Transformer</code> instance.</p>
74       *
75       * <p>An empty <code>Source</code> is represented as an empty document
76       * as constructed by {@link javax.xml.parsers.DocumentBuilder#newDocument()}.
77       * The result of transforming an empty <code>Source</code> depends on
78       * the transformation behavior; it is not always an empty
79       * <code>Result</code>.</p>
80       *
81       * @param xmlSource The XML input to transform.
82       * @param outputTarget The <code>Result</code> of transforming the
83       *   <code>xmlSource</code>.
84       *
85       * @throws TransformerException If an unrecoverable error occurs
86       *   during the course of the transformation.
87       */
88      public abstract void transform(Source   xmlSource, Result   outputTarget)
89          throws TransformerException  ;
90  
91      /**
92       * Add a parameter for the transformation.
93       *
94       * <p>Pass a qualified name as a two-part string, the namespace URI
95       * enclosed in curly braces ({}), followed by the local name. If the
96       * name has a null URL, the String only contain the local name. An
97       * application can safely check for a non-null URI by testing to see if the
98       * first character of the name is a '{' character.</p>
99       * <p>For example, if a URI and local name were obtained from an element
100      * defined with &lt;xyz:foo
101      * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
102      * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
103      * Note that no prefix is used.</p>
104      *
105      * @param name The name of the parameter, which may begin with a
106      * namespace URI in curly braces ({}).
107      * @param value The value object.  This can be any valid Java object. It is
108      * up to the processor to provide the proper object coersion or to simply
109      * pass the object on for use in an extension.
110      *
111      * @throws NullPointerException If value is null.
112      */
113      public abstract void setParameter(String   name, Object   value);
114 
115     /**
116      * Get a parameter that was explicitly set with setParameter.
117      *
118      * <p>This method does not return a default parameter value, which
119      * cannot be determined until the node context is evaluated during
120      * the transformation process.
121      *
122      * @param name of <code>Object</code> to get
123      * @return A parameter that has been set with setParameter.
124      */
125     public abstract Object   getParameter(String   name);
126     
127     /**
128      * <p>Set a list of parameters.</p>
129      * 
130      * <p>Note that the list of parameters is specified as a
131      * <code>Properties</code> <code>Object</code> which limits the parameter
132      * values to <code>String</code>s.  Multiple calls to
133      * {@link #setParameter(String name, Object value)} should be used when the
134      * desired values are non-<code>String</code> <code>Object</code>s.
135      * The parameter names should conform as specified in
136      * {@link #setParameter(String name, Object value)}.
137      * An <code>IllegalArgumentException</code> is thrown if any names do not
138      * conform.</p>
139      * 
140      * <p>New parameters in the list are added to any existing parameters.
141      * If the name of a new parameter is equal to the name of an existing
142      * parameter as determined by {@link java.lang.Object#equals(Object obj)},
143      *  the existing parameter is set to the new value.</p>
144      * 
145      * @param params Parameters to set.
146      * 
147      * @throws IllegalArgumentException If any parameter names do not conform
148      *   to the naming rules.
149      */
150 
151     /**
152      * Clear all parameters set with setParameter.
153      */
154     public abstract void clearParameters();
155 
156     /**
157      * Set an object that will be used to resolve URIs used in
158      * document().
159      *
160      * <p>If the resolver argument is null, the URIResolver value will
161      * be cleared and the transformer will no longer have a resolver.</p>
162      *
163      * @param resolver An object that implements the URIResolver interface,
164      * or null.
165      */
166     public abstract void setURIResolver(URIResolver   resolver);
167 
168     /**
169      * Get an object that will be used to resolve URIs used in
170      * document().
171      *
172      * @return An object that implements the URIResolver interface,
173      * or null.
174      */
175     public abstract URIResolver   getURIResolver();
176 
177     /**
178      * Set the output properties for the transformation.  These
179      * properties will override properties set in the Templates
180      * with xsl:output.
181      *
182      * <p>If argument to this function is null, any properties
183      * previously set are removed, and the value will revert to the value
184      * defined in the templates object.</p>
185      *
186      * <p>Pass a qualified property key name as a two-part string, the namespace
187      * URI enclosed in curly braces ({}), followed by the local name. If the
188      * name has a null URL, the String only contain the local name. An
189      * application can safely check for a non-null URI by testing to see if the
190      * first character of the name is a '{' character.</p>
191      * <p>For example, if a URI and local name were obtained from an element
192      * defined with &lt;xyz:foo
193      * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
194      * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
195      * Note that no prefix is used.</p>
196      * An <code>IllegalArgumentException</code> is thrown  if any of the
197      * argument keys are not recognized and are not namespace qualified.
198      *
199      * @param oformat A set of output properties that will be
200      * used to override any of the same properties in affect
201      * for the transformation.
202      *
203      * @see javax.xml.transform.OutputKeys
204      * @see java.util.Properties
205      *
206      */
207     public abstract void setOutputProperties(Properties   oformat);
208 
209     /**
210      * <p>Get a copy of the output properties for the transformation.</p>
211      *
212      * <p>The properties returned should contain properties set by the user,
213      * and properties set by the stylesheet, and these properties
214      * are "defaulted" by default properties specified by
215      * <a HREF="http://www.w3.org/TR/xslt#output">section 16 of the
216      * XSL Transformations (XSLT) W3C Recommendation</a>.  The properties that
217      * were specifically set by the user or the stylesheet should be in the base
218      * Properties list, while the XSLT default properties that were not
219      * specifically set should be the default Properties list.  Thus,
220      * getOutputProperties().getProperty(String key) will obtain any
221      * property in that was set by {@link #setOutputProperty},
222      * {@link #setOutputProperties}, in the stylesheet, <em>or</em> the default
223      * properties, while
224      * getOutputProperties().get(String key) will only retrieve properties
225      * that were explicitly set by {@link #setOutputProperty},
226      * {@link #setOutputProperties}, or in the stylesheet.</p>
227      *
228      * <p>Note that mutation of the Properties object returned will not
229      * effect the properties that the transformer contains.</p>
230      *
231      * <p>If any of the argument keys are not recognized and are not
232      * namespace qualified, the property will be ignored and not returned.
233      * In other words the behaviour is not orthogonal with
234      * {@link #setOutputProperties setOutputProperties}.</p>
235      *
236      * @return A copy of the set of output properties in effect for
237      *   the next transformation.
238      *
239      * @see javax.xml.transform.OutputKeys
240      * @see java.util.Properties
241      * @see <a HREF="http://www.w3.org/TR/xslt#output">
242      *   XSL Transformations (XSLT) Version 1.0</a>
243      */
244     public abstract Properties   getOutputProperties();
245 
246     /**
247      * Set an output property that will be in effect for the
248      * transformation.
249      *
250      * <p>Pass a qualified property name as a two-part string, the namespace URI
251      * enclosed in curly braces ({}), followed by the local name. If the
252      * name has a null URL, the String only contain the local name. An
253      * application can safely check for a non-null URI by testing to see if the
254      * first character of the name is a '{' character.</p>
255      * <p>For example, if a URI and local name were obtained from an element
256      * defined with &lt;xyz:foo
257      * xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
258      * then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo".
259      * Note that no prefix is used.</p>
260      *
261      * <p>The Properties object that was passed to {@link #setOutputProperties}
262      * won't be effected by calling this method.</p>
263      *
264      * @param name A non-null String that specifies an output
265      * property name, which may be namespace qualified.
266      * @param value The non-null string value of the output property.
267      *
268      * @throws IllegalArgumentException If the property is not supported, and is
269      * not qualified with a namespace.
270      *
271      * @see javax.xml.transform.OutputKeys
272      */
273     public abstract void setOutputProperty(String   name, String   value)
274         throws IllegalArgumentException  ;
275 
276     /**
277      * Get an output property that is in effect for the
278      * transformer.  The property specified may be a property
279      * that was set with setOutputProperty, or it may be a
280      * property specified in the stylesheet.
281      *
282      * @param name A non-null String that specifies an output
283      * property name, which may be namespace qualified.
284      *
285      * @return The string value of the output property, or null
286      * if no property was found.
287      *
288      * @throws IllegalArgumentException If the property is not supported.
289      *
290      * @see javax.xml.transform.OutputKeys
291      */
292     public abstract String   getOutputProperty(String   name)
293         throws IllegalArgumentException  ;
294 
295     /**
296      * Set the error event listener in effect for the transformation.
297      *
298      * @param listener The new error listener.
299      * @throws IllegalArgumentException if listener is null.
300      */
301     public abstract void setErrorListener(ErrorListener   listener)
302         throws IllegalArgumentException  ;
303 
304     /**
305      * Get the error event handler in effect for the transformation.
306      * Implementations must provide a default error listener.
307      *
308      * @return The current error handler, which should never be null.
309      */
310     public abstract ErrorListener   getErrorListener();
311 }
312
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags