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 

   216 package javax.xml.transform;