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