xdocs/sources/xalan/usagepatterns.xml

<?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 (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/>.
 -->
<s1 title="&xslt4c; Basic usage patterns">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="xalantransformer">Basic usage pattern with the XalanTransformer C++ API</link></li>
<li><link anchor="stylepi">Using a stylesheet processing instruction</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<li><link anchor="incremental">Processing output incrementally</link></li>
<li><link anchor="compiled">Performing a series of transformations</link></li>
<li><link anchor="dom">Working with DOM input and output</link></li>
<li><link anchor="xercesdomwrapperparsedsource">Using a Xerces DOM as the source for a Xalan transformation</link></li>
<li><link anchor="xpath">Working with XPath expressions</link></li>
<li><link anchor="tracelistener">Using the TraceListener</link></li>
<li><link anchor="icu">Using the International Components for Unicode (ICU)</link></li>
<li><link anchor="capi">Basic usage pattern with the XalanTransformer C API</link></li>
<li><link anchor="cvar">Variations with the XalanTransformer C API</link></li>
<li>See also: <link idref="extensions">Creating and using extension functions</link></li>
</ul><anchor name="intro"/>

<s2 title="Introduction">  
<p>To perform a transformation, use one of the <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> transform() methods. The transformation requires an XML source document and an XSL stylesheet. Both of these objects may be represented by instances of <jump href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump>. You can construct an XSLTInputSource with a string (the system ID for a file or URI), an input stream, or a DOM.</p>
<p>If you are using an XSL stylesheet to perform a series of transformations, you can improve performance by calling transform() with a compiled stylesheet, an instance of <jump href="apidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>. If you are transforming an XML source more than once, you should call transform() with a parsed XML source, an instance of <jump href="apidocs/class_xalanparsedsource">XalanParsedSource</jump>. See <link anchor="compiled">Performing a series of transformations</link>.</p>
<p>If you XML source document contains a stylesheet Processing Instruction (PI), you do not need to include a stylesheet object when you call transform().</p>
<p>The transformation output is represented by an <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>, which you can set up to refer to an output stream, the system ID for a file or URI, or a DOM.</p>
<p>For detailed API documentation, see <jump href="apidocs/index.html">&xslt4c; API</jump>. For an overview of the
command-line utility, see <link idref="commandline">Command-Line Utility</link>.</p>
</s2><anchor name="xalantransformer"/>
<s2 title="Basic usage patten with the XalanTransformer C++ API">
<p>Using <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> and the C++ API, you can perform one or more transformations as described in the following steps.</p>
<note>For a working sample that illustrates these steps, see the <link idref="samples" anchor="xalantransform">XalanTransform</link> sample.</note>
<s3 title="1. Include the required header files.">
<p>Always start with Include/PlatformDefinitions.hpp, the &xslt4c; base header file. Also include util/PlatformUtils.hpp, XalanTransformer/XalanTransformer.hpp, and any other header files your particular application requires.</p>
<source>#include &lt;Include/PlatformDefinitions.hpp&gt;
#include &lt;util/PlatformUtils.hpp&gt;
#include &lt;XalanTransformer/XalanTransformer.hpp&gt;
...</source>
</s3>
  <s3 title="2. Initialize Xerces and Xalan">
<p>Use the static initializers to initialize the &xslt4c; and &xml4c; platforms. You must initialize &xml4c; once per process. You may initialize and terminate &xslt4c; multiple times, but this is not recommended: it is inefficient and is not thread safe.</p>  
<source>XMLPlatformUtils::Initialize();
XalanTransformer::initialize();</source>
</s3>
  <s3 title="3.Create a XalanTransformer">
  <source>XalanTransformer theXalanTransformer;</source>
  </s3>
  <s3 title="4. Perform each transformation">
    <p>You can explicitly instantiate <jump href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> objects for the XML source document and XSL stylesheet, and an <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> object for the output, and then call <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> transform() with those objects as parameters. For example:</p>
<source>XSLTInputSource xmlIn("foo.xml");
XSLTInputSource xslIn("foo.xsl");
XSLTResultTarget xmlOut("foo-out.xml");
int theResult =
    theXalanTransformer.transform(xmlIn,xslIn,xmlOut)</source>
   <p>Alternatively, you can call transform() with the strings (system identifiers), streams, and/or DOMs that the compiler needs to implicitly construct the <jump href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> and <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> objects. For example:</p>
<source>const char* xmlIn = "foo.xml";
const char* xslIn = "foo.xsl";
const char* xmlOut = "foo-out.xml";
int theResult =
    theXalanTransformer.transform(xmlIn,xslIn,xmlOut)</source>
 <p>Keep in mind that <jump href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> and <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> provide a variety of single-argument constructors that you can use in this manner:</p>
<ul>
  <li><code>XSLTInputSource(const char* systemID);</code></li>
  <li><code>XSLTInputSource(const XMLCh* systemID);//Unicode chars</code></li>
  <li><code>XSLTInputSource(istream* stream);</code></li>
  <li><code>XSLTInputSource(XalanNode* node);</code><br/><br/></li>
  <li><code>XSLTResultTarget(char* fileName);</code></li>
  <li><code>XSLTResultTarget(XalanDOMString&amp; fileName);</code></li>
  <li><code>XSLTResultTarget(ostream* stream);</code></li>
  <li><code>XSLTResultTarget(ostream&amp; stream);</code></li>  
  <li><code>XSLTResultTarget(Writer* characterStream);</code></li>
  <li><code>XSLTResultTarget(XalanDocument* document);</code></li>
  <li><code>XSLTResultTarget(XalanDocumentFragment* documentFragment);</code></li>
  <li><code>XSLTResultTarget(XalanElement* element);</code></li>
</ul>
<note>Each transform() method returns an integer code, 0 for success. If an error occurs, you can use the getLastError() method to return a pointer to the error message.</note>
</s3>
<s3 title="5. Shut down Xalan and (optionally) Xerces">
<p>Use the static terminators.</p>
<source>XalanTransformer::terminate();
XMLPlatformUtils::Terminate();</source>
  <note>Once you have shut down Xerces, you can no longer make Xalan or Xerces calls in the current process.</note>
</s3></s2><anchor name="stylepi"/>
<s2 title="Using a stylesheet processing instruction">
<p>If you want to use the stylesheet referred to by a stylesheet processing instruction in the XMl document, simply call transform() without the second XSLTInputSource argument. For example:</p>
<source>// foo.xml contains a stylesheet PI
const char* xmlIn = "foo.xml";
const char* xmlOut = "foo-out.xml";
int theResult =
    theXalanTransformer.transform(xmlIn,xmlOut)</source>
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<p>An XSL stylesheet can include parameters that are set at run time before 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 <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> setStylesheetParam() method. The setStytlesheetParam() method takes two arguments: the parameter name and the expression. For example:</p>
<source>const XalanDOMString key("param1");
const XalanDOMString expression("'Hello World'");
theXalanTransformer.setStylesheetParam(key, expression);
// foo.xsl defines a stylesheet parameter named param1.
theXalanTransformer.transform("foo.xml","foo.xsl","foo-out.xml")</source>
<note>If the expression is a string, enclose it in single quotes to make it a string expression.</note>
<p>You can include the -param flag with two arguments when you call the <link idref="commandline">command line utility</link>. The first argument is the parameter name or key, and the second argument is the string expression (in single quotes). For example:</p>
<p><code>Xalan -p param1 'boo' foo.xml foo.xsl</code></p>
<p>or</p>
<p><code>testXSLT -in foo.xml -xsl foo.xsl -param param1 'boo'</code></p>
<p>If the string expression includes spaces or other characters that the shell intercepts, first enclose the string in single quotes so &xslt4c; interprets it as a string expression, and then enclose the resulting string in double quotes so the shell interprets it as a single argument. For example:</p>
<p><code>Xalan -p "'hello there'" foo.xml foo.xsl</code></p>
<p>or</p>
<p><code>testXSLT -in foo.xml -xsl foo.xsl -param param1 "'hello there'"</code></p>
<p>The <link idref="samples" anchor="usestylesheetparam">UseStylesheetParam</link> sample application also uses a command-line parameter.</p>
</s2><anchor name="incremental"/>
<s2 title="Processing output incrementally">
<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> provides a transform() method that sends the output in blocks to a callback function, which enables you to begin processing the output while the transformation is still in process:</p>
<source>int
transform(const XSLTInputSource&amp; xmlIn,
          const XSLTInputSource&amp; xslIn,
          void* theOutputHandle,
          XalanOutputHandlerType theOutputHandler
          XalanFlushHanderType theFlushHandler = 0);</source>
<p>For an example, see <link idref="samples" anchor="xalantransformercallback">XalanTransformerCallback</link>.</p>
</s2><anchor name="compiled"/>
<s2 title="Performing a series of transformations">
<p>Before Xalan performs a standard transformation, it must parse the XML document and compile the XSL stylesheet into binary representations. If you plan to use the same XML document or stylesheet in a series of transformations, you can improve performance by parsing the XML document or compiling the stylesheet once and using the binary representation when you call transform().</p>
<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> includes methods for creating compiled stylesheets and parsed XML documents: the compileStylesheet() method returns a pointer to a <jump href="apidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apidocs/class_xalanparsedsource.html">XalanParsedSource</jump>.</p>
<note>In the case of failure, both methods return 0.</note>
<p>Example using a XalanCompiledStylesheet to perform multiple transformations:</p>
<source>XalanCompiledStylesheet* compiledStylesheet = 0;
compiledStylesheet = theXalanTransformer.compileStylesheet("foo.xsl");
assert(compiledStylesheet!=0);
theXalanTransformer.transform("foo1.xml", *compiledStylesheet, "foo1.out.");
theXalanTransformer.transform("foo2.xml", *compiledStylesheet, "foo2.out");
...</source>
<p>For a working sample, see the <link idref="samples" anchor="compilestylesheet">CompileStylesheet</link> sample.</p>
<p>Example using a XalanParsedSource for multiple transformations:</p>
<source>XalanParsedSource* parsedXML = 0;
parsedXML = theXalanTransformer.parseSource("foo.xml");
assert(parsedXML!=0);
theXalanTransformer.transform(*parsedXML, "foo1.xsl", "foo-xsl1.out");
theXalanTransformer.transform(*parsedXML, "foo2.xsl", "foo-xsl2.out");
...</source>
<p>For a sample that uses both a parsed XML source and a compiled stylesheet, see <link idref="samples" anchor="threadsafe">ThreadSafe</link>.</p>
</s2><anchor name="dom"/>
<s2 title="Working with DOM input and output">
<p>You can set up an <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> to produce a DOM when you perform a transformation. You can also use a DOM as input for a transformation.</p>
<p>The following code fragments illustrate the procedures for working with DOM input and output:</p>
<source>

// Use the Xerces DOM parser to create a DOM_Document.
#include &lt;parsers/DOMParser.hpp&gt;
#include &lt;dom/DOM_Node.hpp&gt;

DOMParser  theParser;
// You MUST instruct the Xerces DOMParser NOT to create a DOM_XMLDecNode
// in the DOM to represent the XML declaration. See "Limitations" below.
DOMParser::setToCreateXMLDeclTypeNode(false);
theParser.parse("foo.xml");
const DOM_Document theDOM = theParser.getDocument();

// Set up a XercesParserLiaison and use it to wrap the DOM_Document
// in a XalanDocument.
XercesDOMSupport   theDOMSupport;
XercesParserLiaison	theParserLiaison(theDOMSupport);
XalanDocument* theDoc = theParserLiaison.createDocument(theDOM);

// Use the XalanDocument to create an XSLTInputSource object, which
// you can then use in a transformation.
XSLTInputSource		theInputSource(theDoc);
...
// If you want to produce DOM output, create an empty XalanDocument
// to contain the transformation output.
XalanDocument* docOut = theParserLiaison.createDocument();
XSLTResultTarget theDOMResultTarget(docOut);
...
// After you perform the transformation, the XalanDocument contains
// the output.
// You can also convert the XalanDocument to a Xerces DOM_Document.
DOM_Document domOut = theParserLiaison.mapXercesDocument(docOut)</source>
<p>If you want to use a Xerces DOM object as input for a transformation without wrapping the DOM in
a XercesParserLiaison, see <link anchor="xercesdomwrapperparsedsource">passing in a Xerces DOM</link>.</p>
<s3 title="Limitations">
<p>Performance is much better when &xslt4c; uses native source tree handling rather than interacting with the Xerces DOMParser.</p>
<p>By default, the Xerces DOMParser creates a DOM_XMLDecNode in the DOM tree to represent the XML declaration. The
Xalan bridge for the Xerces DOM does not support this non-standard node type. Accordingly, you must call DOMParser::setToCreateXMLDeclTypeNode(false) <em>before</em> you parse the XML file. If not, the behavior is undefined, and 
your application may crash.</p>
</s3><anchor name="xercesdomwrapperparsedsource"/>
<s3 title="Passing in a Xerces DOM to a transformation">
<p>You may want to use a Xerces DOM that was created without using the XalanTransformer class. As the following code snippet illustrates, you can use <jump href="apidocs/class_xercesdomwrapperparsedsource.html">XercesDOMWrapperParsedSource</jump> to pass in a Xerces DOM as the source for an XSL transformation.</p>
<source>#include &lt;parsers/DOMParser.hpp&gt;
#include &lt;XalanTransformer/XercesDOMWrapperParsedSource.hpp&gt;

void parseWithXerces(XalanTransformer &amp;xalan, 
                     const XSLTInputSource &amp;xmlInput,
                     const XalanCompiledStylesheet* styleSheer,
                     const XSLTResultTarget &amp;output,
                     XMLFileReporter &amp;logFile)
{
  DOMParser the Parser;
  
  // You MUST instruct the Xerces DOMParser NOT to create a DOM_XMLDecNode
  // in the DOM to represent the XML declaration. See "Limitations" above.
  theParser.setToCreateXMLDeclTypeNode(false);
  
  // Turn on validatiion and namespace support.
  theParser.setDoValidation(true);
  theParser.setDoNamespaces(true);
  
  theParser.parse(xmlInput);
  DOM_Document theDOM = theParser.getDocument();
  theDOM.normalize();
  XercesDOMSupport theDOMSupport;
  XercesParserLiaison theParserLiaison(theDOMSupport);
  
  // Use the DOM to create a XercesDOMWrapperParsedSource, 
  // which you can pass to the transform method.
  try
  {
    const XercesDOMWrapperParsedSource parsedSource(
                                   theDOM,
                                   theParserLiaison,
                                   theDOMSupport,
                                   XalanDOMString(xmlInput.getSystemId()));
    xalan.transform(parsedSource, stylesheet, output);
  }
  catch (....)
  {
    ...
  }
}  
                     </source>
</s3>
</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 programmatically and do 
your own processing without a stylesheet. &xslt4c; provides an XPathEvaluator interface to simplify the process of
executing XPath expressions.</p>
<p>For an example that executes XPath expressions against XML source files, see <link idref="samples" anchor="simplexpathapi">SimpleXPathAPI</link> 
(takes advantage of the XPathEvaluator interface) and <link idref="samples" anchor="xpathwrapper">XPathWrapper</link>.</p>
</s2><anchor name="tracelistener"/>
<s2 title="Using TraceListener">
<p>TraceListener is a debugging abstract base class implemented by TraceListenerDefault. You can use TraceListener to trace any combination of the following:</p>
<ul>
  <li>Calls to templates</li>
  <li>Calls to template children</li>
  <li>Selection events</li>    
  <li>Result tree generation events</li>
 </ul>
<p>To construct a TraceListener with TraceListenerDefault, you need a PrintWriter and a boolean for each of these four tracing options. You can then use the XSLTEngimeImpl setTraceSelects and addTraceListener methods to add the TraceListener to an XSLTProcessor. See the <link idref="samples" anchor="tracelisten">TraceListen</link> sample application.</p>
<p>The <link idref="commandline" anchor="testxslt">testXSLT command-line utility</link> and TraceListen both use TraceListenerDefault to write events to the screen.</p>
</s2><anchor name="icu"/>
<s2 title="Using the ICU">
    <p>You can use the <resource-ref idref="icu"/> to extend support for encoding, number
    formatting, and sorting.</p>
    <ul>
      <li><em>Encoding</em>
      <br/> &xml4c; and &xslt4c; use UTF-16 encoding to work with Unicode data.
      If you integrate the ICU with &xml4c;, both &xml4c; and &xslt4c; use ICU support for 
      input and output transcoding.<br/><br/></li>
      <li><em>format-number()</em>
      <br/>This XSLT function includes two or three arguments (the third is
      optional): number, format pattern, and decimal-format name. &xslt4c; ignores the format
      pattern and optional decimal-format name. If you install ICU support for format-number(), 
      this function is fully supported with all its arguments.<br/><br/></li>
      <li><em>xsl:sort</em>
      <br/>If you install ICU support for xml:sort, &xslt4c; implements Unicode-style collation.</li>
     </ul>

    <p>To get the ICU:</p> 
    <ol>
      <li>Download and unzip the <resource-ref idref="icu-download"/> from the IBM
      developerWorks open source zone.<br/><br/></li>
      <li>Do an ICU build -- see the Windows NT or Unix build instructions in the readme.html that
       accompanies the download. 
      <br/><em>Important</em> For Windows, be sure to install the ICU on the same drive and at 
      the same level as &xslt4c; and &xml4c;.<br/><br/></li>
      <li>Set the ICU_DATA environment variable as indicated in the readme.html.</li>
    </ol>
    <s3 title="Enabling ICU support for encoding">
    <p>If you want to enable ICU support for encoding, you must integrate ICU with
    your &xml4c; build. &xml4c; uses ICU for input encoding. See
    <resource-ref idref="xerces-build-icu"/>.</p>
    <p>Once you have integrated the ICU with &xml4c;, &xslt4c; automatically uses ICU support 
    for output encoding (the xsl:output encoding attribute).</p>
     </s3>
    <s3 title="Enabling ICU support for number formatting and sorting"> 
    <p>If you only want to use the ICU to support number formatting and sorting, you do not need to
    integrate the ICU with &xslt4c;, but you must do the following in the application where you
    want to enable ICU support:</p>
    <ol>
      <li>Include the ICUBridge headers.<br/><br/></li>
      <li>Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.<br/><br/></li>
      <li>Windows: Provide your application access to the ICUBridge library.<br/>
      Linux, AIX, or HP-UX 11: Rebuild the Xalan library to include the ICUBridge.</li>
      </ol>
      <p><em>ICUBridge</em></p>
     <p>All &xslt4c; references to ICU are centralized in the ICUBridge module, which supplies the
     infrastructure for enabling ICU support for number formatting and sorting.</p>
     <source>#include &lt;ICUBridge/ICUBridge.hpp&gt;
#include &lt;ICUBridge/FunctionICUFormatNumber.hpp&gt;
#include &lt;ICUBridge/ICUXalanNumberFormatFactory.hpp&gt;
#include &lt;ICUBridge/ICUBridgeCollationCompareFunctor.hpp&gt;</source>
    <p>For Windows be sure &icubridge-win;,the ICUBridge library, is on the path.</p>
    <p>For Linux, rebuild &xslt4c-linuxlib; with XALAN_USE_ICU defined, and place it on the shared library path
    (LD_LIBRARY_PATH for Red Hat Linux 6.1) or copy it to /usr/lib.</p> 
    <p>For AIX, rebuild &xslt4c-aixlib; with XALAN_USE_ICU defined, and place it on the load library
    path (LIBPATH) or copy it to /usr/lib.</p>
    <p>For HP-UX 11, rebuild &xslt4c-hplib; with XALAN_USE_ICU defined, and place it on the shared library
    path (SHLIB_PATH) or copy it to /usr/lib.</p>
    <p>For Solaris, rebuild &xslt4c-solarislib; with XALAN_USE_ICU defined, and place it on the shared library
    path (LD_LIBRARY_PATH) or copy it to /usr/lib.</p>
    
    <p><em>Number formatting</em></p>
    <p>To enable ICU support for the XSLT format-number() function, do
     the following:</p>
<source>// Install ICU support for the format-number() function.
FunctionICUFormatNumber::FunctionICUFormatNumberInstaller theInstaller;</source>
  <p><em>Sorting</em></p> 
  <p>To enable ICU support for xsl:sort, do the following:</p>
  <source>// Set up a StylesheetExecutionContextDefault	object
// (named theExecutionContext in the following fragment),
// and install the ICUCollationCompareFunctor.
ICUBridgeCollationCompareFunctor	theICUFunctor;
theExecutionContext.installCollationCompareFunctor(&amp;theICUFunctor);</source>
 </s3></s2><anchor name="capi"/>
 <s2 title="Basic XalanTransformer usage pattern with the C API">
<p>We also include a simple C interface for using the XalanTransformer class. See <jump href="apidocs/XalanCAPI.h.html">XalanTransformer/XalanCAPI.h</jump>. 
The <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link> sample illustrates the use of this C API.</p>
<p>Basic strategy:</p>

  <s3 title="1. Include the XalanTransformer C API header">
  <source>#include &lt;XalanTransformer/XalanCAPI.h&gt;</source>
  </s3>
  <s3 title="2. Initialize Xalan and Xerces">
  <source>XalanInitialize();</source> 
  </s3>
  <s3 title="3. Create a Xalan transformer">
  <source>XalanHandle xalan = NULL;
xalan = CreateXalanTransformer();</source>
</s3>
  <s3 title="4. Perform each transformation">
<p>  For example:</p>
<source>const char * xmlfilename = "foo.xml";
const char* xslfilename = "foo.xsl";
const char* outfilename = "foo.out";
int theResult = 0;
theResult = XalanTransformToFile(xmlfilename,
                                 xslfilename,
                                 outfilename,
                                 xalan);</source>
<note>If the XML input file contains a stylesheet processing instruction that you want to use, include an empty string ("") for the xslfilename argument.</note>
</s3>                                 
  <s3 title="5. Shut down Xalan">
  <source>XalanTerminate();</source>
</s3></s2><anchor name="cvar"/>
<s2 title="Variations with the XalanTransformer C API">
<p>The <jump href="apidocs/XalanCAPI.h.html">Xalan C API</jump> supports approximately the same set of options as the C++ API. In particular, you can</p>
<ul>
<li>Use stylesheet processing instructions (PI) to supply the stylesheet. Simply supply an empty string ("") for the XSL file name.<br/><br/></li>
<li>Set stylesheet parameters. Use the SetStylesheetParam() function.<br/><br/></li>
<li>Compile stylesheets. Use the CompileStylesheet() method to compile a stylesheet, and the TransformToFileCSS() or TransformToDataCSS() function to use the compiled stylesheet in a transformation.<br/><br/></li>
<li>Parse XML sources. Use the XalanParseSource() or XalanParseSouceUseXalan() method.<br/><br/></li>
<li>Place the transformation output in a character array. Use the TransformToData() or TransformToDataCSS() function. After you perform the transformation, use the XalanFreeData() function to free memory allocated for the output data.<br/><br/></li>
<li>Send the output to a callback function to process blocks of output data as they arrive.</li>
</ul> 
<p>For a sample that sends output in blocks to a callback function, see <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link>.</p>
</s2>
</s1>