TransformerFactory.java revision d21d78fd49a2d798218e8c8aefbddb26a0e71bbb
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: TransformerFactory.java 884963 2009-11-27 19:11:59Z mrglavas $ 19 20package javax.xml.transform; 21 22import org.apache.xalan.processor.TransformerFactoryImpl; 23 24/** 25 * <p>A TransformerFactory instance can be used to create 26 * {@link javax.xml.transform.Transformer} and 27 * {@link javax.xml.transform.Templates} objects.</p> 28 * 29 * <p>The system property that determines which Factory implementation 30 * to create is named <code>"javax.xml.transform.TransformerFactory"</code>. 31 * This property names a concrete subclass of the 32 * <code>TransformerFactory</code> abstract class. If the property is not 33 * defined, a platform default is be used.</p> 34 * 35 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 36 */ 37public abstract class TransformerFactory { 38 39 /** 40 * Default constructor is protected on purpose. 41 */ 42 protected TransformerFactory() { } 43 44 45 /** 46 * <p>Get current state of canonicalization.</p> 47 * 48 * @return current state canonicalization control 49 */ 50 /* 51 public boolean getCanonicalization() { 52 return canonicalState; 53 } 54 */ 55 56 /** 57 * <p>Set canonicalization control to <code>true</code> or 58 * </code>false</code>.</p> 59 * 60 * @param state of canonicalization 61 */ 62 /* 63 public void setCanonicalization(boolean state) { 64 canonicalState = state; 65 } 66 */ 67 68 /** 69 * Returns Android's implementation of {@code TransformerFactory}. Unlike 70 * other Java implementations, this method does not consult system 71 * properties, properties files, or the services API. 72 * 73 * @return new TransformerFactory instance, never null. 74 * 75 * @throws TransformerFactoryConfigurationError never. Included for API 76 * compatibility with other Java implementations. 77 */ 78 public static TransformerFactory newInstance() 79 throws TransformerFactoryConfigurationError { 80 // BEGIN android-changed 81 // instantiate the class directly rather than using reflection 82 return new TransformerFactoryImpl(); 83 // END android-changed 84 } 85 86 // BEGIN android-only 87 // omit this method which wasn't included in Java 5 88 // /** 89 // * @return new TransformerFactory instance, never null. 90 // * 91 // * @throws TransformerFactoryConfigurationError Thrown if the implementation 92 // * is not available or cannot be instantiated. 93 // * @since 1.6 94 // */ 95 // public static TransformerFactory newInstance(String factoryClassName, 96 // ClassLoader classLoader) throws TransformerFactoryConfigurationError { 97 // if (factoryClassName == null) { 98 // throw new TransformerFactoryConfigurationError("factoryClassName cannot be null."); 99 // } 100 // if (classLoader == null) { 101 // classLoader = SecuritySupport.getContextClassLoader(); 102 // } 103 // try { 104 // return (TransformerFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false); 105 // } 106 // catch (FactoryFinder.ConfigurationError e) { 107 // throw new TransformerFactoryConfigurationError(e.getException(), e.getMessage()); 108 // } 109 // } 110 // END android-only 111 112 /** 113 * <p>Process the <code>Source</code> into a <code>Transformer</code> 114 * <code>Object</code>. The <code>Source</code> is an XSLT document that 115 * conforms to <a href="http://www.w3.org/TR/xslt"> 116 * XSL Transformations (XSLT) Version 1.0</a>. Care must 117 * be taken not to use this <code>Transformer</code> in multiple 118 * <code>Thread</code>s running concurrently. 119 * Different <code>TransformerFactories</code> can be used concurrently by 120 * different <code>Thread</code>s.</p> 121 * 122 * @param source <code>Source </code> of XSLT document used to create 123 * <code>Transformer</code>. 124 * Examples of XML <code>Source</code>s include 125 * {@link javax.xml.transform.stream.StreamSource StreamSource}, 126 * {@link javax.xml.transform.sax.SAXSource SAXSource} and 127 * {@link javax.xml.transform.dom.DOMSource DOMSource}. 128 * 129 * @return A <code>Transformer</code> object that may be used to perform 130 * a transformation in a single <code>Thread</code>, never 131 * <code>null</code>. 132 * 133 * @throws TransformerConfigurationException Thrown if there are errors when 134 * parsing the <code>Source</code> or it is not possible to create a 135 * <code>Transformer</code> instance. 136 * 137 * @see <a href="http://www.w3.org/TR/xslt"> 138 * XSL Transformations (XSLT) Version 1.0</a> 139 */ 140 public abstract Transformer newTransformer(Source source) 141 throws TransformerConfigurationException; 142 143 /** 144 * <p>Create a new <code>Transformer</code> that performs a copy 145 * of the <code>Source</code> to the <code>Result</code>. 146 * i.e. the "<em>identity transform</em>".</p> 147 * 148 * @return A Transformer object that may be used to perform a transformation 149 * in a single thread, never null. 150 * 151 * @exception TransformerConfigurationException Thrown if it is not 152 * possible to create a <code>Transformer</code> instance. 153 */ 154 public abstract Transformer newTransformer() 155 throws TransformerConfigurationException; 156 157 /** 158 * Process the Source into a Templates object, which is a 159 * a compiled representation of the source. This Templates object 160 * may then be used concurrently across multiple threads. Creating 161 * a Templates object allows the TransformerFactory to do detailed 162 * performance optimization of transformation instructions, without 163 * penalizing runtime transformation. 164 * 165 * @param source An object that holds a URL, input stream, etc. 166 * 167 * @return A Templates object capable of being used for transformation 168 * purposes, never null. 169 * 170 * @exception TransformerConfigurationException May throw this during the 171 * parse when it is constructing the Templates object and fails. 172 */ 173 public abstract Templates newTemplates(Source source) 174 throws TransformerConfigurationException; 175 176 /** 177 * <p>Get the stylesheet specification(s) associated with the 178 * XML <code>Source</code> document via the 179 * <a href="http://www.w3.org/TR/xml-stylesheet/"> 180 * xml-stylesheet processing instruction</a> that match the given criteria. 181 * Note that it is possible to return several stylesheets, in which case 182 * they are applied as if they were a list of imports or cascades in a 183 * single stylesheet.</p> 184 * 185 * @param source The XML source document. 186 * @param media The media attribute to be matched. May be null, in which 187 * case the preferred templates will be used (i.e. alternate = no). 188 * @param title The value of the title attribute to match. May be null. 189 * @param charset The value of the charset attribute to match. May be null. 190 * 191 * @return A <code>Source</code> <code>Object</code> suitable for passing 192 * to the <code>TransformerFactory</code>. 193 * 194 * @throws TransformerConfigurationException An <code>Exception</code> 195 * is thrown if an error occurs during parsing of the 196 * <code>source</code>. 197 * 198 * @see <a href="http://www.w3.org/TR/xml-stylesheet/"> 199 * Associating Style Sheets with XML documents Version 1.0</a> 200 */ 201 public abstract Source getAssociatedStylesheet( 202 Source source, 203 String media, 204 String title, 205 String charset) 206 throws TransformerConfigurationException; 207 208 /** 209 * Set an object that is used by default during the transformation 210 * to resolve URIs used in document(), xsl:import, or xsl:include. 211 * 212 * @param resolver An object that implements the URIResolver interface, 213 * or null. 214 */ 215 public abstract void setURIResolver(URIResolver resolver); 216 217 /** 218 * Get the object that is used by default during the transformation 219 * to resolve URIs used in document(), xsl:import, or xsl:include. 220 * 221 * @return The URIResolver that was set with setURIResolver. 222 */ 223 public abstract URIResolver getURIResolver(); 224 225 //======= CONFIGURATION METHODS ======= 226 227 /** 228 * <p>Set a feature for this <code>TransformerFactory</code> and <code>Transformer</code>s 229 * or <code>Template</code>s created by this factory.</p> 230 * 231 * <p> 232 * Feature names are fully qualified {@link java.net.URI}s. 233 * Implementations may define their own features. 234 * An {@link TransformerConfigurationException} is thrown if this <code>TransformerFactory</code> or the 235 * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. 236 * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state. 237 * </p> 238 * 239 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. 240 * When the feature is:</p> 241 * <ul> 242 * <li> 243 * <code>true</code>: the implementation will limit XML processing to conform to implementation limits 244 * and behave in a secure fashion as defined by the implementation. 245 * Examples include resolving user defined style sheets and functions. 246 * If XML processing is limited for security reasons, it will be reported via a call to the registered 247 * {@link ErrorListener#fatalError(TransformerException exception)}. 248 * See {@link #setErrorListener(ErrorListener listener)}. 249 * </li> 250 * <li> 251 * <code>false</code>: the implementation will processing XML according to the XML specifications without 252 * regard to possible implementation limits. 253 * </li> 254 * </ul> 255 * 256 * @param name Feature name. 257 * @param value Is feature state <code>true</code> or <code>false</code>. 258 * 259 * @throws TransformerConfigurationException if this <code>TransformerFactory</code> 260 * or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature. 261 * @throws NullPointerException If the <code>name</code> parameter is null. 262 */ 263 public abstract void setFeature(String name, boolean value) 264 throws TransformerConfigurationException; 265 266 /** 267 * Look up the value of a feature. 268 * 269 * <p> 270 * Feature names are fully qualified {@link java.net.URI}s. 271 * Implementations may define their own features. 272 * <code>false</code> is returned if this <code>TransformerFactory</code> or the 273 * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. 274 * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state. 275 * </p> 276 * 277 * @param name Feature name. 278 * 279 * @return The current state of the feature, <code>true</code> or <code>false</code>. 280 * 281 * @throws NullPointerException If the <code>name</code> parameter is null. 282 */ 283 public abstract boolean getFeature(String name); 284 285 /** 286 * Allows the user to set specific attributes on the underlying 287 * implementation. An attribute in this context is defined to 288 * be an option that the implementation provides. 289 * An <code>IllegalArgumentException</code> is thrown if the underlying 290 * implementation doesn't recognize the attribute. 291 * 292 * @param name The name of the attribute. 293 * @param value The value of the attribute. 294 */ 295 public abstract void setAttribute(String name, Object value); 296 297 /** 298 * Allows the user to retrieve specific attributes on the underlying 299 * implementation. 300 * An <code>IllegalArgumentException</code> is thrown if the underlying 301 * implementation doesn't recognize the attribute. 302 * 303 * @param name The name of the attribute. 304 * @return value The value of the attribute. 305 */ 306 public abstract Object getAttribute(String name); 307 308 /** 309 * Set the error event listener for the TransformerFactory, which 310 * is used for the processing of transformation instructions, 311 * and not for the transformation itself. 312 * An <code>IllegalArgumentException</code> is thrown if the 313 * <code>ErrorListener</code> listener is <code>null</code>. 314 * 315 * @param listener The new error listener. 316 */ 317 public abstract void setErrorListener(ErrorListener listener); 318 319 /** 320 * Get the error event handler for the TransformerFactory. 321 * 322 * @return The current error handler, which should never be null. 323 */ 324 public abstract ErrorListener getErrorListener(); 325 326} 327 328