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 165 * exception that occurs during the course of a transformation. A transformer 166 * exception may wrap another exception, and if any of the 167 * {@link javax.xml.transform.TransformerException#printStackTrace()} 168 * methods are called on it, it will produce a list of stack dumps, starting from 169 * the most recent. The transformer exception also provides a 170 * {@link javax.xml.transform.SourceLocator} object which indicates where 171 * in the source tree or transformation instructions the error occurred. 172 * {@link javax.xml.transform.TransformerException#getMessageAndLocation()} 173 * may be called to get an error message with location info, and 174 * {@link javax.xml.transform.TransformerException#getLocationAsString()} 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 216package javax.xml.transform; 217