| /* | |
| * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code is distributed in the hope that it will be useful, but WITHOUT | |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| /** | |
| * Defines the generic APIs for processing transformation instructions, | |
| * and performing a transformation from source to result. These interfaces have no | |
| * dependencies on SAX or the DOM standard, and try to make as few assumptions as | |
| * possible about the details of the source and result of a transformation. It | |
| * achieves this by defining {@link javax.xml.transform.Source} and | |
| * {@link javax.xml.transform.Result} interfaces. | |
| * | |
| * <p> | |
| * To provide concrete classes for the user, the API defines specializations | |
| * of the interfaces found at the root level. These interfaces are found in | |
| * {@link javax.xml.transform.sax}, {@link javax.xml.transform.dom}, | |
| * {@link javax.xml.transform.stax}, and {@link javax.xml.transform.stream}. | |
| * | |
| * | |
| * <h2>Creating Objects</h2> | |
| * | |
| * <p> | |
| * The API allows a concrete {@link javax.xml.transform.TransformerFactory} | |
| * object to be created from the static function | |
| * {@link javax.xml.transform.TransformerFactory#newInstance}. | |
| * | |
| * | |
| * <h2>Specification of Inputs and Outputs</h2> | |
| * | |
| * <p> | |
| * This API defines two interface objects called {@link javax.xml.transform.Source} | |
| * and {@link javax.xml.transform.Result}. In order to pass Source and Result | |
| * objects to the interfaces, concrete classes must be used. The following concrete | |
| * representations are defined for each of these objects: | |
| * {@link javax.xml.transform.stream.StreamSource} and | |
| * {@link javax.xml.transform.stream.StreamResult}, | |
| * {@link javax.xml.transform.stax.StAXSource} and | |
| * {@link javax.xml.transform.stax.StAXResult}, and | |
| * {@link javax.xml.transform.sax.SAXSource} and | |
| * {@link javax.xml.transform.sax.SAXResult}, and | |
| * {@link javax.xml.transform.dom.DOMSource} and | |
| * {@link javax.xml.transform.dom.DOMResult}. Each of these objects defines a | |
| * FEATURE string (which is in the form of a URL), which can be passed into | |
| * {@link javax.xml.transform.TransformerFactory#getFeature} to see if the given | |
| * type of Source or Result object is supported. For instance, to test if a | |
| * DOMSource and a StreamResult is supported, you can apply the following test. | |
| * | |
| * <pre> | |
| * <code> | |
| * TransformerFactory tfactory = TransformerFactory.newInstance(); | |
| * if (tfactory.getFeature(DOMSource.FEATURE) && | |
| * tfactory.getFeature(StreamResult.FEATURE)) { | |
| * ... | |
| * } | |
| * </code> | |
| * </pre> | |
| * | |
| * | |
| * <h2><a id="qname-delimiter">Qualified Name Representation</a></h2> | |
| * | |
| * <p> | |
| * <a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a> present something | |
| * of a problem area when dealing with XML objects. Qualified Names appear in XML | |
| * markup as prefixed names. But the prefixes themselves do not hold identity. | |
| * Rather, it is the URIs that they contextually map to that hold the identity. | |
| * Therefore, when passing a Qualified Name like "xyz:foo" among Java programs, | |
| * one must provide a means to map "xyz" to a namespace. | |
| * | |
| * <p> | |
| * One solution has been to create a "QName" object that holds the namespace URI, | |
| * as well as the prefix and local name, but this is not always an optimal solution, | |
| * as when, for example, you want to use unique strings as keys in a dictionary | |
| * object. Not having a string representation also makes it difficult to specify | |
| * a namespaced identity outside the context of an XML document. | |
| * | |
| * <p> | |
| * In order to pass namespaced values to transformations, for instance when setting | |
| * a property or a parameter on a {@link javax.xml.transform.Transformer} object, | |
| * this specification defines that a String "qname" object parameter be passed as | |
| * two-part string, the namespace URI enclosed in curly braces ({}), followed by | |
| * the local name. If the qname has a null URI, then the String object only | |
| * contains the local name. An application can safely check for a non-null URI by | |
| * testing to see if the first character of the name is a '{' character. | |
| * | |
| * <p> | |
| * For example, if a URI and local name were obtained from an element defined with | |
| * <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the | |
| * Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that the | |
| * prefix is lost. | |
| * | |
| * | |
| * <h2>Result Tree Serialization</h2> | |
| * | |
| * <p> | |
| * Serialization of the result tree to a stream can be controlled with the | |
| * {@link javax.xml.transform.Transformer#setOutputProperties} and the | |
| * {@link javax.xml.transform.Transformer#setOutputProperty} methods. | |
| * These properties only apply to stream results, they have no effect when | |
| * the result is a DOM tree or SAX event stream. | |
| * | |
| * <p> | |
| * Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT | |
| * specification for xsl:output attributes</a> can be referenced from the | |
| * {@link javax.xml.transform.OutputKeys} class. Other strings can be | |
| * specified as well. | |
| * If the transformer does not recognize an output key, a | |
| * {@link java.lang.IllegalArgumentException} is thrown, unless the key name | |
| * is <a href="#qname-delimiter">namespace qualified</a>. Output key names | |
| * that are namespace qualified are always allowed, although they may be | |
| * ignored by some implementations. | |
| * | |
| * <p> | |
| * If all that is desired is the simple identity transformation of a | |
| * source to a result, then {@link javax.xml.transform.TransformerFactory} | |
| * provides a | |
| * {@link javax.xml.transform.TransformerFactory#newTransformer()} method | |
| * with no arguments. This method creates a Transformer that effectively copies | |
| * the source to the result. This method may be used to create a DOM from SAX | |
| * events or to create an XML or HTML stream from a DOM or SAX events. | |
| * | |
| * <h2>Exceptions and Error Reporting</h2> | |
| * | |
| * <p> | |
| * The transformation API throw three types of specialized exceptions. A | |
| * {@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to | |
| * the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown | |
| * when a configuration problem with the TransformerFactory exists. This error | |
| * will typically be thrown when the transformation factory class specified with | |
| * the "javax.xml.transform.TransformerFactory" system property cannot be found or | |
| * instantiated. | |
| * | |
| * <p> | |
| * A {@link javax.xml.transform.TransformerConfigurationException} | |
| * may be thrown if for any reason a Transformer can not be created. A | |
| * TransformerConfigurationException may be thrown if there is a syntax error in | |
| * the transformation instructions, for example when | |
| * {@link javax.xml.transform.TransformerFactory#newTransformer} is | |
| * called. | |
| * | |
| * <p> | |
| * {@link javax.xml.transform.TransformerException} is a general | |
| * exception that occurs during the course of a transformation. A transformer | |
| * exception may wrap another exception, and if any of the | |
| * {@link javax.xml.transform.TransformerException#printStackTrace()} | |
| * methods are called on it, it will produce a list of stack dumps, starting from | |
| * the most recent. The transformer exception also provides a | |
| * {@link javax.xml.transform.SourceLocator} object which indicates where | |
| * in the source tree or transformation instructions the error occurred. | |
| * {@link javax.xml.transform.TransformerException#getMessageAndLocation()} | |
| * may be called to get an error message with location info, and | |
| * {@link javax.xml.transform.TransformerException#getLocationAsString()} | |
| * may be called to get just the location string. | |
| * | |
| * <p> | |
| * Transformation warnings and errors are sent to an | |
| * {@link javax.xml.transform.ErrorListener}, at which point the application may | |
| * decide to report the error or warning, and may decide to throw an | |
| * <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> | |
| * may be set via {@link javax.xml.transform.TransformerFactory#setErrorListener} | |
| * for reporting errors that have to do with syntax errors in the transformation | |
| * instructions, or via {@link javax.xml.transform.Transformer#setErrorListener} | |
| * to report errors that occur during the transformation. The <code>ErrorListener</code> | |
| * on both objects will always be valid and non-<code>null</code>, whether set by | |
| * the application or a default implementation provided by the processor. | |
| * | |
| * | |
| * <h2>Resolution of URIs within a transformation</h2> | |
| * | |
| * <p> | |
| * The API provides a way for URIs referenced from within the stylesheet | |
| * instructions or within the transformation to be resolved by the calling | |
| * application. This can be done by creating a class that implements the | |
| * {@link javax.xml.transform.URIResolver} interface, with its one method, | |
| * {@link javax.xml.transform.URIResolver#resolve}, and use this class to | |
| * set the URI resolution for the transformation instructions or transformation | |
| * with {@link javax.xml.transform.TransformerFactory#setURIResolver} or | |
| * {@link javax.xml.transform.Transformer#setURIResolver}. The | |
| * <code>URIResolver.resolve</code> method takes two String arguments, the URI | |
| * found in the stylesheet instructions or built as part of the transformation | |
| * process, and the base URI against which the first argument will be made absolute | |
| * if the absolute URI is required. | |
| * The returned {@link javax.xml.transform.Source} object must be usable by | |
| * the transformer, as specified in its implemented features. | |
| * | |
| * @since 1.5 | |
| */ | |
| package javax.xml.transform; |