xml/transform/package.html

286N/A<?xml version="1.0" encoding="UTF-8"?>
286N/A<!--
286N/ACopyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
286N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
286N/A
286N/AThis code is free software; you can redistribute it and/or modify it
286N/Aunder the terms of the GNU General Public License version 2 only, as
286N/Apublished by the Free Software Foundation.  Oracle designates this
286N/Aparticular file as subject to the "Classpath" exception as provided
286N/Aby Oracle in the LICENSE file that accompanied this code.
286N/A
286N/AThis code is distributed in the hope that it will be useful, but WITHOUT
286N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
286N/AFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
286N/Aversion 2 for more details (a copy is included in the LICENSE file that
286N/Aaccompanied this code).
286N/A
286N/AYou should have received a copy of the GNU General Public License version
286N/A2 along with this work; if not, write to the Free Software Foundation,
286N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
286N/A
286N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
286N/Aor visit www.oracle.com if you need additional information or have any
286N/Aquestions.
286N/A-->
286N/A
286N/A<!DOCTYPE html
286N/A     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
286N/A     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
286N/A
286N/A<html xmlns="http://www.w3.org/1999/xhtml">
286N/A
286N/A<head>
286N/A  <title>javax.xml.transform</title>
286N/A
286N/A  <meta name="CVS"
286N/A        content="$Id: package.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" />
286N/A  <meta name="AUTHOR"
286N/A        content="Jeff.Suttor@Sun.com" />
286N/A</head>
286N/A
286N/A<body>
286N/A<p>This package defines the generic APIs for processing transformation
286N/Ainstructions, and performing a transformation from source to result. These
286N/Ainterfaces have no dependencies on SAX or the DOM standard, and try to make as
286N/Afew assumptions as possible about the details of the source and result of a
286N/Atransformation. It achieves this by defining
286N/A{@link javax.xml.transform.Source} and
286N/A{@link javax.xml.transform.Result} interfaces.
286N/A</p>
286N/A
286N/A<p>To define concrete classes for the user, the API defines specializations
286N/Aof the interfaces found at the root level. These interfaces are found in
286N/A{@link javax.xml.transform.sax}, {@link javax.xml.transform.dom},
286N/Aand {@link javax.xml.transform.stream}.
286N/A</p>
286N/A
286N/A
286N/A<h3>Creating Objects</h3>
286N/A
286N/A<p>The API allows a concrete
286N/A{@link javax.xml.transform.TransformerFactory} object to be created from
286N/Athe static function
286N/A{@link javax.xml.transform.TransformerFactory#newInstance}.
286N/A</p>
286N/A
286N/A
286N/A<h3>Specification of Inputs and Outputs</h3>
286N/A
286N/A<p>This API defines two interface objects called
286N/A{@link javax.xml.transform.Source} and
286N/A{@link javax.xml.transform.Result}. In order to pass Source and Result
286N/Aobjects to the interfaces, concrete classes must be used.
286N/AThree concrete representations are defined for each of these
286N/Aobjects:
286N/A{@link javax.xml.transform.stream.StreamSource} and
286N/A{@link javax.xml.transform.stream.StreamResult},
286N/A{@link javax.xml.transform.sax.SAXSource} and
286N/A{@link javax.xml.transform.sax.SAXResult}, and
286N/A{@link javax.xml.transform.dom.DOMSource} and
286N/A{@link javax.xml.transform.dom.DOMResult}. Each of these objects defines
286N/Aa FEATURE string (which is i the form of a URL), which can be passed into
286N/A{@link javax.xml.transform.TransformerFactory#getFeature} to see if the
286N/Agiven type of Source or Result object is supported. For instance, to test if a
286N/ADOMSource and a StreamResult is supported, you can apply the following
286N/Atest.
286N/A</p>
286N/A
286N/A<pre>
286N/A<code>
286N/ATransformerFactory tfactory = TransformerFactory.newInstance();
286N/Aif (tfactory.getFeature(DOMSource.FEATURE) &amp;&amp; tfactory.getFeature(StreamResult.FEATURE)) {
286N/A...
286N/A}
286N/A</code>
286N/A</pre>
286N/A
286N/A
286N/A<h3>
286N/A<a name="qname-delimiter">Qualified Name Representation</a>
286N/A</h3>
286N/A
286N/A<p><a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a>
286N/Apresent something of a problem area when dealing with XML objects. Qualified
286N/ANames appear in XML markup as prefixed names. But the prefixes themselves do
286N/Anot hold identity. Rather, it is the URIs that they contextually map to that
286N/Ahold the identity. Therefore, when passing a Qualified Name like "xyz:foo"
286N/Aamong Java programs, one must provide a means to map "xyz" to a namespace.
286N/A</p>
286N/A
286N/A<p>One solution has been to create a "QName" object that holds the
286N/Anamespace URI, as well as the prefix and local name, but this is not always an
286N/Aoptimal solution, as when, for example, you want to use unique strings as keys
286N/Ain a dictionary object. Not having a string representation also makes it
286N/Adifficult to specify a namespaced identity outside the context of an XML
286N/Adocument.
286N/A</p>
286N/A
286N/A<p>In order to pass namespaced values to transformations,
286N/Afor
286N/Ainstance when setting a property or a parameter on a
286N/A{@link javax.xml.transform.Transformer} object,
286N/Athis specification defines that a
286N/AString "qname" object parameter be passed as two-part string, the namespace URI
286N/Aenclosed in curly braces ({}), followed by the local name. If the qname has a
286N/Anull URI, then the String object only contains the local name. An application
286N/Acan safely check for a non-null URI by testing to see if the first character of
286N/Athe name is a '{' character.
286N/A</p>
286N/A
286N/A<p>For example, if a URI and local name were obtained from an element
286N/Adefined with &lt;xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
286N/Athen the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo".
286N/ANote that the prefix is lost.
286N/A</p>
286N/A
286N/A
286N/A<h3>Result Tree Serialization</h3>
286N/A
286N/A<p>Serialization of the result tree to a stream can be controlled with
286N/Athe {@link javax.xml.transform.Transformer#setOutputProperties} and the
286N/A{@link javax.xml.transform.Transformer#setOutputProperty} methods.
286N/AThese properties only apply to stream results, they have no effect when
286N/Athe result is a DOM tree or SAX event stream.</p>
286N/A
286N/A<p>Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT
286N/Aspecification for xsl:output attributes</a> can be referenced from the
286N/A{@link javax.xml.transform.OutputKeys} class. Other strings can be
286N/Aspecified as well.
286N/AIf the transformer does not recognize an output key, a
286N/A{@link java.lang.IllegalArgumentException} is thrown, unless the
286N/Akey name is <a href="#qname-delimiter">namespace qualified</a>. Output key names
286N/Athat are namespace qualified are always allowed, although they may be
286N/Aignored by some implementations.</p>
286N/A
286N/A<p>If all that is desired is the simple identity transformation of a
286N/Asource to a result, then {@link javax.xml.transform.TransformerFactory}
286N/Aprovides a
286N/A{@link javax.xml.transform.TransformerFactory#newTransformer()} method
286N/Awith no arguments. This method creates a Transformer that effectively copies
286N/Athe source to the result. This method may be used to create a DOM from SAX
286N/Aevents or to create an XML or HTML stream from a DOM or SAX events.  </p>
286N/A
286N/A<h3>Exceptions and Error Reporting</h3>
286N/A
286N/A<p>The transformation API throw three types of specialized exceptions. A
286N/A{@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to
286N/Athe {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown
286N/Awhen a configuration problem with the TransformerFactory exists. This error
286N/Awill typically be thrown when the transformation factory class specified with
286N/Athe "javax.xml.transform.TransformerFactory" system property cannot be found or
286N/Ainstantiated.</p>
286N/A
286N/A<p>A {@link javax.xml.transform.TransformerConfigurationException}
286N/Amay be thrown if for any reason a Transformer can not be created. A
286N/ATransformerConfigurationException may be thrown if there is a syntax error in
286N/Athe transformation instructions, for example when
286N/A{@link javax.xml.transform.TransformerFactory#newTransformer} is
286N/Acalled.</p>
286N/A
286N/A<p>{@link javax.xml.transform.TransformerException} is a general
286N/Aexception that occurs during the course of a transformation. A transformer
286N/Aexception may wrap another exception, and if any of the
286N/A{@link javax.xml.transform.TransformerException#printStackTrace()}
286N/Amethods are called on it, it will produce a list of stack dumps, starting from
286N/Athe most recent. The transformer exception also provides a
286N/A{@link javax.xml.transform.SourceLocator} object which indicates where
286N/Ain the source tree or transformation instructions the error occurred.
286N/A{@link javax.xml.transform.TransformerException#getMessageAndLocation()}
286N/Amay be called to get an error message with location info, and
286N/A{@link javax.xml.transform.TransformerException#getLocationAsString()}
286N/Amay be called to get just the location string.</p>
286N/A
286N/A<p>Transformation warnings and errors are sent to an
286N/A{@link javax.xml.transform.ErrorListener}, at which point the
286N/Aapplication may decide to report the error or warning, and may decide to throw
286N/Aan <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> may be set via
286N/A{@link javax.xml.transform.TransformerFactory#setErrorListener} for
286N/Areporting errors that have to do with syntax errors in the transformation
286N/Ainstructions, or via
286N/A{@link javax.xml.transform.Transformer#setErrorListener} to report
286N/Aerrors that occur during the transformation. The <code>ErrorListener</code> on both objects
286N/Awill always be valid and non-<code>null</code>, whether set by the application or a default
286N/Aimplementation provided by the processor.
286N/AThe default implementation provided by the processor will report all warnings and errors to <code>System.err</code>
286N/Aand does not throw any <code>Exception</code>s.
286N/AApplications are <em>strongly</em> encouraged to register and use
286N/A<code>ErrorListener</code>s that insure proper behavior for warnings and
286N/Aerrors.
286N/A</p>
286N/A
286N/A
286N/A<h3>Resolution of URIs within a transformation</h3>
286N/A
286N/A<p>The API provides a way for URIs referenced from within the stylesheet
286N/Ainstructions or within the transformation to be resolved by the calling
286N/Aapplication. This can be done by creating a class that implements the
286N/A{@link javax.xml.transform.URIResolver} interface, with its one method,
286N/A{@link javax.xml.transform.URIResolver#resolve}, and use this class to
286N/Aset the URI resolution for the transformation instructions or transformation
286N/Awith {@link javax.xml.transform.TransformerFactory#setURIResolver} or
286N/A{@link javax.xml.transform.Transformer#setURIResolver}. The
286N/A<code>URIResolver.resolve</code> method takes two String arguments, the URI found in the
286N/Astylesheet instructions or built as part of the transformation process, and the
286N/Abase URI
286N/Aagainst which the first argument will be made absolute if the
286N/Aabsolute URI is required.
286N/AThe returned {@link javax.xml.transform.Source} object must be usable by
286N/Athe transformer, as specified in its implemented features.</p>
286N/A
286N/A
286N/A</body>
286N/A</html>