* 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}. * * *
* The API allows a concrete {@link javax.xml.transform.TransformerFactory} * object to be created from the static function * {@link javax.xml.transform.TransformerFactory#newInstance}. * * *
* 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. * *
*
* TransformerFactory tfactory = TransformerFactory.newInstance();
* if (tfactory.getFeature(DOMSource.FEATURE) &&
* tfactory.getFeature(StreamResult.FEATURE)) {
* ...
* }
*
*
*
*
* * Namespaces 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. * *
* 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. * *
* 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. * *
* 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. * * *
* 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. * *
* Strings that match the XSLT * specification for xsl:output attributes 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 namespace qualified. Output key names * that are namespace qualified are always allowed, although they may be * ignored by some implementations. * *
* 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. * *
* 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. * *
* 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. * *
* {@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. * *
* 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
* Exception for a non-fatal error. The ErrorListener
* 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 ErrorListener
* on both objects will always be valid and non-null, whether set by
* the application or a default implementation provided by the processor.
* The default implementation provided by the processor will report all warnings
* and errors to System.err and does not throw any Exceptions.
* Applications are strongly encouraged to register and use
* ErrorListeners that insure proper behavior for warnings and
* errors.
*
*
*
* 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
* URIResolver.resolve 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;