--- old/src/java.xml/share/classes/javax/xml/transform/package.html 2017-05-23 09:36:11.773560600 -0700 +++ /dev/null 2017-01-27 21:23:58.368196991 -0800 @@ -1,229 +0,0 @@ - - - - - - - javax.xml.transform - - - - - - -

This package 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. -

- -

To define 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}, -and {@link javax.xml.transform.stream}. -

- - -

Creating Objects

- -

The API allows a concrete -{@link javax.xml.transform.TransformerFactory} object to be created from -the static function -{@link javax.xml.transform.TransformerFactory#newInstance}. -

- - -

Specification of Inputs and Outputs

- -

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. -Three 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.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 i 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)) {
-...
-}
-
-
- - -

-Qualified Name Representation -

- -

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. -

- - -

Result Tree Serialization

- -

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.

- -

Exceptions and Error Reporting

- -

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. -

- - -

Resolution of URIs within a transformation

- -

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.

- - - -