dleslie 00/02/15 13:35:30
Modified: xdocs/sources xalanLocal.xml
xdocs/sources/xalan commandline.xml dtm.xml faq.xml
getstarted.xml overview.xml readme.xml samples.xml
Added: xdocs/sources/xalan usagepatterns.xml
Removed: xdocs/sources/xalan api.xml install.xml
Log:
Major revision of doc towards release 1.0. Still in rough shape
but major restructuring in place.
Revision Changes Path
1.2 +21 -18 xml-xalan/xdocs/sources/xalanLocal.xml
Index: xalanLocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalanLocal.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xalanLocal.xml 2000/02/04 14:39:49 1.1
+++ xalanLocal.xml 2000/02/15 21:35:29 1.2
@@ -65,37 +65,40 @@
<document id="overview"
label="Overview"
source="xalan/overview.xml"/>
-
- <separator/>
+
+ <separator/>
- <document id="install"
- label="Installation"
- source="xalan/install.xml"/>
-
- <document id="readme"
- label="Release Notes"
- source="xalan/readme.xml"/>
+ <document id="getstarted"
+ label="Getting Started"
+ source="xalan/getstarted.xml"/>
+ <separator/>
+
- <separator/>
+ <document id="samples"
+ label="Sample Apps"
+ source="xalan/samples.xml"/>
<document id="commandline"
label="Command Line"
source="xalan/commandline.xml"/>
-
- <document id="api"
- label="Xalan API"
- source="xalan/api.xml"/>
- <separator/>
+ <document id="usagepatterns"
+ label="Usage Patterns"
+ source="xalan/usagepatterns.xml"/>
+ <separator/>
+
<document id="dtm"
label="Xalan DTM"
source="xalan/dtm.xml"/>
-
- <separator/>
-
+
<document id="extensions"
label="Extensions"
source="xalan/extensions.xml"/>
+ <separator/>
+
+ <document id="readme"
+ label="Release Notes"
+ source="xalan/readme.xml"/>
</book>
1.2 +7 -6 xml-xalan/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- commandline.xml 2000/02/04 14:39:50 1.1
+++ commandline.xml 2000/02/15 21:35:29 1.2
@@ -63,26 +63,27 @@
<s2 title="Using the Command-Line Utility">
<p>To perform a transformation, you can call &xslt4j; from the command
line (or script),
- an applet, an application, or a servlet. see <resource-ref
idref="APIOverview"/> and <resource-ref idref="APIDocumentation"/>.</p>
+ an applet, an application, or a servlet (see <link
idref="usagepatterns">UsagePatterns</link>).</p>
<p>The org.apache.xalan.xslt.Process main() method provides a
comand-line interface
for performing XSL transformation. To perform a transformation from the
command line or a script,
do the following:</p>
<ol>
<li>Install &xslt4j;. See <resource-ref
idref="Installation"/>.<br/><br/></li>
- <li>Set the java Classpath to include xalan.jar and
xerces.jar.<br/><br/></li>
- <li>Call java and the Process class with the appropriate switches and
+ <li>Set the java Classpath to include xalan.jar and xerces.jar. See
<link idref="getstarted"
+ anchor="classpath">Setting the class path</link><br/><br/></li>
+ <li>Call java and the Process class with the appropriate flags and
arguments (described below). The following command line, for example,
includes the -IN, -XSL,
- and -OUT switches with their accompanying arguments -- the XML source
document, the XSL
+ and -OUT flags with their accompanying arguments -- the XML source
document, the XSL
stylesheet, and the output file:<br/><br/>
<code>java org.apache.xalan.xslt.Process -IN foo.xml -XSL foo.xsl -OUT
foo.out</code>
</li></ol>
- <p>The command line utility can take the following switches and
arguments:</p>
+ <p>The command line utility can take the following flags and
arguments:</p>
<source>
-IN inputXMLURL
-XSL XSLTransformationURL
-OUT outputFileName
-LXCIN compiledStylesheetFileNameIn
- -LXCOUT compiledStylesheetFileNameOut (it will be big!)
+ -LXCOUT compiledStylesheetFileNameOut
-PARSER fully qualified class name of parser liaison
-E (Keep--do not expand -- entity refs)
-V (Version info)
1.2 +9 -6 xml-xalan/xdocs/sources/xalan/dtm.xml
Index: dtm.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/dtm.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dtm.xml 2000/02/04 14:39:50 1.1
+++ dtm.xml 2000/02/15 21:35:29 1.2
@@ -64,12 +64,15 @@
<p>DOM (Document Object Model) is a standard interface for interacting
with XML documents. &xslt4j;
supports this interface: when you provide a Node as input for an XML
source document or XSL
stylesheet, &xslt4j; uses an implementation of the DOM interface. For
large XML documents, however,
- this may involve considerable overhead, since Xalan must create one or
more Java objects for each Node
+ this may involve considerable overhead, since &xslt4j; must create one
or more Java objects for each Node
in the document.</p>
- <p>For those cases where you provide a URL or character stream as input
and use the default XSML parser
- (&xml4j;) &xslt4j; avoids this overhead by implementing what we call a
DTM (Document Table Model), a
- pseudo-DOM that uses integer arrays in place of the DOM. The
performance improvements are very
- significant.</p>
- <p><ref>More to be written.</ref></p>
+ <p>For those cases where you provide a URL, file, character stream, SAX
input stream, or byte stream as input
+ and use the default XML liaison and parser, &xslt4j; avoids this
overhead by implementing a DTM, effectively
+ a "pseudo-DOM" that uses integer arrays in place of the DOM. For larger
input trees, the performance
+ improvements can be very significant.</p>
+ <p>The XSLTProcessorFactory getProcessor() method sets up an XSLT
processor to use the default liaison and
+ parser. If your input is a DOM, you must use a "standard" DOM parser.
In that case, you can use the
+ XercesLiaison and Xerces XML parser. For more information, see <link
idref="usagepatterns"
+ anchor="dom-in">Processing DOM input</link>.</p>
</s2>
</s1>
1.2 +7 -3 xml-xalan/xdocs/sources/xalan/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/faq.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- faq.xml 2000/02/04 14:39:50 1.1
+++ faq.xml 2000/02/15 21:35:29 1.2
@@ -3,10 +3,14 @@
<faqs title="Frequently asked questions about Xalan">
<faq title="title for first question">
- <q>first question?</q>
+ <q>How do I fix " DTMLiaison can not handle nodes of typeclass
org.apache.xerces.dom.DocumentImpl"
+
+</q>
<a>
- <p>answer</p>
- <p>more answer. can also include lists and tables.</p>
+ <p>Instantiate your processor as follows so that it will use
XercesLiaison:
+<source>org.apache.xalan.xslt.XSLTProcessor processor =
+ org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor(new
+
org.apache.xalan.xpath.xdom.XercesLiaison());</source>
</a>
</faq>
<faq title="title for second question">
1.3 +10 -221 xml-xalan/xdocs/sources/xalan/getstarted.xml
Index: getstarted.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/getstarted.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- getstarted.xml 2000/02/11 23:18:59 1.2
+++ getstarted.xml 2000/02/15 21:35:29 1.3
@@ -8,7 +8,6 @@
<li><link anchor="samples">Trying out the samples</link></li>
<li><link anchor="commandline">Performing your own transformations from the
command line</link></li>
<li><link anchor="java-apps">Creating your own XSLT applications</link></li>
-<li><link anchor="usage-patterns">Basic usage patterns</link></li>
</ul>
<anchor name="download"/>
<s2 title="Downloading what you need">
@@ -18,16 +17,16 @@
<li>xalan.jar</li>
<li>xerces.jar</li>
</ul>
-<p>You can get the Sun JDK or JRE from <jump
href="http://www.java.sun.com";>java.sun.com</jump>. Download the latest release
of Xalan and Xerces-java from <jump
href="http://xml.apache.org/dist/";>xml.apache.org</jump>. Check the <link
idref="readme" anchor="status">version release notes</link> to verify that you
are using the correct version of Xerces. <em>Important</em> You may experience
unpredicable difficulties and anomalies if your Xalan and Xerces builds are not
in synch.</p>
-<note>You may also download the latest releases of LotusXSL and the XML
Parser for Java from <jump
href="http://www.alphaworks.ibm.com/tech/LotusXSL";>alphaWorks</jump>. LotusXSL
and the XML Parser for Java are Xalan and Xerces-java respectively, along with
additional features and wrappers to support the core API that was in place on
alphaWorks before the first releases of Xalan and Xerces-java on xml.apache.org
in November 1999.</note>
+<p>You can get the Sun JDK or JRE from <jump
href="http://www.java.sun.com";>java.sun.com</jump>. Download the latest release
of Xalan and Xerces-java from <jump
href="http://xml.apache.org/dist/";>xml.apache.org</jump>. Check the <link
idref="readme" anchor="status">version release notes</link> to verify that you
are using the correct version of Xerces. <em>Important</em> You may experience
unpredicable difficulties and anomalies if your &xslt4j; and &xml4j; builds are
not in synch. You can use &xslt4j; with some other XML parser, but it is up to
you to implement a liaison to that parser. Your liaison class should extend
org.apache.xalan.xpath.xml.XMLParserLiaisonDefault and implement
org.apache.xalan.xpath.XPathSupport.</p>
+<note>You may also download the latest releases of LotusXSL and the XML
Parser for Java from <jump
href="http://www.alphaworks.ibm.com/tech/LotusXSL";>alphaWorks</jump>. LotusXSL
and the XML Parser for Java are Xalan and Xerces-java respectively, along with
additional features and with wrappers to support the core API in place on
alphaWorks before the first releases of Xalan and Xerces-java on xml.apache.org
in November 1999. The alphaWorks LotusXSL release also provides continued
support for earlier alphaWorks releases of the XML4J DOM and TXDOM
parsers.</note>
<p>If you plan to run <link idref="extensions">XSLT extensions</link>. you
need bsf.jar and bsfengines.jar, both of which are included in the Xalan
distribution. If you plan to run XSLT extensions implemented in JavaScript or
another scripting language, you will need one or more additional files as
indicated in <link idref="extensions" anchor="supported-lang">extensions
language requirements</link>.</p>
</s2><anchor name="classpath"/>
<s2 title="Setting up the system class path">
-<p>At the very minimum, you must include xalan.jar and xerces.jar on the
system class path. To run the examples, include xalansamples.jar To run
extensions, include bsf.jar and bsfengines.jar. All these JAR files are
distributed with &xslt4j;. For extensions implemented in JavaScript or another
scripting language, see <link idref="extensions"
anchor="supported-lang">extensions language requirements</link> to identify any
additional JAR files you must place on the class path and where you can get
them.</p>
+<p>At the very minimum, you must include xalan.jar and xerces.jar on the
system class path. To run the sample applications, include xalansamples.jar To
run extensions, include bsf.jar and bsfengines.jar. All these JAR files are
distributed with &xslt4j;. For extensions implemented in JavaScript or another
scripting language, see <link idref="extensions"
anchor="supported-lang">extensions language requirements</link> to identify any
additional JAR files you must place on the class path and where you can get
them.</p>
<p>If you are using JDK or JRE 1.1.x (at least 1.1.7, please), also include
classes.zip on the class path.</p>
</s2><anchor name="samples"/>
<s2 title="Trying out the samples">
-<p>The Xalan distribution includes a number of basic samples. These examples
are easy to run, and you can review the source files -- all of which are brief
-- to see just how they work.</p>
+<p>The Xalan distribution includes a number of basic sample applications.
These samples are easy to run, and you can review the source files -- all of
which are brief -- to see just how they work.</p>
<p>To run the samples, do the following:</p>
<ol>
<li>Set up your class path (see above), including xalansamples.jar.</li>
@@ -39,7 +38,7 @@
<p>For example, go to the SimpleTransformation subdirectory and issue the
following command:</p>
<p><code>java SimpleTransformation</code></p>
<p>The sample displays the transformation result on the screen. To see how
the example works, examine the source files: foo.xml, foo.xsl, and
SimpleTransformation.java.</p>
-<p>The extensions examples require additional JAR files on the class path,
and the procedure for running the sample applet and sample servlet is
different. For information about the samples, see <link
idref="samples">&xslt4j; Samples</link>.</p>
+<p>The extensions examples require additional JAR files on the class path,
and the procedure for running the sample applet and sample servlet is
different. For more information about all the samples, see <link
idref="samples">&xslt4j; Samples</link>.</p>
</s2><anchor name="commandline"/>
<s2 title="Performing your own transformations from the command line">
<p>java.org.apache.xalan.xslt.Process provides a basic utility for
performing transformations from the command line. You use this utility, for
example, to run the extensions samples. The command-line for the most standard
of
@@ -47,18 +46,18 @@
<p><code>java org.apache.xalan.xslt.Process -in
<ref>xmlSource</ref></code><br/>
<code> -xsl <ref>stylesheet</ref> -out
<ref>outputfile</ref></code></p>
<p>where <ref>xmlSource</ref> is the XML source file name,
<ref>stylesheet</ref> is the XSL stylesheet file name, and
<ref>outputfile</ref> is the output file name.</p>
-<p>If you want the output to be displayed on the screen, simply omit the
-out argument.</p>
-<p>You can use this utility to try out XSL stylesheets you have written, to
make sure they do what you expect with the XML source files they are designed
to transform. The utility provides useful messages if the source file or
stylesheet is not well-formed. If you include a DOCTYPE statement in your XML
source files and the -validate flag on the command line, the utility will also
let you know whether the XML document adheres to that DOCTYPE. For more
information, see <link idref="commandline">Command-Line Utility</link>.</p>
+<p>If you want the output to be displayed on the screen, simply omit the
-out flag and argument.</p>
+<p>You can use this utility to try out XSL stylesheets you have written, to
make sure they do what you expect with the XML source files they are designed
to transform. The utility provides useful messages if the source file or
stylesheet is not well-formed. If you include a DOCTYPE statement in your XML
source files and include the -validate flag on the command line, the utility
will also let you know whether the XML document is valid (conforms to that
DOCTYPE). For more information, see <link idref="commandline">Command-Line
Utility</link>.</p>
</s2><anchor name="java-apps"/>
<s2 title="Setting up your own Java applications">
<p>You can start by using your own XML source files and XSL stylesheets with
the sample applications, which illustrate a number of the <link
anchor="usage-patterns">basic usage patterns</link>.</p>
<p>If you modify a java source file, be sure to compile the class and place
it on the system class path. Here are some basic points to keep in mind as you
are setting up transformations:</p>
<ul>
-<li>Use one of the <resource-ref idref="XSLTProcessorFactoryDoc"/> static
getProcessor methods to set up an <resource-ref idref="XSLTProcessorDoc"/>.
<br/><br/>By default, the XSLTProcessor uses the <resource-ref
idref="DTMLiaison"/> and the high-performance <link idref="dtm">Document Table
Model (DTM)</link>"pseudo" DOM parser to process the input. If your input is a
DOM node (rather than a file, character stream, byte stream, or SAX input
stream), you must use a "standard" DOM liaison and parser, such as the
<resource-ref idref="XercesLiaisonDoc"/> and the Xerces DOM parser. For an
example, see <link anchor="dom-in">Processing DOM input</link>.<br/><br/></li>
+<li>Use one of the <resource-ref idref="XSLTProcessorFactoryDoc"/> static
getProcessor methods to set up an <resource-ref idref="XSLTProcessorDoc"/>.
<br/><br/>By default, the XSLTProcessor uses the <resource-ref
idref="DTMLiaisonDoc"/> and the high-performance <link idref="dtm"> Document
Table Model (DTM)</link>"pseudo" DOM parser to process the input. If your
input is a DOM node (rather than a file, character stream, byte stream, or SAX
input stream), you must use a "standard" DOM liaison and parser, such as the
<resource-ref idref="XercesLiaisonDoc"/> and the Xerces DOM parser. For an
example, see <link anchor="dom-in">Processing DOM input</link>.<br/><br/></li>
<li>Set up <resource-ref idref="XSLTInputSourceDoc"/> objects for the XML
input and XSL stylesheet. You can use a file name or URL, character streams,
byte streams, or SAX input stream to instantiate an XSLTInputSource
object.<br/><br/>
If the XML document contains a stylesheet Processing Instruction (PI), you
do not need to create a separate
XSLTInputSource object for an XSL stylesheet.<br/><br/></li>
-<li>For improved performance with a series of transformations, use the
XSLTProcessor processStylesheet method to compile the XSL stylesheet.<br/><br/>
+<li>For improved performance with a series of transformations, use the
XSLTProcessor processStylesheet method to compile the XSL stylesheet (the
result is a <resource-ref idref="StylesheetRootDoc"/>.<br/><br/>
This is also useful when you need to get information from the stylesheet
before the tranformation occurs, for
instance, when you need to find out the output encoding in order to
construct the right kind of Writer.
You must also compile the stylesheet if you are using the XSLTProcessor as a
SAX document handler.<br/><br/></li>
@@ -67,216 +66,6 @@
&xslt4j; is thread-safe for one instance per thread. If you are using the
same instance of XSLTProcessor to perform
more than one transformation, call the reset method between
transformations.</li>
</ul>
-<p>For more information on setting up transformations, see the following
section:</p>
-</s2><anchor name="usage-patterns"/>
-<s2 title="Basic usage patterns">
-<ul>
-<li><link anchor="files">Using a stylesheet file to transform an XML source
file into an output file</link></li>
-<li><link anchor="streams">Using data streams in place of files</link></li>
-<li><link anchor="params">Setting stylesheet parameters</link></li>
-<li><link anchor="compiled">Compiling stylesheets</link></li>
-<li><link anchor="dom-in">Processing DOM input</link></li>
-<li><link anchor="dom-out">Producing DOM output</link></li>
-<li><link anchor="sax">Generating and responding to SAX events</link></li>
-<li><link anchor="xpath">Working with XPath expressions</link></li>
-<li><link anchor="applet">Using the &xslt4j; applet wrapper</link></li>
-<li><link anchor="servlet">Using &xslt4j; in a servlet</link></li>
-<li><link anchor="extensions">Creating and using extensions</link></li>
-
-</ul><anchor name="files"/>
-<s3 title="Using XML source, XSL stylesheet, and output files">
-<p>Use an XML file and an XSL file to instantiate XSLTInput objects, create
a processor with the default DTM liaison, and send the transformation output to
an output file. For example:</p>
-<source>public static void transform(String xmlSourceURL, String xslURL,
String outputURL)
- throws java.io.IOException,
- java.net.MalformedURLException,
- org.xml.sax.SAXException
-{
- // Instantiate an XSLTProcessor.
- org.apache.xalan.xslt.XSLTProcessor processor =
- org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor();
-
- // Create the 3 objects the XSLTProcessor needs to perform the
transformation.
- org.apache.xalan.xslt.XSLTInputSource xmlSource =
- new org.apache.xalan.xslt.XSLTInputSource
("foo.xml");
- org.apache.xalan.xslt.XSLTInputSource xslSheet =
- new org.apache.xalan.xslt.XSLTInputSource ("foo.xsl");
- org.apache.xalan.xslt.XSLTResultTarget xmlResult =
- new org.apache.xalan.xslt.XSLTResultTarget
("foo.out");
-
- // Perform the transformation.
- processor.process(xmlSource, xslSheet, xmlResult);
- }</source>
-<p>For an online example, see <link idref="samples"
anchor="simpletransform">SimpleTransform</link>.</p>
-<p>You can perform this same operation from the <link
idref="commandline">command line</link>. For example:</p>
-<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -out
output.xml</code></p>
-</s3><anchor name="streams"/>
-<s3 title="Using data streams in place of files">
-<p>The context in which you perform a transformation may call for input in
the form of a character stream, byte stream, or SAX input stream, and output in
the form of a character stream, byte stream, or SAX document handler. Suppose,
for example, you want to output a stream of bytes for further processing:</p>
-<source>import org.apache.xalan.xslt.*;
-...
-java.io.OutputStream byteStream = new java.io.OutputStream();
-XSLTRegultTarget out = new XSLTResultTarget(byteStream)
-// Do the transformation...
-// Work with the OutputStream...</source>
-
-</s3><anchor name="params"/>
-<s3 title="Setting stylesheet parameters">
-<p>An XSL stylesheet can include parameters that get set at run time when a
transformation takes place. When we generate the HTML documents that make up
the Xalan doc set, for example, we send the stylesheet an id parameter along
with each XML source document. The id identifies that document and enables the
stylesheet to integrate it into the overall doc set.</p>
-<p>To set a stylesheet parameter, use the XSLTProcessor
setStylesheetParam(String paramName, String paramExpr) method. paramExpr is an
XPath expression, so if the parameter is a String, enclose it in single quotes
to make it a String expression.</p>
-<p>You can also use setStylesheetParam(String key, XObject value). This
option is useful when you are working with the XPath API. For example, you
could use the XObject returned by an Xpath function to set a parameter.</p>
-<p>From the <link idref="commandline">command line</link>, include a -param
argument. For example:</p>
-<p><code>java org.apache.xalan.xsltProcess -in foo.xml -xsl foo.xsl -param
'boo'</code></p>
-</s3><anchor name="compiled"/>
-<s3 title="Compiling stylesheets">
-<p>A <resource-ref idref="StylesheetRootDoc"/> object is a binary
representation of a stylesheet that adds efficiency to the performance of
repeated transformations and supports threadsafe concurrent access by multiple
clients. If, for example, you are setting up a servlet to perform
transformations, you can improve performance by compiling any stylesheets the
servlet repeatedly uses.</p>
-<p>To compile a stylesheet, use one of the the <resource-ref
idref="XSLTProcessorDoc"/> processStylesheet methods. This operation also sets
the XSLTProcessor Stylesheet property. In the interest of clarity, you may want
to explicitly set that property. When you call the process method, include a
null for the "uncompiled" stylesheet parameter so XLTProcessor uses the
compiled stylesheet. For example:</p>
-<source>import org.apache.xalan.xslt.*;
-...
-XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
-StylesheetRoot style = processor.processStylesheet(new
XSLTInputSource("foo.xsl"));
-processor.setStylesheet(style); // Good form!
-...
-processor.process(new XSLTInputSource("foo.xml"),
- null, // Use the Stylesheet property setting.
- new XSLTOutputTarget("foo.out"));</source>
-<p>Alternative: For convenience, StylesheetRoot has its own process method,
so another way to do the preceding is as follows:</p>
-<source>import org.apache.xalan.xslt.*;
-..
-XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
-StylesheetRoot style = processor.processStylesheet(new
XSLTInputSource("foo.xsl"));
-...
-style.process(new XSLTInputSource("foo.xml"), new
XSLTOutputTarget("foo.out"));</source>
-<p>If you want to use the XSLTProcessor as a SAX document handler, you must
provide the processor a compiled stylesheet. See <link anchor="sax">Generating
and Responding to SAX events</link>.</p>
-</s3><anchor name="dom-in"/>
-<s3 title="Processing DOM input">
-<p>The XML source and XSL stylesheet for a transformation may appear in the
form of a DOM Node. To perform transformations with DOM input, you cannot use
the default high-performance DTM liaison and parser. <link idref="dtm">DTM
(Document Table model)</link> uses a table of integers to represent a DOM, thus
avoiding much of the overhead of creating and manipulating actual DOM nodes,
which often involve a large number of Java objects. If you are processing DOM
input, you must use a DOM parser, such as the Xerces DOM parser. When you
create the XSLTProcessor for the transformation, you must specify that it is to
use the Liaison for such a DOM parser.</p>
-<p>The following code fragments illustrate the procedure for working with
DOM input:</p>
-<source>import org.apache.xerces.parsers.DOMParser;
-import org.w3c.dom.Document;
-import org.apache.xalan.xpath.xdom.XercesLiaison;
-import org.apache.xalan.xslt.*;
-...
-// Just in case you want to produce your own DOM input...
-DOMParser parser = new DOMParser();
-parser.parse("foo.xml");
-Document in = parser.getDocument();
-XSLTInputSource xmlID = new XSLTInputSource(in);
-
-// Set up the XSLTProcessor to use XercesLiaison.
-XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor
- (new org.apache.xalan.xpath.xdom.XercesLiaison())
-// or you can use XSLTProcessorFactory.getProcessorUsingLiaisonName
-// ("org.apache.xalan.xpath.xdom.XercesLiaison")
-...
-// Perform the transformation.</source>
-</s3><anchor name="dom-out"/>
-<s3 title="Producing DOM output">
-<p>To produce a DOM Node as your transformation output, use a new Node to
create the XSLTResultTarget for the transformation. Then when you perform the
transformation, the result is output as a DOM Node. For example:</p>
-<source>import org.w3.dom.Document;
-import org.apache.xalan.xslt.*;
-...
-XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor();
-org.w3c.dom.Document out = new org.apache.xerces.dom.DocumentImpl();
-XSLTResultTarget resultTarget = new XSLTResultTarget(out);
-processor.process(new XSLTInputSource("foo.xml"),
- new XSLTInputSource("foo.xsl"),
- resultTarget);</source>
-<p>The XSLTResultTarget object (resultTarget) now contains a Node. For a
working example, see <link idref="samples"
anchor="transformtodom">TransformToDom</link>.</p>
-</s3><anchor name="sax"/>
-<s3 title="Generating and responding to SAX events">
-<p>To set up a transformation to generate SAX events, set the
DocumentHandler property of the XSLTResultTarget object. The transformation
consumer can then respond to these events as they occur, rather than waiting
(as the consumer of a DOM must) for the complete result tree.</p>
-<p>This example sends the output to System.out.</p>
-<source>import org.apache.xalan.xslt.XSLTProcessor;
-import org.apache.xalan.xslt.XSLTInputSource;
-import org.apache.xalan.xslt.XSLTResultTarget;
-import org.apache.xalan.xslt.XSLTProcessorFactory;
-import org.apache.xalan.xslt.StylesheetRoot;
-
-public class TransformToSax
-{
- public static void main(String[] args)
- throws java.io.IOException,
- java.net.MalformedURLException,
- org.xml.sax.SAXException
- {
- XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
-
- // Set the processor to use a compiled stylesheet.
- // The stylesheet provides access to a SAX DocumentHandler,
- // passing it the stylesheet xsl:output settings.
- StylesheetRoot stylesheet = processor.processStylesheet("foo.xsl");
- // This property was just set implicitly, but for good form...
- processor.setStylesheet(stylesheet);
- // In this case, send the output to System.out.
- org.xml.sax.DocumentHandler dh = stylesheet.getSAXSerializer(System.out);
-
- // Use the DocumentHandler to construct an XSLTResultTarget object.
- XSLTResultTarget saxResult = new XSLTResultTarget(dh);
-
- // Perform the transformation. The stylesheet parameter is null, so
- // the processor uses the compiled stylesheet identified by its
- // Stylesheet property setting.
- processor.process(new XSLTInputSource("foo.xml"), null, saxResult);
- }
-}</source>
-<p>XSLTProcessor also has a DocumentHandler property (in fact, XSLTProcessor
extends DocumentHandler). By setting this property, you instruct the processor
to process a sequence of SAX events. The processor needs a compiled stylesheet
to perform this transformation.</p>
-<p>The following example uses the output of one transformation as the input
for a second transformation. It does this by using two SAX DocumentHandlers to
pipe SAX events from the first transformation to the second.</p>
-<source>import org.apache.xalan.xslt.*;
-
-public class ChainTransforms
-{
- public static void main(String[] args)
- throws java.io.IOException,
- java.net.MalformedURLException,
- org.xml.sax.SAXException
- {
- // Create processor for 1st transform.
- XSLTProcessor processor1 = XSLTProcessorFactory.getProcessor();
-
- // Create processor for 2nd transform. Set Stylesheet and
- // DocumentHandler properties so this processor uses the
- // 2nd stylesheet and processes SAX events (output from the
- // 1st transform), sending the final result to System.out.
- XSLTProcessor processor2 = XSLTProcessorFactory.getProcessor();
- StylesheetRoot stylesheet2 = processor2.processStylesheet("foo2.xsl");
- processor2.setStylesheet(stylesheet2);
- org.xml.sax.DocumentHandler dh =
stylesheet2.getSAXSerializer(System.out);
- processor2.setDocumentHandler(dh);
-
- // Set up the 1st transform to produce a series of SAX events, and
- // to pass these events to the processor for the 2nd transform.
- // To accomplish this, create an XSLTResultTarget object for the
- // 1st transform, and use the processor for the 2nd transform to set
- // the XSLTResultTarget DocumentHandler property.
- XSLTResultTarget intermedResult = new XSLTResultTarget();
- intermedResult.setDocumentHandler(processor2);
-
- // Perform the 1st transform, which produces a series of
- // SAX events that are in turn processed by the processor2
DocumentHandler
- // in conjunction with stylesheet2, sending the output to System.out.
- processor1.process(new XSLTInputSource("foo.xml"),
- new XSLTInputSource("foo.xsl"),
- intermedResult);
- }
-}</source>
-<p>For a more compact (and elegant) form of this example, see the <link
idref="samples" anchor="pipe">Pipe</link>.</p>
-</s3><anchor name="xpath"/>
-<s3 title="Working with XPath expressions">
-<p>XSL stylesheets use XPath expressions to select nodes, specify
conditions, and generate text for the result tree. XPath provides an API that
you can call directly. For example, you may want to select nodes
programatically and do your own processing without a stylesheet. For a
preliminary example that verifies the syntax of inidvidual XPath expressions,
see <link idref="samples" anchor="validatexpath">ValidateXPath</link>.</p>
-</s3><anchor name="applet"/>
-<s3 title="Using the &xslt4j; applet wrapper">
-<ol>
-<li>Include <resource-ref idref="XSLTProcessorAppletDoc"/> in an HTML
client.<br/><br/></li>
-<li>Specify the XML source document and XSL stylesheet.<br/><br/>
-You can use the DocumentURL and StyleURL PARAM tags or the <resource-ref
idref="XSLTProcessorAppletsetDocumentURLDoc"/> and <resource-ref
idref="XSLTProcessorAppletsetStyleURLDoc"/>. If the XML document contains a
stylesheet Processing Instruction (PI), you do not need to specify an XSL
stylesheet.<br/><br/></li>
-<li>Call the <resource-ref
idref="XSLTProcessorApplettransformtoHTMLstringstringDoc"/> which performs the
transformation and returns the new document as a String.</li></ol>
-<p>For an example, see the <jump href="samples/applet/readme.html">sample
applet readme</jump>.</p>
-</s3><anchor name="servlet"/>
-<s3 title="Using &xslt4j; in a servlet">
-<p>You can set up a servlet to use &xslt4j; to respond to requests for XML
documents by transforming those documents into HTML and serving them to
clients. For a sample of how this might be done, see <link idref="samples"
anchor="servlet">sample servlet</link>.</p>
-</s3><anchor name="extensions"/>
-<s3 title="Creating and using extensions">
-<p>For those cases where you want to be able to call procedural code from
within a stylesheet, the &xslt4j; Extensions facility supports the creation of
extension elements and extension functions. See <link
idref="extensions">Extensions</link> and <link idref="samples"
anchor="extensions">Extensions samples</link>.</p>
-</s3>
+<p>For more information on setting up applications, see <link
idref="usagepatterns">Usage Patterns</link>.</p>
</s2>
</s1>
1.3 +63 -59 xml-xalan/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/overview.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- overview.xml 2000/02/11 23:18:58 1.2
+++ overview.xml 2000/02/15 21:35:29 1.3
@@ -59,83 +59,88 @@
-->
<s1 title="&xslt4j; Overview">
-
+<ul>
+<li><link anchor="intro">Introduction</link></li>
+<li><link anchor="features">&xslt4j; Features</link></li>
+<li><link anchor="towork">Getting to work with &xslt4j;</link></li>
+<li><link anchor="uptospeed">Getting up to speed with XSLT</link></li>
+<li><link anchor="glossary">Glossary</link></li>
+</ul><anchor name="intro"/>
<s2 title="Introduction">
- <p>&xslt4j; (named after a rare musical instrument) provides high-
- performance XSL stylesheet processing. &xslt4j; fully implements the
W3C
- XSLT recommendation. The stylesheet processor is feature rich and
- robust.
- </p>
- <p>XSL is a language for expressing stylesheets and other types of
transformations.
- It consists of two parts:</p>
- <ol>
- <li>XLST, a language for transforming XML documents into
other XML documents,
- HTML documents, or other document types. This part of the language
includes the XSL
- Transformation vocabulary and XPath, a language for addressing parts
of an XML document.
- XPath is designed to be used by both XSLT and
XPointer.<br/><br/></li>
- <li>An XML vocabulary for specifying formatting semantics
(called <ref>Formatting
- Objects</ref>).<br/><br/></li>
- </ol>
-
- <p>&xslt4j; implements the first part of XSL, the
<resource-ref idref="xsl-draft-used"/>.
- An XSLT stylesheet specifies the transformation that may be performed
with a range of XML
- documents by describing how to transform such a tree of nodes into
another XML tree of
- nodes.</p>
- <note>The XSLT stylesheet may include cascading style sheets (CSS) in
the result.</note>
- <p>In the following example, the foo.xsl stylesheet is used to
transform foo.xml into foo.out:</p>
- <p>foo.xml:</p>
- <source>
-<?xml version="1.0"?>
-<doc>Hello</doc>
- </source>
+ <p>&xslt4j; (named after a rare musical instrument) fully implements the
<resource-ref idref="xsl-draft-used"/>.
+ XSLT is the first part of the XSL stylesheet language for XML. It
includes the XSL Transformation vocabulary and the
+ XML Path language (XPath), a language for addressing parts of XML
documents. For links to background materials,
+ discussion groups, frequently asked questions, and tutorials on XSLT,
see <link anchor="uptospeed">Getting up
+ to speed with XSLT</link>.</p>
+ <note>XSL also includes a formatting vocabulary, which is still under
design and is not part of &xslt4j;.
+ For more information, see <jump href="http://www.w3.org/TR/xsl/";>W3C XSL
Working Draft</jump> and the <jump
+ href="http://xml.apache.org/fop";>Apache XML FOP (Formatting Objects
Project)</jump>.</note>
+ <p>You use XSLT to compose stylesheets (themselves XML documents) for
transforming XML documents into other XML
+ documents, HTML documents, or other document types. In structural terms,
an XSLT stylesheet specifies the transformation
+ of one tree of nodes (the XML input) into another tree of nodes (the
output or transformation result).</p>
+ <note>The XSLT stylesheet may include cascading style sheets (CSS) in
the result.</note>
+ <p>In the following example, the foo.xsl stylesheet is used to transform
foo.xml into foo.out:</p>
+ <p>foo.xml:</p>
+ <source><?xml version="1.0"?>
+<doc>Hello</doc></source>
<p>foo.xsl:</p>
- <source>
-<?xml version="1.0"?>
+ <source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0">
<xsl:template match="doc">
<out><xsl:value-of select="."/></out>
</xsl:template>
</xsl:stylesheet></source>
- <p>foo.out:</p><source>
-<out>Hello</out></source>
- <p>By default, &xslt4j; uses &xml4j;
- to parse input XML documents and XSL stylesheets, but it can be
adapted to work with
- other DOM-producing mechanisms.</p>
- <p>During the course of a transformation, &xslt4j; produces SAX
events,
- an output DOM, or an XML result document based on the transformations
specified in the
- XSL stylesheet.</p>
- </s2>
+<p>foo.out:</p>
+<source><out>Hello</out></source>
+<p>By default, &xslt4j; uses a high-performance <link idref="dtm">Document
Table Model (DTM)</link> to parse the input -- XML documents and XSL
stylesheets, but it can be set to use the &xml4j; XML parser, and it can be
adapted to work with other DOM-producing mechanisms and SAX document handlers.
The input may appear in the form of a file, a character stream, a byte stream,
a DOM, or a SAX input stream.</p>
+<p>&xslt4j; performs the transformations specified in the XSL stylesheet and
produces a document file, a character
+ stream, a byte stream, a DOM, or a series of SAX events, as you specify
when you set up the transformation.</p>
+ </s2><anchor name="features"/>
<s2 title="&xslt4j; Features">
<ul>
<li>Implements the <resource-ref
idref="xsl-draft-used"/>.</li>
- <li>Uses &xml4j;</li>
- <li>Can interface to any XML parser that produces Java DOM Trees</li>
+ <li>Uses <jump
href="http://xml.apache.org/xerces-j/index.html";>&xml4j;</jump>
+ (and <jump href="http://www.alphaworks.ibm.com/tech/xml4j";>the
alphaWorks XML Parser for Java</jump>)</li>
+ <li>Can interface to a SAX document handler or to any XML parser that
produces Java DOM Trees</li>
<li>Can output to SAX or DOM</li>
- <li>Includes an applet wrapper</li>
- <li>Supports Java and JavaScript extensions</li>
- <li>Supports the production in a single operation
- of multiple output documents</li>
+ <li>May be run from the <link idref="commandline">command
line</link></li>
+ <li>Includes an <link idref="getstarted" anchor="applet">applet
wrapper</link></li>
+ <li>May be used in a <link idref="samples"
anchor="servlet">servlet</link> to transform XML documents into HTML
+ and serve the results to clients.</li>
+ <li>Supports <link idref="extensions">Java and scripting language
extensions</link></li>
+ <li>Provides <link idref="extensions" anchor="redirect">an extension
to support the production of multiple
+ output documents in a single operation</link></li>
</ul>
- </s2>
-
+ </s2><anchor name="towork"/>
+ <s2 title="Getting to work with &xslt4j;">
+ <p>For instructions and some suggestions about how to get started using
&xslt4j;, see
+ <link idref="getstarted">Getting Started</link>.</p>
+ </s2><anchor name="uptospeed"/>
+
<s2 title="Getting up to speed with XSLT">
- <p>If you are still working through some of the details of the XSLT
spec, you may want to make use of one or more
- of the following:</p>
+ <p>If you are still working through the details of the XSLT spec (the
W3C 1.0 Recommendation), you may want to consult
+ one or more of the following:</p>
<ul>
<li>Elliotte Rusty Harold's <jump
href="http://metalab.unc.edu/xml/books/bible/updates/14.html";>Chapter 14 of
the XML Bible: XSL Transformations</jump><br/><br/></li>
- <li>Crane Softwright's <jump
href="http://www.CraneSoftwrights.com/training/";>Free preview of Practical
Transformation Using XSLT
- and XPath</jump><br/><br/></li>
+ <li>Crane Softwright's <jump
href="http://www.CraneSoftwrights.com/training/";>Free preview of Practical
+ Transformation Using XSLT and XPath</jump><br/><br/></li>
<li>The Mulberry <jump
href="http://www.mulberrytech.com/xsl/xsl-list/";>XSL-List -- Open Forum on
XSL</jump>
(of interest to XSL users at all levels)<br/><br/></li>
- <li>Dave Pawson's <jump
href="http://freespace.virgin.net/b.pawson/xsl/index.html#top";>XSL Frequently
Asked Questions</jump><br/><br/></li>
-<li>Objects by Design's <jump
href="http://www.objectsbydesign.com/projects/xmi_to_html.html";>Transforming
XMI to HTML</jump><br/><br/></li>
-<li>Nic Miloslav's <jump
href="http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/index.html";>XSL
Tutorial</jump>
-<br/><br/></li>
+ <li>Dave Pawson's <jump
href="http://freespace.virgin.net/b.pawson/xsl/index.html#top";>XSL Frequently
Asked
+ Questions</jump><br/><br/></li>
+ <li>Objects by Design's <jump
href="http://www.objectsbydesign.com/projects/xmi_to_html.html";>Transforming
XMI to
+ HTML</jump><br/><br/></li>
+ <li>Nic Miloslav's <jump
href="http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/index.html";>XSL
Tutorial</jump>
+ <br/><br/></li>
+ <li>OASIS (the Organization for the Advancement of Structured
Information Standards):
+ <jump href="http://www.oasis-open.org/cover/xsl.html";>Extensible
Stylesheet Language (XSL)</jump> by Robin
+ Cover</li>
</ul>
- <p>This is a very preliminary list. If you have come across other useful
introductionary or background materials,
- please email <human-resource-ref idref="dleslie"/>, so he can add them
to this list.</p>
- </s2>
+ <p>When you come across other useful introductionary or background
materials, please email <human-resource-ref
+ idref="dleslie"/>, so he can add them to this list.</p>
+
+ </s2><anchor name="glossary"/>
<s2 title="Glossary">
<gloss>
<label>XSL Instruction</label>
@@ -164,5 +169,4 @@
<jump
href="http://freespace.virgin.net/b.pawson/xsl/xslvocab.html#top";>XSLT
Terminology
Clarification</jump>.</p>
</s2>
-
</s1>
1.2 +90 -153 xml-xalan/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/readme.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- readme.xml 2000/02/04 14:39:50 1.1
+++ readme.xml 2000/02/15 21:35:29 1.2
@@ -61,159 +61,96 @@
* <http://www.apache.org/>.
-->
<s1 title="Release Notes">
-
- <s2 title="Disclaimer">
- <p>In its current form, &xslt4j; is a Developer Preview, not a product.
- It implements a draft standard that is still in design. APIs will
continue to change,
- with no promise of backwards compatibility. This software contains
known and unknown bugs.
- We recommend against using this software for mission critical
applications.
- The Apache Software Foundation will not take responsibility for any
problems that may ensue
- from using this software.</p>
- <p>For a general overview of &xslt4j;, see <resource-ref
idref="Introduction"/>. For information about the &xslt4j;
- API, see <resource-ref idref="APIOverview"/> and <resource-ref
idref="APIDocumentation"/>.</p>
- <p>For the Apacke Software License, see <resource-ref
idref="ApacheLicense"/>.</p>
- </s2>
-
- <s2 title="Performance Notes">
- <p>We have done a great deal in versions 0.18 and 0.19 to
improve performance. However, as these things often go, we
- have not yet met our goal for a 10-fold performance increase. We provide
his list of what we understand the bottlenecks
- to be so that you may understand and, in some cases, work around them.
The bottlenecks appear
- to be:</p>
- <gloss>
- <label>Class load and JIT (Just In Time compiler)</label>
- <item>As we've added architecture to improve raw transform
performance, we've
- also increased the number of classes and class
instances that need loading, and
- the amount of code that needs JIT compiling. Although
we can shrink the code size
- a bit, the time required to load the processor will
continue to be an issue. The
- one thing the caller of the API can do is pre-warm the
JIT by transforming
- a dummy document. For an example of this technique, see
the init() method in the
- <link idref="XSLTProcessorAppletDoc"/>. During applet
initialization, a dummy document
- is transformed, so the response time for performing "real"
- transformations will be reasonable.<br/><br/></item>
- <label>Stylesheet Compilation</label>
- <item>&xslt4j; now reads the stylesheet from the parser's
SAX events (unless you
- give it a DOM, in which case it produces SAX events
from the DOM), and builds
- an internal tree structure. This structure processes
the attributes, precompiles
- the XPath expressions, and does other things that can
be done before it knows
- about the input tree. The construction of large
stylesheets is not as fast as
- we would like. We have been focusing on the
transformation itself, and will
- have to concentrate on optimizing the stylesheet
compilation down the road a bit.
- <br/><br/></item>
- <label>The DOM</label>
- <item>DOM nodes are big. Every node, including attribute
nodes and whitespace nodes,
- have a next, previous, parent, first child, last child,
ownerDocument, name, value, userData,
- and a few internal flags. So building the input DOM can
take a lot of memory
- management. We are working on ways to get around this
when &xslt4j; builds
- the input tree, while still maintaining our DOM input
architecture.<br/><br/></item>
- <label>Union Sorting in Document Order</label>
- <item>XSLT has to return nodes in document order.
Determining document order from
- a pure DOM is difficult. We have developed a method to
determine the order
- that is pretty good, but it is not as fast as simply
determining document order
- based on a integer. Also, the collation method of
combining two node lists
- is not as effecient as it needs to be, simply because
we haven't had time to
- address it yet (the issues are more complex than was
first apparent). The net
- of this is that union expressions aren't scalable to
large node sets. For instance,
- we have one user who has a large document with 3800
elements right under the
- root node, and they apply a standard
-
select="*|@*|comment()|processing-instruction()|text()" expression to these
- nodes. The 3800 elements happen to have 3800
whitespace nodes interleafed
- between them, and the union selection has to create a
nodelist of 3800 elements
- and 3800 whitespace nodes, and combine them, testing
for document order as
- it goes. As a result, the processing takes forever.
We're working on ways
- to fix this, but, the answer for this user was to not
do the union selection
- at the top level (they didn't care about the
whitespace nodes anyway).
- <br/><br/></item>
- <label>Selects in Large Documents</label>
- <item>&xslt4j; currently builds no inverted indexes for
the input document, and
- does not take advantage of DTD structures to
optimize, and otherwise does
- no special magic to locate nodes other than try to
implement efficient
- algorithms. While inverted indexes and taking
advantage of DTD structures
- are on our list for options, users should be aware
that patterns such as
- '//foo' at the top of the tree can be expensive.
- <br/><br/></item>
- <label>xsl:number and xsl:sort</label>
- <item>Both sorting and numbering are not as efficient as
they could be.
- <br/><br/></item>
- </gloss>
- </s2>
- <s2 title="API">
- <p>Please see the <resource-ref idref="APIOverview"/> for
- information about the &xslt4j; Application Programmer's
Interface and the
- source code.</p>
- <p>The <resource-ref idref="APIDocumentation"/> is in the
<resource-ref idref="APIDocumentationDir"/>.</p>
- </s2>
-
- <s2 title="Tips">
- <ul>
- <li>&xslt4j; is thread-safe with an instance per thread.
You can not run
- the same instance in multiple threads.</li>
- <li>&xslt4j; contains a DTD for XSL when used for HTML.
(Thanks be to
- Henrique M. Holschuh for this). This DTD should not be used for
run-time
- production when performance is a concern, but is useful during
the development
- stages. It is used in the readme XSL.<br/><br/></li>
- <li>
- The rule for whitespace that can be stripped is as follows:<br/>
- If a text node contains whitespace followed by a non-whitespace
- character followed by whitespace, none of the whitespace is ever
- stripped. If a text node is all whitespace, and does not have
- siblings that are character data, it should be stripped. A
- CDATA section is interpreted as character data.<br/><br/>
- </li>
- <li>
- Be aware that select arguments for variables, or arguments passed
through the
- command line via the -PARAM switch, are expressions, not strings.
So to set
- a variable to a string you need to do:<br/>
- <code>
- <![CDATA[<xsl:variable name="ExpressionTest"
- select="'A test for xsl:constant and
xsl:value-of'"/>]]>
- </code><br/>
- Notice the extra single quotes (').<br/><br/>
- </li>
- <li>
- If you're using an XSL stylesheet with a DTD, attributes typed as
IDs will
- have a problem when you try and put an attribute template into them.
Just
- something to watch out for. We don't really have a solution for
this,
- except that you probably can't type literal result element
attributes as
- IDs for the XSL stylesheet.<br/><br/>
- </li>
- </ul>
- </s2>
-
- <s2 title="Redirect Extension (Multiple Output Docs)">
- <p>&xslt4j; has a built in extension to let you produce multiple
output documents
- from a single stylesheet. The extension is limited right now to
producing
- files, when the output method is "xml", "html", or "text". See
<resource-ref
- idref="RedirectDoc"/> for details.</p>
- </s2>
-
- <s2 title="Version Notes">
- &done-j;
+ <ul>
+ <li><link anchor="status">Status</link></li>
+ <li><link anchor="build">Build Notes</link></li>
+ <li><link anchor="contact">Getting in touch</link></li>
+ </ul>
+ <s2 title="Status">
+ <ul>
+ <li><link anchor="status">Version of &xml4j; to use</link></li>
+ <li><link anchor="done">Bug fixes</link></li>
+ <li><link anchor="bugs">Outstanding bugs</link></li>
+ </ul>
<anchor name="status"/>
&status-j;
+ <anchor name="done"/>
+ &done-j;
+ <anchor name="bugs"/>
&bugs-j;
- </s2>
-
- <s2 title="Contact Info and Bug Reports">
- <p>Contact information for &xslt4j;: <human-resource-ref
idref="xalandev"/></p>
- </s2>
-
- <s2 title="Glossary">
- <gloss>
- <label>XSL Instruction</label>
- <item>Any tag with an XSL namespace prefix.<br/><br/></item>
- <label>XSL Template Instruction</label>
- <item>Any tag with an XSL namespace prefix that occurs inside
an
- xsl:template element.<br/><br/></item>
- <label>Template Child</label>
- <item>Any node that is a child of an xsl:template
element.<br/><br/></item>
- <label>Source Tree</label>
- <item>The tree input to the XSL process.<br/><br/></item>
- <label>Result Tree</label>
- <item>The tree that is output by the XSL
process.<br/><br/></item>
- <label>Stylesheet Tree</label>
- <item>The stylesheet tree produced from the XSL
file.<br/><br/></item>
- <label>Pattern List</label>
- <item>A parsed query or match pattern.<br/><br/></item>
- </gloss>
- </s2>
-</s1>
+ </s2>
+ <anchor name="build"/>
+ <s2 title="Build Notes">
+<ul>
+<li><link anchor="jar">Rebuilding xalan.jar</link></li>
+<li><link anchor="samples">Rebuilding sample applications</link></li>
+<li><link anchor="doc">Rebuilding the &xslt4j; documentation</link></li>
+</ul>
+<anchor name="jar"/>
+ <s3 title="Rebuilding &xslt4j;">
+ <p>The &xslt4j; build is in xalan.jar. The &xslt4j; source code tree is
in the src directory.
+ If you want to rebuild xalan.jar, you can do the following:</p>
+ <ol>
+ <li>Set up GNU or the equivalent build environment on your
workstation.<br/><br/>
+ If you are running Windows 95/98/NT, you can use the Cygwin port of
GNU. Be sure to put the
+ appropriate Cygwin bin directory at the beginning of your system
path. For information about
+ Cygwin, see <jump
href="http://www.sourceware.cygnus.com/cygwin/";>Cygwin</jump>.<br/><br/></li>
+ <li>Place <resource-ref idref="xerces-used"/> xerces.jar in the Java
classpath.<br/><br/></li>
+ <li>If you are working in Windows, set MAKE_MODE as follows:<br/><br/>
+ <code>set MAKE_MODE=UNIX</code><br/><br/></li>
+ <li>Run the make file in the &xslt4j; root directory:<br/><br/>
+ <code>make build</code><br/><br/></li>
+ </ol>
+ <p>If you want to do the build without the GNU build environment, keep
the following in mind:</p>
+ <ul>
+ <li>Set the class path to include the src directory, xerces.jar,
bsf.jar, and bsfengines.jar.</li>
+ <li>Use javac to compile all the .java files in the src tree. </li>
+ <li>Use the Sun jar utility to store the resulting .class files in
xalan.jar</li>
+ </ul>
+ </s3><anchor name="samples"/>
+ <s3 title="Rebuilding a sample application">
+ <p>If you modify a sample and want to recompile it, you can run javac in
the directory containing the
+ example. Be sure xalan.jar and xerces.jar are on the class path. To
recompile (and run!) the class files in the
+ Servlet subdirectory, the javax.servlet and javax.servlet.http packages
must also be on the class path. Sun
+ distributes these packages in the JSWDK 1.0.1 servlet.jar file.</p>
+ <p>After recompiling a sample, you can use the Sun jar utility to place
your new .class files in
+ xalansamples.jar.</p>
+ </s3><anchor name="doc"/>
+ <s3 title="Rebuilding the &xslt4j; documentation">
+ <p>&xslt4j; includes a number of XML source files, XSL stylesheets,
document type definition (DTD)
+ files, entity relationship (ENT) files, graphics, and a JavaScript
file that provide the input for the Xalan
+ HTML User's Guide, and the overview and package-level documents used
during the generation of Javadoc.</p>
+ <p>To generate the Xalan HTML User's Guide, run the Xalan make file in
the Xalan xdocs directory:<br/><br/>
+ <code>make stylebook</code></p>
+ <p>To generate Xalan API documentation, set up the make file to use the
Javadoc tool in the Java JDK 1.2.2 bin
+ directory.</p>
+ <p>Do the following:</p>
+ <ol>
+ <li>Put the Java JDK 1.2.2 bin directory on your path (in front of
any JDK 1.1.x bin
+ directory that appears on the path).<br/><br/></li>
+ <li>In the Xalan docs directory, run the Xalan make file as
follows:<br/><br/>
+ <code>make javadoc</code><br/><br/></li>
+ </ol>
+ <p>If you want to rebuild the documentation without using the GNU
build environment, keep the following in
+ mind:</p>
+ <ul>
+ <li>Be sure stylebook-1.0-b1.jar, xalan.jar, bsf.jar, bsfengines.jar,
and xerces.jar are on the class
+ path.<br/><br/></li>
+ <li>To build doc in a build/docs subdirectory, run StyleBook from the
xdocs directory as follows:<br/><br/>
+<code>java org.apache.stylebook.StyleBook "targetDirectory=../build/docs/"
sources/xalanLocal.xml style</code>
+ <br/><br/></li>
+ <li>To build the html source files that javadoc needs for top-level
and package-level documentation, run
+ StyleBook from the xdocs directory as follows:<br/><br/>
+ <code>java org.apache.stylebook.StyleBook
"loaderConfig=sbk:/style/loaderjdoc.xml" targetDirectory=../src
sources/javadocPackages.xml style</code><br/><br/></li>
+ <li>Before you run javadoc, make sure the following directory
structure exists under the Xalan root
+ directory: build/docs/apidocs.<br/><br/></li>
+ <li>To build the API documentation, run the JDK 1.2.2 javadoc tool
from the xdocs directory:<br/><br/>
+<code>javadoc -overview ../src/javadocOverview.html -sourcepath ../src
org.apache.xalan.xpath org.apache.xalan.xpath.xdom org.apache.xalan.xpath.dtm
org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apache.xalan.xslt.trace
org.apache.xalan.xslt.client org.apache.xalan.xslt.extensions -windowtitle
Xalan -d ../build/docs/apidocs</code></li>
+</ul>
+ </s3>
+ </s2><anchor name="contact"/>
+ <s2 title="Getting in Touch">
+ <p>Your feedback is more than welcome. Offers of help are even more so!
Perhaps you would like to contribute to the ongoing development, testing, or
documentation of &xslt4j;?</p>
+<p>Please email your comments, questions, suggestions, bug reports, and
offers to help to <human-resource-ref idref="xalandev"/>.</p>
+ </s2>
+</s1>
\ No newline at end of file
1.3 +23 -18 xml-xalan/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- samples.xml 2000/02/11 23:18:58 1.2
+++ samples.xml 2000/02/15 21:35:30 1.3
@@ -11,7 +11,7 @@
<li><link anchor="simpletransform">SimpleTransform</link></li>
<li><link anchor="transformtodom">TransformToDom</link></li>
<li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
-<li><link anchor="validatexpath">ValidateXPath</link></li>
+<li><link anchor="xpath">ApplyXPath</link></li>
<li><link anchor="pipe">Pipe (SAX)</link></li>
<li><link anchor="extensions">Extensions</link></li>
<li><link anchor="applet">Applet</link></li>
@@ -36,9 +36,8 @@
<p>The basic command line for running most of the samples is </p>
<p><code>java <ref>classname args</ref></code></p>
<p>where <ref>classname</ref> is the classname and <ref>args</ref> are
the arguments, if any. As described in
- the
- following sections, some samples take no arguments. The samples in
params and ValidateXPath take an argument
- in addition to classname. The samples in extensions use the &xslt4j;
<link idref="commandline">command-line
+ the following sections, some samples take no arguments. The samples in
UseStylesheetParam and ApplyXPath take
+ additional arguments. The samples in extensions use the &xslt4j; <link
idref="commandline">command-line
utility</link>, so they take arguments for the XML source file and the
XSL stylesheet.</p>
</s2><anchor name="simpletransform"/>
<s2 title="SimpleTransform">
@@ -61,12 +60,17 @@
<p>Run this sample from the UseStylesheetParam subdirectory with</p>
<p><code>java UseStylesheetParam <ref>param</ref></code></p>
<p>where <ref>param</ref> is the stylesheet parameter.</p>
- </s2><anchor name="validatexpath"/>
- <s2 title="ValidateXPath">
- <p>What it does: The ValidateXPath class validates and displays a
textual diagram of an XPath expression.</p>
+ </s2><anchor name="xpath"/>
+ <s2 title="ApplyXPath">
+ <p>What it does: The ApplyXPath class executes an XPath expression
against an XML document and returns
+ information about the route it takes and the nodes (if any) it
finds.</p>
<p>Run this sample from the ValidateXPath subdirectory with</p>
- <p><code>java ValidateXPath <ref>XPathExpression</ref></code></p>
- <p>where <ref>XPathExpression</ref> is an XPath expression, such as
"aa/bb//xx".</p>
+ <p><code>java ApplyXPath <ref>XMLFile XPathExpression</ref></code></p>
+ <p>where <ref>XMLFile</ref> is an XML source file and
<ref>XPathExpression</ref> is an XPath expression to apply to that
+ file. The ApplyXPath subdirectory contains an XML file named foo.xml, so
you can try command lines like</p>
+ <p><code>java ApplyXPath foo.xml /</code></p>
+ <p>and</p>
+ <p><code>java ApplyXPath foo.xml /doc/name/@first</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
<p>What it does: The Pipe class uses the output of the first
transformation as input to a second
@@ -84,13 +88,14 @@
extensions implemented in JavaScript, and two of the samples use
extensions implemented in Java. All of
the samples are documented in <link
idref="extensions">Extensions</link>.</p>
<p>To run these examples, you must place bsf.jar and bsfengines.jar
(distributed with &xslt4j;), and js.jar
- (availablee from http://www.mozilla.org/rhino) on the class path. You
do not need js.jar
+ (available from http://www.mozilla.org/rhino) on the class path. You do
not need js.jar
on the class path for the samples that use Java extensions. </p>
<p>Use java.org.apache.xalan.xslt.Process, the &xslt4j; command-line
utility, to run these samples from
the command line. The command line must include an -in argument with
the XML source and an -xsl argument with
the XSL stylesheet. If you want the output to be printed to a file,
rather than to the screen, add an -out
argument for the output file.</p>
- <p>Run these samples from the extensions directory as follows:</p>
+ <p>Run these samples from the extensions directory as follows (each of
the following is a single command
+ line):</p>
<p><code>java org.apache.xslt.xalan.Process -in 1basicJscript</code>
<br/> <code>-xsl 1basicJscript</code></p>
@@ -101,7 +106,7 @@
<p><code> java org.apache.xslt.xalan.Process -in 4numlistJcript.xml
</code>
<br/> <code>-xsl 4numlistJscript.xsl</code></p>
</s2><anchor name="applet"/>
- <s2 title="Applet">
+ <s2 title="AppletXMLtoHTML">
<p>The applet uses a stylesheet to transform an XML document into HTML.
It displays the XML document, the
stylesheet, and the HTML output.</p>
<p>How to run it: See <jump href="samples/applet/readme.html">sample
applet readme</jump>.</p>
@@ -114,7 +119,7 @@
which stylesheet is to be used depending on the client
browser/device.</p>
<p>How to run it:</p>
<ol>
- <li>Configure your application server (Websphere or JServ, for
example)so it can find the classes (in
+ <li>Configure your application server (Websphere or JServ, for
example) so it can find the classes (in
xalansamples.jar) as well as the stylesheets and properties file in
the servlet subdirectory.</li>
<li>Set up an HTML client to call DefaultApplyXSL with arguments as
illustrated below.</li>
</ol>
@@ -122,23 +127,23 @@
<gloss>
<label>http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl</label>
<item>...applies the style.xsl stylesheet to the data.xml data. Both files
are
-served from the Web server's HTTP XSLTInputSource root.</item>
+served from the Web server's HTTP XSLTInputSource root.<br/><br/></item>
<label>http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl&debug=true</label>
<item>...ensures that XML and XSL processor messages are returned in the
event of problems
-applying style.xsl to data.xml</item>
+applying style.xsl to data.xml<br/><br/></item>
<label>http://localhost/servlet/DefaultApplyXSL/data.xml?xslURL=/style.xsl</label>
<item>...applies the style.xsl stylesheet to the data.xml data, just like
the first example.
This is an alternative way of specifying the XML XSLTInputSource by
utilizing the HTTP request's path
-information.</item>
+information.<br/><br/></item>
<label>http://localhost/servlet/DefaultApplyXSL/data.xml</label>
<item>...examines data.xml for an <jump
href="http://www.w3.org/TR/1999/PR-xml-stylesheet-19990114";>associated</jump>
XSL stylesheet. If multiple XSLs are associated with the data, the
stylesheet whose media
attribute maps to your browser type will be chosen. If no mapping is
-successful, the primary associated stylesheet is used.</item>
+successful, the primary associated stylesheet is used.<br/><br/></item>
<label>http://localhost/servlet/data.xml</label>
<item>...provides the same function as the previous example, but this
example assumes
that /servlet/data.xml has been mapped to be executed by this servlet. The
servlet engine may be configured
-to map all or some *.xml files to this servlet through the use of servlet
aliases or filters.</item>
+to map all or some *.xml files to this servlet through the use of servlet
aliases or filters.<br/><br/></item>
<label>http://localhost/servlet/data.xml?catalog=http://www.xml.org/dtds/oag.xml</label>
<item>...supplements any servlet-configured XCatalog
with a catalog of supply chain DTDs residing at the XML.ORG DTD
repository.</item>
1.1 xml-xalan/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Basic usage patterns">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="files">Using a stylesheet file to transform an XML source
file into an output file</link></li>
<li><link anchor="streams">Using data streams in place of files</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<li><link anchor="compiled">Compiling stylesheets</link></li>
<li><link anchor="dom-in">Processing DOM input</link></li>
<li><link anchor="dom-out">Producing DOM output</link></li>
<li><link anchor="sax">Generating and responding to SAX events</link></li>
<li><link anchor="xpath">Working with XPath expressions</link></li>
<li><link anchor="applet">Using the &xslt4j; applet wrapper</link></li>
<li><link anchor="servlet">Using &xslt4j; in a servlet</link></li>
<li><link anchor="extensions">Creating and using extensions</link></li>
<li><link anchor="debugging">Debugger interface</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
<p>&xslt4j; takes as primary input an XML source document and an XSL
stylesheet, both represented by instances of the <resource-ref
idref="XSLTInputSourceDoc"/>. You can use a URL or file, a character stream, a
byte stream, a DOM tree, or a SAX input source to create an XSLTInputSource
object. The stylesheet may also take the form of a compiled stylesheet (an
instance of the <resource-ref idref="StylesheetRootDoc"/>. If the XML document
contains a stylesheet Processing Instruction (PI), a separate stylesheet is not
required.</p>
<p>&xslt4j; uses an implementation of the <resource-ref
idref="XMLParserLiaisonDoc"/> to interact with an XML parser and sends the
output to <resource-ref idref="XSLTResultTargetDoc"/>. Unless your ar
processing a DOM, you probably want to use the default <link
idref="dtm">Document Table Model (DTM)</link> liaison and XML parser. When you
process DOM input, you can use the <resource-ref idref="XercesLiaisonDoc"/>
along with the &xml4j; XML parser.</p>
<p>The XSLT and XPath engines are independent of any given DOM or XML
implementation. All parser-dependent
calls are funneled through the XMLParserLiaison.</p>
<p>For detailed API documentation (javadoc), see <resource-ref
idref="APIDocumentation"/>. For an overview of the
command-line utility, see <link idref="commandline">Command-Line
Utility</link>.</p>
</s2>
<anchor name="files"/>
<s2 title="Using XML source, XSL stylesheet, and output files">
<p>Use an XML file and an XSL file to instantiate XSLTInput objects, create a
processor with the default DTM liaison, and send the transformation output to
an output file. For example:</p>
<source>public static void Transform(String xmlSourceURL, String xslURL,
String outputURL)
throws java.io.IOException,
java.net.MalformedURLException,
org.xml.sax.SAXException
{
// Use XSLTProcessor to instantiate an XSLTProcessor.
org.apache.xalan.xslt.XSLTProcessor processor =
org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor();
// Create the 3 objects the XSLTProcessor needs to perform the
transformation.
org.apache.xalan.xslt.XSLTInputSource xmlSource =
new org.apache.xalan.xslt.XSLTInputSource ("foo.xml");
org.apache.xalan.xslt.XSLTInputSource xslSheet =
new org.apache.xalan.xslt.XSLTInputSource ("foo.xsl");
org.apache.xalan.xslt.XSLTResultTarget xmlResult =
new org.apache.xalan.xslt.XSLTResultTarget ("foo.out");
// Perform the transformation.
processor.process(xmlSource, xslSheet, xmlResult);
}</source>
<p>For an online example, see <link idref="samples"
anchor="simpletransform">SimpleTransform</link>.</p>
<p>You can perform this same operation from the <link
idref="commandline">command line</link>. For example:</p>
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -out
output.xml</code></p>
</s2><anchor name="streams"/>
<s2 title="Using data streams in place of files">
<p>The context in which you perform a transformation may call for input in
the form of a character stream, byte stream, or SAX input stream, and output in
the form of a character stream, byte stream, or SAX document handler. Suppose,
for example, you want to output a stream of bytes for further processing:</p>
<source>import org.apache.xalan.xslt.*;
...
java.io.OutputStream byteStream = new java.io.OutputStream();
XSLTRegultTarget out = new XSLTResultTarget(byteStream)
// Do the transformation...
// Work with the OutputStream...</source>
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<p>An XSL stylesheet can include parameters that get set at run time when a
transformation takes place. When we generate the HTML documents that make up
the Xalan doc set, for example, we send the stylesheet an id parameter along
with each XML source document. The id identifies that document and enables the
stylesheet to integrate it into the overall doc set.</p>
<p>To set a stylesheet parameter, use the XSLTProcessor
setStylesheetParam(String paramName, String paramExpr) method. paramExpr is an
XPath expression, so if the parameter is a String, enclose it in single quotes
to make it a String expression.</p>
<p>You can also use setStylesheetParam(String key, XObject value). This
option is useful when you are working with the XPath API. For example, you
could use the XObject returned by an Xpath function to set a parameter.</p>
<p>From the <link idref="commandline">command line</link>, include a -param
argument. For example:</p>
<p><code>java org.apache.xalan.xsltProcess -in foo.xml -xsl foo.xsl -param
'boo'</code></p>
</s2><anchor name="compiled"/>
<s2 title="Compiling stylesheets">
<p>A <resource-ref idref="StylesheetRootDoc"/> object is a binary
representation of a stylesheet that adds efficiency to the performance of
repeated transformations and supports threadsafe concurrent access by multiple
clients. If, for example, you are setting up a servlet to perform
transformations, you can improve performance by compiling any stylesheets the
servlet repeatedly uses.</p>
<p>To compile a stylesheet, use one of the the <resource-ref
idref="XSLTProcessorDoc"/> processStylesheet methods. This operation also sets
the XSLTProcessor Stylesheet property. In the interest of clarity, you may want
to explicitly set that property. When you call the process method, include a
null for the "uncompiled" stylesheet parameter so XLTProcessor uses the
compiled stylesheet. For example:</p>
<source>import org.apache.xalan.xslt.*;
...
XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
StylesheetRoot style = processor.processStylesheet(new
XSLTInputSource("foo.xsl"));
processor.setStylesheet(style); // Good form!
...
processor.process(new XSLTInputSource("foo.xml"),
null, // Use the Stylesheet property setting.
new XSLTOutputTarget("foo.out"));</source>
<p>Alternative: For convenience, StylesheetRoot has its own process method,
so another way to do the preceding is as follows:</p>
<source>import org.apache.xalan.xslt.*;
..
XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
StylesheetRoot style = processor.processStylesheet(new
XSLTInputSource("foo.xsl"));
...
style.process(new XSLTInputSource("foo.xml"), new
XSLTOutputTarget("foo.out"));</source>
<p>If you want to use the XSLTProcessor as a SAX document handler, you must
provide the processor a compiled stylesheet. See <link anchor="sax">Generating
and Responding to SAX events</link>.</p>
</s2><anchor name="dom-in"/>
<s2 title="Processing DOM input">
<p>The XML source and XSL stylesheet for a transformation may appear in the
form of a DOM Node. To perform transformations with DOM input, you cannot use
the default high-performance DTM liaison and parser. <link idref="dtm">DTM
(Document Table model)</link> uses a table of integers to represent a DOM, thus
avoiding much of the overhead of creating and manipulating actual DOM nodes,
which often involve a large number of Java objects. If you are processing DOM
input, you must use a DOM parser, such as the Xerces DOM parser. When you
create the XSLTProcessor for the transformation, you must specify that it is to
use the Liaison for such a DOM parser.</p>
<p>The following code fragments illustrate the procedure for working with DOM
input:</p>
<source>import org.apache.xerces.parsers.DOMParser;
import org.w3c.dom.Document;
import org.apache.xalan.xpath.xdom.XercesLiaison;
import org.apache.xalan.xslt.*;
...
// Just in case you want to produce your own DOM input...
DOMParser parser = new DOMParser();
parser.parse("foo.xml");
Document in = parser.getDocument();
XSLTInputSource xmlID = new XSLTInputSource(in);
// Set up the XSLTProcessor to use XercesLiaison.
XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor
(new org.apache.xalan.xpath.xdom.XercesLiaison())
// or you can use XSLTProcessorFactory.getProcessorUsingLiaisonName
// ("org.apache.xalan.xpath.xdom.XercesLiaison")
...
// Perform the transformation.</source>
</s2><anchor name="dom-out"/>
<s2 title="Producing DOM output">
<p>To produce a DOM Node as your transformation output, use a new Node to
create the XSLTResultTarget for the transformation. Then when you perform the
transformation, the result is output as a DOM Node. For example:</p>
<source>import org.w3.dom.Document;
import org.apache.xalan.xslt.*;
...
XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor();
org.w3c.dom.Document out = new org.apache.xerces.dom.DocumentImpl();
XSLTResultTarget resultTarget = new XSLTResultTarget(out);
processor.process(new XSLTInputSource("foo.xml"),
new XSLTInputSource("foo.xsl"),
resultTarget);</source>
<p>The XSLTResultTarget object (resultTarget) now contains a Node. For a
working example, see <link idref="samples"
anchor="transformtodom">TransformToDom</link>.</p>
</s2><anchor name="sax"/>
<s2 title="Generating and responding to SAX events">
<p>To set up a transformation to generate SAX events, set the DocumentHandler
property of the XSLTResultTarget object. The transformation consumer can then
respond to these events as they occur, rather than waiting (as the consumer of
a DOM must) for the complete result tree.</p>
<p>This example sends the output to System.out.</p>
<source>import org.apache.xalan.xslt.XSLTProcessor;
import org.apache.xalan.xslt.XSLTInputSource;
import org.apache.xalan.xslt.XSLTResultTarget;
import org.apache.xalan.xslt.XSLTProcessorFactory;
import org.apache.xalan.xslt.StylesheetRoot;
public class TransformToSax
{
public static void main(String[] args)
throws java.io.IOException,
java.net.MalformedURLException,
org.xml.sax.SAXException
{
XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
// Set the processor to use a compiled stylesheet.
// The stylesheet provides access to a SAX DocumentHandler,
// passing it the stylesheet xsl:output settings.
StylesheetRoot stylesheet = processor.processStylesheet("foo.xsl");
// This property was just set implicitly, but for good form...
processor.setStylesheet(stylesheet);
// In this case, send the output to System.out.
org.xml.sax.DocumentHandler dh = stylesheet.getSAXSerializer(System.out);
// Use the DocumentHandler to construct an XSLTResultTarget object.
XSLTResultTarget saxResult = new XSLTResultTarget(dh);
// Perform the transformation. The stylesheet parameter is null, so
// the processor uses the compiled stylesheet identified by its
// Stylesheet property setting.
processor.process(new XSLTInputSource("foo.xml"), null, saxResult);
}
}</source>
<p>XSLTProcessor also has a DocumentHandler property (in fact, XSLTProcessor
extends DocumentHandler). By setting this property, you instruct the processor
to process a sequence of SAX events. The processor needs a compiled stylesheet
to perform this transformation.</p>
<p>The following example uses the output of one transformation as the input
for a second transformation. It does this by using two SAX DocumentHandlers to
pipe SAX events from the first transformation to the second.</p>
<source>import org.apache.xalan.xslt.*;
public class ChainTransforms
{
public static void main(String[] args)
throws java.io.IOException,
java.net.MalformedURLException,
org.xml.sax.SAXException
{
// Create processor for 1st transform.
XSLTProcessor processor1 = XSLTProcessorFactory.getProcessor();
// Create processor for 2nd transform. Set Stylesheet and
// DocumentHandler properties so this processor uses the
// 2nd stylesheet and processes SAX events (output from the
// 1st transform), sending the final result to System.out.
XSLTProcessor processor2 = XSLTProcessorFactory.getProcessor();
StylesheetRoot stylesheet2 = processor2.processStylesheet("foo2.xsl");
processor2.setStylesheet(stylesheet2);
org.xml.sax.DocumentHandler dh = stylesheet2.getSAXSerializer(System.out);
processor2.setDocumentHandler(dh);
// Set up the 1st transform to produce a series of SAX events, and
// to pass these events to the processor for the 2nd transform.
// To accomplish this, create an XSLTResultTarget object for the
// 1st transform, and use the processor for the 2nd transform to set
// the XSLTResultTarget DocumentHandler property.
XSLTResultTarget intermedResult = new XSLTResultTarget();
intermedResult.setDocumentHandler(processor2);
// Perform the 1st transform, which produces a series of
// SAX events that are in turn processed by the processor2 DocumentHandler
// in conjunction with stylesheet2, sending the output to System.out.
processor1.process(new XSLTInputSource("foo.xml"),
new XSLTInputSource("foo.xsl"),
intermedResult);
}
}</source>
<p>For a more compact (and elegant) form of this example, see the <link
idref="samples" anchor="pipe">Pipe</link>.</p>
</s2><anchor name="xpath"/>
<s2 title="Working with XPath expressions">
<p>XSL stylesheets use XPath expressions to select nodes, specify conditions,
and generate text for the result tree. XPath provides an API that you can call
directly. For example, you may want to select nodes programatically and do your
own processing without a stylesheet. For an example that executes individual
XPath expressions against XML source files, see <link idref="samples"
anchor="xpath">ApplyXPath</link>.</p>
</s2><anchor name="applet"/>
<s2 title="Using the &xslt4j; applet wrapper">
<ol>
<li>Include <resource-ref idref="XSLTProcessorAppletDoc"/> in an HTML
client.<br/><br/></li>
<li>Specify the XML source document and XSL stylesheet.<br/><br/>
You can use the DocumentURL and StyleURL PARAM tags or the <resource-ref
idref="XSLTProcessorAppletsetDocumentURLDoc"/> and <resource-ref
idref="XSLTProcessorAppletsetStyleURLDoc"/>. If the XML document contains a
stylesheet Processing Instruction (PI), you do not need to specify an XSL
stylesheet.<br/><br/></li>
<li>Call the <resource-ref
idref="XSLTProcessorApplettransformtoHTMLstringstringDoc"/> which performs the
transformation and returns the new document as a String.</li></ol>
<p>For an example, see the <jump href="samples/applet/readme.html">sample
applet readme</jump>.</p>
</s2><anchor name="servlet"/>
<s2 title="Using &xslt4j; in a servlet">
<p>You can set up a servlet to use &xslt4j; to respond to requests for XML
documents by transforming those documents into HTML and serving them to
clients. For a sample of how this might be done, see <link idref="samples"
anchor="servlet">sample servlet</link>.</p>
</s2><anchor name="extensions"/>
<s2 title="Creating and using extensions">
<p>For those cases where you want to be able to call procedural code from
within a stylesheet, the &xslt4j; Extensions facility supports the creation of
extension elements and extension functions. See <link
idref="extensions">Extensions</link> and <link idref="samples"
anchor="extensions">Extensions samples</link>.</p>
</s2>
<anchor name="debugging"/>
<s2 title="Debugger Interface">
<p>&xslt4j; contains a debugger interface in the
org.apache.xalan.xslt.trace package:</p>
<ul>
<li>The <resource-ref idref="TraceListenerDoc"/> is an
interface that debuggers
can implement. The interface can be set on the
<resource-ref idref="XSLTProcessorDoc"/> by calling the
addTraceListener function.<br/><br/></li>
<li>The <resource-ref idref="PrintTraceListenerDoc"/> is an
implementation of
the TraceListener interface that is used by the <link
idref="commandline">command-line utility</link>
for the -TT, TG, and -TTC. You can examine the utility code
(org.apache.xalan.xslt.Process.java)
for examples of how you might use the trace
functionality.<br/><br/></li>
<li>The <resource-ref idref="TracerEventDoc"/> is an event
that is
passed to the TraceListener.trace function. It is called
before a node is 'executed'
in the stylesheet.<br/><br/></li>
<li>The <resource-ref idref="GenerateEventDoc"/> is an event
that is
passed to the TraceListener.generated() function. It is
called after an event
occurs to create something in the result tree.<br/><br/></li>
</ul>
<p>Example:</p>
<source>
import org.apache.xalan.xslt.XSLTProcessor;
import org.apache.xalan.xslt.trace.PrintTraceListener;
...
// Set up a PrintTraceListener object to print to a file.
java.io.FileWriter fw = new java.io.FileWriter("events.log");
java.io.PrintWriter pw = new java.io.PrintWriter(fw);
PrintTraceListener ptl = new PrintTraceListener(pw);
// Print information as each node is 'executed' in the stylesheet.
ptl.m_traceElements = true;
// Print information after each result-tree generation event.
ptl.m_traceGeneration = true;
// Print information after each selection event.
ptl.m_traceSelection = true;
// Print information whenever a template is invoked.
ptl.m_traceTemplates = true;
// Register the PrintTraceListener with the XSLTProcessor.
XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
processor.addTraceListener(ptl);
...
// Perform the transformation -- printing information to
// events.log during the process.
processor.process(new XSLTInputSource("foo.xml"),
new XSLTInputSource("foo.xsl"),
new XSLTResultTarget("foo.out"));
...
// Close the PrintWriter and FileWriter.
pw.close();
fw.close();
</source>
</s2>
</s1>
