Source code: org/jdom/transform/XSLTransformer.java
1 /*--
2
3 $Id: XSLTransformer.java,v 1.2 2004/02/06 09:28:32 jhunter Exp $
4
5 Copyright (C) 2001-2004 Jason Hunter & Brett McLaughlin.
6 All rights reserved.
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions
10 are met:
11
12 1. Redistributions of source code must retain the above copyright
13 notice, this list of conditions, and the following disclaimer.
14
15 2. Redistributions in binary form must reproduce the above copyright
16 notice, this list of conditions, and the disclaimer that follows
17 these conditions in the documentation and/or other materials
18 provided with the distribution.
19
20 3. The name "JDOM" must not be used to endorse or promote products
21 derived from this software without prior written permission. For
22 written permission, please contact <request_AT_jdom_DOT_org>.
23
24 4. Products derived from this software may not be called "JDOM", nor
25 may "JDOM" appear in their name, without prior written permission
26 from the JDOM Project Management <request_AT_jdom_DOT_org>.
27
28 In addition, we request (but do not require) that you include in the
29 end-user documentation provided with the redistribution and/or in the
30 software itself an acknowledgement equivalent to the following:
31 "This product includes software developed by the
32 JDOM Project (http://www.jdom.org/)."
33 Alternatively, the acknowledgment may be graphical using the logos
34 available at http://www.jdom.org/images/logos.
35
36 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39 DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
40 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 SUCH DAMAGE.
48
49 This software consists of voluntary contributions made by many
50 individuals on behalf of the JDOM Project and was originally
51 created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
52 Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
53 on the JDOM Project, please see <http://www.jdom.org/>.
54
55 */
56
57 package org.jdom.transform;
58
59 import java.util.*;
60 import java.io.*;
61 import javax.xml.transform.*;
62 import javax.xml.transform.stream.StreamSource;
63 import org.jdom.*;
64
65 /**
66 * A convenience class to handle simple transformations. The JAXP TrAX classes
67 * have more bells and whistles and can be used with {@link JDOMSource} and
68 * {@link JDOMResult} for advanced uses. This class handles the common case and
69 * presents a simple interface. XSLTransformer is thread safe and may be
70 * used from multiple threads.
71 *
72 * <pre><code>
73 * XSLTransformer transformer = new XSLTransformer("file.xsl");
74 *
75 * Document x2 = transformer.transform(x); // x is a Document
76 * Document y2 = transformer.transform(y); // y is a Document
77 * </code></pre>
78 *
79 * JDOM relies on TrAX to perform the transformation.
80 * The <code>javax.xml.transform.TransformerFactory</code> Java system property
81 * determines which XSLT engine TrAX uses. Its value should be
82 * the fully qualified name of the implementation of the abstract
83 * <code>javax.xml.transform.TransformerFactory</code> class.
84 * Values of this property for popular XSLT processors include:
85 * </p>
86 * <ul><li>Saxon 6.x: <code>com.icl.saxon.TransformerFactoryImpl</code></li>
87 * <li>Saxon 7.x: <code>net.sf.saxon.TransformerFactoryImpl</code></li>
88 * <li>Xalan: <code>org.apache.xalan.processor.TransformerFactoryImpl</code></li>
89 * <li>jd.xslt: <code>jd.xml.xslt.trax.TransformerFactoryImpl</code></li>
90 * <li>Oracle: <code>oracle.xml.jaxp.JXSAXTransformerFactory</code></li>
91 * </ul>
92 * <p>
93 * This property can be set in all the usual ways a Java system property
94 * can be set. TrAX picks from them in this order:</p>
95 * <ol>
96 * <li> Invoking <code>System.setProperty( "javax.xml.transform.TransformerFactory",
97 * "<i><code>classname</code></i>")</code></li>
98 * <li>The value specified at the command line using the
99 * <tt>-Djavax.xml.transform.TransformerFactory=<i><code>classname</code></i></tt>
100 * option to the <b>java</b> interpreter</li>
101 * <li>The class named in the <code>lib/jaxp.properties</code> properties file
102 * in the JRE directory, in a line like this one:
103 * <pre>javax.xml.parsers.DocumentBuilderFactory=<i><code>classname</code></i></pre></li>
104 * <li>The class named in the
105 * <code>META-INF/services/javax.xml.transform.TransformerFactory</code> file
106 * in the JAR archives available to the runtime</li>
107 * <li>Finally, if all of the above options fail,
108 * a default implementation is chosen. In Sun's JDK 1.4, this is
109 * Xalan 2.2d10. </li>
110 * </ol>
111
112 * @version $Revision: 1.2 $, $Date: 2004/02/06 09:28:32 $
113 * @author Jason Hunter
114 * @author Elliotte Rusty Harold
115 */
116 public class XSLTransformer {
117
118 private static final String CVS_ID =
119 "@(#) $RCSfile: XSLTransformer.java,v $ $Revision: 1.2 $ $Date: 2004/02/06 09:28:32 $ $Name: jdom_1_0 $";
120
121 private Templates templates;
122
123 // Internal constructor to support the other constructors
124 private XSLTransformer(Source stylesheet) throws XSLTransformException {
125 try {
126 templates = TransformerFactory.newInstance()
127 .newTemplates(stylesheet);
128 }
129 catch (TransformerException e) {
130 throw new XSLTransformException("Could not construct XSLTransformer", e);
131 }
132 }
133
134 /**
135 * Creates a transformer for a given stylesheet system id.
136 *
137 * @param stylesheetSystemId source stylesheet as a Source object
138 * @throws XSLTransformException if there's a problem in the TrAX back-end
139 */
140 public XSLTransformer(String stylesheetSystemId) throws XSLTransformException {
141 this(new StreamSource(stylesheetSystemId));
142 }
143
144 /**
145 * <p>
146 * This will create a new <code>XSLTransformer</code> by
147 * reading the stylesheet from the specified
148 * <code>InputStream</code>.
149 * </p>
150 *
151 * @param stylesheet <code>InputStream</code> from which the stylesheet is read.
152 * @throws XSLTransformException when an IOException, format error, or
153 * something else prevents the stylesheet from being compiled
154 */
155 public XSLTransformer(InputStream stylesheet) throws XSLTransformException {
156 this(new StreamSource(stylesheet));
157 }
158
159 /**
160 * <p>
161 * This will create a new <code>XSLTransformer</code> by
162 * reading the stylesheet from the specified
163 * <code>Reader</code>.
164 * </p>
165 *
166 * @param stylesheet <code>Reader</code> from which the stylesheet is read.
167 * @throws XSLTransformException when an IOException, format error, or
168 * something else prevents the stylesheet from being compiled
169 */
170 public XSLTransformer(Reader stylesheet) throws XSLTransformException {
171 this(new StreamSource(stylesheet));
172 }
173
174 /**
175 * <p>
176 * This will create a new <code>XSLTransformer</code> by
177 * reading the stylesheet from the specified
178 * <code>File</code>.
179 * </p>
180 *
181 * @param stylesheet <code>File</code> from which the stylesheet is read.
182 * @throws XSLTransformException when an IOException, format error, or
183 * something else prevents the stylesheet from being compiled
184 */
185 public XSLTransformer(File stylesheet) throws XSLTransformException {
186 this(new StreamSource(stylesheet));
187 }
188
189 /**
190 * <p>
191 * This will create a new <code>XSLTransformer</code> by
192 * reading the stylesheet from the specified
193 * <code>Document</code>.
194 * </p>
195 *
196 * @param stylesheet <code>Document</code> containing the stylesheet.
197 * @throws XSLTransformException when the supplied <code>Document</code>
198 * is not syntactically correct XSLT
199 */
200 public XSLTransformer(Document stylesheet) throws XSLTransformException {
201 this(new JDOMSource(stylesheet));
202 }
203
204 /**
205 * Transforms the given input nodes to a list of output nodes.
206 *
207 * @param inputNodes input nodes
208 * @return transformed output nodes
209 * @throws XSLTransformException if there's a problem in the transformation
210 */
211 public List transform(List inputNodes) throws XSLTransformException {
212 JDOMSource source = new JDOMSource(inputNodes);
213 JDOMResult result = new JDOMResult();
214 try {
215 templates.newTransformer().transform(source, result);
216 return result.getResult();
217 }
218 catch (TransformerException e) {
219 throw new XSLTransformException("Could not perform transformation", e);
220 }
221 }
222
223 /**
224 * Transforms the given document to an output document.
225 *
226 * @param inputDoc input document
227 * @return transformed output document
228 * @throws XSLTransformException if there's a problem in the transformation
229 */
230 public Document transform(Document inputDoc) throws XSLTransformException {
231 JDOMSource source = new JDOMSource(inputDoc);
232 JDOMResult result = new JDOMResult();
233 try {
234 templates.newTransformer().transform(source, result);
235 return result.getDocument();
236 }
237 catch (TransformerException e) {
238 throw new XSLTransformException("Could not perform transformation", e);
239 }
240 }
241 }