| <?xml version="1.0" standalone="no"?> |
| <!-- |
| * 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 apache@apache.org. |
| * |
| * 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/>. |
| --> |
| |
| <!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"> |
| <s1 title="&xslt4c; Samples"> |
| <ul> |
| <li><link anchor="getstarted">Samples to help you get started</link></li> |
| <li><link anchor="xalantransform">XalanTransform</link></li> |
| <li><link anchor="simpletransform">SimpleTransform</link></li> |
| <li><link anchor="streamtransform">StreamTransform</link></li> |
| <li><link anchor="usestylesheetparam">UseStylesheetParam</link></li> |
| <li><link anchor="xalantransformercallback">XalanTransformerCallback</link></li> |
| <li><link anchor="tracelisten">TraceListen</link></li> |
| <li><link anchor="compilestylesheet">CompileStylesheet</link></li> |
| <li><link anchor="documentbuilder">DocumentBuilder</link></li> |
| <li><link anchor="threadsafe">ThreadSafe</link></li> |
| <li><link anchor="xpathwrapper">XPathWrapper</link></li> |
| <li><link anchor="simplexpathapi">SimpleXPathAPI</link></li> |
| <li><link anchor="simplexpathcapi">SimpleXPathCAPI</link></li> |
| <li><link anchor="serializenodeset">SerializeNodeSet</link></li> |
| <li><link anchor="externalfunctions">ExternalFunctions</link></li> |
| <li><link anchor="apachemodulexslt">ApacheModuleXSLT</link></li> |
| </ul> |
| |
| <anchor name="getstarted"/> |
| <s2 title="Samples to help you get started"> |
| <p>Each of the subdirectories in the &xslt4c; samples directory contains the source files for a |
| sample application. The executables for the samples are in the build subdirectory, which should be on the system |
| path.</p> |
| <p>With most of the samples, you can use the following procedure:</p> |
| <ol> |
| <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows) |
| <br/><br/></li> |
| <li>Run the sample from the command line (as indicated below)<br/><br/></li> |
| <li>Examine the application source files. You may also want to modify the source files. Remember that if you |
| modify a .cpp file, you must rebuild the executable and place it on the path before you can run the |
| modified application.</li> |
| </ol> |
| <note> Each sample application looks for input files in the current directory, the directory from |
| which you run the application. The input files are in the samples subdirectory along with the sample source |
| files. For the UNIX builds, application executables are in the bin subdirectory. For the Windows32 build, the |
| application executable is in the build subdirectory (xml-xalan\c\Build\Win32\VC6\ Debug and Release). To run a sample, be sure the |
| executable is on the path, and run it from the samples subdirectory that contains the input files.</note> |
| </s2><anchor name="xalantransform"/> |
| <s2 title="XalanTransform"> |
| <p>What it does: XalanTransform uses the XalanTransformer class and the associated C++ API to apply an XSL stylesheet file to an XML document file and write |
| the transformation output to either an output file or to a stream. XalanTransform takes command-line |
| arguments for the XML document to be transformed, the XSL stylesheet to apply, and an optional output file argument. If you omit |
| the third argument, XalanTransform writes the transformation output to a stream that is sent to standard out (the console).</p> |
| <p>You can run XalanTransform from the XalanTransform subdirectory with</p> |
| <p><code>XalanTransform foo.xml foo.xsl foo.out</code></p> |
| <p>Omit the third argument to write the transformation result to the console. See also: <link idref="usagepatterns" |
| anchor="xalantransformer">Using the XalanTransformer class.</link>.</p> |
| </s2><anchor name="simpletransform"/> |
| <s2 title="SimpleTransform"> |
| <p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and writes the |
| output to foo.out.</p> |
| <p>You can run it from the SimpleTransform subdirectory with</p> |
| <p><code>SimpleTransform</code></p> |
| <p>See also: <link idref="usagepatterns" anchor="xalantransformer">Basic procedures for performing XSL |
| transformations</link>.</p> |
| </s2><anchor name="streamtransform"/> |
| <s2 title="StreamTransform"> |
| <p>What it does: The StreamTransform class processes character input streams containing a stylesheet and an XML document, and |
| writes the transformation output to a character output stream. This sample illustrates the process for working with stylesheets and documents that you assemble in memory.</p> |
| <p>You can run it from the SimpleTransform subdirectory with</p> |
| <p><code>StreamTransform</code></p> |
| </s2><anchor name="usestylesheetparam"/> |
| <s2 title="UseStylesheetParam"> |
| <p>What it does: Set a stylesheet parameter that the stylesheet uses during the transformation.</p> |
| <p>You can run it from the UseStylesheetParam subdirectory with</p> |
| <p><code>UseStylesheetParam <ref>key expression</ref></code></p> |
| <p>where <ref>key</ref> is the parameter key (or name) and <ref>expression</ref> is a string expression enclosed |
| in single quotes.</p> |
| <p>The example uses a stylesheet (foo.xsl) with a parameter named param1. The stylesheet accepts any string |
| expression. Enclose the string expression in single quotes (so it is interpreted as an expression); if it |
| includes more than a single word, enclose the resulting string in double quotes so the executable interprets it |
| as a single argument. For example:</p> |
| <p><code>UseStylesheetParam param1 "'hello out there'"</code></p> |
| <p>See also: <link idref="usagepatterns" anchor="params">Setting stylesheet parameters</link>.</p> |
| </s2><anchor name="xalantransformercallback"/> |
| <s2 title="XalanTransformerCallback"> |
| <p>What it does: Return transformation output in blocks to a callback function, which writes the output to a file. |
| This sample illustrates the use of a callback function to incrementally process a transformation result, that is to begin |
| working with the transformation result before the transformation has beeen completed. See <link idref="usagepatterns" |
| anchor="incremental">Processing output incrementally</link>.</p> |
| <p>You can run it from the XalanTransformerCallback subdirectory with</p> |
| <p><code>XalanTransformerCallback foo.xml foo.xsl [foo.out]</code></p> |
| <note>If you omit the third argument, the transformation result is written to the console.</note> |
| </s2> |
| <anchor name="tracelisten"/> |
| <s2 title="TraceListen"> |
| <p>What it does: Trace events during a transformation; the transformation uses birds.xsl to transform birds.xml and writes the |
| output to birds.out.</p> |
| <p>You can run it from the TraceListen subdirectory with</p> |
| <p><code>TraceListen <ref>traceFlags</ref></code></p> |
| <p>where <ref>traceFlags</ref> is one or more of the following:</p> |
| <p> <code>-tt</code> (Trace the templates as they are being called)</p> |
| <p> <code>-tg</code> (Trace each result tree generation event)</p> |
| <p> <code>-ts</code> (Trace each selection event)</p> |
| <p> <code>-ttc</code> (Trace the template children as they are being processed)</p> |
| <p>These flags are also available in the <link idref="commandline">command-line utility (TestXSLT)</link>.</p> |
| <p>The core of this example is the following fragment:</p> |
| <source>// Set up a diagnostic writer to be used by the TraceListener... |
| XalanStdOutputStream theStdErr(cerr); |
| XalanOutputStreamPrintWriter diagnosticsWriter(theStdErr); |
| // Make sure that error reporting, which includes any TraceListener |
| // output does not throw exceptions when transcoding, since that could |
| // result in an exception being thrown while another exception is active. |
| // In particular, characters that the TraceListener writes might not be |
| // representable in the local code page. |
| theStdErr.setThrowTranscodeException(false); |
| |
| // Set up the TraceListener... |
| // traceTemplates, traceTemplateChildren, traceGenerationEvent, |
| // and TraceSelectionEvent are booleans set by the command line. |
| TraceListenerDefault theTraceListener( |
| diagnosticsWriter, |
| traceTemplates, |
| traceTemplateChildren, |
| traceGenerationEvent, |
| traceSelectionEvent); |
| |
| // Add the TraceListener to the XSLT processor... |
| theProcessor.setTraceSelects(traceSelectionEvent); |
| theProcessor.addTraceListener(&theTraceListener); |
| |
| // Perform the transformation |
| ....</source> |
| |
| </s2><anchor name="compilestylesheet"/> |
| <s2 title="CompileStylesheet"> |
| <p>What it does: Use a compiled stylesheet to perform a series of transformations.</p> |
| <p>You can run it from the CompileStylesheet subdirectory with</p> |
| <p><code>CompileStylesheet</code></p> |
| <p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p> |
| </s2> <anchor name="documentbuilder"/> |
| <s2 title="DocumentBuilder"> |
| <p>What it does: Use a DocumentBuilder to programmatically construct an XML document, apply the foo.xsl stylesheet to |
| this document, and write the ouput to foo.out.</p> |
| <p>You can run it from the DocumentBuilder subdirectory with</p> |
| <p><code>DocumentBuilder</code></p> |
| </s2><anchor name="threadsafe"/> |
| <s2 title="ThreadSafe (Windows32 Only)"> |
| <p>What it does: Multiple threads use a single compiled stylesheet (StylesheetRoot) and DOM source tree (XalanNode) to perform |
| transformations concurrently. The application tracks the progress of the threads in messages to the console, and each thread |
| writes its own output file. Imagine a server application responding to multiple clients who happen to request the same |
| transformation.</p> |
| <note>This sample uses Windows libraries, but could readily be adapted to run under Linux, AIX, or other environments. It |
| could also be adapted to perform a variety of transformations, each with its own XML input.</note> |
| <p>You can run it from the ThreadSafe subdirectory with</p> |
| <p><code>ThreadSafe</code></p> |
| <p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p> |
| </s2><anchor name="xpathwrapper"/> |
| <s2 title="XPathWrapper"> |
| <note>For a more streamlined sample that uses the XPathEvaluator interface, see |
| <link anchor="simplexpathapi">SimpleXPathAPI</link>.</note> |
| <p>This sample uses an executable (TestDriver in Windows, XPathWrapper in Linux and AIX), and two classes: XPathWrapper and |
| XPathWrapperImp.</p> |
| <p>What it does: The executable passes XPathWrapper an XML file name, a context node location path, and an XPath |
| expression. XPathWrapper in turn passes these arguments to the XPathWrapperImpl evaluate() method, which executes the |
| XPath expression from specified context node in the XML document and returns the nodes it finds (if any).</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 context node in an XML file.</note> |
| <p>Run this sample from the XPathWrapper subdirectory with the same command line arguments described for <link |
| anchor="simplexpathapi">SimpleXPathAPI</link>. Under Windows, the executable is TestDriver; under UNIX, the |
| executable is XPathWrapper.</p> |
| </s2><anchor name="simplexpathapi"/> |
| <s2 title="SimpleXPathAPI"> |
| <p>What it does: Use the XPathEvaluator interface to evaluate an XPath expression from the specified context node of |
| an XML file and display the nodeset returned by the expression.</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 context node in an XML file.</note> |
| <p>Run this sample from the SimpleXPathAPI subdirectory with</p> |
| <p><code>SimpleXPathAPI <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p> |
| <p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context |
| node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node.</p> |
| <note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the nodeset returned by the expresssion.</note> |
| <p>The XPathWrapper subdirectory contains an XML file named xml.foo (part of it appears below).</p> |
| <source><?xml version="1.0"?> |
| <doc> |
| <name first="David" last="Marston">Mr. Marson</name> |
| <name first="David" last="Bertoni">Mr. Bertoni</name> |
| ... |
| <name first="Paul" last="Dick">Mr. Dick</name> |
| </doc></source> |
| <p>You can try command lines like</p> |
| <p><code>SimpleXPathAPI foo.xml /doc name/@last</code></p> |
| <p>and</p> |
| <p><code>SimpleXPathAPI foo.xml / '//name[position()="4"]/@first'</code></p> |
| <note>If a SimpleXPathAPI argument includes characters (such as *) that the shell interprets incorrectly, enclose the argument |
| in double quotes.</note> |
| <p>See also: <link idref="usagepatterns" anchor="xpath">Working with XPath expressions</link>.</p> |
| </s2><anchor name="simplexpathcapi"/> |
| <s2 title="SimpleXPathCAPI"> |
| <p>What it does: Use the XPathEvaluator C interface to evaluate an XPath epxeression and display the string value returned by the epxression.</p> |
| <note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the nodeset returned by the epxresssion.</note> |
| <p>Run this sample from the SimpleXPathCAPI subdirectory with</p> |
| <p><code>SimpleXPathCAPI <ref>XMLFile</ref> <ref>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 the XML source file. The SimpleXPathCAPI subdirectory contains an XML file named xml.foo identical to foo.xml in the preceding example.</p> |
| <p>You can try command lines like</p> |
| <p><code>SimpleXPathCAPI foo.xml /doc/name[3]</code></p> |
| </s2><anchor name="serializenodeset"/> |
| <s2 title="SerializeNodeSet"> |
| <p>What it does: Serialize the node set returned by the application of an XPath expression to an XML document.</p> |
| <p>Run this sample from the SerializeNodeSet subdirectory with</p> |
| <p><code>SerializeNodeSet <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p> |
| <p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context |
| node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node. The SerializeNodeSet directory contains the same foo.xml sample source file as the preceding examples.</p> |
| </s2><anchor name="externalfunctions"/> |
| <s2 title="ExternalFunctions"> |
| <p>What it does: implement, install, and illustrate the usage of three extension functions. The functions return a |
| square root, a cube, and a string with the current date and time. The sample stylesheet (foo.xsl) gets the area |
| of a cube and units of measurement from an XML document (foo.xml), computes the length of each side |
| of a cube and the volume of the cube, and enters the date and time of the transformation. The output appears in |
| foo.out.</p> |
| <p>Run this sample from the ExternalFunctions subdirectory with</p> |
| <p><code>ExternalFunctions</code></p> |
| <p>See also: <link idref="extensions">Extension Functions</link>.</p> |
| </s2><anchor name="apachemodulexslt"/> |
| <s2 title="ApacheModuleXSLT"> |
| <note>This sample must be built with the Apache Web server, and the &xslt4c; distribution files do not include a binary |
| for ApacheModuleXSLT. Assuming you have installed the Apache server on your platform, you can use Visual C++ on Windows to |
| build ApacheModuleXSLT.dll, or the makefile on UNIX to build xslt_module (with the appropriate library suffix).</note> |
| |
| <p>What it does: runs as an Apache module on an Apache Web server; performs transformations and returns the output to a Web |
| browser. You configure Apache to respond to a given URL request for an output file (html or txt file in the configuration below) |
| by applying an xsl stylesheet file to an xml document file (both with the specified name in a given location) and returning |
| the transformation output to the client.</p> |
| <p>This sample also illustrates use of the XalanTransformer class and the C API defined in src/XalanTransformer/XalanCAPI.h. It returns |
| transformation output in blocks to a callback function, which enables the browser to start displaying the result before the transformation |
| has been completed.</p> |
| <note>You may need to adjust the Visual C++ or makefile settings to locate the required Apache header files. As shipped, the Visual C++ |
| project file looks in \Apache Group\Apache\src\include, and the UNIX makefile looks in usr/lib.</note> |
| <p>To build the Apache module, follow the instructions in <link idref="readme" anchor="win32">Steps for doing a Windows |
| build</link> or <link idref="readme" anchor="unix">Steps for doing a UNIX build</link>. For UNIX platforms, you do the build with<br/> |
| <code>make ApacheModuleXSLT</code>.</p> |
| <s3 title="Setting up and using ApacheModuleXSLT"> |
| <p>To use ApacheModuleXSLT, do the following:</p> |
| <ol> |
| <li>(UNIX only) Be sure the Xalan and Xerces libraries are on your library path (you can accomplish this by copying them to |
| /usr/lib; see <link idref="getstarted" anchor="path">Setting up the path/library path</link>), and copy the Apache module to |
| /usr/lib/apache.<br/><br/></li> |
| <li>Add LoadModule and (UNIX only) AddModule entries to the Apache configuration file: httpd.conf.<br/><br/> |
| Windows: <code>LoadModule xslt_module xml-xalan\c\Build\Win32\VC6\Release\ApacheModuleXSLT.dll</code><br/><br/> |
| UNIX: <code>AddModule mod_xslt.c</code><br/> |
| and<br/> |
| <code>LoadModule xslt_module /usr/lib/apache/mod_xslt.<ref>xx</ref></code><br/><br/> |
| where <ref>xx</ref> is the appropriate library suffix for the UNIX platform ("so" or "a").<br/><br/></li> |
| <li>Add a <Location> entry to httpd.conf that indicates where xml/xsl file pairs are to be found, and what target file extensions |
| to recognize. We suggest the following:<br/><br/> |
| <code><Location /xslt></code><br/> |
| <code>AddHandler mod_xslt .html</code><br/> |
| <code>AddHandler mod_xslt .txt</code><br/> |
| <code></Location></code><br/><br/> |
| This <Location> element instructs the module to respond to requests for <ref>xxx</ref>.html and <ref>xxx</ref>.txt files in the |
| in the xslt subdirectory (under the document root; see next item) by applying the <ref>xxx</ref>.xsl stylesheet to <ref>xxx</ref>.xml |
| (both in that directory) and returning the transformation result to the browser.<br/><br/> |
| For example, a request for foo.html instructs the module to apply foo.xsl to foo.xml and return the result.<br/><br/> |
| Note: It is up to the stylesheet to apply the appropriate xsl:output method to the output. Whether the user specifies html or txt is, of |
| itself, immaterial.<br/><br/></li> |
| <li>Put xml/xsl file pairs in the <Location> subdirectory (xslt in the example)) under the document root directory specified in httpd.conf by the |
| DocumentRoot and <Directory> settings. Alternatively, you can modify these settings to point to xml-xalan/c/samples/ApacheModuleXSLT, |
| which includes an xslt subdirectory with xml/xsl file pairs (foo.xml/xsl, apachemod.xml/xsl).<br/><br/></li> |
| <li>Start the Apache server.<br/><br/></li> |
| <li>From a Web browser, call the module with a URL as follows:<br/> |
| <code>http://<ref>serverName</ref>/xslt/<ref>xxx</ref>.html</code><br/> |
| where <ref>serverName</ref> is the Apache server (such as www.myServer.com) and <ref>xxx</ref> is the name of an xml/xsl pair of files |
| (such as foo.xml and foo.xsl) in the xslt subdirectory under the DocumentRoot directory.<br/><br/> |
| For example,<br/> |
| <code>http://www.myServer.com/xslt/apachemod.html</code><br/> |
| instructs ApacheModuleXSLT to apply the apachemod.xsl stylesheet to the apachemod.xml XML document (both files in the xslt directory under the |
| Apache DocumentRoot directory) and return the transformation result to the browser.</li> |
| </ol> |
| </s3> |
| </s2> |
| </s1> |
