- 001
/* - 002
* The contents of this file are subject to the terms - 003 * of the Common Development and Distribution License
- 004 * (the "License"). You may not use this file except
- 005 * in compliance with the License.
- 006 *
- 007 * You can obtain a copy of the license at
- 008 * https://jaxp.dev.java.net/CDDLv1.0.html.
- 009 * See the License for the specific language governing
- 010 * permissions and limitations under the License.
- 011 *
- 012 * When distributing Covered Code, include this CDDL
- 013 * HEADER in each file and include the License file at
- 014 * https://jaxp.dev.java.net/CDDLv1.0.html
- 015 * If applicable add the following below this CDDL HEADER
- 016 * with the fields enclosed by brackets "[]" replaced with
- 017 * your own identifying information: Portions Copyright
- 018 * [year] [name of copyright owner]
- 019
*/ - 020
- 021/*
- 022 * $Id: TransformerFactory.java,v 1.5 2006/04/06 00:26:40 jeffsuttor Exp $
- 023 * @(#)TransformerFactory.java 1.46 06/06/21
- 024 *
- 025 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
- 026 */
- 027
- 028package javax.xml.transform;
- 029
- 030/**
- 031 * <p>A TransformerFactory instance can be used to create
- 032 * {@link javax.xml.transform.Transformer} and
- 033 * {@link javax.xml.transform.Templates} objects.</p>
- 034 *
- 035 * <p>The system property that determines which Factory implementation
- 036 * to create is named <code>"javax.xml.transform.TransformerFactory"</code>.
- 037 * This property names a concrete subclass of the
- 038 * <code>TransformerFactory</code> abstract class. If the property is not
- 039 * defined, a platform default is be used.</p>
- 040 *
- 041 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
- 042 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
- 043 *
- 044 */
- 045public abstract class TransformerFactory {
- 046
- 047 /**
- 048 * Default constructor is protected on purpose.
- 049 */
- 050 protected TransformerFactory() { }
- 051
- 052
- 053
- 054 /**
- 055 * <p>Obtain a new instance of a <code>TransformerFactory</code>.
- 056 * This static method creates a new factory instance
- 057 * This method uses the following ordered lookup procedure to determine
- 058 * the <code>TransformerFactory</code> implementation class to
- 059 * load:</p>
- 060 * <ul>
- 061 * <li>
- 062 * Use the <code>javax.xml.transform.TransformerFactory</code> system
- 063 * property.
- 064 * </li>
- 065 * <li>
- 066 * Use the properties file "lib/jaxp.properties" in the JRE directory.
- 067 * This configuration file is in standard <code>java.util.Properties
- 068 * </code> format and contains the fully qualified name of the
- 069 * implementation class with the key being the system property defined
- 070 * above.
- 071 *
- 072 * The jaxp.properties file is read only once by the JAXP implementation
- 073 * and it's values are then cached for future use. If the file does not exist
- 074 * when the first attempt is made to read from it, no further attempts are
- 075 * made to check for its existence. It is not possible to change the value
- 076 * of any property in jaxp.properties after it has been read for the first time.
- 077 * </li>
- 078 * <li>
- 079 * Use the Services API (as detailed in the JAR specification), if
- 080 * available, to determine the classname. The Services API will look
- 081 * for a classname in the file
- 082 * <code>META-INF/services/javax.xml.transform.TransformerFactory</code>
- 083 * in jars available to the runtime.
- 084 * </li>
- 085 * <li>
- 086 * Platform default <code>TransformerFactory</code> instance.
- 087 * </li>
- 088 * </ul>
- 089 *
- 090 * <p>Once an application has obtained a reference to a <code>
- 091 * TransformerFactory</code> it can use the factory to configure
- 092 * and obtain transformer instances.</p>
- 093 *
- 094 * @return new TransformerFactory instance, never null.
- 095 *
- 096 * @throws TransformerFactoryConfigurationError Thrown if the implementation
- 097 * is not available or cannot be instantiated.
- 098 */
- 099 public static TransformerFactory newInstance()
- 100 throws TransformerFactoryConfigurationError {
- 101 try {
- 102 return (TransformerFactory) FactoryFinder.find(
- 103 /* The default property name according to the JAXP spec */
- 104 "javax.xml.transform.TransformerFactory",
- 105 /* The fallback implementation class name, XSLTC */
- 106 "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl");
- 107 } catch (FactoryFinder.ConfigurationError e) {
- 108 throw new TransformerFactoryConfigurationError(
- 109 e.getException(),
- 110 e.getMessage());
- 111 }
- 112 }
- 113
- 114 /**
- 115 * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
- 116 * This function is useful when there are multiple providers in the classpath.
- 117 * It gives more control to the application as it can specify which provider
- 118 * should be loaded.</p>
- 119 *
- 120 * <p>Once an application has obtained a reference to a <code>
- 121 * TransformerFactory</code> it can use the factory to configure
- 122 * and obtain transformer instances.</p>
- 123 *
- 124 * <h2>Tip for Trouble-shooting</h2>
- 125 * <p>Setting the <code>jaxp.debug</code> system property will cause
- 126 * this method to print a lot of debug messages
- 127 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
- 128 *
- 129 * <p> If you have problems try:</p>
- 130 * <pre>
- 131 * java -Djaxp.debug=1 YourProgram ....
- 132 * </pre>
- 133 *
- 134 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
- 135 *
- 136 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
- 137 * current <code>Thread</code>'s context classLoader is used to load the factory class.
- 138 *
- 139 * @return new TransformerFactory instance, never null.
- 140 *
- 141 * @throws TransformerFactoryConfigurationError
- 142 * if <code>factoryClassName</code> is <code>null</code>, or
- 143 * the factory class cannot be loaded, instantiated.
- 144 *
- 145 * @see #newInstance()
- 146 *
- 147 * @since 1.6
- 148 */
- 149 public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
- 150 throws TransformerFactoryConfigurationError{
- 151 try {
- 152 //do not fallback if given classloader can't find the class, throw exception
- 153 return (TransformerFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
- 154 } catch (FactoryFinder.ConfigurationError e) {
- 155 throw new TransformerFactoryConfigurationError(
- 156 e.getException(),
- 157 e.getMessage());
- 158 }
- 159 }
- 160 /**
- 161 * <p>Process the <code>Source</code> into a <code>Transformer</code>
- 162 * <code>Object</code>. The <code>Source</code> is an XSLT document that
- 163 * conforms to <a href="http://www.w3.org/TR/xslt">
- 164 * XSL Transformations (XSLT) Version 1.0</a>. Care must
- 165 * be taken not to use this <code>Transformer</code> in multiple
- 166 * <code>Thread</code>s running concurrently.
- 167 * Different <code>TransformerFactories</code> can be used concurrently by
- 168 * different <code>Thread</code>s.</p>
- 169 *
- 170 * @param source <code>Source </code> of XSLT document used to create
- 171 * <code>Transformer</code>.
- 172 * Examples of XML <code>Source</code>s include
- 173 * {@link javax.xml.transform.dom.DOMSource DOMSource},
- 174 * {@link javax.xml.transform.sax.SAXSource SAXSource}, and
- 175 * {@link javax.xml.transform.stream.StreamSource StreamSource}.
- 176 *
- 177 * @return A <code>Transformer</code> object that may be used to perform
- 178 * a transformation in a single <code>Thread</code>, never
- 179 * <code>null</code>.
- 180 *
- 181 * @throws TransformerConfigurationException Thrown if there are errors when
- 182 * parsing the <code>Source</code> or it is not possible to create a
- 183 * <code>Transformer</code> instance.
- 184 *
- 185 * @see <a href="http://www.w3.org/TR/xslt">
- 186 * XSL Transformations (XSLT) Version 1.0</a>
- 187 */
- 188 public abstract Transformer newTransformer(Source source)
- 189 throws TransformerConfigurationException;
- 190
- 191 /**
- 192 * <p>Create a new <code>Transformer</code> that performs a copy
- 193 * of the <code>Source</code> to the <code>Result</code>.
- 194 * i.e. the "<em>identity transform</em>".</p>
- 195 *
- 196 * @return A Transformer object that may be used to perform a transformation
- 197 * in a single thread, never null.
- 198 *
- 199 * @throws TransformerConfigurationException When it is not
- 200 * possible to create a <code>Transformer</code> instance.
- 201 */
- 202 public abstract Transformer newTransformer()
- 203 throws TransformerConfigurationException;
- 204
- 205 /**
- 206 * Process the Source into a Templates object, which is a
- 207 * a compiled representation of the source. This Templates object
- 208 * may then be used concurrently across multiple threads. Creating
- 209 * a Templates object allows the TransformerFactory to do detailed
- 210 * performance optimization of transformation instructions, without
- 211 * penalizing runtime transformation.
- 212 *
- 213 * @param source An object that holds a URL, input stream, etc.
- 214 *
- 215 * @return A Templates object capable of being used for transformation
- 216 * purposes, never <code>null</code>.
- 217 *
- 218 * @throws TransformerConfigurationException When parsing to
- 219 * construct the Templates object fails.
- 220 */
- 221 public abstract Templates newTemplates(Source source)
- 222 throws TransformerConfigurationException;
- 223
- 224 /**
- 225 * <p>Get the stylesheet specification(s) associated with the
- 226 * XML <code>Source</code> document via the
- 227 * <a href="http://www.w3.org/TR/xml-stylesheet/">
- 228 * xml-stylesheet processing instruction</a> that match the given criteria.
- 229 * Note that it is possible to return several stylesheets, in which case
- 230 * they are applied as if they were a list of imports or cascades in a
- 231 * single stylesheet.</p>
- 232 *
- 233 * @param source The XML source document.
- 234 * @param media The media attribute to be matched. May be null, in which
- 235 * case the prefered templates will be used (i.e. alternate = no).
- 236 * @param title The value of the title attribute to match. May be null.
- 237 * @param charset The value of the charset attribute to match. May be null.
- 238 *
- 239 * @return A <code>Source</code> <code>Object</code> suitable for passing
- 240 * to the <code>TransformerFactory</code>.
- 241 *
- 242 * @throws TransformerConfigurationException An <code>Exception</code>
- 243 * is thrown if an error occurings during parsing of the
- 244 * <code>source</code>.
- 245 *
- 246 * @see <a href="http://www.w3.org/TR/xml-stylesheet/">
- 247 * Associating Style Sheets with XML documents Version 1.0</a>
- 248 */
- 249 public abstract Source getAssociatedStylesheet(
- 250 Source source,
- 251 String media,
- 252 String title,
- 253 String charset)
- 254 throws TransformerConfigurationException;
- 255
- 256 /**
- 257 * Set an object that is used by default during the transformation
- 258 * to resolve URIs used in document(), xsl:import, or xsl:include.
- 259 *
- 260 * @param resolver An object that implements the URIResolver interface,
- 261 * or null.
- 262 */
- 263 public abstract void setURIResolver(URIResolver resolver);
- 264
- 265 /**
- 266 * Get the object that is used by default during the transformation
- 267 * to resolve URIs used in document(), xsl:import, or xsl:include.
- 268 *
- 269 * @return The URIResolver that was set with setURIResolver.
- 270 */
- 271 public abstract URIResolver getURIResolver();
- 272
- 273 //======= CONFIGURATION METHODS =======
- 274
- 275 /**
- 276 * <p>Set a feature for this <code>TransformerFactory</code> and <code>Transformer</code>s
- 277 * or <code>Template</code>s created by this factory.</p>
- 278 *
- 279 * <p>
- 280 * Feature names are fully qualified {@link java.net.URI}s.
- 281 * Implementations may define their own features.
- 282 * An {@link TransformerConfigurationException} is thrown if this <code>TransformerFactory</code> or the
- 283 * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
- 284 * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state.
- 285 * </p>
- 286 *
- 287 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
- 288 * When the feature is:</p>
- 289 * <ul>
- 290 * <li>
- 291 * <code>true</code>: the implementation will limit XML processing to conform to implementation limits
- 292 * and behave in a secure fashion as defined by the implementation.
- 293 * Examples include resolving user defined style sheets and functions.
- 294 * If XML processing is limited for security reasons, it will be reported via a call to the registered
- 295 * {@link ErrorListener#fatalError(TransformerException exception)}.
- 296 * See {@link #setErrorListener(ErrorListener listener)}.
- 297 * </li>
- 298 * <li>
- 299 * <code>false</code>: the implementation will processing XML according to the XML specifications without
- 300 * regard to possible implementation limits.
- 301 * </li>
- 302 * </ul>
- 303 *
- 304 * @param name Feature name.
- 305 * @param value Is feature state <code>true</code> or <code>false</code>.
- 306 *
- 307 * @throws TransformerConfigurationException if this <code>TransformerFactory</code>
- 308 * or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature.
- 309 * @throws NullPointerException If the <code>name</code> parameter is null.
- 310 */
- 311 public abstract void setFeature(String name, boolean value)
- 312 throws TransformerConfigurationException;
- 313
- 314 /**
- 315 * Look up the value of a feature.
- 316 *
- 317 * <p>
- 318 * Feature names are fully qualified {@link java.net.URI}s.
- 319 * Implementations may define their own features.
- 320 * <code>false</code> is returned if this <code>TransformerFactory</code> or the
- 321 * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
- 322 * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state.
- 323 * </p>
- 324 *
- 325 * @param name Feature name.
- 326 *
- 327 * @return The current state of the feature, <code>true</code> or <code>false</code>.
- 328 *
- 329 * @throws NullPointerException If the <code>name</code> parameter is null.
- 330 */
- 331 public abstract boolean getFeature(String name);
- 332
- 333 /**
- 334 * Allows the user to set specific attributes on the underlying
- 335 * implementation. An attribute in this context is defined to
- 336 * be an option that the implementation provides.
- 337 * An <code>IllegalArgumentException</code> is thrown if the underlying
- 338 * implementation doesn't recognize the attribute.
- 339 *
- 340 * @param name The name of the attribute.
- 341 * @param value The value of the attribute.
- 342 *
- 343 * @throws IllegalArgumentException When implementation does not
- 344 * recognize the attribute.
- 345 */
- 346 public abstract void setAttribute(String name, Object value);
- 347
- 348 /**
- 349 * Allows the user to retrieve specific attributes on the underlying
- 350 * implementation.
- 351 * An <code>IllegalArgumentException</code> is thrown if the underlying
- 352 * implementation doesn't recognize the attribute.
- 353 *
- 354 * @param name The name of the attribute.
- 355 *
- 356 * @return value The value of the attribute.
- 357 *
- 358 * @throws IllegalArgumentException When implementation does not
- 359 * recognize the attribute.
- 360 */
- 361 public abstract Object getAttribute(String name);
- 362
- 363 /**
- 364 * Set the error event listener for the TransformerFactory, which
- 365 * is used for the processing of transformation instructions,
- 366 * and not for the transformation itself.
- 367 * An <code>IllegalArgumentException</code> is thrown if the
- 368 * <code>ErrorListener</code> listener is <code>null</code>.
- 369 *
- 370 * @param listener The new error listener.
- 371 *
- 372 * @throws IllegalArgumentException When <code>listener</code> is
- 373 * <code>null</code>
- 374 */
- 375 public abstract void setErrorListener(ErrorListener listener);
- 376
- 377 /**
- 378 * Get the error event handler for the TransformerFactory.
- 379 *
- 380 * @return The current error handler, which should never be null.
- 381 */
- 382 public abstract ErrorListener getErrorListener();
- 383
- 384}
- 385
