You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sb...@locus.apache.org on 2000/11/15 03:34:32 UTC
cvs commit: xml-xalan/java/src/javax/xml/transform/stream StreamResult.java StreamSource.java package.html
sboag 00/11/14 18:34:32
Modified: java/src/javax/xml/transform ErrorListener.java package.html
java/src/javax/xml/transform/dom DOMResult.java
DOMSource.java package.html
java/src/javax/xml/transform/sax SAXResult.java
SAXSource.java SAXTransformerFactory.java
TemplatesHandler.java package.html
java/src/javax/xml/transform/stream StreamResult.java
StreamSource.java package.html
Log:
Changed TemplateHandler#setSystemID to TemplateHandler#setSystemId.
Delete the Features class, and define FEATURE variables on
the Source and Result derived classes, as well as on SAXTransformerFactory
and also define FEATURE_XMLFILTER on SAXTransformerFactory.
The overview is now broken from the javax.xml.transform package doc.
Other minor javadoc fixes.
Revision Changes Path
1.3 +1 -1 xml-xalan/java/src/javax/xml/transform/ErrorListener.java
Index: ErrorListener.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/ErrorListener.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ErrorListener.java 2000/11/14 17:02:39 1.2
+++ ErrorListener.java 2000/11/15 02:34:31 1.3
@@ -58,7 +58,7 @@
/**
* <p>To provide customized error handling, implement this interface and
- * use the setErrorListener method to register an instance of the implmeentation
+ * use the setErrorListener method to register an instance of the implmentation
* with the Transformer. The Transformer then reports all errors and warnings through this interface.</p>
*
* <p>If an application does <em>not</em>
1.4 +154 -441 xml-xalan/java/src/javax/xml/transform/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/package.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- package.html 2000/11/13 16:26:28 1.3
+++ package.html 2000/11/15 02:34:31 1.4
@@ -2,312 +2,23 @@
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>
-</title>
+<title>javax.xml.transform</title>
</head>
-<body>
- <h2>Transformations API For XML (TrAX)</h2>
- <p>
-<b>Edit Date: </b>November 12, 2000</p>
-
-
- <h3>Introduction</h3>
- <p>This overview describes the set of APIs contained in
- javax.xml.transform. These interfaces are referred to, for the sake of brevity,
- as TrAX (Transformations for XML). </p>
- <p>There is a broad need for Java applications to be able to transform XML
- and related tree-shaped data structures. In fact, XML is not normally very
- useful to an application without going through some sort of transformation,
- unless the semantic structure is used directly as data. Almost all xml-related
- applications need to perform transformations. Transformations may be described
- by Java code, Perl code, <A href="http://www.w3.org/TR/xslt">XSLT</A>
- Stylesheets, other types of script, or by proprietary formats. The inputs, one
- or multiple, to a transformation, may be a URL, XML stream, a DOM tree, SAX
- Events, or a proprietary format or data structure. The output types are the
- pretty much the same types as the inputs, but different inputs may need to be
- combined with different outputs.</p>
- <p>The great challenge of a transformation API is how to deal with
- combinations of inputs and outputs, without becoming specialized for any of the
- given types.</p>
- <p>The Java community will greatly benefit from a common API that will
- allow them to understand and apply a single model, write to consistent
- interfaces, and apply the transformations polymorphically. TrAX attempts to
- define a model that is clean and generic, yet will fill the requirements of
- general applications across a great variety of uses. </p>
-
- <h3>General Terminology</h3>
- <p>This section will explain some general terminology used in this
- document. Technical terminology will be explained in the Model section. In many
- cases, the general terminology overlaps with the technical terminology.</p>
- <ul>
-<li>
-<p>
-<b>Tree</b>
-<br>This term, as used within this document, describes an
- abstract structure that consists of nodes or events that may be produced by
- XML. A Tree physically may be a DOM tree, a series of well balanced parse
- events (such as those coming from a SAX2 ContentHander), a series of requests
- (the result of which can describe a tree), or a stream of marked-up
- characters.</p>
-</li>
-<li>
-<p>
-<b>Source Tree(s)</b>
-<br>One or more trees that are the inputs to the
- transformation.</p>
-</li>
-<li>
-<p>
-<b>Result Tree(s)</b>
-<br>One or more trees that are the output of the
- transformation.</p>
-</li>
-<li>
-<p>
-<b>Transformation</b>
-<br>The processor of consuming a stream or tree to produce
- another stream or tree.</p>
-</li>
-<li>
-<p>
-<b>Identity (or Copy) Transformation</b>
-<br>The process of transformation from a source to a result,
- making as few structural changes as possible and no informational changes. The
- term is somewhat loosely used, as the process is really a copy.</p>
-</li>
-<li>
-<p>
-<b>Serialization</b>
-<br>The process of taking a tree and turning it into a stream. In
- some sense, serialization is a specialization of transformation.</p>
-</li>
-<li>
-<p>
-<b>Parsing</b>
-<br>The process of taking a stream and turning it into a tree. In
- some sense, parsing is a specialization of transformation.</p>
-</li>
-<li>
-<p>
-<b>Transformer</b>
-<br>A transformer is the thing that executes the transformation.
- </p>
-</li>
-<li>
-<p>
-<b>Transformation instructions</b>
-<br>Describes the transformation. A form of code, script, or
- simply a declaration or series of declarations.</p>
-</li>
-<li>
-<p>
-<b>Stylesheet</b>
-<br>The same as "transformation instructions", except it is
- likely to be used in conjunction with <A href="http://www.w3.org/TR/xslt">XSLT</A>.</p>
-</li>
-<li>
-<p>
-<b>Template or Templates</b>
-<br>Another form of "transformation instructions", except in the
- TrAX interface it is used to describe the processed transformation
- instructions. A template is an object through which the source flows, to be
- formed into the result.</p>
-</li>
-<li>
-<p>
-<b>Processor</b>
-<br>A general term for the thing that may both process the
- transformation instructions, and perform the transformation.</p>
-</li>
-<li>
-<p>
-<b>DOM</b>
-<br>Document Object Model, specifically referring to the
- <A href="#http://www.w3.org/TR/DOM-Level-2 ">Document Object Model
- (DOM) Level 2 Specification</A>.</p>
-</li>
-<li>
-<p>
-<b>SAX</b>
-<br>Simple API for XML, specifically referring to the
- <A href="#http://www.megginson.com/SAX/SAX2">SAX 2.0
- release</A>.</p>
-</li>
-</ul>
-
- <h3>Requirements</h3>
- <p>The following requirements have been determined from broad experience
- with XML projects from the various members participating on the JCP.</p>
- <ol>
-<li>TrAX must provide a clean, simple
- interface for simple uses.</li>
-<li>TrAX must be powerful enough to be
- applied to a wide range of uses, such as, e-commerce, content management,
- server content delivery, and client applications.</li>
-<li>A processor that implements a TrAX
- interface must be optimizeable. Performance is a critical issue for most
- transformation use cases.</li>
-<li>As a specialization of the above
- requirement, a TrAX processor must be able to support a compiled model, so that
- a single set of transformation instructions can be compiled, optimized, and
- applied to a large set of input sources.</li>
-<li>TrAX must not be dependent an any
- given type of transformation instructions. For instance, it must remain
- independent of <A href="http://www.w3.org/TR/xslt">XSLT</A>.</li>
-<li>TrAX must be able to allow processors
- to transform DOM trees.</li>
-<li>TrAX must be able to allow processors to
- produce DOM trees.</li>
-<li>TrAX must be able to allow processors
- to transform SAX events.</li>
-<li>TrAX must be able to allow processors to
- produce SAX events.</li>
-<li>TrAX must be able to allow
- processors to transform streams of XML.</li>
-<li>TrAX must be able to allow processors
- to produce XML, HTML, and other types of streams.</li>
-<li>TrAX must be able to allow
- processors to implement the various combinations of inputs and outputs within a
- single processor.</li>
-<li>TrAX must be able to allow
- processors to implement only a limited set of inputs. For instance, it should
- be possible to write a processor that implements the TrAX interfaces that only
- processor DOM trees, not streams or SAX events.</li>
-<li>TrAX should allow a
- processor to implement transformations of proprietary data structures. For
- instance, it should be possible to implement a processor that provides TrAX
- interfaces that performs transformation of JDOM trees.</li>
-<li>TrAX must be able to allow
- the setting of serialization properties, without constraint as to what the
- details of those properties are.</li>
-<li>TrAX must allow the setting
- of parameters to the transformation instructions.</li>
-<li>TrAX must be able to
- support the setting of parameters and properties as XML Namespaced items (i.e.
- qualified names).</li>
-<li>TrAX must be able to
- support URL resolution from within the transformation, and have it return the
- needed data structure.</li>
-<li>TrAX must have a mechanism for
- reporting of errors and warnings by the calling application.</li>
-</ol>
- <h3>Model</h3>
- <p>The section defines the abstract model for TrAX, apart from the details
- of the interfaces.</p>
- <p>A TRaX <A href="#pattern-TransformerFactory">TransformerFactory</A> is an object
- that processes transformation instructions, and produces
- <A href="#pattern-Templates">Templates</A> (in the technical
- terminology). The <A href="#pattern-Templates">Templates</A>
- provide <A href="#pattern-Transformer">Transformer</A>, which
- transform one or more <A href="#pattern-Source">Source</A>s into
- one or more <A href="#pattern-Result">Result</A>s.</p>
- <p>To use the TRaX interface, you create a
- <A href="#pattern-TransformerFactory">TransformerFactory</A>,
- which may directly provide <A href="#pattern-Transformers">Transformers</A>, or which can provide
- <A href="#pattern-Templates">Templates</A> from a variety of
- <A href="#pattern-Source">Source</A>s. The
- <A href="#pattern-Templates">Templates</A> object is normally a
- processed or compiled representation of the transformation instructions, and
- provides a <A href="#pattern-Transformer">Transformer</A>. The
- <A href="#pattern-Transformer">Transformer</A> processes a
- <A href="#pattern-Transformer">Source</A> according to the
- instructions found in the <A href="#pattern-Templates">Templates</A>, and produces a
- <A href="#pattern-Result">Result</A>.</p>
- <p>The process of transformation from a tree, either in the form of an
- object model, or in the form of parse events, into a stream, is known as
- <U>serialization</U>. This term, although it overlaps with Java
- object serialization, is the best description of this process.</p>
- <H3>TRaX Patterns</H3>
-<ul>
-<p>
-<b><a name="pattern-Processor">Processor</a></b>
-<br>
-<br>
-<i>Intent: </i>Generic concept for the
- set of objects that implement the TrAX
- interfaces.<br>
-<i>Responsibilities: </i>Create compiled transformation
- instructions, transform resources, and manager parameters and properties of
- those transformations.<br>
-<i>Thread safety: </i>Only the Templates
- object can be used concurrently in multiple threads. The rest of the processor
- does not do synchronized blocking, and so can not be used
- concurrently.</p>
-<p>
-<b><a name="pattern-TransformerFactory">TransformerFactory</a></b>
-<br>
-<br>
-<i>Intent: </i>Serve as a vendor neutral Processor interface for
- <A href="http://www.w3.org/TR/xslt">XSLT</A> processors and similar
- processors.<br>
-<i>Responsibilities: </i>Serve as a factory for a concrete
- implementation of an TransformerFactory, serve as a direct factory for
- Transformer objects, serve as a factory for Templates objects, and manage
- processor specific features.<br>
-<i>Thread safety: </i>TransformerFactorys can not run concurrently.</p>
-<p>
-<b><a name="pattern-Templates">Templates</a></b>
-<br>
-<br>
-<i>Intent: </i>The run time
- representation of the transformation instructions.<br>
-<i>Responsibilities: </i>Acts as a data bag for transformation instructions, act as a
- factory for Transformers.<br>
-<i>Thread safety: </i>Threadsafe
- concurrently over multiple threads once construction is
- complete.</p>
-<p>
-<b><a name="pattern-Transformer">Transformer</a></b>
-<br>
-<br>
-<i>Intent: </i>Act
- as a per-thread execution context for transformations, act as an interface for
- performing the transformation.<br>
-<i>Responsibilities: </i>Perform the
- transformation.<br>
-<i>Thread safety: </i>Only safe one instance per
- thread.<br>
-<i>Notes: </i>The Transformer is bound to the Templates object
- that created it.</p>
-<p>
-<b><a name="pattern-Source">Source</a></b>
-<br>
-<br>
-<i>Intent: </i>Serve as a single
- vendor-neutral object for multiple types of input.<br>
-<i>Responsibilities: </i>Act as simple data holder for System IDs, DOM nodes, streams,
- etc.<br>
-<i>Thread safety: </i>Threadsafe concurrently over multiple
- threads for read-only, must be synchronized for edit.</p>
-<p>
-<b><a name="pattern-Result">Result</a></b>
-<br>
-<br>
-<i>Potential alternate name: </i>ResultTarget<br>
-<i>Intent: </i>Serve
- as a single object for multiple types of output, so there can be simple process
- method signatures.<br>
-<i>Responsibilities: </i>Act as simple data holder for
- output stream, DOM node, ContentHandler, etc.<br>
-<i>Thread safety: </i>Threadsafe concurrently over multiple threads for read-only,
- must be synchronized for edit.</p>
-</ul>
-
- <h3>Interfaces and Usage</h3>
- <p> TrAX defines a top-level series of interfaces in
- {@link javax.xml.transform}. 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 transform. It achieves this by
- defining {@link javax.xml.transform.Source} and
- {@link javax.xml.transform.Result} interfaces.</p>
- <p>In order to define concrete, usable classes for the user, TrAX
- defines specialization of the interfaces found at the TrAX root level. These
- interfaces are found in {@link javax.xml.transform.sax},
- {@link javax.xml.transform.dom}, and
- {@link javax.xml.transform.stream}.</p>
- <p>The following illustrates a very simple transformation from input URI
- to result stream.</p>
- <code>
+<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, TrAX defines specializations
+ of the interfaces found at the TrAX root level. These interfaces are found in
+ {@link javax.xml.transform.sax}, {@link javax.xml.transform.dom},
+ and {@link javax.xml.transform.stream}.</p>
+<p>The following illustrates a simple transformation from input URI to
+ result stream.</p>
+<code>
<pre> // Create a transform factory instance.
TransformerFactory tfactory = TransformerFactory.newInstance();
@@ -320,84 +31,93 @@
new StreamResult(System.out));
</pre>
</code>
-
<h3>Creating Objects</h3>
- <p>TrAX allows a concrete
+ <p>TrAX allows a concrete
{@link javax.xml.transform.TransformerFactory} object to be created from
- the static function
- {@link javax.xml.transform.TransformerFactory#newInstance}. The system
- property that controls which factory implementation to create is named
- "javax.xml.transform.TransformerFactory". This property names a class that is a
- concrete subclass of this TransformerFactory abstract class. If no property is
- defined, a platform default will be used.</p>
-
+ the static function
+ {@link javax.xml.transform.TransformerFactory#newInstance}. The
+ "javax.xml.transform.TransformerFactory" system property determines which
+ factory implementation to instantiate. This property names a concrete subclass
+ of the TransformerFactory abstract class. If this system property is not
+ defined, a platform default is used.</p>
<h3>Specification of Inputs and Outputs</h3>
- <p>TrAX defines two interface objects called
- {@link javax.xml.transform.Source} and
+ <p>TrAX 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 TrAX interfaces, concrete classes need to be used. TrAX defines
- three concrete representations of source and result pairs:
- {@link javax.xml.transform.stream.StreamSource} and
+ objects to the TrAX interfaces, concrete classes must be used. TrAX defines
+ three concrete representations 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}.</p>
-
-
- <h3>
+ {@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>
+ <code>
+<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
+
+ if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE))
+ {
+ ...
+ }</pre>
+</code>
+
+ <h3>
<a name="qname-delimiter">Qualified Name representation</a>
</h3>
- <p>One of the facts of dealing with XML objects is having to deal with
- <A href="http://www.w3.org/TR/REC-xml-names">Namespaces</A>. 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 Qualified Names in among Java
- programs, it is impossible to pass "xyz:foo" without have some sort of object
- that maps "xyz" to a namespace. </p>
- <p>One solution to this has been to create a "QName" object that holds
- the namespace URI, as well as the prefix and local name. But this is not a
- great solution when you want to use unique strings as keys in a dictionary
- object, for instance. Not having a string representation also makes it very
- hard to specify namespaced identity outside the context of a XML
- document.</p>
- <p>In order to pass namespaced values to transformations, for instance
- as a set of properties to the Serializer, this specification defines that
- parameter String object specified as "qname" be passed as two-part string, with
- the first part being the URL, the delimiter being the '{' for the start of the
- URI and '}' signifies the end, with the local name following. If the qname has
- a null URL, then the String object will only contain 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 TrAX QName 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.
- 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, however, if the transformer does not recognize one, a
- {@link java.lang.IllegalArgumentException} will be thrown,
- if the key name is not <A href="#qname-delimiter">namespace qualified</A>. Output key names that are
- qualified by a namespace will be silently ignored, or passed on to the
- serializer mechanism.</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
- that does not have any arguments. The method will create a Transformer that
- will simply perform a copy of the source to the result. The most common uses of
- this will be to create a DOM from SAX events, or create an XML or HTML stream
- from DOM or SAX events. The following example illustrates the serialization of
- a DOM node to an XML stream.</p>
- <code>
+ <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
+ as a set of properties to the Serializer, 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 TrAX 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.
+ 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
+ unless the key name is <A href="#qname-delimiter">namespace qualified</A>. Output key names that are
+ qualified by a namespace are ignored or passed on to the serializer
+ mechanism.</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. The
+ following example illustrates the serialization of a DOM node to an XML
+ stream.</p>
+ <code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
Transformer serializer = tfactory.newTransformer();
Properties oprops = new Properties();
@@ -407,70 +127,66 @@
serializer.transform(new DOMSource(doc),
new StreamResult(System.out));</pre>
</code>
-
-
- <h3>Exceptions and Error Reporting</h3>
- <p>The TrAX APIs throw three types of specialized exceptions. A
- {@link javax.xml.transform.TFactoryConfigurationError} is parallel to
- the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown
- when a problem with configuration with the Transformer Factories exists. This
- error will typically be thrown when the class of a transformation factory
- specified in the system properties 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, when, for example,
- {@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
- occured.{@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 normally first sent to a
- {@link javax.xml.transform.ErrorListener}, at which point the
- implementor may decide to report the error or warning, and may decide to throw
- an exception for a non-fatal error. The error listener 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 error listener on both objects
- should always be valid and non-null, whether set by the user or a default
- implementation provided by the processor.</p>
-
-
- <h3>Resolution of URIs within a transformation</h3>
- <p>TrAX provides a way for URLs that are referenced from within the
- stylesheet instructions or within the transformation to be reused, by creating
- a class that implements the {@link javax.xml.transform.URIResolver}
- interface, and using
- {@link javax.xml.transform.TransformerFactory#setURIResolver} and
- {@link javax.xml.transform.Transformer#setURIResolver} to set the URI
- resolution for the transformation instructions and the transformation. The URI
- resolver needs to implement only one method,
- {@link javax.xml.transform.URIResolver#resolve}. The TrAX implementation
- will pass into this method a string that represents the URL, found in the
- stylesheet instructions or built as part of the transformation process, as the
- first argument. The second argument will be the base URI in effect when the URL
- passed as the first argument was encountered. The
- {@link javax.xml.transform.Source} object must be usable by the
- transformer, according to it's implemented features.</p>
- <p>The following example illustrates the use of the URI resolver to
- resolve URIs to DOM nodes, in a transformation whose input is totally DOM
- based.</p>
- <code>
+
+ <h3>Exceptions and Error Reporting</h3>
+ <p>The TrAX APIs throw three types of specialized exceptions. A
+ {@link javax.xml.transform.TFactoryConfigurationError} 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 normally first sent to a
+ {@link javax.xml.transform.ErrorListener}, at which point the
+ implementor may decide to report the error or warning, and may decide to throw
+ an exception for a non-fatal error. The error listener 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 error listener on both objects
+ should always be valid and non-null, whether set by the user or a default
+ implementation provided by the processor.</p>
+
+ <h3>Resolution of URIs within a transformation</h3>
+ <p>TrAX 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
+ 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 in effect when the URI passed as the first argument was encountered.
+ The returned {@link javax.xml.transform.Source} object must be usable by
+ the transformer, as specified in its implemented features.</p>
+ <p>The following example illustrates the use of the URI resolver to
+ resolve URIs to DOM nodes, in a transformation whose input is totally DOM
+ based.</p>
+ <code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
- if (tfactory.getFeature(Features.DOM))
+ if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE))
{
DocumentBuilderFactory dfactory =
DocumentBuilderFactory.newInstance();
@@ -480,7 +196,7 @@
// Set up to resolve URLs that correspond to our inc1.xsl,
// to a DOM node. Use an anonymous class for the URI resolver.
final Node xslInc1 = docBuilder.parse("xsl/inc1/inc1.xsl");
- final Node xslInc2 = docBuilder.parse("xsl/inc1/inc2/inc2.xsl");
+ final Node xslInc2 = docBuilder.parse("xsl/inc2/inc2.xsl");
tfactory.setURIResolver(new URIResolver() {
public Source resolve(String href, String base)
throws TransformerException
@@ -522,8 +238,5 @@
}
</pre>
</code>
-
-
-
</body>
</html>
1.5 +6 -0 xml-xalan/java/src/javax/xml/transform/dom/DOMResult.java
Index: DOMResult.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/dom/DOMResult.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DOMResult.java 2000/11/14 17:31:38 1.4
+++ DOMResult.java 2000/11/15 02:34:31 1.5
@@ -74,6 +74,12 @@
*/
public class DOMResult implements Result
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Result output of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.dom.DOMResult/feature";
/**
* Zero-argument default constructor. If this constructor is used, and
1.5 +6 -0 xml-xalan/java/src/javax/xml/transform/dom/DOMSource.java
Index: DOMSource.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/dom/DOMSource.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DOMSource.java 2000/11/14 17:31:38 1.4
+++ DOMSource.java 2000/11/15 02:34:31 1.5
@@ -73,6 +73,12 @@
*/
public class DOMSource implements Source
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Source input of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.dom.DOMSource/feature";
/**
* Zero-argument default constructor. If this is used, and
1.3 +24 -24 xml-xalan/java/src/javax/xml/transform/dom/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/dom/package.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- package.html 2000/11/13 16:26:32 1.2
+++ package.html 2000/11/15 02:34:31 1.3
@@ -5,41 +5,41 @@
<title>javax.xml.transform.dom</title>
</head>
<body>
-<p>This package implements DOM specific transformation APIs.</p>
+<p>This package implements DOM-specific transformation APIs.</p>
<p>The {@link javax.xml.transform.dom.DOMSource} class allows the
-client of the TrAX implementation to specify a
-DOM{@link org.w3c.dom.Node} as the source of the input tree. The model
-of how the transformer deals with the DOM tree in terms of mismatches with
-the<A href="http://www.w3.org/TR/xslt#data-model">XSLT data model</A> or
-other data models is beyond the scope of this API specification. Any of the
-nodes derived from {@link org.w3c.dom.Node} are legal input.</p>
-<p>The {@link javax.xml.transform.dom.DOMResult} class allows
-a{@link org.w3c.dom.Node} to be specified to which result DOM nodes will
-be appended, or, if an output node is not specified, the transformer will
-create an output {@link org.w3c.dom.Document} node
-using{@link javax.xml.parsers.DocumentBuilder#newDocument}. If a node is
-specified, it should be one of
-{@link org.w3c.dom.Document},{@link org.w3c.dom.Element},
-or{@link org.w3c.dom.DocumentFragment}. Specification of any other type
-of nodes is implementation dependent and undefined by this API. If the result
-is a{@link org.w3c.dom.Document}, the output of the transformation must
-have a single element root to set as the document element.</p>
+client of the TrAX implementation to specify a DOM
+{@link org.w3c.dom.Node} as the source of the input tree. The model of
+how the Transformer deals with the DOM tree in terms of mismatches with the
+<A href="http://www.w3.org/TR/xslt#data-model">XSLT data model</A> or
+other data models is beyond the scope of this document. Any of the nodes
+derived from {@link org.w3c.dom.Node} are legal input.</p>
+<p>The {@link javax.xml.transform.dom.DOMResult} class allows a
+{@link org.w3c.dom.Node} to be specified to which result DOM nodes will
+be appended. If an output node is not specified, the transformer will use
+{@link javax.xml.parsers.DocumentBuilder#newDocument} to create an
+output {@link org.w3c.dom.Document} node. If a node is specified, it
+should be one of the following: {@link org.w3c.dom.Document},
+{@link org.w3c.dom.Element}, or
+{@link org.w3c.dom.DocumentFragment}. Specification of any other node
+type is implementation dependent and undefined by this API. If the result is a
+{@link org.w3c.dom.Document}, the output of the transformation must have
+a single element root to set as the document element.</p>
<p>The {@link javax.xml.transform.dom.DOMLocator} node may be passed
to {@link javax.xml.transform.TransformerException} objects, and
retrieved by trying to cast the result of
-the{@link javax.xml.transform.TransformerException#getLocator()} method.
+the {@link javax.xml.transform.TransformerException#getLocator()} method.
The implementation has no responsibility to use a DOMLocator instead of
-a{@link javax.xml.transform.SourceLocator} (though line numbers and the
-like doesn't make much sense for a DOM), so the result of getLocator must
-always be tested with an instanceof. </p>
+a {@link javax.xml.transform.SourceLocator} (though line numbers and the
+like do not make much sense for a DOM), so the result of getLocator must always
+be tested with an instanceof. </p>
<p>The following example performs a transformation using DOM nodes as input
-for the transformer factory, as input for the transformer, and as the output of
+for the TransformerFactory, as input for the Transformer, and as the output of
the transformation.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
// Make sure the TransformerFactory supports the DOM feature.
- if (tfactory.getFeature(Features.DOM))
+ if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(DOMResult.FEATURE))
{
// Use javax.xml.parsers to create our DOMs.
DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
1.6 +6 -0 xml-xalan/java/src/javax/xml/transform/sax/SAXResult.java
Index: SAXResult.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/sax/SAXResult.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- SAXResult.java 2000/11/14 20:30:06 1.5
+++ SAXResult.java 2000/11/15 02:34:31 1.6
@@ -72,6 +72,12 @@
*/
public class SAXResult implements Result
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Result output of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.sax.SAXResult/feature";
/**
* Zero-argument default constructor.
1.5 +6 -0 xml-xalan/java/src/javax/xml/transform/sax/SAXSource.java
Index: SAXSource.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/sax/SAXSource.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- SAXSource.java 2000/11/14 20:30:06 1.4
+++ SAXSource.java 2000/11/15 02:34:32 1.5
@@ -74,6 +74,12 @@
*/
public class SAXSource implements Source
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Source input of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.sax.SAXSource/feature";
/**
* Zero-argument default constructor. If this constructor
1.7 +17 -0 xml-xalan/java/src/javax/xml/transform/sax/SAXTransformerFactory.java
Index: SAXTransformerFactory.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/sax/SAXTransformerFactory.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- SAXTransformerFactory.java 2000/11/14 20:30:06 1.6
+++ SAXTransformerFactory.java 2000/11/15 02:34:32 1.7
@@ -78,6 +78,23 @@
*/
public abstract class SAXTransformerFactory extends TransformerFactory
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the TransformerFactory returned from
+ * {@link javax.xml.transform.TransformerFactory#newInstance} may
+ * be safely cast to a SAXTransformerFactory.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.sax.SAXTransformerFactory/feature";
+
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the {@link #newXMLFilter(Source src)}
+ * and {@link #newXMLFilter(Templates templates)} methods are supported.
+ */
+ public static final String FEATURE_XMLFILTER
+ = "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter";
+
/**
* The default constructor is protected on purpose.
*/
1.4 +1 -1 xml-xalan/java/src/javax/xml/transform/sax/TemplatesHandler.java
Index: TemplatesHandler.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/sax/TemplatesHandler.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- TemplatesHandler.java 2000/11/14 20:30:06 1.3
+++ TemplatesHandler.java 2000/11/15 02:34:32 1.4
@@ -88,5 +88,5 @@
* resolve relative URIs in the stylesheet.
* @param baseID Base URI for this stylesheet.
*/
- public void setSystemID(String systemID);
+ public void setSystemId(String systemID);
}
1.3 +65 -68 xml-xalan/java/src/javax/xml/transform/sax/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/sax/package.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- package.html 2000/11/13 16:26:32 1.2
+++ package.html 2000/11/15 02:34:32 1.3
@@ -5,29 +5,28 @@
<title>javax.xml.transform.sax</title>
</head>
<body>
-<p>This package implements SAX2 specific transformation APIs. It provides
- classes which allow the transformation from
- {@link org.xml.sax.ContentHandler} events, and also classes that produce
- {@link org.xml.sax.ContentHandler} events. It also provides methods to
- set the input source as an {@link org.xml.sax.XMLReader}, or to use a
- {@link org.xml.sax.InputSource} as the source. It also allows the
- creation of a {@link org.xml.sax.XMLFilter}, which allows
- transformations to "pull" from other transformations, and allows the
- transformer to be used polymorphically as an
- {@link org.xml.sax.XMLReader}.</p>
+<p>This package implements SAX2-specific transformation APIs. It provides
+ classes which allow input from {@link org.xml.sax.ContentHandler}
+ events, and also classes that produce org.xml.sax.ContentHandler events. It
+ also provides methods to set the input source as an
+ {@link org.xml.sax.XMLReader}, or to use a
+ {@link org.xml.sax.InputSource} as the source. It also allows the
+ creation of a {@link org.xml.sax.XMLFilter}, which enables
+ transformations to "pull" from other transformations, and lets the transformer
+ to be used polymorphically as an {@link org.xml.sax.XMLReader}.</p>
<p>The {@link javax.xml.transform.sax.SAXSource} class allows the
- setting of a {@link org.xml.sax.XMLReader} to be used for "pulling"
- parse events, and a {@link org.xml.sax.InputSource} that may be used to
- specify the SAX source.</p>
+ setting of an {@link org.xml.sax.XMLReader} to be used for "pulling"
+ parse events, and an {@link org.xml.sax.InputSource} that may be used to
+ specify the SAX source.</p>
<p>The {@link javax.xml.transform.sax.SAXResult} class allows the
- setting of a {@link org.xml.sax.ContentHandler} to be the receiver of
- SAX2 events from the transformation. The following code fragment illustrates
- both the use of the source and result objects.</p>
+ setting of a {@link org.xml.sax.ContentHandler} to be the receiver of
+ SAX2 events from the transformation. The following code fragment illustrates
+ the use of the SAXSource and SAXResult objects.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
// Does this factory support SAX features?
- if (tfactory.getFeature(Features.SAX))
+ if (tfactory.getFeature(SAXSource.FEATURE) && tfactory.getFeature(SAXResult.FEATURE))
{
// Get a transformer.
Transformer transformer
@@ -41,23 +40,21 @@
}
</pre>
</code>
-<p>The {@link javax.xml.transform.sax.SAXTransformerFactory}
- extends {@link javax.xml.transform.TransformerFactory} to provide
- factory methods for creating
- {@link javax.xml.transform.sax.TemplatesHandler},
- {@link javax.xml.transform.sax.TransformerHandler}, and
- {@link org.xml.sax.XMLReader} instances.</p>
-<p>To obtain a
- {@link javax.xml.transform.sax.SAXTransformerFactory}, the caller must
- cast the {@link javax.xml.transform.TransformerFactory} instance
- returned from
- {@link javax.xml.transform.TransformerFactory#newInstance}. For
- example:</p>
+<p>The {@link javax.xml.transform.sax.SAXTransformerFactory} extends
+ {@link javax.xml.transform.TransformerFactory} to provide factory
+ methods for creating {@link javax.xml.transform.sax.TemplatesHandler},
+ {@link javax.xml.transform.sax.TransformerHandler}, and
+ {@link org.xml.sax.XMLReader} instances.</p>
+<p>To obtain a {@link javax.xml.transform.sax.SAXTransformerFactory},
+ the caller must cast the {@link javax.xml.transform.TransformerFactory}
+ instance returned from
+ {@link javax.xml.transform.TransformerFactory#newInstance}. For
+ example:</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
- // Does this factory support SAX features?
- if (tfactory.getFeature(Features.SAX))
+ // Does this factory support the SAXTransformerFactory feature?
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
{
// If so, we can safely cast.
SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
@@ -71,29 +68,29 @@
</pre>
</code>
<p>The {@link javax.xml.transform.sax.TransformerHandler} interface
- allows a transformation to be created from SAX2 parse events, which is a "push"
- model rather than the "pull" model that normally occurs for a transformation.
- Normal parse events are received through the
- {@link org.xml.sax.ContentHandler} interface, lexical events such as
- startCDATA and endCDATA are received through the
- {@link org.xml.sax.ext.LexicalHandler} interface, and events that signal
- the start of end of disabling output escaping are received via
- {@link org.xml.sax.ContentHandler#processingInstruction}, with the
- target parameter being
- {@link javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING} and
- {@link javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING}. If
- parameters, output properties, or other features need to be set on the
- transformer handler, a {@link javax.xml.transform.Transformer} reference
- will need to be obtained from
- {@link javax.xml.transform.sax.TransformerHandler#getTransformer}, and
- the methods invoked from that reference. The following illustrates the feeding
- of SAX events from an {@link org.xml.sax.XMLReader} to a
- transformer.</p>
+ allows a transformation to be created from SAX2 parse events, which is a "push"
+ model rather than the "pull" model that normally occurs for a transformation.
+ Normal parse events are received through the
+ {@link org.xml.sax.ContentHandler} interface, lexical events such as
+ startCDATA and endCDATA are received through the
+ {@link org.xml.sax.ext.LexicalHandler} interface, and events that signal
+ the start or end of disabling output escaping are received via
+ {@link org.xml.sax.ContentHandler#processingInstruction}, with the
+ target parameter being
+ {@link javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING} and
+ {@link javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING}. If
+ parameters, output properties, or other features need to be set on the
+ Transformer handler, a {@link javax.xml.transform.Transformer} reference
+ will need to be obtained from
+ {@link javax.xml.transform.sax.TransformerHandler#getTransformer}, and
+ the methods invoked from that reference. The following illustrates the feeding
+ of SAX events from an {@link org.xml.sax.XMLReader} to a
+ Transformer.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
// Does this factory support SAX features?
- if (tfactory.getFeature(Features.SAX))
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
{
// If so, we can safely cast.
SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
@@ -123,19 +120,19 @@
</pre>
</code>
<p>The {@link javax.xml.transform.sax.TemplatesHandler} interface
- allows the creation of {@link javax.xml.transform.Templates} objects
- from SAX2 parse events. Once the {@link org.xml.sax.ContentHandler}
- events are complete, the templates object may be obtained from
- {@link javax.xml.transform.sax.TemplatesHandler#getTemplates}. Note that
- {@link javax.xml.transform.sax.TemplatesHandler#setSystemID} should
- normally be called in order to establish a base system ID from where relative
- URLs may be resolved. The following code fragment illustrates the creation of a
- templates object from SAX2 events sent from an XMLReader.</p>
+ allows the creation of {@link javax.xml.transform.Templates} objects
+ from SAX2 parse events. Once the {@link org.xml.sax.ContentHandler}
+ events are complete, the Templates object may be obtained from
+ {@link javax.xml.transform.sax.TemplatesHandler#getTemplates}. Note that
+ {@link javax.xml.transform.sax.TemplatesHandler#setSystemId} should
+ normally be called in order to establish a base system ID from which relative
+ URLs may be resolved. The following code fragment illustrates the creation of a
+ Templates object from SAX2 events sent from an XMLReader.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
// Does this factory support SAX features?
- if (tfactory.getFeature(Features.SAX))
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
{
// If so, we can safely cast.
SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
@@ -146,7 +143,7 @@
// If you don't do this, the TemplatesHandler won't know how to
// resolve relative URLs.
- handler.setSystemID(xslID);
+ handler.setSystemId(xslID);
// Create a reader, and set it's content handler to be the TemplatesHandler.
XMLReader reader = XMLReaderFactory.createXMLReader();
@@ -165,18 +162,18 @@
</pre>
</code>
<p>The
- {@link javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter}
- method allows the creation of a {@link org.xml.sax.XMLFilter}, which is
- the SAX2 notion of a "pull" transformation. The following illustrates several
- transformations chained together. Each filter points to a parent
- {@link org.xml.sax.XMLReader}, and the final transformation is caused by
- invoking {@link org.xml.sax.XMLReader#parse} on the final reader in the
- chain.</p>
+ {@link javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter}
+ method allows the creation of a {@link org.xml.sax.XMLFilter}, which
+ encapsulates the SAX2 notion of a "pull" transformation. The following
+ illustrates several transformations chained together. Each filter points to a
+ parent {@link org.xml.sax.XMLReader}, and the final transformation is
+ caused by invoking {@link org.xml.sax.XMLReader#parse} on the final
+ reader in the chain.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
// Does this factory support SAX features?
- if (tfactory.getFeature(Features.SAX))
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
{
Templates stylesheet1 = tfactory.newTemplates(new StreamSource(xslID_1));
Transformer transformer1 = stylesheet1.newTransformer();
1.5 +6 -0 xml-xalan/java/src/javax/xml/transform/stream/StreamResult.java
Index: StreamResult.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/stream/StreamResult.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- StreamResult.java 2000/11/14 20:54:09 1.4
+++ StreamResult.java 2000/11/15 02:34:32 1.5
@@ -72,6 +72,12 @@
*/
public class StreamResult implements Result
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Result output of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.stream.StreamResult/feature";
/**
* Zero-argument default constructor.
1.5 +6 -0 xml-xalan/java/src/javax/xml/transform/stream/StreamSource.java
Index: StreamSource.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/stream/StreamSource.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- StreamSource.java 2000/11/14 20:54:09 1.4
+++ StreamSource.java 2000/11/15 02:34:32 1.5
@@ -70,6 +70,12 @@
*/
public class StreamSource implements Source
{
+ /** If {@link javax.xml.transform.TransformerFactory#getFeature}
+ * returns true when passed this value as an argument,
+ * the Transformer supports Source input of this type.
+ */
+ public static final String FEATURE
+ = "http://javax.xml.transform.stream.StreamSource/feature";
/**
* Zero-argument default constructor. If this constructor
1.3 +24 -24 xml-xalan/java/src/javax/xml/transform/stream/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/stream/package.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- package.html 2000/11/13 16:26:34 1.2
+++ package.html 2000/11/15 02:34:32 1.3
@@ -5,36 +5,36 @@
<title>javax.xml.transform.stream</title>
</head>
<body>
-<p>This package implements stream and URL specific transformation APIs.
- </p>
+<p>This package implements stream- and URI- specific transformation APIs.
+ </p>
<p>The {@link javax.xml.transform.stream.StreamSource} class
- provides methods for specifying {@link java.io.InputStream} input,
- {@link java.io.Reader} input, and URL input in the form of strings. Even
- if an input stream or reader is specified as the source,
- {@link javax.xml.transform.stream.StreamSource#setSystemId} should still
- be called, so that the transformer can know from where it should resolve
- relative URIs. The public identifier is always optional: if the application
- writer includes one, it will be provided as part of the
- {@link javax.xml.transform.SourceLocator} information.</p>
+ provides methods for specifying {@link java.io.InputStream} input,
+ {@link java.io.Reader} input, and URL input in the form of strings. Even
+ if an input stream or reader is specified as the source,
+ {@link javax.xml.transform.stream.StreamSource#setSystemId} should still
+ be called, so that the transformer can know from where it should resolve
+ relative URIs. The public identifier is always optional: if the application
+ writer includes one, it will be provided as part of the
+ {@link javax.xml.transform.SourceLocator} information.</p>
<p>The {@link javax.xml.transform.stream.StreamResult} class
- provides methods for specifying {@link java.io.OutputStream},
- {@link java.io.Writer}, or an output system ID, as the output of the
- transformation result.</p>
-<p>In both the stream and result, normally streams should be used rather
- than readers or writers, since readers and writers already have the encoding
- establish to and from the internal Unicode format. However, there are times
- when it is useful to write to a character stream, such as when using a
- StringWriter in order to write to a String, or in the case of reading source
- XML from a StringReader.</p>
-<p>The following code fragment illustrates the use of the stream source
- and result objects.</p>
+ provides methods for specifying {@link java.io.OutputStream},
+ {@link java.io.Writer}, or an output system ID, as the output of the
+ transformation result.</p>
+<p>Normally streams should be used rather than readers or writers, for
+ both the Source and Result, since readers and writers already have the encoding
+ established to and from the internal Unicode format. However, there are times
+ when it is useful to write to a character stream, such as when using a
+ StringWriter in order to write to a String, or in the case of reading source
+ XML from a StringReader.</p>
+<p>The following code fragment illustrates the use of the stream Source
+ and Result objects.</p>
<code>
-<pre> // Create a transform factory instance.
+<pre> // Create a TransformerFactory instance.
TransformerFactory tfactory = TransformerFactory.newInstance();
InputStream xslIS = new BufferedInputStream(new FileInputStream(xslID));
StreamSource xslSource = new StreamSource(xslIS);
- // Note that if we don't do this, relative URLs can not be resolved correctly!
+ // Note that if we don't do this, relative URLs cannot be resolved correctly!
xslSource.setSystemId(xslID);
// Create a transformer for the stylesheet.
@@ -42,7 +42,7 @@
InputStream xmlIS = new BufferedInputStream(new FileInputStream(sourceID));
StreamSource xmlSource = new StreamSource(xmlIS);
- // Note that if we don't do this, relative URLs can not be resolved correctly!
+ // Note that if we don't do this, relative URLs cannot be resolved correctly!
xmlSource.setSystemId(sourceID);
// Transform the source XML to System.out.