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