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