diff options
Diffstat (limited to 'src/share/classes/javax/xml/transform/package.html')
| -rw-r--r-- | src/share/classes/javax/xml/transform/package.html | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/src/share/classes/javax/xml/transform/package.html b/src/share/classes/javax/xml/transform/package.html new file mode 100644 index 0000000..45c2d78 --- /dev/null +++ b/src/share/classes/javax/xml/transform/package.html @@ -0,0 +1,233 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- +Copyright (c) 2000, 2005, 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. +--> + +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <title>javax.xml.transform</title> + + <meta name="CVS" + content="$Id: package.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" /> + <meta name="AUTHOR" + content="Jeff.Suttor@Sun.com" /> +</head> + +<body> +<p>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. +</p> + +<p>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}. +</p> + + +<h3>Creating Objects</h3> + +<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}. +</p> + + +<h3>Specification of Inputs and Outputs</h3> + +<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. +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. +</p> + +<pre> +<code> +TransformerFactory tfactory = TransformerFactory.newInstance(); +if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) { +... +} +</code> +</pre> + + +<h3> +<a name="qname-delimiter">Qualified Name Representation</a> +</h3> + +<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> + +<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> + +<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> + +<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. +</p> + + +<h3>Result Tree Serialization</h3> + +<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> + +<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> + +<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. </p> + +<h3>Exceptions and Error Reporting</h3> + +<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> + +<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> + +<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> + +<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. +The default implementation provided by the processor will report all warnings and errors to <code>System.err</code> +and does not throw any <code>Exception</code>s. +Applications are <em>strongly</em> encouraged to register and use +<code>ErrorListener</code>s that insure proper behavior for warnings and +errors. +</p> + + +<h3>Resolution of URIs within a transformation</h3> + +<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.</p> + + +</body> +</html> |