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