1 /*
2 * Copyright (c) 2000, 2006, 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
35 * This property names a concrete subclass of the
36 * <code>TransformerFactory</code> abstract class. If the property is not
37 * defined, a platform default is be used.</p>
38 *
39 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
40 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
41 *
42 * @since 1.5
43 */
44 public abstract class TransformerFactory {
45
46 /**
47 * Default constructor is protected on purpose.
48 */
49 protected TransformerFactory() { }
50
51
52
53 /**
54 * <p>Obtain a new instance of a <code>TransformerFactory</code>.
55 * This static method creates a new factory instance
56 * This method uses the following ordered lookup procedure to determine
57 * the <code>TransformerFactory</code> implementation class to
58 * load:</p>
59 * <ul>
60 * <li>
61 * Use the <code>javax.xml.transform.TransformerFactory</code> system
62 * property.
63 * </li>
64 * <li>
65 * Use the properties file "lib/jaxp.properties" in the JRE directory.
66 * This configuration file is in standard <code>java.util.Properties
67 * </code> format and contains the fully qualified name of the
68 * implementation class with the key being the system property defined
69 * above.
70 *
71 * The jaxp.properties file is read only once by the JAXP implementation
72 * and it's values are then cached for future use. If the file does not exist
73 * when the first attempt is made to read from it, no further attempts are
74 * made to check for its existence. It is not possible to change the value
75 * of any property in jaxp.properties after it has been read for the first time.
76 * </li>
77 * <li>
78 * Use the Services API (as detailed in the JAR specification), if
79 * available, to determine the classname. The Services API will look
80 * for a classname in the file
81 * <code>META-INF/services/javax.xml.transform.TransformerFactory</code>
82 * in jars available to the runtime.
83 * </li>
84 * <li>
85 * Platform default <code>TransformerFactory</code> instance.
86 * </li>
87 * </ul>
88 *
89 * <p>Once an application has obtained a reference to a <code>
90 * TransformerFactory</code> it can use the factory to configure
91 * and obtain transformer instances.</p>
92 *
93 * @return new TransformerFactory instance, never null.
94 *
95 * @throws TransformerFactoryConfigurationError Thrown if the implementation
96 * is not available or cannot be instantiated.
97 */
98 public static TransformerFactory newInstance()
99 throws TransformerFactoryConfigurationError {
100 try {
101 return (TransformerFactory) FactoryFinder.find(
102 /* The default property name according to the JAXP spec */
103 "javax.xml.transform.TransformerFactory",
104 /* The fallback implementation class name, XSLTC */
105 "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl");
106 } catch (FactoryFinder.ConfigurationError e) {
107 throw new TransformerFactoryConfigurationError(
108 e.getException(),
109 e.getMessage());
110 }
111 }
112
113 /**
114 * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
115 * This function is useful when there are multiple providers in the classpath.
116 * It gives more control to the application as it can specify which provider
117 * should be loaded.</p>
118 *
119 * <p>Once an application has obtained a reference to a <code>
120 * TransformerFactory</code> it can use the factory to configure
121 * and obtain transformer instances.</p>
122 *
123 * <h2>Tip for Trouble-shooting</h2>
124 * <p>Setting the <code>jaxp.debug</code> system property will cause
125 * this method to print a lot of debug messages
126 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
127 *
128 * <p> If you have problems try:</p>
129 * <pre>
130 * java -Djaxp.debug=1 YourProgram ....
131 * </pre>
132 *
133 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
134 *
135 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
136 * current <code>Thread</code>'s context classLoader is used to load the factory class.
137 *
138 * @return new TransformerFactory instance, never null.
139 *
140 * @throws TransformerFactoryConfigurationError
141 * if <code>factoryClassName</code> is <code>null</code>, or
142 * the factory class cannot be loaded, instantiated.
143 *
144 * @see #newInstance()
145 *
146 * @since 1.6
147 */
148 public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
149 throws TransformerFactoryConfigurationError{
150 try {
151 //do not fallback if given classloader can't find the class, throw exception
152 return (TransformerFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
153 } catch (FactoryFinder.ConfigurationError e) {
154 throw new TransformerFactoryConfigurationError(
155 e.getException(),
156 e.getMessage());
157 }
158 }
159 /**
160 * <p>Process the <code>Source</code> into a <code>Transformer</code>
161 * <code>Object</code>. The <code>Source</code> is an XSLT document that
162 * conforms to <a href="http://www.w3.org/TR/xslt">
163 * XSL Transformations (XSLT) Version 1.0</a>. Care must
164 * be taken not to use this <code>Transformer</code> in multiple
165 * <code>Thread</code>s running concurrently.
166 * Different <code>TransformerFactories</code> can be used concurrently by
167 * different <code>Thread</code>s.</p>
168 *
169 * @param source <code>Source </code> of XSLT document used to create
170 * <code>Transformer</code>.
171 * Examples of XML <code>Source</code>s include
172 * {@link javax.xml.transform.dom.DOMSource DOMSource},
173 * {@link javax.xml.transform.sax.SAXSource SAXSource}, and
174 * {@link javax.xml.transform.stream.StreamSource StreamSource}.
175 *
176 * @return A <code>Transformer</code> object that may be used to perform
177 * a transformation in a single <code>Thread</code>, never
|
1 /*
2 * Copyright (c) 2000, 2013, 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
35 * This property names a concrete subclass of the
36 * <code>TransformerFactory</code> abstract class. If the property is not
37 * defined, a platform default is be used.</p>
38 *
39 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
40 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
41 *
42 * @since 1.5
43 */
44 public abstract class TransformerFactory {
45
46 /**
47 * Default constructor is protected on purpose.
48 */
49 protected TransformerFactory() { }
50
51
52
53 /**
54 * <p>Obtain a new instance of a <code>TransformerFactory</code>.
55 * This static method creates a new factory instance.</p>
56 * <p>This method uses the following ordered lookup procedure to determine
57 * the <code>TransformerFactory</code> implementation class to
58 * load:</p>
59 * <ul>
60 * <li>
61 * Use the <code>javax.xml.transform.TransformerFactory</code> system
62 * property.
63 * </li>
64 * <li>
65 * Use the properties file "lib/jaxp.properties" in the JRE directory.
66 * This configuration file is in standard <code>java.util.Properties
67 * </code> format and contains the fully qualified name of the
68 * implementation class with the key being the system property defined
69 * above.
70 * <br>
71 * The jaxp.properties file is read only once by the JAXP implementation
72 * and it's values are then cached for future use. If the file does not exist
73 * when the first attempt is made to read from it, no further attempts are
74 * made to check for its existence. It is not possible to change the value
75 * of any property in jaxp.properties after it has been read for the first time.
76 * </li>
77 * <li>
78 * Use the service-provider loading facilities, defined by the
79 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
80 * implementation of the service.
81 * </li>
82 * <li>
83 * Otherwise, the system-default implementation is returned.
84 * </li>
85 * </ul>
86 *
87 * <p>Once an application has obtained a reference to a <code>
88 * TransformerFactory</code> it can use the factory to configure
89 * and obtain transformer instances.</p>
90 *
91 * @return new TransformerFactory instance, never null.
92 *
93 * @throws TransformerFactoryConfigurationError Thrown in case of {@linkplain
94 * java.util.ServiceConfigurationError service configuration error} or if
95 * the implementation is not available or cannot be instantiated.
96 */
97 public static TransformerFactory newInstance()
98 throws TransformerFactoryConfigurationError {
99
100 return FactoryFinder.find(
101 /* The default property name according to the JAXP spec */
102 TransformerFactory.class,
103 /* The fallback implementation class name, XSLTC */
104 "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl");
105 }
106
107 /**
108 * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
109 * This function is useful when there are multiple providers in the classpath.
110 * It gives more control to the application as it can specify which provider
111 * should be loaded.</p>
112 *
113 * <p>Once an application has obtained a reference to a <code>
114 * TransformerFactory</code> it can use the factory to configure
115 * and obtain transformer instances.</p>
116 *
117 * <h2>Tip for Trouble-shooting</h2>
118 * <p>Setting the <code>jaxp.debug</code> system property will cause
119 * this method to print a lot of debug messages
120 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
121 *
122 * <p> If you have problems try:</p>
123 * <pre>
124 * java -Djaxp.debug=1 YourProgram ....
125 * </pre>
126 *
127 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
128 *
129 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
130 * current <code>Thread</code>'s context classLoader is used to load the factory class.
131 *
132 * @return new TransformerFactory instance, never null.
133 *
134 * @throws TransformerFactoryConfigurationError
135 * if <code>factoryClassName</code> is <code>null</code>, or
136 * the factory class cannot be loaded, instantiated.
137 *
138 * @see #newInstance()
139 *
140 * @since 1.6
141 */
142 public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
143 throws TransformerFactoryConfigurationError{
144
145 //do not fallback if given classloader can't find the class, throw exception
146 return FactoryFinder.newInstance(TransformerFactory.class,
147 factoryClassName, classLoader, false, false);
148 }
149 /**
150 * <p>Process the <code>Source</code> into a <code>Transformer</code>
151 * <code>Object</code>. The <code>Source</code> is an XSLT document that
152 * conforms to <a href="http://www.w3.org/TR/xslt">
153 * XSL Transformations (XSLT) Version 1.0</a>. Care must
154 * be taken not to use this <code>Transformer</code> in multiple
155 * <code>Thread</code>s running concurrently.
156 * Different <code>TransformerFactories</code> can be used concurrently by
157 * different <code>Thread</code>s.</p>
158 *
159 * @param source <code>Source </code> of XSLT document used to create
160 * <code>Transformer</code>.
161 * Examples of XML <code>Source</code>s include
162 * {@link javax.xml.transform.dom.DOMSource DOMSource},
163 * {@link javax.xml.transform.sax.SAXSource SAXSource}, and
164 * {@link javax.xml.transform.stream.StreamSource StreamSource}.
165 *
166 * @return A <code>Transformer</code> object that may be used to perform
167 * a transformation in a single <code>Thread</code>, never
|