1 <!doctype html> |
|
2 <!-- |
|
3 Copyright (c) 2000, 2017, 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> |
|