blob: 414693fbea2e29da0103c6e9d2c69ae1500b9588 [file] [log] [blame]
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../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 ("
* 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
* 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 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., For more
* information on the Apache Software Foundation, please see
* <>.
<s1 title="&xslt4j2; Samples">
<li><link anchor="simpletransform">SimpleTransform</link></li>
<li><link anchor="usestylesheetpi">UseStylesheetPI</link></li>
<li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
<li><link anchor="sax2sax">SAX2SAX</link></li>
<li><link anchor="dom2dom">DOM2DOM</link></li>
<li><link anchor="pipe">Pipe</link></li>
<li><link anchor="usexmlfilters">UseXMLFilters</link></li>
<li><link anchor="applyxpath">ApplyXPath</link></li>
<li><link anchor="appletxmltohtml">AppletXMLtoHTML</link></li>
<li><link anchor="get-trax">get-trax</link></li>
<li><link anchor="servlet">servlet</link></li>
<li><link anchor="extensions">Extensions</link></li>
<li><link anchor="trace">Trace</link></li>
<li><link anchor="validate">Validate</link></li>
<li><link anchor="trax">trax</link></li>&xsltcsampleshead;
<s2 title="Samples to help you get started">
<p>Each of the subdirectories in the &xslt4j; java/samples directory contains the source files for one or more
sample applications. The class files for the samples are in xalansamples.jar (everything except the servlet) and xalanservlet.jar, so to run the samples, you should place these JAR files on the system classpath.</p>
<p>With most of the samples, you can use the following procedure:</p>
<li>Be sure xalan.jar, xalansamples.jar, and &xml4j-jar; are on the system class
path. For the extension examples, bsf.jar and (for the JavaScript extensions) js.jar must also be on the class
<li>Be sure the java executable is on your path.</li>
<li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows).</li>
<li>Run the sample from the command line (as indicated below).</li>
<li>Examine the application source files. You may also want to modify the source files. Remember that if you
modify a java file, you must recompile the class and place it on the classpath before you can run the
modified application.</li>
<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 sample class and <ref>args</ref> are the arguments, if any. As described in
the following sections, some samples take no arguments. The UseStylesheetParam sample takes an
additional argument. Several 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">
<p>What it does: The SimpleTransform class uses the birds.xsl stylesheet to transform birds.xml, and prints the
output to birds.out.</p>
<p>You can run it from the SimpleTransform subdirectory with</p>
<p><code>java SimpleTransform</code></p>
</s2><anchor name="usestylesheetpi"/>
<s2 title="UseStylesheetPI">
<p>What it does: The UseStylesheetPI class uses the stylesheet processing instruction in the XML source document to determine
which stylesheet to use to perform the transformation.</p>
<p>You can run it from the UseStylesheetPI subdirectory with</p>
<p><code>java UseStylesheetPI</code></p>
<p>For more information, see <link idref="usagepatterns" anchor="embed">Working with embedded stylesheets</link>.</p>
</s2><anchor name="usestylesheetparam"/>
<s2 title="UseStylesheetParam">
<p>What it does: The UseStyleSheetParam class uses foo.xsl and a stylesheet parameter to transform foo.xml,
and prints the output to System.out. The stylesheet parameter appears as a text node in the output.</p>
<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 value (a string of your choice).</p>
</s2><anchor name="sax2sax"/>
<s2 title="SAX2SAX">
<p>What it does: Explicitly set the SAX XMLReader and SAX ContentHandler for processing the stylesheet (birds.xsl), processing the XML input (birds.xml), and producing the output (birds.out).</p>
<p>Run this sample from the SAX2SAX subdirectory with</p>
<p><code>java SAX2SAX</code></p>
</s2><anchor name="dom2dom"/>
<s2 title="DOM2DOM">
<p>What it does: the DOM2DOM class uses the birds.xsl stylesheet to transform a DOM Document generated from birds.xml,
produces an output DOM, and traverses the DOM, printing the traversal to System.out. In contrast to SimpleTransform,
DOM2DOM illustrates the procedure for processing an input DOM and creating an output DOM that is available for
further processing.</p>
<p>You can run it from the DOM2DOM subdirectory with</p>
<p><code>java DOM2DOM</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
<p>What it does: Pipes the output from one transformation to a second transformation, then from the second
transformation to the third transformation. Transformer1 is the ContentHandler for the XMLReader (which parses the
input document). Transformer2 provides the ContentHandler for Transformer1, and Transformer3 for Transformer2.</p>
<note>Pipe and UseXMLFilters illustrate two strategies for using the output of one transformation as the input for
another transformation. The Pipe sample incorporates a "push" model -- Transformer1 "pushes" its output to
Transformer2, and so on -- whereas in the UseXMLFilters sample, Transformer3 "pulls" its input from Transformer2,
and so on.</note>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java Pipe</code></p>
</s2><anchor name="usexmlfilters"/>
<s2 title="UseXMLFilters">
<p>What it does: Chains together the same transformations as the preceding Pipe sample. Using each Transformer
object as an extension of the SAX XMLFilter interface, sets the XMLReader as the parent of filter1,
filter1 as the parent of filter2, and filter2 as the parent of of filter3.</p>
<p><img src="xmlfilters.gif" alt="xmlfilters.gif"/></p>
<p>Run this sample from the UseXMLFilters subdirectory with</p>
<p><code>java UseXMLFilters</code></p>
</s2><anchor name="applyxpath"/>
<s2 title="ApplyXPath">
<p>What it does: ApplyXPath uses the <jump href="apidocs/org/apache/xpath/XPathAPI.html">XPathAPI</jump> convenience methods to
execute an XPath expression against an XML document and return the nodes (if any) it finds.</p>
<note>You can use this sample as an aid when you want to find out what a given XPath expression returns from a
given XML file. Keep in mind that the context node (base point of evaluation) for the XPath expression is the document
<p>Run this sample from the ApplyXPath subdirectory with</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 --<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>&lt;doc&gt;&lt;name first="David" last="Marston"/&gt;...&lt;/doc></code><br/> -- so you can try command
lines like</p>
<p><code>java ApplyXPath foo.xml /</code></p>
<p><code>java ApplyXPath foo.xml /doc/name/@first</code></p>
<p>For more information, see <link idref="usagepatterns" anchor="xpath">Working with XPath expressions</link>.</p>
</s2><anchor name="appletxmltohtml"/>
<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: Open appletXMLtoHTML.hmtl in the Internet Explorer 5 browser.</p>
<note>For information about running &xslt4j; applets in Netscape Communicator, see <link idref="usagepatterns" anchor="netscape">Problems
with Netscape</link>.<br/><br/>
Both applets look for xalan.jar, xml-apis.jar, and xercesImpl.jar (Xerces-J2) or xerces.jar (Xerces-J 1) in the bin
subdirectory. If you have placed these JAR files
elsewhere, adjust the applet archive setting in client.html and get-trax.html accordingly.</note>
</s2><anchor name="get-trax"/>
<s2 title="get-trax">
<p>This applet uses spec.xsl to transform trax.xml and display the result. The XML source (trax.xml) is part of a draft
for the TrAX (Transformation API for XML) specification written by Scott Boag. It contains a useful overview of what
was to become the JAXP 1.1 interface for performing XML transformations.</p>
<p>How to run it: Open get-trax.html in the Internet Explorer 5 browser.</p>
</s2><anchor name="servlet"/>
<s2 title="servlet">
<p>For a general introduction, see <link idref="usagepatterns" anchor="servlet">Using &xslt4j; in a servlet</link>.</p>
<p>The servlet subdirectory contains four sample servlets that use &xslt4j; to perform transformations. These servlets
are in a package named servlet and are compiled in xalanservlet.jar. To run these samples, you must place
xalanservlet.jar, and any XML and XSL files you want to use on a web server with a servlet engine, place
xalanservlet.jar, xalan.jar, and &xml4j-jar; on the servlet engine class path, and configure the servlet engine to
locate the XML and XSL files, and the properties file used by ApplyXSL.</p>
<p><link anchor="simplexsltservlet">servlet.SimpleXSLTServlet</link> applies a particular stylesheet to a particular
XML document.</p>
<p><link anchor="usestylesheetparamservlet">servlet.UseStylesheetParamServlet</link> sets a stylesheet parameter
(the parameter name is hardwired into the servlet), and requires the user to supply parameters for the
XML document and XSL stylesheet.</p>
<p><link anchor="jspsample">jspSample.jsp</link> is a Java ServerPage that sets a stylesheet parameter and applies the
stylesheet to the XML document.</p>
<p><link anchor="xsltservletwithparams">servlet.XSLTServletWithParams</link> accepts parameters for the XML document,
the XSL stylesheet, and any number of stylesheet parameters.</p>
<p><link anchor="applyxslt">servlet.ApplyXSLT</link> (and associated classes) is closer to a production level servlet. It accepts parameters, provides a
listener for capturing and reporting debugger messages, and supports use of a property file to determine which
stylesheet to apply based on the identity of the client browser/device.</p>
<anchor name="simplexsltservlet"/>
<s3 title="servlet.SimpleXSLTServlet">
<p>What it does: servlet.SimpleXSLTServlet applies the spec.xsl stylesheet to trax.xml (see the <link anchor="get-trax">
get-trax applet</link>) and returns the transformation result to the HTTP client.</p>
<p>To run this servlet: place spec.xsl and trax.xml (from the samples/AppletXMLtoHTML directory) in the directory where your servlet engine
looks for HTTP documents, place xalanservlet.jar on the servlet engine classpath, and set up an HTML page to call the servlet as
</s3><anchor name="usestylesheetparamservlet"/>
<s3 title="servlet.UseStylesheetParamServlet">
<note>Paul Campbell &lt;; wrote this servlet and the following explanatory text.
Thank you, Paul!</note>
<p>What it does: The client (perhaps an HTML form ) specifies an XML document, a stylesheet, and a value to be passed
to the stylesheet for a stylesheet parameter named "param1". The servlet performs the transformation and returns
the output to the client. The client must specify which stylesheet (containing a "param1" stylesheet parameter")
and XML file are to be used.</p>
<p>How to run it: Configure your application server (Tomcat, Websphere or JServ, for example)
so it can find servlet.UseStylesheetParamServlet (in xalanservlet.jar) as well as the XML document
and XSL stylesheet. For example, you can copy fooparam.xml and fooparam.xsl from samples/servlet to the application
server root directory for documents.</p>
<p>Then you can set up an HTML client to call the servlet with arguments along the lines of</p>
<p>In the doGet() method, the servlet obtains the PVAL value "GoodBye") from the servlet request and passes it to the
stylesheet as the paramValue argument in a Transformer setParameter() call:</p>
<p><code>String paramValue = httpServletRequest.getParameter("PVAL");</code><br/>
<code>transformer.setParameter("param1", paramValue);</code></p>
<p>The result is returned to the client:</p>
</s3><anchor name="jspsample"/>
<s3 title="jspSample.jsp">
<note>Paul Campbell &lt;; wrote this Java Server Page.</note>
<p>This Java Server Page performs essentially the same operation as
<link anchor="usestylesheetparamservlet">servlet.UseStylesheetParamServlet</link>. It applies a stylesheet parameter
to a stylesheet (fooparam.xsl), applies the stylesheet to an XML source document (fooparam.xml), and returns the
</s3><anchor name="xsltservletwithparams"/>
<s3 title="servlet.XSLTServletWithParams">
<p>What it does: servlet.XSLTServletWithParams takes parameters in the request -- a URL parameter for
the XML input document URL and an xslURL parameter for the stylesheet URL.</p>
<p>To use XSLTServletWithParams to perform the same transformation as SimplestServlet:
place spec.xsl and trax.xml in the directory where your servlet engine looks for HTTP documents, place
xalanservlet.jar on the servlet engine classpath, and set up an HTML page to call the servlet as follows:</p>
<p>If the XML document contains an associated stylesheet (a stylesheet Processing Instruction) that you want to use, simply omit the
xslURL parameter.</p>
<p>If the stylesheet takes stylesheet parameters, you can include them in the URL. For example to set set the param1
stylesheet parameter to foo, include param1=foo in the URL.</p>
</s3><anchor name="applyxslt"/>
<s3 title="servlet.ApplyXSLT">
<p>What it does: The client (which you must set up) specifies an XML document and a stylesheet. The servlet
performs the transformation and returns the output to the client. You can use to specify
which stylesheet is to be used depending on the client browser/device.</p>
<note>The source files for this servlet include,,,, and</note>
<p>To run the servlet: put xalanservlet.jar on the servlet engine classpath, configure your servlet engine so it can find the
stylesheets and properties file in the servlet subdirectory (and in xalanservlet.jar), and set up an HTML page to call
servlet.ApplyXSLT with arguments as illustrated below.</p>
<item>...applies the style.xsl stylesheet to the data.xml data. Both files are<br/>
served from the Web server's HTTP document root.<br/><br/></item>
<item>...ensures that XML and XSL processor messages are returned in the event of problems
applying style.xsl to data.xml<br/><br/></item>
<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
<item>...examines data.xml for an associated XSL stylesheet (a stylesheet Processing Instruction). 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.<br/><br/></item>
<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.<br/><br/></item>
<item>...supplements any servlet-configured XCatalog
with a catalog of supply chain DTDs residing at the XML.ORG DTD repository.</item>
</s2><anchor name="extensions"/>
<s2 title="Extensions">
<p>For an introduction to the creation and use of extension elements and extension functions, and
for information about the extensions library distributed with &xslt4j;, see
<link idref="extensions">Extensions</link>.</p>
<li><link anchor="ext1">1-redir</link></li>
<li><link anchor="ext2">2-basicJscript</link></li>
<li><link anchor="ext3">3-java-namespace</link></li>
<li><link anchor="ext4">4-numlistJava</link></li>
<li><link anchor="ext5">5-numlistJScript</link></li>
<li><link anchor="sql">SQL library extensions</link></li>
<p>The extensions subdirectory contains six samples with &xslt4j; extensions. Two of the samples use
extensions implemented in JavaScript, and four of the samples use extensions implemented in Java.</p>
<p>To run these examples, you must place bsf.jar (distributed with &xslt4j;), and js.jar
(version 1.5, available from
<jump href=""></jump>) on the classpath.
You do not need js.jar on the classpath for the samples that use Java extensions. </p>
<p>Use, the &xslt4j; command-line utility, to run most of these samples from
the <link idref="commandline">command line</link>. The command line must include an -in flag with the
XML source and an -xsl flag with the XSL stylesheet. If you want the output to be written to a file, rather
than to the screen, add an -out flag with the output file name.</p>
<p>Run these samples from the extensions directory as follows (each of the following is a single command
<anchor name="ext1"/>
<s3 title="1-redir">
<p>What it does: Uses the Redirect extension elements shipped with &xslt4j; to direct output to two output
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 1-redir.xml</code><br/>
&nbsp;&nbsp;<code>-xsl 1-redir.xsl</code></p>
<p>The standard (non-redirected) output is written to the screen. The redirected output is written to 1-redir-out, or
whatever filename you assign to the doc/foo @file attribute in 1-redir.xml. The stylesheet gets the file name for
redirected output from the XML input file.</p>
</s3><anchor name="ext2"/>
<s3 title="2-basicJscript">
<p>What it does: Uses an extension element and extension function implemented in JavaScript to compute a
deadline for responding to a customer inquiry.</p>
<note>js.jar must be on the classpath.</note>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 2-basicJscript.xml</code>
<br/>&nbsp;&nbsp;<code>-xsl 2-basicJscript.xsl</code></p>
</s3><anchor name="ext3"/>
<s3 title="3-java-namespace">
<p>What it does: Uses extension functions to format dates. This sample illustrates use of the predefined java
extension namespace to provide ready access to extensions implemented in Java.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 3-java-namespace.xml</code>
<br/>&nbsp;&nbsp;<code>-xsl 3-java-namespace.xsl</code></p>
</s3><anchor name="ext4"/>
<s3 title="4-numlistJava">
<p>What it does: Uses a Java extension to transform a set of name elements into a numbered and alphabetized
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in numlist.xml</code>
<br/>&nbsp;&nbsp;<code>-xsl 4-numlistJava.xsl</code></p>
</s3><anchor name="ext5"/>
<s3 title="5-numlistJscript">
<p>What it does: Uses a JavaScript extension to transform a set of name elements into a numbered and
alphabetized list. This sample performs the same operations as the preceding Java extension.</p>
<note>js.jar must be on the classpath.</note>
<p>Run this sample from the extensions subdirectory with</p>
<p><code> java org.apache.xalan.xslt.Process -in numlist.xml</code>
<br/>&nbsp;&nbsp;<code>-xsl 5-numlistJscript.xsl</code></p>
</s2><anchor name="sql"/>
<s2 title="SQL library extensions">
<p>The <link idref="extensionslib" anchor="sql">SQL library </link> extension enables you to execute SQL queries from within a stylesheet,
and to incorporate query result sets in the XML output. To use the SQL library, you need
a JDBC driver, the underying DBMS, and a database. Our samples use Lutris&reg; InstantDB, available "free of charge for research and
development use."</p><anchor name="instantdbsetup"/>
<s3 title="Setting up the InstantDB samples">
<p>To run the SQL library extension samples, do the following:</p>
<li>Obtain a copy of InstantDB. You can download a free "Development license" copy for research and development from
<jump href="">Lutris Downloads</jump>.<br/><br/></li>
<li>Follow the instructions Lutris provides for installing InstantDB and generating the sample database.<br/><br/></li>
<li>Add idb.jar and the Java Transaction API JAR (jta-spec1_0_1.jar in the InstantDB 4.0 release) to the system class path.<br/><br/></li>
<li>Create an instantdb directory in the samples/extensions subdirectory, and copy the sample database to instantdb. The sample database
is in the Examples subdirectory where you installed InstantDB. For our purposes, it includes samples.prp and three subdirectories:
indexes, system, and tables.<br/><br/>
Alternative: You can adjust the references to samples.prp in the XSL stylesheets and XML document dburl nodes to point to sample.prp in
its original location, in which case you do not need to copy the samples database. For example, if you have installed InstantDB in /idb,
you can change 'jdbc:idb:./instantdb/sample.prp' in the XConnection new() call in extensions/6-sqllib-instantdb to
<p>For more information about InstantDB, see the <jump href="">InstantDB
<s3 title="SQL Library samples with InstantDB">
<li><link anchor="ext6">6-sqllib-instantdb</link></li>
<li><link anchor="basic-conn">Basic Connections</link></li>
<li><link anchor="ext-conn">ExternalConnection</link></li>
<li><link anchor="pquery">Parameterized query</link></li>
<li><link anchor="streamable">Streamable</link></li>
<li><link anchor="showerror">Show-error</link></li>
<note>Except for 6-sqllib-instantdb, all these samples have been created by John Gentilin
( to take illustrate the rich feature set he has contributed to the SQL Library.
To run each of these samples, be sure you are in the appropriate extensions/sql subdirectory.</note>
</s3><anchor name="ext6"/>
<s3 title="6-sqllib-instantdb">
<p>What it does: Uses the SQL library XConnection extension to connect to the InstantDB sample database,
performs a query, and returns the query result in an HTML table.</p>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample from the extensions subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/>&nbsp;&nbsp;<code>-xsl 6-sqllib-instantdb.xsl -out import1.html</code></p>
</s3><anchor name="basic-conn"/>
<s3 title="Basic-Connection">
<p><em>Contributed by John Gentilin (</em></p>
<p>What it does: illustrates two strategies for connecting to a database, executing a static query, and returning
the query result.</p>
<p>The first strategy is to get connection information along with the static query from the stylesheet (dbtest.xsl)\
in the form of stylesheet parameters.</p>
<p>The second strategy is to get connection information from a nodeset in an XML source document (dbInfo.xml).</p>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample from the extensions/sql/basic-connection
<p>1. To get connection information from the stylesheet:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/>&nbsp;&nbsp;<code>-xsl dbtest.xsl -out import1.html</code></p>
<p>2. To get connection information in the form of a nodeset from the XML source document:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/>&nbsp;&nbsp;<code>-in dbinfo.xml -xsl dbtest-cinfo.xsl</code>
<br/>&nbsp;&nbsp;<code>-out import1.html</code></p>
<p>3. To get connection information from the stylesheet and dump the raw result set to an XML file:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/>&nbsp;&nbsp;<code>-xsl DumpSQL.xsl -out import1.xml</code></p>
</s3> <anchor name="ext-conn"/>
<s3 title="ExternalConnection">
<p><em>Contributed by John Gentilin (</em></p>
<p>What it does: The ExternalConnection classes uses the default implementation of the ConnectionPool interface
to create a pool of connections. A stylesheet in turn uses a connection from this pool to instantiate an
XConnection object and connect to a datasouce.</p>
<p>The stylesheet uses this named connection pool to instantiate an XConnection object and connect to the datasource.
The ExternalConnection class is in xalansamples.jar.</p>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, be sure xalanxamples.jar is on the class path, and run this
sample from the extensions/sql/ext-connection directory:</p>
<p><code>java ExternalConnection</code></p>
<p>ExternalConnection creates the ConnectionPool, and performs a transformation with dbtest.xsl, which draws
from the pool to instantiate an XConnection object, connect to the datasource, execute a static query, and return the
query result.</p>
</s3><anchor name="pquery"/>
<s3 title="Parameterized query">
<p><em>Contributed by John Gentilin (</em></p>
<p>What it does: connect to a datasource, execute a parameterized query, and return the result. The XML source document
provides the parameter value as well as the connection information. The parameter value is in a node in the XML source.</p>
<p>The stylesheet gets the required connection and parameter information from the XML source, sets up and executes the
parameterized query, and retuns the query result set.</p>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample from the sql/pquery subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process -in dbInfo.xml</code>
<br/><code>-xsl dbTest.xsl -out dbTest.html</code></p>
</s3><anchor name="streamable"/>
<s3 title="Streamable">
<p><em>Contributed by John Gentilin (</em></p>
<p>What it does: Illustrates enabling and disabling of caching the streamable result set returned by a query.</p>
<p>The stylesheets use the XConnection enableCacheNodes() and disableCacheNodes() methods.</p>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, and run these samples from the sql/streamable subdirectory.</p>
<p>1. To turn caching on:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/><code>-xsl cachedNodes.xsl</code></p>
<p>1. To turn caching off:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/><code>-xsl streamNodes.xsl</code></p>
<p>3. <ref>To be added</ref></p>
</s3><anchor name="showerror"/>
<s3 title="Show-error">
<p><em>Contributed by John Gentilin (</em></p>
<p>What it does: use the SQL library ExtensionError class to return an error message in the output stream. The stylesheet
calls a template with a select statement that returns a nodeset when an error occurs.</p>
<source>&lt;xsl:variable name="table" select='sql:query($db, $query)'/&gt;
&lt;xsl:apply-templates select="$table/row-set" /&gt;
&lt;xsl:apply-templates select="$table/ext-error"/&gt;</source>
<p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample from the extensions/sql/show-error subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/><code> -xsl <ref>invalidSomething.xsl</ref> -out dbtestout.html</code></p>
<p>where <ref>invalidSomething.xsl</ref> is <code>invalidConn.xsl</code> (specifies a database that does not exist),
<code>invalidQuery.xsl</code> (specifies a table that does not exist), or <code>invalidPQuery.xsl</code> (includes
too many parameters for the parameterized query).</p>
</s2><anchor name="trace"/>
<s2 title="Trace">
<p>What it does: Trace uses the TraceListener and TraceManager classes to log transformation events.</p>
<p>Run this sample from the Trace subdirectory with</p>
<p><code>java Trace</code></p>
<p>and examine the result in events.log. For more information, see <link idref="usagepatterns" anchor="debugging">Debugger
</s2><anchor name="validate"/>
<s2 title="Validate">
<li><link anchor="validatexmlinput">ValidateXMLInput</link></li>
<li><link anchor="validateutility">Validate utility</link></li>
</ul><anchor name="validatexmlinput"/>
<s3 title="ValidateXMLInput">
<p>What it does: Uses <jump href="apidocs/javax/xml/parsers/SAXParserFactory.html">SAXParserFactory</jump> to turn on validation, and
<jump href="apidocs/org/xml/sax/XMLReader.html">XMLReader</jump> to parse the XML input and report errors and warnings to a SAX event
handler. The XML input (birds.xml) contains an internal DOCTYPE declaration, and a few minor document type violations, which you are
invited to fix, add to, and vary in any way you find useful.</p>
<p>Run this sample from the Validate subdirectory with</p>
<p><code>java ValidateXMLInput</code></p>
</s3><anchor name="validateutility"/>
<s3 title="Validate utility">
<p>What it does: Uses the <jump href="apidocs\javax\xml\parsers\SAXParser.html">JAXP SAXParser</jump> with a SAX event handler
(extends <jump href="apidocs/org/xml/sax/helpers/DefaultHandler.html">DefaultHandler</jump> and implements
<jump href="apidocs/org/xml/sax/ext/LexicalHandler.html">LexicalHandler</jump>) to verify that XML files conform to their declared
document type. You can use this utility to verify that an individual file or all the .xml files in a directory are
well-formed and valid. Each .xml file should contain a DOCTYPE declaration.</p>
<p>Run this sample from any directory with</p>
<p><code>java Validate <ref>file-or-dir-name</ref> [<ref>logfile</ref></code>]</p>
<p>where <ref>file-or-dir-name</ref> is an XML file or directory pathname, and <ref>logfile</ref> designates a log.
If you omit the second argument, Validate reports its findings to the screen.</p>
<note>A limitation: Files containing document parts appear to fail if you check them with Validate. Check readme.xml,
which "includes" by entity reference a number of files, and it passes. The parse operation scans the entire document
with the includes. Check an "included" file (such as history.xml) as if it were an independent document and it fails.</note>
<anchor name="trax"/>
<s2 title="trax">
<p>What it does: run a number of samples illustrating uses of the <link idref="trax">TRaX (Transformation API for XML)</link> interfaces.</p>
<p>Run this sample from the trax subdirectory with</p>
<p><code>java Examples</code></p>
<p>and examine the source in and</p>