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