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