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