You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@apache.org on 2001/08/15 19:32:41 UTC
cvs commit: xml-xalan/c/xdocs/sources/xalan extensions.xml readme.xml usagepatterns.xml
dleslie 01/08/15 10:32:41
Modified: c/xdocs/sources/xalan extensions.xml readme.xml
usagepatterns.xml
Log:
Updates for 1.2 per Dave Bertoni's review.
Revision Changes Path
1.15 +3 -3 xml-xalan/c/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/extensions.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- extensions.xml 2001/08/10 19:16:43 1.14
+++ extensions.xml 2001/08/15 17:32:40 1.15
@@ -158,10 +158,10 @@
}</source>
</s2><anchor name="install"/>
<s2 title="Installing an extension function">
-<p><jump href="apdidocs/class_xalantransformer.html">XalanTransformer</jump> provides methods for installing and unistalling external functions:</p>
+<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> provides methods for installing and unistalling external functions:</p>
<ul>
<li>installExternalFunction() makes the function available in the current instance of XalanTransformer. Use uninstallExternalFunction() to remove the function.<br/><br/></li>
-<li>installExternalFunctionGlobal() makes the function available globally. Use uninstallExternalFunctionGlobal() to remove the function. The global functions are static.</li>
+<li>installExternalFunctionGlobal() makes the function available globally. Use uninstallExternalFunctionGlobal() to remove the function. The global functions are static; they are not thread-safe!</li>
</ul>
<p>These methods include arguments for the namespace, the function name, and the function implementation.</p>
<p>When you install an extension function, the function inhabits the namespace you designate. For information about XML namespaces, see <jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</jump>.</p>
@@ -227,7 +227,7 @@
<p>Please keep in mind that <em>all</em> LocationPath expressions return a node-set, even if the expression only
returns a single attribute or a text node (node-sets with one member). You can use the XSLT string() function
to convert a node-set value to string, and the number() function to convert a node-set value to number (a double).</p>
-<p>If you want to pass a node-set to an extension function, set up the function to accept a <jump href="apidocs/class_xnodeset.html">XNodeSet</jump>.</p>
+<p>If you pass a node-set to an extension function, be sure to set up the function to process a node-set.</p>
<p>Suppose, for example, you have a ProcessNodes function class that uses<br/><br/>
<code>const NodeRefListBase& theNodeList = args[0]->nodeset();</code><br/><br/>
in the execute() method to get a reference to the node-set.</p>
1.29 +10 -7 xml-xalan/c/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/readme.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- readme.xml 2001/08/10 19:16:43 1.28
+++ readme.xml 2001/08/15 17:32:40 1.29
@@ -81,9 +81,12 @@
<p>Major updates since version 1.1 include:</p>
<ul>
<li><link idref="extensionslib">Introduction of a library of extension functions</link></li>
- <li></li>
- <li></li>
- <li></li>
+ <li>Support for pre-parsed source documents and pre-compiled stylesheets in
+ <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump> and the C API.</li>
+ <li>Support for stylesheet params in <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
+ and the C API</li>
+ <li>Support for extension functions in <jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump></li>
+ <li>Performance enhancements</li>
</ul>
</s3>
<anchor name="bugs"/>
@@ -173,7 +176,7 @@
<code>chmod +x conf*</code><br/><br/></li>
<li>Run the runConfigure utility with at least the platform flag (Linux) or the platform, C compilier, and C++ compiler flags (AIX) as indicated below.<br/><br/>
<ref>Linux:</ref> <code>runConfigure -p linux</code><br/>
- <ref>AIX:</ref> <code>runConfigure -p aix -c xlc_r -x xlC_r</code><br/><br/>
+ <ref>AIX:</ref> <code>runConfigure -p aix -c xlc -x xlC</code><br/><br/>
<ref>HP-UX 11:</ref> <code>runConfigure -p hp-11 -c cc -x aCC</code><br/><br/>
<ref>Solaris:</ref> <code>runConfigure -p solaris -c cc -x CC</code><br/><br/>
To see the other runConfigure flags you may include, use the help flag:<br/><br/>
@@ -185,13 +188,13 @@
or<br/>
<code>make <ref>targ</ref></code><br/><br/>
where <ref>targ</ref> is ommitted or is <code>all</code> (rebuild all), <code>lib</code> (the XSLT libary), or
- <code>TestXSLT</code> (the TestSXSLT executable). ICUBridge is included in the build of TestXSLT if XALAN_USE_ICU is
+ <code>testXSLT</code> (the testSXSLT executable). ICUBridge is included in the build of TestXSLT if XALAN_USE_ICU is
defined.<br/><br/></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/>
+ 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</note>
</s3><anchor name="samples"/>
1.29 +22 -13 xml-xalan/c/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/usagepatterns.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- usagepatterns.xml 2001/08/09 20:10:36 1.28
+++ usagepatterns.xml 2001/08/15 17:32:40 1.29
@@ -74,15 +74,15 @@
</ul><anchor name="intro"/>
<s2 title="Introduction">
-<p>To perform a transformation, use one of the <jump href="apdidocs/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>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="apdidocs/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>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="cpp"/>
<s2 title="Basic usage patten with the XalanTransformer C++ API">
-<p>Using <jump href="apdidocs/class_xalantransformer.html">XalanTransformer</jump> and the C++ API, you can perform one or more transformations as described in the following steps.</p>
+<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>
@@ -100,7 +100,7 @@
<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="apdidocs/class_xalantransformer.html">XalanTransformer</jump> transform() with those objects as parameters. For example:</p>
+ <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");
@@ -145,7 +145,7 @@
</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="apdidocs/class_xalantransformer.html">XalanTransformer</jump> setStylesheetParam() method. The setStytlesheetParam() method takes two arguments: the parameter name and the expression. For example:</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);
@@ -159,7 +159,7 @@
<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="apdidocs/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>
+<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& xmlIn,
const XSLTInputSource& xslIn,
@@ -169,8 +169,8 @@
<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 styleheet once and using the binary representation when you call transform().</p>
-<p><jump href="apdidocs/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="apdidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apdidocs/class_xalanparsedsource.html">XalanParsedSource</jump>.</p>
+<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;
@@ -199,12 +199,15 @@
#include <dom/DOM_Node.hpp>
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.
-DOMSupportDefault theDOMSupport;
+XercesDOMSupport theDOMSupport;
XercesParserLiaison theParserLiaison(theDOMSupport);
XalanDocument* theDoc = theParserLiaison.createDocument(theDOM);
@@ -221,6 +224,12 @@
// the output.
// You can also convert the XalanDocument to a Xerces DOM_Document.
DOM_Document domOut = theParserLiaison.mapXercesDocument(docOut)</source>
+<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>
</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.
@@ -239,7 +248,7 @@
<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">command-line utility (TextXSLT)</link> and TraceListen both use TraceListenerDefault to write events to the screen.</p>
+<p>The <link idref="commandline">command-line utility (testXSLT)</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
@@ -349,10 +358,10 @@
<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() method.<br/><br/></li>
-<li>Compile stylesheets. Use the CompileStylesheet() method to compile a stylesheet, and the TransformToFileCSS() or TransformToDataCSS() method to use the compiled stylesheet in a transformation.<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() method. After you perform the transformation, use the XalanFreeData() method to free memory allocated for the output data.<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>
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org