http://xml.apache.org/http://www.apache.org/http://www.w3.org/

What's New
XSLTC Translets

Overview
Getting Started

FAQs

Sample Apps
Command Line

Usage Patterns

TrAX
API (Javadoc)

Extensions
Extensions Library

Release Notes

Xalan 2 Design
XSLTC Design

Bugs
Testing

Credits
XSLTC Credits

Samples to help you get started
 

Each of the subdirectories in the Xalan-Java 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.

With most of the samples, you can use the following procedure:

  1. Be sure xalan.jar, xalansamples.jar, and xerces.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 path.
  2. Be sure the java executable is on your path.
  3. Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows).
  4. Run the sample from the command line (as indicated below).
  5. 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.

The basic command line for running most of the samples is

java classname args

where classname is the sample class and args 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 Xalan-Java command-line utility, so they take arguments for the XML source file and the XSL stylesheet.


SimpleTransform
 

What it does: The SimpleTransform class uses the birds.xsl stylesheet to transform birds.xml, and prints the output to birds.out.

You can run it from the SimpleTransform subdirectory with

java SimpleTransform


UseStylesheetPI
 

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.

You can run it from the UseStylesheetPI subdirectory with

java UseStylesheetPI

For more information, see Working with embedded stylesheets.


UseStylesheetParam
 

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.

Run this sample from the UseStylesheetParam subdirectory with

java UseStylesheetParam param

where param is the stylesheet parameter value (a string of your choice).


SAX2SAX
 

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).

Run this sample from the SAX2SAX subdirectory with

java SAX2SAX


DOM2DOM
 

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.

You can run it from the DOM2DOM subdirectory with

java DOM2DOM


Pipe
 

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.

NotePipe 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.

Run this sample from the Pipe subdirectory with

java Pipe


UseXMLFilters
 

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 Transformer1, Transformer1 as the parent of Transformer2, and Transformer2 as the parent of of Transformer3.

Run this sample from the UseXMLFilters subdirectory with

java UseXMLFilters


ApplyXPath
 

What it does: ApplyXPath uses the XPathAPI convenience methods to execute an XPath expression against an XML document and return the nodes (if any) it finds.

NoteYou 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 root.

Run this sample from the ApplyXPath subdirectory with

java ApplyXPath XMLFile XPathExpression

where XMLFile is an XML source file and XPathExpression is an XPath expression to apply to that file. The ApplyXPath subdirectory contains an XML file named foo.xml --
     <doc><name first="David" last="Marston"/>...</doc>
-- so you can try command lines like

java ApplyXPath foo.xml /

and

java ApplyXPath foo.xml /doc/name/@first

For more information, see Working with XPath expressions.


AppletXMLtoHTML
 

The applet uses a stylesheet to transform an XML document into HTML. It displays the XML document, the stylesheet, and the HTML output.

How to run it: Open appletXMLtoHTML.hmtl in the Internet Explorer 5 browser.

NoteThis and the following sample applet do not work in the Netscape Communicator 4.7. We have some work to do to get our basic strategy of using system properties to identify the Transformer and XML Parser to work in the Netscape applet sandbox.

Both applets look for xalan.jar and xerces.jar in the bin subdirectory. If you have placed these JAR files elsewhere, adjust the applet archive setting in client.html and get-todo-list.html accordingly.

get-todo-list
 

This applet uses todo.xsl to transform todo.xml and display the result. The XML source (todo.xml) is a snapshot of an ongoing list of tasks and task completions for the Xalan-Java 2 project that is maintained in the xml-xalan/java subdirectory of the Apache CVS repository.

How to run it: Open get-todo-list.html in the Internet Explorer 5 browser.


servlet
 

For a general introduction, see Using Xalan-Java in a servlet.

The servlet subdirectory contains four sample servlets that use Xalan-Java 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 xerces.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.

servlet.SimpleXSLTServlet applies a particular stylesheet to a particular XML document.

servlet.UseStylesheetParamServlet 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.

jspSample.jsp is a Java ServerPage that sets a stylesheet parameter and applies the stylesheet to the XML document.

servlet.XSLTServletWithParams accepts parameters for the XML document, the XSL stylesheet, and any number of stylesheet parameters.

servlet.ApplyXSLT (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.

servlet.SimpleXSLTServlet
 

What it does: servlet.SimpleXSLTServlet applies the todo.xsl stylesheet to todo.xml and returns the transformation result to the HTTP client.

To run this servlet: place todo.xsl and todo.xml (from the distribution root 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 follows:

http://localhost/servlethome/servlet.SimpleXSLTServlet

servlet.UseStylesheetParamServlet
 
NotePaul Campbell <seapwc@halcyon.com> wrote this servlet and the following explanatory text. Thank you, Paul!

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.

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.

Then you can set up an HTML client to call the servlet with arguments along the lines of

http://localhost/servlethome/servlet.UseStylesheetParamServlet? XML=fooparam.xml&XSL=fooparam.xsl&PVAL=GoodBye

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:

String paramValue = httpServletRequest.getParameter("PVAL");
...
transformer.setParameter("param1", paramValue);

The result is returned to the client:

<html><body><p>GoodBye</p></body></html>


jspSample.jsp
 
NotePaul Campbell <seapwc@halcyon.com> wrote this Java Server Page.

This Java Server Page performs essentially the same operation as servlet.UseStylesheetParamServlet. It applies a stylesheet parameter to a stylesheet (fooparam.xsl), applies the stylesheet to an XML source document (fooparam.xml), and returns the result.


servlet.XSLTServletWithParams
 

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.

To use XSLTServletWithParams to perform the same transformation as SimplestServlet: place todo.xsl and todo.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:

http://localhost/servlethome/servlet.XSLTServletWithParams?URL=file:todo.xml& xslURL=file:todo.xsl

If the XML document contains an associated stylesheet (a stylesheet Processing Instruction) that you want to use, simply omit the xslURL parameter.

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.


servlet.ApplyXSLT
 

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 media.properties to specify which stylesheet is to be used depending on the client browser/device.

NoteThe source files for this servlet include ApplyXSLT.java, ApplyXSLTProperties.java, DefaultApplyXSLTProperties.java, ApplyXSLTListener.java, and ApplyXSLTException.java.

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.

Examples:

http://localhost/servlethome/servlet.ApplyXSLT?URL=/data.xml&xslURL= /style.xsl
...applies the style.xsl stylesheet to the data.xml data. Both files are
served from the Web server's HTTP document root.

http://localhost/servlethome/servlet.ApplyXSLT?URL=/data.xml&xslURL= /style.xsl&debug=true
...ensures that XML and XSL processor messages are returned in the event of problems applying style.xsl to data.xml

http://localhost/servlethome/servlet.ApplyXSLT/data.xml?xslURL=/style.xsl
...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.

http://localhost/servlethome/servlet.ApplyXSLT/data.xml
...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.

http://localhost/servlet/data.xml
...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.

http://localhost/servlet/data.xml?catalog=http://www.xml.org/dtds/oag.xml
...supplements any servlet-configured XCatalog with a catalog of supply chain DTDs residing at the XML.ORG DTD repository.


Extensions
 

For an introduction to the creation and use of extension elements and extension functions, and for information about the extensions library distributed with Xalan-Java, see Extensions.

The extensions subdirectory contains six samples with Xalan-Java extensions. Two of the samples use extensions implemented in JavaScript, and four of the samples use extensions implemented in Java.

To run these examples, you must place bsf.jar (distributed with Xalan-Java), and js.jar (version 1.5, available from http://www.mozilla.org/rhino) on the classpath. You do not need js.jar on the classpath for the samples that use Java extensions.

Use java.org.apache.xalan.xslt.Process, the Xalan-Java command-line utility, to run most of these samples from the command line. 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.

Run these samples from the extensions directory as follows (each of the following is a single command line):

1-redir
 

What it does: Uses the Redirect extension elements shipped with Xalan-Java to direct output to two output files.

Run this sample from the extensions subdirectory with

java org.apache.xalan.xslt.Process -in 1-redir.xml
  -xsl 1-redir.xsl

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.


2-basicJscript
 

What it does: Uses an extension element and extension function implemented in JavaScript to compute a deadline for responding to a customer inquiry.

Notejs.jar must be on the classpath.

Run this sample from the extensions subdirectory with

java org.apache.xalan.xslt.Process -in 2-basicJscript.xml
  -xsl 2-jbasicJscript.xsl


3-java-namespace
 

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.

Run this sample from the extensions subdirectory with

java org.apache.xalan.xslt.Process -in 3-java-namespace.xml
  -xsl 3-java-namespace.xsl


4-numlistJava
 

What it does: Uses a Java extension to transform a set of name elements into a numbered and alphabetized list.

Run this sample from the extensions subdirectory with

java org.apache.xalan.xslt.Process -in numlist.xml
  -xsl 4-numlistJava.xsl


5-numlistJscript
 

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.

Notejs.jar must be on the classpath.

Run this sample from the extensions subdirectory with

java org.apache.xalan.xslt.Process -in numlist.xml
  -xsl 5-numlistJscript.xsl



SQL Library extensions
 

The SQL Library extension samples use SQL library XConnection extensionto connect to an InstantDB datasource, perform queries, and return query result sets.

NoteTo run these samples, you must include idb.jar on the classpath. We have placed a copy of idb.jar from InstantDB version 3.25 in samples/extensions/instantdb. For information about InstantDB, see InstantDB and the Enydra Public License.
NoteExcept for 6-sqllib-instantdb, all these samples have been created by John Gentilin (johnglinux@eyecatching.com) 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.
6-sqllib-instantdb
 

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.

Add idb.jar to the classpath, and run this sample from the extensions subdirectory:

java org.apache.xalan.xslt.Process
  -xsl 6-sqllib-instantdb.xsl -out import1.html


Basic-Connection
 

Contributed by John Gentilin (johnglinux@eyecatching.com).

What it does: illustrates two strategies for connecting to a database, executing a static query, and returning the query result.

The first strategy is to get connection information along with the static query from the stylesheet (dbtest.xsl)\ in the form of stylesheet parameters.

The second strategy is to get connection information from a nodeset in an XML source document (dbInfo.xml).

Add extensions/instantdb/idb.jar to the classpath, and run this sample from the extensions/sql/basic-connection directory.

1. To get connection information from the stylesheet:

java org.apache.xalan.xslt.Process
  -xsl dbtest.xsl -out import1.html

2. To get connection information in the form of a nodeset from the XML source document:

java org.apache.xalan.xslt.Process
  -in dbinfo.xml -xsl dbtest-cinfo.xsl
  -out import1.html

3. To get connection information from the stylesheet and dump the raw result set to an XML file:

java org.apache.xalan.xslt.Process
  -xsl DumpSQL.xsl -out import1.xml


ExternalConnection
 

Contributed by John Gentilin (johnglinux@eyecatching.com).

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.

The stylesheet uses this named connection pool to instantiate an XConnection object and connect to the datasource.

The ExternalConnection class is in xalansamples.jar. Be sure xalansamples.jar and idb.jar are on the classpath, and run this sample from the extensions/sql/ext-connection directory:

java ExternalConnection

ExternalConnection creates the ConnectionPool, and performs a transformation wiht 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.


Parameterized query
 

Contributed by John Gentilin (johnglinux@eyecatching.com).

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.

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.

Be sure idb.jar is on the classpath, and run this sample from the sql/pquery subdirectory:

java org.apache.xalan.xslt.Process -in dbInfo.xml
-xsl dbTest.xsl -out dbTest.html


Streamable
 

Contributed by John Gentilin (johnglinux@eyecatching.com).

What it does: Illustrates enabling and disabling of caching the streamable result set returned by a query.

The stylesheets use the XConnection enableCacheNodes() and disableCacheNodes() methods.

Be sure idb.jar is on the classpath, and run these samples from the sql/streamable subdirectory.

1. To turn caching on:

java org.apache.xalan.xslt.Process
-xsl cachedNodes.xsl

1. To turn caching off:

java org.apache.xalan.xslt.Process
-xsl streamNodes.xsl

3. To be added


Show-error
 

Contributed by John Gentilin (johnglinux@eyecatching.com).

What it does: use the SQL library ExtensionError class to return an error message in the output stream. The stylesheet (dbtest.xsl) calls a template with a select statement that only returns a nodeset if an error has occured:

<xsl:variable name="table" select='sql:query($db, $query)'/>
  <xsl:apply-templates select="$table/row-set" />	
  <xsl:apply-templates select="$table/ext-error"/>

Since the query contains an incorrect table name, this example does return an error message. Correct the table name (change 'import1X' to 'import1') and the example returns a standard result set.

With idb.jar on the classpath, run this sample from the extensions/sql/show-error subdirectory:

java org.apache.xalan.xslt.Process
-in dbtest.xsl -out dbtestout.html



Trace
 

What it does: Trace uses the TraceListener and TraceManager classes to log transformation events.

Run this sample from the Trace subdirectory with

java Trace

and examine the result in events.log. For more information, see Debugger Interface


trax
 
NoteTo run the trax sample, you must be using an XML parser (such as Xerces 1.4 or Crimson 1.1) that fully implements the JAXP 1.1 javax.xml.parsers interface.

What it does: run a number of samples illustrating uses of the TRaX (Transformation API for XML) interfaces.

Run this sample from the trax subdirectory with

java Examples

and examine the source in Examples.java and ExampleContentHandler.java.


Translets
 

See also: XSLTC demos.

You can use the TrAX/JAXP 1.1 interfaces to compile and run translets. For this release, you must still use StreamSource objects for the XSL stylesheet and XML input document, and a StreamResult object for the transformation output. For an overview of the usage patterns these samples illustrate, see Calling XSLTC with the TrAX/JAXP API.

Important: To run these samples, you must compile the sample class files and adjust the system classpath.

  1. To compile the samples, you can run the Ant build from the root directory as follows:

      build xsltc.samples

  2. Add xsltc.jar, runtime.jar, BCEL.jar, java_cup.jar, and the samples/translets subdirectory to the classpath
NoteThe JAR files listed above are in the bin directory. The samples/translets directory contains the sample class files as well as the translet class file that is generated at tun time (todo.class from the todo.xsl stylesheet).
JAXPTransletOneTransformation
 

What it does: Uses the XSLTC TransformerFactory to compile a translet and use the translet to transform the XSLTC to-do list from XML into HTML.

Complete the steps detailed above, and run this sample from the translets subdirectory with

java JAXPTransletOneTransformation

View the result in todo-xsltc.html.


JAXPTransletMultipleTransformations
 

What it does: Uses the XSLTC TransformerFactory to compile a translet and use the Templates object associated with the translet to transform the XSLTC and Xalan to-do lists from XML into HTML.

Complete the steps detailed above, and run this sample from the translets subdirectory with

java JAXPTransletOneTransformation

View the results in todo-xsltc.html and todo-xalan.html.




Copyright © 2000 The Apache Software Foundation. All Rights Reserved.