sboag 01/01/01 19:49:03
Modified: java/src/javax/xml/parsers FactoryConfigurationError.java
java/src/javax/xml/transform TransformerException.java
TransformerFactoryConfigurationError.java
package.html
java/src/javax/xml/transform/dom package.html
java/src/javax/xml/transform/sax package.html
java/src/javax/xml/transform/stream package.html
Log:
Minor javadoc tweaks to make clean doc build.
Revision Changes Path
1.4 +1 -0
xml-xalan/java/src/javax/xml/parsers/FactoryConfigurationError.java
Index: FactoryConfigurationError.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/javax/xml/parsers/FactoryConfigurationError.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- FactoryConfigurationError.java 2000/12/20 04:55:17 1.3
+++ FactoryConfigurationError.java 2001/01/02 03:49:02 1.4
@@ -70,6 +70,7 @@
public class FactoryConfigurationError extends Error {
+ /** @serial */
private Exception exception;
/**
1.11 +5 -3
xml-xalan/java/src/javax/xml/transform/TransformerException.java
Index: TransformerException.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/javax/xml/transform/TransformerException.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- TransformerException.java 2000/12/20 04:55:20 1.10
+++ TransformerException.java 2001/01/02 03:49:03 1.11
@@ -55,7 +55,7 @@
* <http://www.apache.org/>.
*/
/**
- * $Id: TransformerException.java,v 1.10 2000/12/20 04:55:20 sboag Exp $
+ * $Id: TransformerException.java,v 1.11 2001/01/02 03:49:03 sboag Exp $
*/
package javax.xml.transform;
@@ -72,7 +72,8 @@
*/
public class TransformerException extends Exception {
- /** Field locator specifies where the error occured */
+ /** Field locator specifies where the error occured.
+ * @serial */
SourceLocator locator;
/**
@@ -95,7 +96,8 @@
locator = location;
}
- /** Field containedException specifies a wrapped exception. May be
null. */
+ /** Field containedException specifies a wrapped exception. May be null.
+ * @serial */
Throwable containedException;
/**
1.3 +3 -1
xml-xalan/java/src/javax/xml/transform/TransformerFactoryConfigurationError.java
Index: TransformerFactoryConfigurationError.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/javax/xml/transform/TransformerFactoryConfigurationError.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TransformerFactoryConfigurationError.java 2000/12/20 04:55:20 1.2
+++ TransformerFactoryConfigurationError.java 2001/01/02 03:49:03 1.3
@@ -55,7 +55,7 @@
* <http://www.apache.org/>.
*/
/*
- * $Id: TransformerFactoryConfigurationError.java,v 1.2 2000/12/20 04:55:20
sboag Exp $
+ * $Id: TransformerFactoryConfigurationError.java,v 1.3 2001/01/02 03:49:03
sboag Exp $
*/
package javax.xml.transform;
@@ -67,6 +67,8 @@
*/
public class TransformerFactoryConfigurationError extends Error {
+ /** The contained exception.
+ * @serial */
private Exception exception;
/**
1.9 +119 -29 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.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- package.html 2000/12/20 04:55:20 1.8
+++ package.html 2001/01/02 03:49:03 1.9
@@ -5,41 +5,60 @@
<title>javax.xml.transform</title>
</head>
<body>
-<p>This package defines the generic APIs for processing transformation
- instructions, and performing a transformation from source to
result. These
+<p>This package defines the generic APIs for processing transformation
instructions,
+ and performing a transformation from source to result. For an
overview, see
+ <A href="trax.html">Transformation API for XML (TrAX)</A>. The TrAX
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
- [EMAIL PROTECTED] javax.xml.transform.Source} and
+ transformation. TrAX achieves this by defining
+ [EMAIL PROTECTED] javax.xml.transform.Source} and
[EMAIL PROTECTED] 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
+<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
[EMAIL PROTECTED] javax.xml.transform.sax}, [EMAIL PROTECTED]
javax.xml.transform.dom},
and [EMAIL PROTECTED] 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();
+
+ // Create a transformer for the stylesheet.
+ Transformer transformer
+ = tfactory.newTransformer(new StreamSource(xslID));
+
+ // Transform the source XML to System.out.
+ transformer.transform( new StreamSource(sourceID),
+ new StreamResult(System.out));
+</pre>
+</code>
<h3>Creating Objects</h3>
-<p>The API allows a concrete
+<p>TrAX allows a concrete
[EMAIL PROTECTED] javax.xml.transform.TransformerFactory}
object to be created from
- the static function
- [EMAIL PROTECTED]
javax.xml.transform.TransformerFactory#newInstance}.
+ the static function
+ [EMAIL PROTECTED]
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>This API defines two interface objects called
- [EMAIL PROTECTED] javax.xml.transform.Source} and
+<p>TrAX defines two interface objects called
+ [EMAIL PROTECTED] javax.xml.transform.Source} and
[EMAIL PROTECTED] 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:
- [EMAIL PROTECTED] 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:
+ [EMAIL PROTECTED] javax.xml.transform.stream.StreamSource}
and
[EMAIL PROTECTED] javax.xml.transform.stream.StreamResult},
- [EMAIL PROTECTED] javax.xml.transform.sax.SAXSource} and
- [EMAIL PROTECTED] javax.xml.transform.sax.SAXResult}, and
- [EMAIL PROTECTED] javax.xml.transform.dom.DOMSource} and
+ [EMAIL PROTECTED] javax.xml.transform.sax.SAXSource} and
+ [EMAIL PROTECTED] javax.xml.transform.sax.SAXResult}, and
+ [EMAIL PROTECTED] javax.xml.transform.dom.DOMSource} and
[EMAIL PROTECTED] 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
+ a FEATURE string (which is i the form of a URL), which can be
passed into
[EMAIL PROTECTED]
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
@@ -52,7 +71,7 @@
{
...
}</pre>
-</code>
+</code>
<h3>
@@ -85,21 +104,21 @@
<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";.
+ 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 [EMAIL PROTECTED]
javax.xml.transform.Transformer#setOutputProperties} and the
+ the [EMAIL PROTECTED]
javax.xml.transform.Transformer#setOutputProperties} and the
[EMAIL PROTECTED]
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
+ specification for xsl:output attributes</A> can be referenced
from the
[EMAIL PROTECTED] javax.xml.transform.OutputKeys} class. Other
strings can be
- specified as well. If the transformer does not recognize an
output key, a
- [EMAIL PROTECTED] java.lang.IllegalArgumentException} is
thrown, unless the
- key name is <A href="#qname-delimiter">namespace qualified</A>.
Output key names that are
+ specified as well. If the transformer does not recognize an
output key, a
+ [EMAIL PROTECTED] 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>
@@ -109,13 +128,25 @@
[EMAIL PROTECTED]
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>
+ 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();
+ oprops.put("method", "html");
+ oprops.put("indent-amount", "2");
+ serializer.setOutputProperties(oprops);
+ serializer.transform(new DOMSource(doc),
+ new StreamResult(System.out));</pre>
+</code>
<h3>Exceptions and Error Reporting</h3>
-<p>The transformation API throw three types of specialized exceptions. A
+<p>The TrAX APIs throw three types of specialized exceptions. A
[EMAIL PROTECTED]
javax.xml.transform.TransformerFactoryConfigurationError} is parallel to
the [EMAIL PROTECTED] javax.xml.parsers.FactoryConfigurationError},
and is thrown
when a configuration problem with the TransformerFactory exists. This
error
@@ -158,7 +189,7 @@
<h3>Resolution of URIs within a transformation</h3>
-<p>The API provides a way for URIs referenced from within the stylesheet
+<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,
@@ -172,6 +203,65 @@
The returned [EMAIL PROTECTED] 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(DOMSource.FEATURE) &&
tfactory.getFeature(StreamResult.FEATURE))
+ {
+ DocumentBuilderFactory dfactory =
+ DocumentBuilderFactory.newInstance();
+ dfactory.setNamespaceAware(true); // Always, required for XSLT
+ DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
+
+ // 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/inc2/inc2.xsl");
+ tfactory.setURIResolver(new URIResolver() {
+ public Source resolve(String href, String base)
+ throws TransformerException
+ {
+ // ignore base because we're lazy, or we don't care.
+ return (href.equals("inc1/inc1.xsl"))
+ ? new DOMSource(xslInc1) :
+ (href.equals("inc2/inc2.xsl"))
+ ? new DOMSource(xslInc2) : null;
+ }});
+
+ // The TransformerFactory will call the anonymous URI
+ // resolver set above when it encounters
+ // <xsl:include href="inc1/inc1.xsl"/>
+ Templates templates
+ = tfactory.newTemplates(new DOMSource(docBuilder.parse(xslID),
xslID));
+
+ // Get a transformer from the templates.
+ Transformer transformer = templates.newTransformer();
+
+ // Set up to resolve URLs that correspond to our foo2.xml, to
+ // a DOM node. Use an anonymous class for the URI resolver.
+ // Be sure to return the same DOM tree every time for the
+ // given URI.
+ final Node xmlSubdir1Foo2Node =
docBuilder.parse("xml/subdir1/foo2.xml");
+ transformer.setURIResolver(new URIResolver() {
+ public Source resolve(String href, String base)
+ throws TransformerException
+ {
+ // ignore base because we're lazy, or we don't care.
+ return (href.equals("subdir1/foo2.xml"))
+ ? new DOMSource(xmlSubdir1Foo2Node) : null;
+ }});
+
+ // Now the transformer will call our anonymous URI resolver
+ // when it encounters the document('subdir1/foo2.xml') invocation.
+ transformer.transform(new DOMSource(docBuilder.parse(sourceID),
sourceID),
+ new StreamResult(System.out));
+ }
+</pre>
+</code>
</body>
</html>
1.7 +49 -11 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.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- package.html 2000/12/20 04:55:24 1.6
+++ package.html 2001/01/02 03:49:03 1.7
@@ -7,30 +7,68 @@
<body>
<p>This package implements DOM-specific transformation APIs.</p>
<p>The [EMAIL PROTECTED] javax.xml.transform.dom.DOMSource} class allows the
-client of the implementation of this API to specify a DOM
+client of the TrAX implementation to specify a DOM
[EMAIL PROTECTED] 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 [EMAIL PROTECTED] org.w3c.dom.Node} are legal input.</p>
-<p>The [EMAIL PROTECTED] javax.xml.transform.dom.DOMResult} class allows
-a [EMAIL PROTECTED] 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
+<p>The [EMAIL PROTECTED] javax.xml.transform.dom.DOMResult} class allows a
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] javax.xml.parsers.DocumentBuilder#newDocument} to create an
output [EMAIL PROTECTED] org.w3c.dom.Document} node. If a node is specified,
it
-should be one of the following: [EMAIL PROTECTED] org.w3c.dom.Document},
[EMAIL PROTECTED] org.w3c.dom.Element}, or
+should be one of the following: [EMAIL PROTECTED] org.w3c.dom.Document},
[EMAIL PROTECTED] org.w3c.dom.Element}, or
[EMAIL PROTECTED] org.w3c.dom.DocumentFragment}. Specification of any other
node
-type is implementation dependent and undefined by this API. If the result is
a
+type is implementation dependent and undefined by this API. If the result is
a
[EMAIL PROTECTED] org.w3c.dom.Document}, the output of the transformation
must have
a single element root to set as the document element.</p>
<p>The [EMAIL PROTECTED] javax.xml.transform.dom.DOMLocator} node may be
passed
to [EMAIL PROTECTED] javax.xml.transform.TransformerException} objects, and
-retrieved by trying to cast the result of the
[EMAIL PROTECTED] javax.xml.transform.TransformerException#getLocator()}
method.
-The implementation has no responsibility to use a DOMLocator instead of a
[EMAIL PROTECTED] javax.xml.transform.SourceLocator} (though line numbers and
the
+retrieved by trying to cast the result of
+the [EMAIL PROTECTED] javax.xml.transform.TransformerException#getLocator()}
method.
+The implementation has no responsibility to use a DOMLocator instead of
+a [EMAIL PROTECTED] 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 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(DOMSource.FEATURE) &&
tfactory.getFeature(DOMResult.FEATURE))
+ {
+ // Use javax.xml.parsers to create our DOMs.
+ DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
+ dfactory.setNamespaceAware(true); // do this always for XSLT
+ DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
+
+ // Create the Templates from a DOM.
+ Node xslDOM = docBuilder.parse(xslID);
+ DOMSource dsource = new DOMSource(xslDOM, xslID);
+ Templates templates = tfactory.newTemplates(dsource);
+
+ // Create the source tree in the form of a DOM.
+ Node sourceNode = docBuilder.parse(sourceID);
+
+ // Create a DOMResult that the transformation will fill in.
+ DOMResult dresult = new DOMResult();
+
+ // And transform from the source DOM tree to a result DOM tree.
+ Transformer transformer = templates.newTransformer();
+ transformer.transform(new DOMSource(sourceNode, sourceID), dresult);
+
+ // The root of the result tree may now be obtained from
+ // the DOMResult object.
+ Node out = dresult.getNode();
+
+ // Serialize it to System.out for diagnostics.
+ Transformer serializer = tfactory.newTransformer();
+ serializer.transform(new DOMSource(out), new StreamResult(System.out));
+ }</pre>
+</code>
</body>
</html>
1.7 +146 -5 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.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- package.html 2000/12/20 04:55:29 1.6
+++ package.html 2001/01/02 03:49:03 1.7
@@ -20,7 +20,26 @@
specify the SAX source.</p>
<p>The [EMAIL PROTECTED] javax.xml.transform.sax.SAXResult} class allows the
setting of a [EMAIL PROTECTED] org.xml.sax.ContentHandler} to be the
receiver of
- SAX2 events from the transformation.
+ 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(SAXSource.FEATURE) &&
tfactory.getFeature(SAXResult.FEATURE))
+ {
+ // Get a transformer.
+ Transformer transformer
+ = tfactory.newTransformer(new StreamSource(xslID));
+
+ // Create an reader for reading.
+ XMLReader reader = XMLReaderFactory.createXMLReader();
+
+ transformer.transform(new SAXSource(reader, new InputSource(sourceID)),
+ new SAXResult(new ExampleContentHandler()));
+ }
+</pre>
+</code>
<p>The [EMAIL PROTECTED] javax.xml.transform.sax.SAXTransformerFactory}
extends
[EMAIL PROTECTED] javax.xml.transform.TransformerFactory} to provide
factory
methods for creating [EMAIL PROTECTED]
javax.xml.transform.sax.TemplatesHandler},
@@ -29,8 +48,25 @@
<p>To obtain a [EMAIL PROTECTED]
javax.xml.transform.sax.SAXTransformerFactory},
the caller must cast the [EMAIL PROTECTED]
javax.xml.transform.TransformerFactory}
instance returned from
- [EMAIL PROTECTED] javax.xml.transform.TransformerFactory#newInstance}.
+ [EMAIL PROTECTED] javax.xml.transform.TransformerFactory#newInstance}. For
+ example:</p>
+<code>
+<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
+ // Does this factory support the SAXTransformerFactory feature?
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
+ {
+ // If so, we can safely cast.
+ SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
+
+ // A TransformerHandler is a ContentHandler that will listen for
+ // SAX events, and transform them to the result.
+ TransformerHandler handler
+ = stfactory.newTransformerHandler(new StreamSource(xslID));
+ // ...
+ }
+</pre>
+</code>
<p>The [EMAIL PROTECTED] 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.
@@ -47,16 +83,84 @@
Transformer handler, a [EMAIL PROTECTED] javax.xml.transform.Transformer}
reference
will need to be obtained from
[EMAIL PROTECTED]
javax.xml.transform.sax.TransformerHandler#getTransformer}, and
- the methods invoked from that reference.
+ the methods invoked from that reference. The following illustrates the
feeding
+ of SAX events from an [EMAIL PROTECTED] org.xml.sax.XMLReader} to a
+ Transformer.</p>
+<code>
+<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
+
+ // Does this factory support SAX features?
+ if (tfactory.getFeature(SAXTransformerFactory.FEATURE))
+ {
+ // If so, we can safely cast.
+ SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
+
+ // A TransformerHandler is a ContentHandler that will listen for
+ // SAX events, and transform them to the result.
+ TransformerHandler handler
+ = stfactory.newTransformerHandler(new StreamSource(xslID));
+ // Set the result handling to be a serialization to System.out.
+ handler.setResult(new StreamResult(System.out));
+
+ handler.getTransformer().setParameter("a-param",
+ "hello to you!");
+
+ // Create a reader, and set it's content handler to be the
TransformerHandler.
+ XMLReader reader = XMLReaderFactory.createXMLReader();
+ reader.setContentHandler(handler);
+
+ // It's a good idea for the parser to send lexical events.
+ // The TransformerHandler is also a LexicalHandler.
+ reader.setProperty("http://xml.org/sax/properties/lexical-handler";,
handler);
+
+ // Parse the source XML, and send the parse events to the
TransformerHandler.
+ reader.parse(sourceID);
+ }
+</pre>
+</code>
<p>The [EMAIL PROTECTED] javax.xml.transform.sax.TemplatesHandler} interface
allows the creation of [EMAIL PROTECTED] javax.xml.transform.Templates}
objects
from SAX2 parse events. Once the [EMAIL PROTECTED]
org.xml.sax.ContentHandler}
events are complete, the Templates object may be obtained from
- [EMAIL PROTECTED] javax.xml.transform.sax.TemplatesHandler#getTemplates}.
Note that
+ [EMAIL PROTECTED] javax.xml.transform.sax.TemplatesHandler#getTemplates}.
Note that
[EMAIL PROTECTED] 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.
+ 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(SAXTransformerFactory.FEATURE))
+ {
+ // If so, we can safely cast.
+ SAXTransformerFactory stfactory = ((SAXTransformerFactory) tfactory);
+
+ // Have the factory create a special ContentHandler that will
+ // create a Templates object.
+ TemplatesHandler handler = stfactory.newTemplatesHandler();
+
+ // If you don't do this, the TemplatesHandler won't know how to
+ // resolve relative URLs.
+ handler.setSystemId(xslID);
+
+ // Create a reader, and set it's content handler to be the
TemplatesHandler.
+ XMLReader reader = XMLReaderFactory.createXMLReader();
+ reader.setContentHandler(handler);
+
+ // Parse the source XML, and send the parse events to the
TemplatesHandler.
+ reader.parse(xslID);
+
+ // Get the Templates reference from the handler.
+ Templates templates = handler.getTemplates();
+
+ // Ready to transform.
+ Transformer transformer = templates.newTransformer();
+ transformer.transform(new StreamSource(sourceID), new
StreamResult(System.out));
+ }
+</pre>
+</code>
<p>The
[EMAIL PROTECTED]
javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter}
method allows the creation of a [EMAIL PROTECTED] org.xml.sax.XMLFilter},
which
@@ -65,5 +169,42 @@
parent [EMAIL PROTECTED] org.xml.sax.XMLReader}, and the final
transformation is
caused by invoking [EMAIL PROTECTED] 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(SAXTransformerFactory.FEATURE))
+ {
+ Templates stylesheet1 = tfactory.newTemplates(new
StreamSource(xslID_1));
+ Transformer transformer1 = stylesheet1.newTransformer();
+
+ SAXTransformerFactory stf = (SAXTransformerFactory)tfactory;
+ XMLReader reader = XMLReaderFactory.createXMLReader();
+
+ XMLFilter filter1 = stf.newXMLFilter(new StreamSource(xslID_1));
+ XMLFilter filter2 = stf.newXMLFilter(new StreamSource(xslID_2));
+ XMLFilter filter3 = stf.newXMLFilter(new StreamSource(xslID_3));
+
+ // transformer1 will use a SAX parser as it's reader.
+ filter1.setParent(reader);
+
+ // transformer2 will use transformer1 as it's reader.
+ filter2.setParent(filter1);
+
+ // transform3 will use transform2 as it's reader.
+ filter3.setParent(filter2);
+
+ filter3.setContentHandler(new ExampleContentHandler());
+ // filter3.setContentHandler(new org.xml.sax.helpers.DefaultHandler());
+
+ // Now, when you call transformer3 to parse, it will set
+ // itself as the ContentHandler for transform2, and
+ // call transform2.parse, which will set itself as the
+ // content handler for transform1, and call transform1.parse,
+ // which will set itself as the content listener for the
+ // SAX parser, and call parser.parse(new InputSource("xml/foo.xml")).
+ filter3.parse(new InputSource(sourceID));
+ }</pre>
+</code>
</body>
</html>
1.7 +23 -0
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.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- package.html 2000/12/20 04:55:32 1.6
+++ package.html 2001/01/02 03:49:03 1.7
@@ -26,5 +26,28 @@
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 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 cannot be resolved
correctly!
+ xslSource.setSystemId(xslID);
+
+ // Create a transformer for the stylesheet.
+ Transformer transformer = tfactory.newTransformer(xslSource);
+
+ InputStream xmlIS = new BufferedInputStream(new
FileInputStream(sourceID));
+ StreamSource xmlSource = new StreamSource(xmlIS);
+ // Note that if we don't do this, relative URLs cannot be resolved
correctly!
+ xmlSource.setSystemId(sourceID);
+
+ // Transform the source XML to System.out.
+ transformer.transform( xmlSource, new StreamResult(System.out));
+</pre>
+</code>
</body>
</html>
