--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/package.html Sun Aug 17 15:51:56 2014 +0100
@@ -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>