1 /* 2 * Copyright (c) 2000, 2017, 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 com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl; 29 30 /** 31 * <p>A TransformerFactory instance can be used to create 32 * {@link javax.xml.transform.Transformer} and 33 * {@link javax.xml.transform.Templates} objects. 34 * 35 * <p>The system property that determines which Factory implementation 36 * to create is named {@code "javax.xml.transform.TransformerFactory"}. 37 * This property names a concrete subclass of the 38 * {@code TransformerFactory} abstract class. If the property is not 39 * defined, a platform default is be used. 40 * 41 * @author Jeff Suttor 42 * @author Neeraj Bajaj 43 * 44 * @since 1.5 45 */ 46 public abstract class TransformerFactory { 47 48 /** 49 * Default constructor is protected on purpose. 50 */ 51 protected TransformerFactory() { } 52 53 54 55 /** 56 * Creates a new instance of the {@code TransformerFactory} builtin 57 * system-default implementation. 58 * 59 * @return A new instance of the {@code TransformerFactory} builtin 60 * system-default implementation. 61 * 62 * @since 9 63 */ 64 public static TransformerFactory newDefaultInstance() { 65 return new TransformerFactoryImpl(); 66 } 67 68 /** 69 * Obtain a new instance of a {@code TransformerFactory}. 70 * This static method creates a new factory instance. 71 * <p> 72 * This method uses the following ordered lookup procedure to determine 73 * the {@code TransformerFactory} implementation class to load: 74 * <ul> 75 * <li> 76 * Use the {@code javax.xml.transform.TransformerFactory} system 77 * property. 78 * </li> 79 * <li> 80 * <p> 81 * Use the configuration file "jaxp.properties". The file is in standard 82 * {@link java.util.Properties} format and typically located in the 83 * {@code conf} directory of the Java installation. It contains the fully qualified 84 * name of the implementation class with the key being the system property 85 * defined above. 86 * <p> 87 * The jaxp.properties file is read only once by the JAXP implementation 88 * and its values are then cached for future use. If the file does not exist 89 * when the first attempt is made to read from it, no further attempts are 90 * made to check for its existence. It is not possible to change the value 91 * of any property in jaxp.properties after it has been read for the first time. 92 * </li> 93 * <li> 94 * <p> 95 * Use the service-provider loading facility, defined by the 96 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 97 * implementation of the service using the {@linkplain 98 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: 99 * the service-provider loading facility will use the {@linkplain 100 * java.lang.Thread#getContextClassLoader() current thread's context class loader} 101 * to attempt to load the service. If the context class 102 * loader is null, the {@linkplain 103 * ClassLoader#getSystemClassLoader() system class loader} will be used. 104 * </li> 105 * <li> 106 * <p> 107 * Otherwise, the {@linkplain #newDefaultInstance() system-default} 108 * implementation is returned. 109 * </li> 110 * </ul> 111 * 112 * <p> 113 * Once an application has obtained a reference to a 114 * {@code TransformerFactory} it can use the factory to configure 115 * and obtain transformer instances. 116 * 117 * @return new TransformerFactory instance, never null. 118 * 119 * @throws TransformerFactoryConfigurationError Thrown in case of {@linkplain 120 * java.util.ServiceConfigurationError service configuration error} or if 121 * the implementation is not available or cannot be instantiated. 122 */ 123 public static TransformerFactory newInstance() 124 throws TransformerFactoryConfigurationError { 125 126 return FactoryFinder.find( 127 /* The default property name according to the JAXP spec */ 128 TransformerFactory.class, 129 /* The fallback implementation class name, XSLTC */ 130 "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"); 131 } 132 133 /** 134 * Obtain a new instance of a {@code TransformerFactory} from factory class name. 135 * This function is useful when there are multiple providers in the classpath. 136 * It gives more control to the application as it can specify which provider 137 * should be loaded. 138 * 139 * <p>Once an application has obtained a reference to a 140 * {@code TransformerFactory} it can use the factory to configure 141 * and obtain transformer instances. 142 * 143 * <h2>Tip for Trouble-shooting</h2> 144 * <p>Setting the {@code jaxp.debug} system property will cause 145 * this method to print a lot of debug messages 146 * to {@code System.err} about what it is doing and where it is looking at. 147 * 148 * <p> If you have problems try: 149 * <pre> 150 * java -Djaxp.debug=1 YourProgram .... 151 * </pre> 152 * 153 * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.transform.TransformerFactory}. 154 * 155 * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null} 156 * current {@code Thread}'s context classLoader is used to load the factory class. 157 * 158 * @return new TransformerFactory instance, never null. 159 * 160 * @throws TransformerFactoryConfigurationError 161 * if {@code factoryClassName} is {@code null}, or 162 * the factory class cannot be loaded, instantiated. 163 * 164 * @see #newInstance() 165 * 166 * @since 1.6 167 */ 168 public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader) 169 throws TransformerFactoryConfigurationError{ 170 171 //do not fallback if given classloader can't find the class, throw exception 172 return FactoryFinder.newInstance(TransformerFactory.class, 173 factoryClassName, classLoader, false); 174 } 175 /** 176 * Process the {@code Source} into a {@code Transformer} 177 * {@code Object}. The {@code Source} is an XSLT document that 178 * conforms to <a href="http://www.w3.org/TR/xslt"> 179 * XSL Transformations (XSLT) Version 1.0</a>. Care must 180 * be taken not to use this {@code Transformer} in multiple 181 * {@code Thread}s running concurrently. 182 * Different {@code TransformerFactories} can be used concurrently by 183 * different {@code Thread}s. 184 * 185 * @param source {@code Source } of XSLT document used to create 186 * {@code Transformer}. 187 * Examples of XML {@code Source}s include 188 * {@link javax.xml.transform.dom.DOMSource DOMSource}, 189 * {@link javax.xml.transform.sax.SAXSource SAXSource}, and 190 * {@link javax.xml.transform.stream.StreamSource StreamSource}. 191 * 192 * @return A {@code Transformer} object that may be used to perform 193 * a transformation in a single {@code Thread}, never 194 * {@code null}. 195 * 196 * @throws TransformerConfigurationException Thrown if there are errors when 197 * parsing the {@code Source} or it is not possible to create a 198 * {@code Transformer} instance. 199 * 200 * @see <a href="http://www.w3.org/TR/xslt"> 201 * XSL Transformations (XSLT) Version 1.0</a> 202 */ 203 public abstract Transformer newTransformer(Source source) 204 throws TransformerConfigurationException; 205 206 /** 207 * Create a new {@code Transformer} that performs a copy 208 * of the {@code Source} to the {@code Result}. 209 * i.e. the "<em>identity transform</em>". 210 * 211 * @return A Transformer object that may be used to perform a transformation 212 * in a single thread, never null. 213 * 214 * @throws TransformerConfigurationException When it is not 215 * possible to create a {@code Transformer} instance. 216 */ 217 public abstract Transformer newTransformer() 218 throws TransformerConfigurationException; 219 220 /** 221 * Process the Source into a Templates object, which is a 222 * a compiled representation of the source. This Templates object 223 * may then be used concurrently across multiple threads. Creating 224 * a Templates object allows the TransformerFactory to do detailed 225 * performance optimization of transformation instructions, without 226 * penalizing runtime transformation. 227 * 228 * @param source An object that holds a URL, input stream, etc. 229 * 230 * @return A Templates object capable of being used for transformation 231 * purposes, never {@code null}. 232 * 233 * @throws TransformerConfigurationException When parsing to 234 * construct the Templates object fails. 235 */ 236 public abstract Templates newTemplates(Source source) 237 throws TransformerConfigurationException; 238 239 /** 240 * Get the stylesheet specification(s) associated with the 241 * XML {@code Source} document via the 242 * <a href="http://www.w3.org/TR/xml-stylesheet/"> 243 * xml-stylesheet processing instruction</a> that match the given criteria. 244 * Note that it is possible to return several stylesheets, in which case 245 * they are applied as if they were a list of imports or cascades in a 246 * single stylesheet. 247 * 248 * @param source The XML source document. 249 * @param media The media attribute to be matched. May be null, in which 250 * case the prefered templates will be used (i.e. alternate = no). 251 * @param title The value of the title attribute to match. May be null. 252 * @param charset The value of the charset attribute to match. May be null. 253 * 254 * @return A {@code Source} {@code Object} suitable for passing 255 * to the {@code TransformerFactory}. 256 * 257 * @throws TransformerConfigurationException An {@code Exception} 258 * is thrown if an error occurings during parsing of the 259 * {@code source}. 260 * 261 * @see <a href="http://www.w3.org/TR/xml-stylesheet/"> 262 * Associating Style Sheets with XML documents Version 1.0</a> 263 */ 264 public abstract Source getAssociatedStylesheet( 265 Source source, 266 String media, 267 String title, 268 String charset) 269 throws TransformerConfigurationException; 270 271 /** 272 * Set an object that is used by default during the transformation 273 * to resolve URIs used in document(), xsl:import, or xsl:include. 274 * 275 * @param resolver An object that implements the URIResolver interface, 276 * or null. 277 */ 278 public abstract void setURIResolver(URIResolver resolver); 279 280 /** 281 * Get the object that is used by default during the transformation 282 * to resolve URIs used in document(), xsl:import, or xsl:include. 283 * 284 * @return The URIResolver that was set with setURIResolver. 285 */ 286 public abstract URIResolver getURIResolver(); 287 288 //======= CONFIGURATION METHODS ======= 289 290 /** 291 * <p>Set a feature for this {@code TransformerFactory} and {@code Transformer}s 292 * or {@code Template}s created by this factory. 293 * 294 * <p> 295 * Feature names are fully qualified {@link java.net.URI}s. 296 * Implementations may define their own features. 297 * An {@link TransformerConfigurationException} is thrown if this {@code TransformerFactory} or the 298 * {@code Transformer}s or {@code Template}s it creates cannot support the feature. 299 * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state. 300 * 301 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. 302 * When the feature is: 303 * <ul> 304 * <li> 305 * {@code true}: the implementation will limit XML processing to conform to implementation limits 306 * and behave in a secure fashion as defined by the implementation. 307 * Examples include resolving user defined style sheets and functions. 308 * If XML processing is limited for security reasons, it will be reported via a call to the registered 309 * {@link ErrorListener#fatalError(TransformerException exception)}. 310 * See {@link #setErrorListener(ErrorListener listener)}. 311 * </li> 312 * <li> 313 * {@code false}: the implementation will processing XML according to the XML specifications without 314 * regard to possible implementation limits. 315 * </li> 316 * </ul> 317 * 318 * @param name Feature name. 319 * @param value Is feature state {@code true} or {@code false}. 320 * 321 * @throws TransformerConfigurationException if this {@code TransformerFactory} 322 * or the {@code Transformer}s or {@code Template}s it creates cannot support this feature. 323 * @throws NullPointerException If the {@code name} parameter is null. 324 */ 325 public abstract void setFeature(String name, boolean value) 326 throws TransformerConfigurationException; 327 328 /** 329 * Look up the value of a feature. 330 * 331 * <p> 332 * Feature names are fully qualified {@link java.net.URI}s. 333 * Implementations may define their own features. 334 * {@code false} is returned if this {@code TransformerFactory} or the 335 * {@code Transformer}s or {@code Template}s it creates cannot support the feature. 336 * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state. 337 * 338 * @param name Feature name. 339 * 340 * @return The current state of the feature, {@code true} or {@code false}. 341 * 342 * @throws NullPointerException If the {@code name} parameter is null. 343 */ 344 public abstract boolean getFeature(String name); 345 346 /** 347 * Allows the user to set specific attributes on the underlying 348 * implementation. An attribute in this context is defined to 349 * be an option that the implementation provides. 350 * An {@code IllegalArgumentException} is thrown if the underlying 351 * implementation doesn't recognize the attribute. 352 * <p> 353 * All implementations that implement JAXP 1.5 or newer are required to 354 * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and 355 * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} properties. 356 * 357 * <ul> 358 * <li> 359 * <p> 360 * Access to external DTDs in the source file is restricted to the protocols 361 * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. 362 * If access is denied during transformation due to the restriction of this property, 363 * {@link javax.xml.transform.TransformerException} will be thrown by 364 * {@link javax.xml.transform.Transformer#transform(Source, Result)}. 365 * 366 * <p> 367 * Access to external DTDs in the stylesheet is restricted to the protocols 368 * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. 369 * If access is denied during the creation of a new transformer due to the 370 * restriction of this property, 371 * {@link javax.xml.transform.TransformerConfigurationException} will be thrown 372 * by the {@link #newTransformer(Source)} method. 373 * 374 * <p> 375 * Access to external reference set by the stylesheet processing instruction, 376 * Import and Include element is restricted to the protocols specified by the 377 * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} property. 378 * If access is denied during the creation of a new transformer due to the 379 * restriction of this property, 380 * {@link javax.xml.transform.TransformerConfigurationException} will be thrown 381 * by the {@link #newTransformer(Source)} method. 382 * 383 * <p> 384 * Access to external document through XSLT document function is restricted 385 * to the protocols specified by the property. If access is denied during 386 * the transformation due to the restriction of this property, 387 * {@link javax.xml.transform.TransformerException} will be thrown by the 388 * {@link javax.xml.transform.Transformer#transform(Source, Result)} method. 389 * 390 * </li> 391 * </ul> 392 * 393 * @param name The name of the attribute. 394 * @param value The value of the attribute. 395 * 396 * @throws IllegalArgumentException When implementation does not 397 * recognize the attribute. 398 */ 399 public abstract void setAttribute(String name, Object value); 400 401 /** 402 * Allows the user to retrieve specific attributes on the underlying 403 * implementation. 404 * An {@code IllegalArgumentException} is thrown if the underlying 405 * implementation doesn't recognize the attribute. 406 * 407 * @param name The name of the attribute. 408 * 409 * @return value The value of the attribute. 410 * 411 * @throws IllegalArgumentException When implementation does not 412 * recognize the attribute. 413 */ 414 public abstract Object getAttribute(String name); 415 416 /** 417 * Set the error event listener for the TransformerFactory, which 418 * is used for the processing of transformation instructions, 419 * and not for the transformation itself. 420 * An {@code IllegalArgumentException} is thrown if the 421 * {@code ErrorListener} listener is {@code null}. 422 * 423 * @param listener The new error listener. 424 * 425 * @throws IllegalArgumentException When {@code listener} is 426 * {@code null} 427 */ 428 public abstract void setErrorListener(ErrorListener listener); 429 430 /** 431 * Get the error event handler for the TransformerFactory. 432 * 433 * @return The current error handler, which should never be null. 434 */ 435 public abstract ErrorListener getErrorListener(); 436 437 }