1 <!doctype html>
2 <!--
3 Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5
6 This code is free software; you can redistribute it and/or modify it
7 under the terms of the GNU General Public License version 2 only, as
8 published by the Free Software Foundation. Oracle designates this
9 particular file as subject to the "Classpath" exception as provided
10 by Oracle in the LICENSE file that accompanied this code.
11
12 This code is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 version 2 for more details (a copy is included in the LICENSE file that
16 accompanied this code).
17
18 You should have received a copy of the GNU General Public License version
19 2 along with this work; if not, write to the Free Software Foundation,
20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21
22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23 or visit www.oracle.com if you need additional information or have any
24 questions.
25 -->
26
27 <html>
28
29 <head>
30 <title>javax.xml.transform</title>
31
32 <meta name="CVS"
33 content="$Id: package.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" />
34 <meta name="AUTHOR"
35 content="Jeff.Suttor@Sun.com" />
36 </head>
37
38 <body>
39 <p>This package defines the generic APIs for processing transformation
40 instructions, and performing a transformation from source to result. These
41 interfaces have no dependencies on SAX or the DOM standard, and try to make as
42 few assumptions as possible about the details of the source and result of a
43 transformation. It achieves this by defining
44 {@link javax.xml.transform.Source} and
45 {@link javax.xml.transform.Result} interfaces.
46 </p>
47
48 <p>To define concrete classes for the user, the API defines specializations
49 of the interfaces found at the root level. These interfaces are found in
50 {@link javax.xml.transform.sax}, {@link javax.xml.transform.dom},
51 and {@link javax.xml.transform.stream}.
52 </p>
53
54
55 <h3>Creating Objects</h3>
56
57 <p>The API allows a concrete
58 {@link javax.xml.transform.TransformerFactory} object to be created from
59 the static function
60 {@link javax.xml.transform.TransformerFactory#newInstance}.
61 </p>
62
63
64 <h3>Specification of Inputs and Outputs</h3>
65
66 <p>This API defines two interface objects called
67 {@link javax.xml.transform.Source} and
68 {@link javax.xml.transform.Result}. In order to pass Source and Result
69 objects to the interfaces, concrete classes must be used.
70 Three concrete representations are defined for each of these
71 objects:
72 {@link javax.xml.transform.stream.StreamSource} and
73 {@link javax.xml.transform.stream.StreamResult},
74 {@link javax.xml.transform.sax.SAXSource} and
75 {@link javax.xml.transform.sax.SAXResult}, and
76 {@link javax.xml.transform.dom.DOMSource} and
77 {@link javax.xml.transform.dom.DOMResult}. Each of these objects defines
78 a FEATURE string (which is i the form of a URL), which can be passed into
79 {@link javax.xml.transform.TransformerFactory#getFeature} to see if the
80 given type of Source or Result object is supported. For instance, to test if a
81 DOMSource and a StreamResult is supported, you can apply the following
82 test.
83 </p>
84
85 <pre>
86 <code>
87 TransformerFactory tfactory = TransformerFactory.newInstance();
88 if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) {
89 ...
90 }
91 </code>
92 </pre>
93
94
95 <h3>
96 <a id="qname-delimiter">Qualified Name Representation</a>
97 </h3>
98
99 <p><a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a>
100 present something of a problem area when dealing with XML objects. Qualified
101 Names appear in XML markup as prefixed names. But the prefixes themselves do
102 not hold identity. Rather, it is the URIs that they contextually map to that
103 hold the identity. Therefore, when passing a Qualified Name like "xyz:foo"
104 among Java programs, one must provide a means to map "xyz" to a namespace.
105 </p>
106
107 <p>One solution has been to create a "QName" object that holds the
108 namespace URI, as well as the prefix and local name, but this is not always an
109 optimal solution, as when, for example, you want to use unique strings as keys
110 in a dictionary object. Not having a string representation also makes it
111 difficult to specify a namespaced identity outside the context of an XML
112 document.
113 </p>
114
115 <p>In order to pass namespaced values to transformations,
116 for
117 instance when setting a property or a parameter on a
118 {@link javax.xml.transform.Transformer} object,
119 this specification defines that a
120 String "qname" object parameter be passed as two-part string, the namespace URI
121 enclosed in curly braces ({}), followed by the local name. If the qname has a
122 null URI, then the String object only contains the local name. An application
123 can safely check for a non-null URI by testing to see if the first character of
124 the name is a '{' character.
125 </p>
126
127 <p>For example, if a URI and local name were obtained from an element
128 defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
129 then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo".
130 Note that the prefix is lost.
131 </p>
132
133
134 <h3>Result Tree Serialization</h3>
135
136 <p>Serialization of the result tree to a stream can be controlled with
137 the {@link javax.xml.transform.Transformer#setOutputProperties} and the
138 {@link javax.xml.transform.Transformer#setOutputProperty} methods.
139 These properties only apply to stream results, they have no effect when
140 the result is a DOM tree or SAX event stream.</p>
141
142 <p>Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT
143 specification for xsl:output attributes</a> can be referenced from the
144 {@link javax.xml.transform.OutputKeys} class. Other strings can be
145 specified as well.
146 If the transformer does not recognize an output key, a
147 {@link java.lang.IllegalArgumentException} is thrown, unless the
148 key name is <a href="#qname-delimiter">namespace qualified</a>. Output key names
149 that are namespace qualified are always allowed, although they may be
150 ignored by some implementations.</p>
151
152 <p>If all that is desired is the simple identity transformation of a
153 source to a result, then {@link javax.xml.transform.TransformerFactory}
154 provides a
155 {@link javax.xml.transform.TransformerFactory#newTransformer()} method
156 with no arguments. This method creates a Transformer that effectively copies
157 the source to the result. This method may be used to create a DOM from SAX
158 events or to create an XML or HTML stream from a DOM or SAX events. </p>
159
160 <h3>Exceptions and Error Reporting</h3>
161
162 <p>The transformation API throw three types of specialized exceptions. A
163 {@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to
164 the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown
165 when a configuration problem with the TransformerFactory exists. This error
166 will typically be thrown when the transformation factory class specified with
167 the "javax.xml.transform.TransformerFactory" system property cannot be found or
168 instantiated.</p>
169
170 <p>A {@link javax.xml.transform.TransformerConfigurationException}
171 may be thrown if for any reason a Transformer can not be created. A
172 TransformerConfigurationException may be thrown if there is a syntax error in
173 the transformation instructions, for example when
174 {@link javax.xml.transform.TransformerFactory#newTransformer} is
175 called.</p>
176
177 <p>{@link javax.xml.transform.TransformerException} is a general
178 exception that occurs during the course of a transformation. A transformer
179 exception may wrap another exception, and if any of the
180 {@link javax.xml.transform.TransformerException#printStackTrace()}
181 methods are called on it, it will produce a list of stack dumps, starting from
182 the most recent. The transformer exception also provides a
183 {@link javax.xml.transform.SourceLocator} object which indicates where
184 in the source tree or transformation instructions the error occurred.
185 {@link javax.xml.transform.TransformerException#getMessageAndLocation()}
186 may be called to get an error message with location info, and
187 {@link javax.xml.transform.TransformerException#getLocationAsString()}
188 may be called to get just the location string.</p>
189
190 <p>Transformation warnings and errors are sent to an
191 {@link javax.xml.transform.ErrorListener}, at which point the
192 application may decide to report the error or warning, and may decide to throw
193 an <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> may be set via
194 {@link javax.xml.transform.TransformerFactory#setErrorListener} for
195 reporting errors that have to do with syntax errors in the transformation
196 instructions, or via
197 {@link javax.xml.transform.Transformer#setErrorListener} to report
198 errors that occur during the transformation. The <code>ErrorListener</code> on both objects
199 will always be valid and non-<code>null</code>, whether set by the application or a default
200 implementation provided by the processor.
201 The default implementation provided by the processor will report all warnings and errors to <code>System.err</code>
202 and does not throw any <code>Exception</code>s.
203 Applications are <em>strongly</em> encouraged to register and use
204 <code>ErrorListener</code>s that insure proper behavior for warnings and
205 errors.
206 </p>
207
208
209 <h3>Resolution of URIs within a transformation</h3>
210
211 <p>The API provides a way for URIs referenced from within the stylesheet
212 instructions or within the transformation to be resolved by the calling
213 application. This can be done by creating a class that implements the
214 {@link javax.xml.transform.URIResolver} interface, with its one method,
215 {@link javax.xml.transform.URIResolver#resolve}, and use this class to
216 set the URI resolution for the transformation instructions or transformation
217 with {@link javax.xml.transform.TransformerFactory#setURIResolver} or
218 {@link javax.xml.transform.Transformer#setURIResolver}. The
219 <code>URIResolver.resolve</code> method takes two String arguments, the URI found in the
220 stylesheet instructions or built as part of the transformation process, and the
221 base URI
222 against which the first argument will be made absolute if the
223 absolute URI is required.
224 The returned {@link javax.xml.transform.Source} object must be usable by
225 the transformer, as specified in its implemented features.</p>
226
227
228 </body>
229 </html>