You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sh...@apache.org on 2012/02/26 10:12:49 UTC
svn commit: r1293790 [20/21] - in /xalan/c/branches/XalanDocs: docs/xalan/
docs/xalan/resources/ docs/xalan/xalan-c/ docs/xalan/xalan-c/resources/
docs/xalan/xalan-j/ docs/xalan/xalan-j/design/
docs/xalan/xalan-j/design/resources/ docs/xalan/xalan-j/re...
Modified: xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/test-faqs.xml
URL: http://svn.apache.org/viewvc/xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/test-faqs.xml?rev=1293790&r1=1293789&r2=1293790&view=diff
==============================================================================
--- xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/test-faqs.xml (original)
+++ xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/test-faqs.xml Sun Feb 26 09:12:45 2012
@@ -1,81 +1,81 @@
-<?xml version="1.0" standalone="no"?>
-
-<!--
- This is a StyleBook XML test for <faqs> containing <group> constructs
--->
-
-<!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd"
-[<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
-%entity-c-values; ]>
-
-<faqs title="Frequently asked questions">
-<group title="Faq-Group 1">
-<faq title="Faq #1">
- <q>Test Question #1</q>
- <a><p>Test Answer #1</p></a>
-</faq>
-<faq title="Faq #2">
- <q>Test Question #2</q>
- <a><p>Test Answer #2</p></a>
-</faq>
-<faq title="Faq #3">
- <q>Test Question #3</q>
- <a><p>Test Answer #3</p></a>
-</faq>
-</group>
-
-<group title="Faq-Group 2">
-<faq title="Faq #4">
- <q>Test Question #4</q>
- <a><p>Test Answer #4</p></a>
-</faq>
-<faq title="Faq #5">
- <q>Test Question #5</q>
- <a><p>Test Answer #5</p></a>
-</faq>
-</group>
-
-<group title="Faq-Group 3">
-<faq title="Faq #6 with Multiple Answers">
- <q>Test Question #6</q>
- <a><p>Test Answer #6</p></a>
- <a><p>This item has more than one answer</p></a>
-</faq>
-</group>
-
-<group title="Faq-Group 4 = Empty">
-</group>
-
-<group title="Faq-Group 5">
-<faq title="Faq #7">
- <q>Test Question #7</q>
- <a><p>Test Answer #7</p></a>
-</faq>
-<faq title="Faq #8">
- <q>Test Question #8</q>
- <a><p>Test Answer #8</p></a>
-</faq>
-<faq title="Faq #9 with no Answer">
- <q>Test Question #9</q>
-</faq>
-<faq title="Faq #10 with no Question">
- <a><p>Test Answer #10</p></a>
-</faq>
-<faq title="Faq #11">
- <q>Test Question #11</q>
- <a><p>Test Answer #11</p></a>
-</faq>
-</group>
-
-<group title="Faq-Group 6">
-<faq title="Faq #12">
- <q>Test Question #12</q>
- <a><p>Test Answer #12</p></a>
-</faq>
-<faq title="Faq #13">
- <q>Test Question #13</q>
- <a><p>Test Answer #13</p></a>
-</faq>
-</group>
-
-</faqs>
+<?xml version="1.0" standalone="no"?>
+
+<!--
+ This is a StyleBook XML test for <faqs> containing <group> constructs
+-->
+
+<!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd"
+[<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
+%entity-c-values; ]>
+
+<faqs title="Frequently asked questions">
+<group title="Faq-Group 1">
+<faq title="Faq #1">
+ <q>Test Question #1</q>
+ <a><p>Test Answer #1</p></a>
+</faq>
+<faq title="Faq #2">
+ <q>Test Question #2</q>
+ <a><p>Test Answer #2</p></a>
+</faq>
+<faq title="Faq #3">
+ <q>Test Question #3</q>
+ <a><p>Test Answer #3</p></a>
+</faq>
+</group>
+
+<group title="Faq-Group 2">
+<faq title="Faq #4">
+ <q>Test Question #4</q>
+ <a><p>Test Answer #4</p></a>
+</faq>
+<faq title="Faq #5">
+ <q>Test Question #5</q>
+ <a><p>Test Answer #5</p></a>
+</faq>
+</group>
+
+<group title="Faq-Group 3">
+<faq title="Faq #6 with Multiple Answers">
+ <q>Test Question #6</q>
+ <a><p>Test Answer #6</p></a>
+ <a><p>This item has more than one answer</p></a>
+</faq>
+</group>
+
+<group title="Faq-Group 4 = Empty">
+</group>
+
+<group title="Faq-Group 5">
+<faq title="Faq #7">
+ <q>Test Question #7</q>
+ <a><p>Test Answer #7</p></a>
+</faq>
+<faq title="Faq #8">
+ <q>Test Question #8</q>
+ <a><p>Test Answer #8</p></a>
+</faq>
+<faq title="Faq #9 with no Answer">
+ <q>Test Question #9</q>
+</faq>
+<faq title="Faq #10 with no Question">
+ <a><p>Test Answer #10</p></a>
+</faq>
+<faq title="Faq #11">
+ <q>Test Question #11</q>
+ <a><p>Test Answer #11</p></a>
+</faq>
+</group>
+
+<group title="Faq-Group 6">
+<faq title="Faq #12">
+ <q>Test Question #12</q>
+ <a><p>Test Answer #12</p></a>
+</faq>
+<faq title="Faq #13">
+ <q>Test Question #13</q>
+ <a><p>Test Answer #13</p></a>
+</faq>
+</group>
+
+</faqs>
Modified: xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/usagepatterns.xml
URL: http://svn.apache.org/viewvc/xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/usagepatterns.xml?rev=1293790&r1=1293789&r2=1293790&view=diff
==============================================================================
--- xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/usagepatterns.xml (original)
+++ xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/usagepatterns.xml Sun Feb 26 09:12:45 2012
@@ -1,544 +1,544 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"
-[<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
-%entity-c-values; ]>
-
-<!--
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
--->
-<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/classXalanTransformer.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/classXSLTInputSource.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/classXalanCompiledStylesheet.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/classXalanParsedSource.html">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/classXSLTResultTarget.html">XSLTResultTarget</jump>, which
- you can set up to refer to an output stream, the system ID for a file or URI, or a Formatter for one of the various styles of
- DOM output.</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/classXalanTransformer.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 xalanc/Include/PlatformDefinitions.hpp, the &xslt4c; base header file. Also include xercesc/util/PlatformUtils.hpp,
- xalanc/XalanTransformer/XalanTransformer.hpp, and any other header files your particular application requires.</p>
-<source>
-#include <xalanc/Include/PlatformDefinitions.hpp>
-#include <xercesc/util/PlatformUtils.hpp>
-#include <xalanc/XalanTransformer/XalanTransformer.hpp>
-...
-</source>
-</s3>
-
-<s3 title="2. Define namespaces">
-<p>As of version 1.5, &xslt4c; now uses C++ namespaces for those platforms which support them. A number of macros are provided to
- make using the &xslt4c; (and &xml4c;) namespaces easier.</p>
-<p>In the following example, the <em>XALAN_USING_XERCES</em> and <em>XALAN_USING_XALAN</em> macros are used to declare that the
- program is using <em>XMLPlatformUtils</em> and <em>XalanTransformer</em> from the &xml4c; and &xslt4c; namespaces respectively.</p>
-<source>
-XALAN_USING_XERCES(XMLPlatformUtils)
-XALAN_USING_XALAN(XalanTransformer)
-</source>
-
-<p>These macros can be used immediately after the included header files (for global applicability in a given source file) or within
- functions and methods for local applicability.</p>
-<note>Whilst you can use the standard C++ namespace syntax directly, the &xml4c; and &xslt4c; namespaces are linked to the version
- number. For example, the Xalan namespace is currently <em>xalanc_1_9</em>. The macros will automatically take care of this
- when code is re-compiled against a new version of the libraries. Using the namespaces directly will require each namespace
- related statement be updated by hand.</note>
-</s3>
-
-<s3 title="3. 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="4. Create a XalanTransformer.">
-<source>
-XalanTransformer theXalanTransformer;
-</source>
-</s3>
-
-<s3 title="5. Perform each transformation.">
-<p>You can explicitly instantiate <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> objects for the XML
- source document and XSL stylesheet, and an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> object
- for the output, and then call <jump href="apiDocs/classXalanTransformer.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/classXSLTInputSource.html">XSLTInputSource</jump> and
- <jump href="apiDocs/classXSLTResultTarget.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/classXSLTInputSource.html">XSLTInputSource</jump> and
- <jump href="apiDocs/classXSLTResultTarget.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& fileName);</code></li>
- <li><code>XSLTResultTarget(ostream* stream);</code></li>
- <li><code>XSLTResultTarget(ostream& 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>
- <li><code>XSLTResultTarget(FormatterListener& flistener);</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="6. Shut down Xalan.">
-<p>When you shut down Xalan, you may also want to shut down Xerces and ICU support (if enabled). Keep the following considerations
- in mind:</p>
-<ul>
- <li>Once you have shut down Xerces, you can no longer make Xalan or Xerces calls in the current process.<br/><br/></li>
- <li>Shut down ICU support if you have enabled it (see <link anchor="icusupport">enabling ICU support</link>) and if the
- application is exiting or no longer requires the ICU. The <code>XMLPlatformUtils::Terminate()</code> call does nothing
- if ICU support has not been enabled.</li>
- <li>Ensure that there are no &xslt4c; or &xml4c; objects extant at the point of termination. Any deletion of objects after
- termination could cause errors.</li>
-</ul>
-<p>Use the static terminators.</p>
-<source>
-XalanTransformer::terminate();
-XMLPlatformUtils::Terminate();
-XalanTransformer::ICUCleanUp();
-</source>
-</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/classXalanTransformer.html">XalanTransformer</jump>
- setStylesheetParam() method. The setStylesheetParam() 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>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>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/classXalanTransformer.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& xmlIn,
- const XSLTInputSource& 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/classXalanTransformer.html">XalanTransformer</jump> includes methods for creating compiled stylesheets and
- parsed XML documents: the compileStylesheet() method returns a pointer to a <jump href="apiDocs/classXalanCompiledStylesheet.html">
- XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apiDocs/classXalanParsedSource.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/classXSLTResultTarget.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 fragment illustrates the procedures for working with DOM output :</p>
-<source>
-
-// Use the Xerces DOM parser to create a DOMDocument.
-
-#include <xercesc/dom/DOMDocument.hpp>
-#include <xercesc/dom/DOMImplementation.hpp>
-
-#include <xalanc/XMLSupport/FormatterToXML.hpp>
-#include <xalanc/XMLSupport/XalanTransformer.hpp>
-
-XALAN_USING_XERCES(DOMDocument)
-XALAN_USING_XERCES(DOMImplementation)
-
-XALAN_USING_XALAN(FormatterToXML)
-XALAN_USING_XALAN(XalanTransformer)
-
-
- // If you want to produce DOM output, create an empty Xerces Document
- // to contain the transformation output.
-
- DOMDocument * theDOM =
- DOMImplementation::getImplementation()->createDocument();
-
- // Now create a FormatterListener which can be used by the transformer
- // to send each output node to the new Xerces document
-
- FormatterToXercesDOM theFormatter(theDOM);
-
- // Now do the transform as normal
- XalanTransformer theXalanTransformer
- int theResult = theXalanTransformer.transform(
- "foo.xml",
- "foo.xsl",
- theFormatter);
-...
-
- // After you perform the transformation, the DOMDocument contains
- // the output.
-</source>
-<note>You can also follow the same process but use a <em>FormatterToDeprecatedXercesDOM</em> if you require a DOM_Document
- output. However this is discouraged, as support for the deprecated DOM may be removed in future releases of &xslt4c;</note>
-<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>If you are using the deprecated DOM, the Xerces DOMParser by default, 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/classXercesDOMWrapperParsedSource.html">XercesDOMWrapperParsedSource</jump> to
- pass in a Xerces DOM as the source for an XSL transformation.</p>
-<source>
-#include <xercesc/parsers/DOMParser.hpp>
-#include <xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp>
-
-void parseWithXerces(XalanTransformer &xalan,
- const XSLTInputSource &xmlInput,
- const XalanCompiledStylesheet* styleSheet,
- const XSLTResultTarget &output,
- XMLFileReporter &logFile)
-{
- XercesDOMParser theParser;
-
- // Turn on validation and namespace support.
- theParser.setDoValidation(true);
- theParser.setDoNamespaces(true);
-
- // Parse the document
-
- theParser.parse(xmlInput);
- DOMDocument *theDOM = theParser.getDocument();
- theDOM->normalize();
-
- XercesDOMSupport theDOMSupport;
- XercesParserLiaison theParserLiaison;
-
- // 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 TraceListen uses 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>If you choose to build Xalan with ICU, you will need to rebuild Xerces with ICU as well.</p>
-<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 build_instruct.html that accompanies the download.<br/>
- <em>Important</em> For Windows, define the environment variable ICUROOT and then restart Visual C++ or Visual Studio .NET.
- in order for the ICUROOT variable to take effect.<br/><br/></li>
-</ol>
-
-<anchor name="icusupport"/>
-<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>Define the environment variable ICUROOT.<br/><br/></li>
- <li>Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.<br/><br/></li>
- <li>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 <xalanc/ICUBridge/ICUBridge.hpp>
-#include <xalanc/ICUBridge/FunctionICUFormatNumber.hpp>
-#include <xalanc/ICUBridge/ICUXalanNumberFormatFactory.hpp>
-#include <xalanc/ICUBridge/ICUBridgeCollationCompareFunctor.hpp>
-</source>
-<p>For Windows, do a clean build of the Xalan library using the "XalanICU.dsw" workspace (for Visual C++ users) or
- "XalanICU.sln" solution (for Visual Studio .NET users).</p>
-<p>For UNIX:</p>
-<ol>
- <li>Define the XALAN_USE_ICU environment variable.<br/><br/></li>
- <li>Set the XALANROOT environment variable to the path to to the ICU root (unless you have copied the ICU library to
- /usr/lib).<br/><br/></li>
- <li><link idref="build_instruct" anchor="unix">Rebuild the Xalan library</link> (&xslt4c-linuxlib; for Linux, &xslt4c-aixlib; for AIX,
- &xslt4c-hplib; for HP-UX 11, and &xslt4c-solarislib; for Solaris).<br/><br/></li>
- <li>Be sure the Xalan library is on the library path (LD_LIBRARY_PATH for Red Hat Linux, LIBPATH for AIX, SHLIB_PATH for
- HP-UX 11, LD_LIBRARY_PATH for Solaris).</li>
-</ol>
-<note>The command you use for setting environment variables depends on the shell you are using.<br/>
- For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR="val"<br/>
- For C Shell, use <em>setenv</em> ENVAR "val"<br/>
- where ENVAR is the environment variable name and val is the environment variable
- setting. You can check the setting of an environment variable with <em>echo</em> $ENVAR<br/>To define XALAN_USE_ICU,
- set its value to "1".
-</note>
-<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 StylesheetExecutionContextDefaultobject
-// (named theExecutionContext in the following fragment),
-// and install the ICUCollationCompareFunctor.
-ICUBridgeCollationCompareFunctortheICUFunctor;
-theExecutionContext.installCollationCompareFunctor(&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_8h.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 <XalanTransformer/XalanCAPI.h></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, use an empty XSLTInputSource
- for the stylesheet 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_8h.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 indicate the URI of the stylesheet. Supply NULL for the stylesheet argument.<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>
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd" [
+<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
+%entity-c-values; ]>
+
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+-->
+<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/classXalanTransformer.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/classXSLTInputSource.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/classXalanCompiledStylesheet.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/classXalanParsedSource.html">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/classXSLTResultTarget.html">XSLTResultTarget</jump>, which
+ you can set up to refer to an output stream, the system ID for a file or URI, or a Formatter for one of the various styles of
+ DOM output.</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/classXalanTransformer.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 xalanc/Include/PlatformDefinitions.hpp, the &xslt4c; base header file. Also include xercesc/util/PlatformUtils.hpp,
+ xalanc/XalanTransformer/XalanTransformer.hpp, and any other header files your particular application requires.</p>
+<source>
+#include <xalanc/Include/PlatformDefinitions.hpp>
+#include <xercesc/util/PlatformUtils.hpp>
+#include <xalanc/XalanTransformer/XalanTransformer.hpp>
+...
+</source>
+</s3>
+
+<s3 title="2. Define namespaces">
+<p>As of version 1.5, &xslt4c; now uses C++ namespaces for those platforms which support them. A number of macros are provided to
+ make using the &xslt4c; (and &xml4c;) namespaces easier.</p>
+<p>In the following example, the <em>XALAN_USING_XERCES</em> and <em>XALAN_USING_XALAN</em> macros are used to declare that the
+ program is using <em>XMLPlatformUtils</em> and <em>XalanTransformer</em> from the &xml4c; and &xslt4c; namespaces respectively.</p>
+<source>
+XALAN_USING_XERCES(XMLPlatformUtils)
+XALAN_USING_XALAN(XalanTransformer)
+</source>
+
+<p>These macros can be used immediately after the included header files (for global applicability in a given source file) or within
+ functions and methods for local applicability.</p>
+<note>Whilst you can use the standard C++ namespace syntax directly, the &xml4c; and &xslt4c; namespaces are linked to the version
+ number. For example, the Xalan namespace is currently <em>xalanc_1_11</em>. The macros will automatically take care of this
+ when code is re-compiled against a new version of the libraries. Using the namespaces directly will require each namespace
+ related statement be updated by hand.</note>
+</s3>
+
+<s3 title="3. 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="4. Create a XalanTransformer.">
+<source>
+XalanTransformer theXalanTransformer;
+</source>
+</s3>
+
+<s3 title="5. Perform each transformation.">
+<p>You can explicitly instantiate <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> objects for the XML
+ source document and XSL stylesheet, and an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> object
+ for the output, and then call <jump href="apiDocs/classXalanTransformer.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/classXSLTInputSource.html">XSLTInputSource</jump> and
+ <jump href="apiDocs/classXSLTResultTarget.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/classXSLTInputSource.html">XSLTInputSource</jump> and
+ <jump href="apiDocs/classXSLTResultTarget.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& fileName);</code></li>
+ <li><code>XSLTResultTarget(ostream* stream);</code></li>
+ <li><code>XSLTResultTarget(ostream& 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>
+ <li><code>XSLTResultTarget(FormatterListener& flistener);</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="6. Shut down Xalan.">
+<p>When you shut down Xalan, you may also want to shut down Xerces and ICU support (if enabled). Keep the following considerations
+ in mind:</p>
+<ul>
+ <li>Once you have shut down Xerces, you can no longer make Xalan or Xerces calls in the current process.<br/><br/></li>
+ <li>Shut down ICU support if you have enabled it (see <link anchor="icusupport">enabling ICU support</link>) and if the
+ application is exiting or no longer requires the ICU. The <code>XMLPlatformUtils::Terminate()</code> call does nothing
+ if ICU support has not been enabled.</li>
+ <li>Ensure that there are no &xslt4c; or &xml4c; objects extant at the point of termination. Any deletion of objects after
+ termination could cause errors.</li>
+</ul>
+<p>Use the static terminators.</p>
+<source>
+XalanTransformer::terminate();
+XMLPlatformUtils::Terminate();
+XalanTransformer::ICUCleanUp();
+</source>
+</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. Traditionally, a top-level parameter value is of text string type. The Xalan library now supports three types of top-level parameters that can be set. One is a text string parameter. Another is a number parameter of floating point type double. The third is a nodeset (XalanNode *) parameter, usually implemented as a parsed document.</p>
+
+<p>Any XObject that is created outside of the transformation can be associated with a top-level parameter. The XalanTransformer has an XObject factory whereby top-level parameters can be owned by the XalanTransformer object.</p>
+
+<p>To set a stylesheet parameter, use the
+<jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> setStylesheetParam() method. The setStylesheetParam() method takes two arguments: the parameter name and the value. The value can be a string type, a number double type, an (XalanNode *) pointer to a nodeset or parsed document, or any XObjectPtr returned from an XObject factory.</p>
+
+<p>Top level parameters are sticky. Once set to an instance of an XalanTransformer object, they can be used for multiple transformations. The XalanTransformer reset() method prepares a transformer for a new transformation. Use the clearStylesheetParams() method to release the top-level stylesheet parameters.</p>
+
+<p>The Xalan command line utility currently supports only a text string value for a top-level stylesheet parameter. The single quotes are required to identify a text string value.</p>
+
+<p><code>Xalan -p param1 "'string expression'"foo.xml foo.xsl</code></p>
+
+<p>If the string expression includes spaces or other characters that the shell intercepts, first enclose the string in single quotes so Xalan-C++ interprets it as a string expression, and then enclose the resulting string in double quotes so the shell interprets it as a single argument.</p>
+
+<p>The <link idref="samples" anchor="usestylesheetparam">UseStylesheetParam</link> sample application supports all three types of top-level stylesheet parameters.</p>
+
+<p>The 'C' language interface XalanCAPI also supports the three types of top-level parameters. The sample program TestCAPIparms.c shows how to use top-level parameters with 'C' language programs.</p>
+
+<note>The Xalan command line utility should be revised to accommodate the number and nodeset types of top-level stylesheet parameters. Only text string values are currently supported.</note>
+
+<p>Top-level stylesheet parameters of nodeset type (XalanNode *) are useful for the merging of multiple XML documents.</p>
+</s2>
+
+<anchor name="incremental"/>
+<s2 title="Processing output incrementally">
+<p><jump href="apiDocs/classXalanTransformer.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& xmlIn,
+ const XSLTInputSource& 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/classXalanTransformer.html">XalanTransformer</jump> includes methods for creating compiled stylesheets and
+ parsed XML documents: the compileStylesheet() method returns a pointer to a <jump href="apiDocs/classXalanCompiledStylesheet.html">
+ XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apiDocs/classXalanParsedSource.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/classXSLTResultTarget.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 fragment illustrates the procedures for working with DOM output :</p>
+<source>
+
+// Use the Xerces DOM parser to create a DOMDocument.
+
+#include <xercesc/dom/DOMDocument.hpp>
+#include <xercesc/dom/DOMImplementation.hpp>
+
+#include <xalanc/XMLSupport/FormatterToXML.hpp>
+#include <xalanc/XMLSupport/XalanTransformer.hpp>
+
+XALAN_USING_XERCES(DOMDocument)
+XALAN_USING_XERCES(DOMImplementation)
+
+XALAN_USING_XALAN(FormatterToXML)
+XALAN_USING_XALAN(XalanTransformer)
+
+
+ // If you want to produce DOM output, create an empty Xerces Document
+ // to contain the transformation output.
+
+ DOMDocument * theDOM =
+ DOMImplementation::getImplementation()->createDocument();
+
+ // Now create a FormatterListener which can be used by the transformer
+ // to send each output node to the new Xerces document
+
+ FormatterToXercesDOM theFormatter(theDOM);
+
+ // Now do the transform as normal
+ XalanTransformer theXalanTransformer
+ int theResult = theXalanTransformer.transform(
+ "foo.xml",
+ "foo.xsl",
+ theFormatter);
+...
+
+ // After you perform the transformation, the DOMDocument contains
+ // the output.
+</source>
+<note>You can also follow the same process but use a <em>FormatterToDeprecatedXercesDOM</em> if you require a DOM_Document
+ output. However this is discouraged, as support for the deprecated DOM may be removed in future releases of &xslt4c;</note>
+<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>If you are using the deprecated DOM, the Xerces DOMParser by default, 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/classXercesDOMWrapperParsedSource.html">XercesDOMWrapperParsedSource</jump> to
+ pass in a Xerces DOM as the source for an XSL transformation.</p>
+<source>
+#include <xercesc/parsers/DOMParser.hpp>
+#include <xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp>
+
+void parseWithXerces(XalanTransformer &xalan,
+ const XSLTInputSource &xmlInput,
+ const XalanCompiledStylesheet* styleSheet,
+ const XSLTResultTarget &output,
+ XMLFileReporter &logFile)
+{
+ XercesDOMParser theParser;
+
+ // Turn on validation and namespace support.
+ theParser.setDoValidation(true);
+ theParser.setDoNamespaces(true);
+
+ // Parse the document
+
+ theParser.parse(xmlInput);
+ DOMDocument *theDOM = theParser.getDocument();
+ theDOM->normalize();
+
+ XercesDOMSupport theDOMSupport;
+ XercesParserLiaison theParserLiaison;
+
+ // 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 TraceListen uses 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>If you choose to build Xalan with ICU, you will need to rebuild Xerces with ICU as well.</p>
+<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 build_instruct.html that accompanies the download.<br/>
+ <em>Important</em> For Windows, define the environment variable ICUROOT and then restart Visual C++ or Visual Studio .NET.
+ in order for the ICUROOT variable to take effect.<br/><br/></li>
+</ol>
+
+<anchor name="icusupport"/>
+<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>Define the environment variable ICUROOT.<br/><br/></li>
+ <li>Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.<br/><br/></li>
+ <li>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 <xalanc/ICUBridge/ICUBridge.hpp>
+#include <xalanc/ICUBridge/FunctionICUFormatNumber.hpp>
+#include <xalanc/ICUBridge/ICUXalanNumberFormatFactory.hpp>
+#include <xalanc/ICUBridge/ICUBridgeCollationCompareFunctor.hpp>
+</source>
+<p>For Windows, do a clean build of the Xalan library using the "XalanICU.dsw" workspace (for Visual C++ users) or
+ "XalanICU.sln" solution (for Visual Studio .NET users).</p>
+<p>For UNIX:</p>
+<ol>
+ <li>Define the XALAN_USE_ICU environment variable.<br/><br/></li>
+ <li>Set the XALANROOT environment variable to the path to to the ICU root (unless you have copied the ICU library to
+ /usr/lib).<br/><br/></li>
+ <li><link idref="build_instruct" anchor="unix">Rebuild the Xalan library</link> (&xslt4c-linuxlib; for Linux, &xslt4c-aixlib; for AIX,
+ &xslt4c-hplib; for HP-UX 11, and &xslt4c-solarislib; for Solaris).<br/><br/></li>
+ <li>Be sure the Xalan library is on the library path (LD_LIBRARY_PATH for Red Hat Linux, LIBPATH for AIX, SHLIB_PATH for
+ HP-UX 11, LD_LIBRARY_PATH for Solaris).</li>
+</ol>
+<note>The command you use for setting environment variables depends on the shell you are using.<br/>
+ For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR="val"<br/>
+ For C Shell, use <em>setenv</em> ENVAR "val"<br/>
+ where ENVAR is the environment variable name and val is the environment variable
+ setting. You can check the setting of an environment variable with <em>echo</em> $ENVAR<br/>To define XALAN_USE_ICU,
+ set its value to "1".
+</note>
+<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 StylesheetExecutionContextDefaultobject
+// (named theExecutionContext in the following fragment),
+// and install the ICUCollationCompareFunctor.
+ICUBridgeCollationCompareFunctortheICUFunctor;
+theExecutionContext.installCollationCompareFunctor(&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_8h.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 <XalanTransformer/XalanCAPI.h></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, use an empty XSLTInputSource
+ for the stylesheet 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_8h.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 indicate the URI of the stylesheet. Supply NULL for the stylesheet argument.<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>
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org