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 [19/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/samples.xml
URL: http://svn.apache.org/viewvc/xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/samples.xml?rev=1293790&r1=1293789&r2=1293790&view=diff
==============================================================================
--- xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/samples.xml (original)
+++ xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/samples.xml Sun Feb 26 09:12:45 2012
@@ -1,385 +1,402 @@
-<?xml version="1.0" standalone="no"?>
-<!--
- * 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.
--->
-
-<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"
-[<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
-%entity-c-values; ]>
-
-<s1 title="&xslt4c; Samples">
-<ul>
- <li><link anchor="getstarted">Samples to help you get started</link></li>
- <li><link anchor="rebuilding">Rebuilding a Sample application</link></li>
- <li><link anchor="apachemodulexslt">ApacheModuleXSLT</link></li>
- <li><link anchor="compilestylesheet">CompileStylesheet</link></li>
- <li><link anchor="documentbuilder">DocumentBuilder</link></li>
- <li><link anchor="externalfunctions">ExternalFunctions</link></li>
- <li><link anchor="parsedsourcewrappers">ParsedSourceWrappers</link></li>
- <li><link anchor="serializenodeset">SerializeNodeSet</link></li>
- <li><link anchor="simpletransform">SimpleTransform</link></li>
- <li><link anchor="simplexpathapi">SimpleXPathAPI</link></li>
- <li><link anchor="simplexpathcapi">SimpleXPathCAPI</link></li>
- <li><link anchor="streamtransform">StreamTransform</link></li>
- <li><link anchor="threadsafe">ThreadSafe</link></li>
- <li><link anchor="tracelisten">TraceListen</link></li>
- <li><link anchor="transformtoxercesdom">TransformToXercesDOM</link></li>
- <li><link anchor="usememorymanager">UseMemoryManager</link></li>
- <li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
- <li><link anchor="xalantransform">XalanTransform</link></li>
- <li><link anchor="xalantransformercallback">XalanTransformerCallback</link></li>
-</ul>
-
-<anchor name="getstarted"/>
-<s2 title="Samples to help you get started">
-<p>Each of the subdirectories in the &xslt4c; samples directory contains the source files for a
- sample application. The executables for the samples are in the build subdirectory, which should be on the system
- path.</p>
-<p>With most of the samples, you can use the following procedure:</p>
-<ol>
- <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows)<br/><br/></li>
- <li>Run the sample from the command line (as indicated below)<br/><br/></li>
- <li>Examine the application source files. You may also want to modify the source files. Remember that if you
- modify a .cpp file, you must rebuild the executable and place it on the path before you can run the
- modified application.</li>
-</ol>
-<note>Each sample application looks for input files in the current directory, the directory from
- which you run the application. The input files are in the samples subdirectory along with the sample source
- files. For the UNIX builds, application executables are in the bin subdirectory. For the Windows32 build, the
- application executable is in the bin subdirectory (&xslt4c-dist;-<my_Windows_distribution>\bin). To run a
- sample, be sure the executable is on the path, and run it from the samples subdirectory that contains the input
- files.</note>
-<note>The most of the samples are implemented without providing a pluggable memory manager. The <link anchor="simpletransform">SimpleTransform</link> sample illustrates,
- in addition to a simple transformation, the usage of the processor with memory manager</note>
-
-</s2>
-
-<anchor name="rebuilding"/>
-<s2 title="Rebuilding a Sample application">
-<p>Instructions for rebuilding the samples differ depending on whether you are using the binary package or the source
-package. </p>
-<p>For Windows users, the Xalan Visual C++ workspace contains project configurations for building
- each of the samples. Users who have downloaded the source package, can find the XalanICU.dsw workspace
- file under:<br/><br/> <code>&xslt4c-dist;-src\src\xalanc\Projects\Win32\VC6</code>
- <br/><br/> and XalanICU.sln solution file under:<br/><br/>
- <code>&xslt4c-dist;-src\src\xalanc\Projects\Win32\VC7.1</code>
-
- <br/><br/> Users who have downloaded the binary package, should use the Samples.dsw workspace file
- located under: <br/><br/>
- <code>&xslt4c-dist;-<my_Win32_distribution>\Samples\Projects\Win32\VC6</code><br/><br/>
- or the Samples.sln solution file for .NET V7.1 users, located under: <br/><br/>
- <code>&xslt4c-dist;-<my_Win32_distribution>\Samples\Projects\Win32\VC7.1</code><br/><br/>
-</p>
-<p>The Makefile that comes with the UNIX distributions include targets for rebuilding one or all of
- the sample applications. To rebuild one or more sample applications from the UNIX source package,
- go to the &xslt4c-dist;-src directory and run<br/><br/>
- <code>gmake <ref>Target</ref></code><br/><br/>
- where <ref>Target</ref> is <code>Samples</code> (all the samples), <code>ApacheModuleXSLT</code>,
- <code>CompileStylesheet</code>, <code>DocumentBuilder</code>, <code>ExternalFunctions</code>,
- <code>ParsedSourceWrappers</code>, <code>SerializedNodeSet</code>, <code>SimpleTransform</code>,
- <code>SimpleXPathAPI</code>, <code>SimpleXPathCAPI</code>, <code>StreamTransform</code>,
- <code>ThreadSafe</code>, <code>TraceListen</code>, <code>TransformToXercesDOM</code>,
- <code>UseStylesheetParam</code>, <code>XalanTransform</code>, or
- <code>XalanTransformerCallback</code>.</p>
-<p>To rebuild the samples from the UNIX binary package, go to the ../samples directory of your installation,
- run the runConfigure utility for your target platform, and then run gmake. For example, AIX users would
- issue the following command:<br/><br/>
- <code>./runConfigure -p aix -c xlc_r -x xlC_r</code><br/>
- <code>cd samples</code><br/><br/>
- <code>gmake <ref>Target</ref></code><br/><br/>
- where <ref>Target</ref> can be Samples (for building all samples), or the individual sample name as
- listed above.</p>
-<note>For information on building Apache Module, see <link idref="samples"
- anchor="apachemodulexslt">ApacheModuleXSLT</link></note>
-</s2>
-
-<anchor name="apachemodulexslt"/>
-<s2 title="ApacheModuleXSLT">
-<note>This sample must be built with the Apache Web server, and the &xslt4c; distribution files do not include a binary
- for ApacheModuleXSLT. Assuming you have installed the Apache server on your platform, you can use Visual C++ on Windows to
- build ApacheModuleXSLT.dll, or the Makefile on UNIX to build xslt_module (with the appropriate library suffix).</note>
-
-<p>What it does: runs as an Apache module on an Apache Web server; performs transformations and returns the output to a Web
- browser. You configure Apache to respond to a given URL request for an output file (html or txt file in the configuration below)
- by applying an xsl stylesheet file to an xml document file (both with the specified name in a given location) and returning
- the transformation output to the client.</p>
-<p>This sample also illustrates use of the XalanTransformer class and the C API defined in src/XalanTransformer/XalanCAPI.h. It returns
- transformation output in blocks to a callback function, which enables the browser to start displaying the result before the transformation
- has been completed.</p>
-<note>You may need to adjust the Visual C++ or Makefile settings to locate the required Apache header files. As shipped, the Visual C++
- project file looks in \Apache Group\Apache\src\include, and the UNIX Makefile looks in usr/lib.</note>
-<p>To build the Apache module, follow the instructions in <link idref="buildlibs" anchor="winbldenv">Steps for doing a Windows
- build</link> or <link idref="buildlibs" anchor="unixbldenv">Steps for doing a UNIX build</link>. For UNIX platforms, you do the build with<br/>
- <code>gmake ApacheModuleXSLT</code>.</p>
-
-<s3 title="Setting up and using ApacheModuleXSLT">
-<p>To use ApacheModuleXSLT, do the following:</p>
-<ol>
- <li>(UNIX only) Be sure the Xalan and Xerces libraries are on your library path (you can accomplish this by copying them to
- /usr/lib; see <link idref="getstarted" anchor="path">Setting up the path/library path</link>), and copy the Apache module to
- /usr/lib/apache.<br/><br/></li>
- <li>Add LoadModule and (UNIX only) AddModule entries to the Apache configuration file: httpd.conf.<br/><br/>
- Windows: <code>LoadModule xslt_module &xslt4c-dist;-<my_Windows_distribution>\bin\ApacheModuleXSLT.dll</code><br/><br/>
- UNIX: <code>AddModule mod_xslt.c</code><br/>
- and<br/>
- <code>LoadModule xslt_module /usr/lib/apache/mod_xslt.<ref>xx</ref></code><br/><br/>
- where <ref>xx</ref> is the appropriate library suffix for the UNIX platform ("so" or "a").<br/><br/></li>
- <li>Add a <Location> entry to httpd.conf that indicates where xml/xsl file pairs are to be found, and what target file extensions
- to recognize. We suggest the following:<br/><br/>
- <code><Location /xslt></code><br/>
- <code>AddHandler mod_xslt .html</code><br/>
- <code>AddHandler mod_xslt .txt</code><br/>
- <code></Location></code><br/><br/>
- This <Location> element instructs the module to respond to requests for <ref>xxx</ref>.html and <ref>xxx</ref>.txt files in the
- in the xslt subdirectory (under the document root; see next item) by applying the <ref>xxx</ref>.xsl stylesheet to <ref>xxx</ref>.xml
- (both in that directory) and returning the transformation result to the browser.<br/><br/>
- For example, a request for foo.html instructs the module to apply foo.xsl to foo.xml and return the result.<br/><br/>
- Note: It is up to the stylesheet to apply the appropriate xsl:output method to the output. Whether the user specifies html or txt is, of
- itself, immaterial.<br/><br/></li>
- <li>Put xml/xsl file pairs in the <Location> subdirectory (xslt in the example)) under the document root directory specified in
- httpd.conf by the DocumentRoot and <Directory> settings. Alternatively, you can modify these settings to point to
- &xslt4c-dist;-<my_UNIX_distribution>/samples/ApacheModuleXSLT, which includes an xslt subdirectory with xml/xsl file pairs
- (foo.xml/xsl, apachemod.xml/xsl).<br/><br/></li>
- <li>Start the Apache server.<br/><br/></li>
- <li>From a Web browser, call the module with a URL as follows:<br/>
- <code>http://<ref>serverName</ref>/xslt/<ref>xxx</ref>.html</code><br/>
- where <ref>serverName</ref> is the Apache server (such as www.myServer.com) and <ref>xxx</ref> is the name of an xml/xsl pair of files
- (such as foo.xml and foo.xsl) in the xslt subdirectory under the DocumentRoot directory.<br/><br/>
- For example,<br/>
- <code>http://www.myServer.com/xslt/apachemod.html</code><br/>
- instructs ApacheModuleXSLT to apply the apachemod.xsl stylesheet to the apachemod.xml XML document (both files in the xslt directory
- under the Apache DocumentRoot directory) and return the transformation result to the browser.</li>
-</ol>
-</s3>
-</s2>
-
-<anchor name="compilestylesheet"/>
-<s2 title="CompileStylesheet">
-<p>What it does: Use a compiled stylesheet to perform a series of transformations.</p>
-<p>You can run it from the CompileStylesheet subdirectory with</p>
-<p><code>CompileStylesheet</code></p>
-<p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p>
-</s2>
-
-<anchor name="documentbuilder"/>
-<s2 title="DocumentBuilder">
-<p>What it does: Use a DocumentBuilder to programmatically construct an XML document, apply the foo.xsl stylesheet to
- this document, and write the ouput to foo.out.</p>
-<p>You can run it from the DocumentBuilder subdirectory with</p>
-<p><code>DocumentBuilder</code></p>
-</s2>
-
-<anchor name="externalfunctions"/>
-<s2 title="ExternalFunctions">
-<p>What it does: implement, install, and illustrate the usage of three extension functions. The functions return a
- square root, a cube, and a string with the current date and time. The sample stylesheet (foo.xsl) gets the area
- of a cube and units of measurement from an XML document (foo.xml), computes the length of each side
- of a cube and the volume of the cube, and enters the date and time of the transformation. The output appears in
- foo.out.</p>
-<p>Run this sample from the ExternalFunctions subdirectory with</p>
-<p><code>ExternalFunctions</code></p>
-<p>See also: <link idref="extensions">Extension Functions</link>.</p>
-</s2>
-
-<anchor name="parsedsourcewrappers"/>
-<s2 title="ParsedSourceWrappers">
-<p>What it does: performs a transformation with input in the form of a pre-built XercesDOM or XalanSourceTree.</p>
-<p>Run this sample from the ParsedSourceWrappers subdirectory with</p>
-<p><code>ParsedSourceWrappers</code></p>
-<p>See transformXercesDOM() and transformXalanSourceTree() as called by transform() in ParsedSourceWrappers.cpp.</p>
-</s2>
-
-<anchor name="serializenodeset"/>
-<s2 title="SerializeNodeSet">
-<p>What it does: Serialize the node set returned by the application of an XPath expression to an XML document.</p>
-<p>Run this sample from the SerializeNodeSet subdirectory with</p>
-<p><code>SerializeNodeSet <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p>
-<p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context
- node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node. The SerializeNodeSet
- directory contains the same foo.xml sample source file as the preceding examples.</p>
-</s2>
-
-<anchor name="simpletransform"/>
-<s2 title="SimpleTransform">
-<p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and writes the
- output to foo.out. The source for this sample has been modified to demonstrate the usage of the new pluggable
- memory management feature.</p>
-<p>You can run it from the SimpleTransform subdirectory with</p>
-<p><code>SimpleTransform</code></p>
-<p>See also: <link idref="usagepatterns" anchor="xalantransformer">Basic procedures for performing XSL
- transformations</link>.</p>
-</s2>
-
-<anchor name="simplexpathapi"/>
-<s2 title="SimpleXPathAPI">
-<p>What it does: Use the XPathEvaluator interface to evaluate an XPath expression from the specified context node of
- an XML file and display the nodeset returned by the expression.</p>
-<note>You can use this sample as an aid when you want to find out what a given XPath expression returns from a
- given context node in an XML file.</note>
-<p>Run this sample from the SimpleXPathAPI subdirectory with</p>
-<p><code>SimpleXPathAPI <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p>
-<p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context
- node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node.</p>
-<note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the
- nodeset returned by the expresssion.</note>
-<p>The XPathWrapper subdirectory contains an XML file named xml.foo (part of it appears below).</p>
-<source>
-<?xml version="1.0"?>
-<doc>
- <name first="David" last="Marston">Mr. Marson</name>
- <name first="David" last="Bertoni">Mr. Bertoni</name>
- ...
- <name first="Paul" last="Dick">Mr. Dick</name>
-</doc>
-</source>
-<p>You can try command lines like</p>
-<p><code>SimpleXPathAPI foo.xml /doc name/@last</code></p>
-<p>and</p>
-<p><code>SimpleXPathAPI foo.xml / '//name[position()="4"]/@first'</code></p>
-<note>If a SimpleXPathAPI argument includes characters (such as *) that the shell interprets incorrectly, enclose the argument
- in double quotes.</note>
-<p>See also: <link idref="usagepatterns" anchor="xpath">Working with XPath expressions</link>.</p>
-</s2>
-
-<anchor name="simplexpathcapi"/>
-<s2 title="SimpleXPathCAPI">
-<p>What it does: Use the XPathEvaluator C interface to evaluate an XPath epxeression and display the string value returned
- by the epxression.</p>
-<note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the nodeset
- returned by the epxresssion.</note>
-<p>Run this sample from the SimpleXPathCAPI subdirectory with</p>
-<p><code>SimpleXPathCAPI <ref>XMLFile</ref> <ref>XPathExpression</ref></code></p>
-<p>where <ref>XMLFile</ref> is an XML source file, and <ref>XPathExpression</ref> is an XPath expression to apply to the XML
- source file. The SimpleXPathCAPI subdirectory contains an XML file named xml.foo identical to foo.xml in the preceding
- example.</p>
-<p>You can try command lines like</p>
-<p><code>SimpleXPathCAPI foo.xml /doc/name[3]</code></p>
-</s2>
-
-<anchor name="streamtransform"/>
-<s2 title="StreamTransform">
-<p>What it does: The StreamTransform class processes character input streams containing a stylesheet and an XML document, and
- writes the transformation output to a character output stream. This sample illustrates the process for working with stylesheets
- and documents that you assemble in memory.</p>
-<p>You can run it from the SimpleTransform subdirectory with</p>
-<p><code>StreamTransform</code></p>
-</s2>
-
-<anchor name="threadsafe"/>
-<s2 title="ThreadSafe">
-<p>What it does: Multiple threads use a single compiled stylesheet (StylesheetRoot) and DOM source tree (XalanNode) to perform
- transformations concurrently. The application tracks the progress of the threads in messages to the console, and each thread
- writes its own output file. Imagine a server application responding to multiple clients who happen to request the same
- transformation.</p>
-<p>You can run it from the ThreadSafe subdirectory with</p>
-<p><code>ThreadSafe</code></p>
-<p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p>
-</s2>
-
-<anchor name="tracelisten"/>
-<s2 title="TraceListen">
-<p>What it does: Trace events during a transformation; the transformation uses birds.xsl to transform birds.xml and writes the
- output to birds.out.</p>
-<p>You can run it from the TraceListen subdirectory with</p>
-<p><code>TraceListen <ref>traceFlags</ref></code></p>
-<p>where <ref>traceFlags</ref> is one or more of the following:</p>
-<p> <code>-tt</code> (Trace the templates as they are being called)</p>
-<p> <code>-tg</code> (Trace each result tree generation event)</p>
-<p> <code>-ts</code> (Trace each selection event)</p>
-<p> <code>-ttc</code> (Trace the template children as they are being processed)</p>
-<p>These flags are also available in the <link idref="commandline">command-line utility (TestXSLT)</link>.</p>
-<p>The core of this example is the following fragment:</p>
-<source>
-// Set up a diagnostic writer to be used by the TraceListener...
-XalanStdOutputStream theStdErr(cerr);
-XalanOutputStreamPrintWriter diagnosticsWriter(theStdErr);
-// Make sure that error reporting, which includes any TraceListener
-// output does not throw exceptions when transcoding, since that could
-// result in an exception being thrown while another exception is active.
-// In particular, characters that the TraceListener writes might not be
-// representable in the local code page.
-theStdErr.setThrowTranscodeException(false);
-
-// Set up the TraceListener...
-// traceTemplates, traceTemplateChildren, traceGenerationEvent,
-// and TraceSelectionEvent are booleans set by the command line.
-TraceListenerDefault theTraceListener(
- diagnosticsWriter,
- traceTemplates,
- traceTemplateChildren,
- traceGenerationEvent,
- traceSelectionEvent);
-
-// Add the TraceListener to the XSLT processor...
-theProcessor.setTraceSelects(traceSelectionEvent);
-theProcessor.addTraceListener(&theTraceListener);
-
-// Perform the transformation
-....
-</source>
-</s2>
-
-<anchor name="transformtoxercesdom"/>
-<s2 title="TransformToXercesDOM">
-<p>What it does: Performs a simple transformation but puts the result in a Xerces DOMDocument</p>
-<p>Run this sample from the TransformToXercesDOM subdirectory with</p>
-<p><code>TransformToXercesDOM <ref>XMLFile</ref> <ref>XSLFile</ref></code></p>
-<p>where <ref>XMLFile</ref> is a source XML file, and <ref>XSLFile</ref> is the XLST input file. The program will use
- <ref>XSLFile</ref> to transform the input file <ref>XMLFile</ref> using Xerces DOM as the output destination.</p>
-<p>See the FormatterToXercesDOM usage in the sample code.</p>
-</s2>
-
-<anchor name="usestylesheetparam"/>
-<s2 title="UseStylesheetParam">
-<p>What it does: Set a stylesheet parameter that the stylesheet uses during the transformation.</p>
-<p>You can run it from the UseStylesheetParam subdirectory with</p>
-<p><code>UseStylesheetParam <ref>key expression</ref></code></p>
-<p>where <ref>key</ref> is the parameter key (or name) and <ref>expression</ref> is a string expression enclosed
- in single quotes.</p>
-<p>The example uses a stylesheet (foo.xsl) with a parameter named param1. The stylesheet accepts any string
- expression. Enclose the string expression in single quotes (so it is interpreted as an expression); if it
- includes more than a single word, enclose the resulting string in double quotes so the executable interprets it
- as a single argument. For example:</p>
-<p><code>UseStylesheetParam param1 "'hello out there'"</code></p>
-<p>See also: <link idref="usagepatterns" anchor="params">Setting stylesheet parameters</link>.</p>
-</s2>
-
-<anchor name="xalantransform"/>
-<s2 title="XalanTransform">
-<p>What it does: XalanTransform uses the XalanTransformer class and the associated C++ API to apply an XSL stylesheet
- file to an XML document file and write the transformation output to either an output file or to a stream. XalanTransform
- takes command-line arguments for the XML document to be transformed, the XSL stylesheet to apply, and an optional output
- file argument. If you omit the third argument, XalanTransform writes the transformation output to a stream that is sent to
- standard out (the console).</p>
-<p>You can run XalanTransform from the XalanTransform subdirectory with</p>
-<p><code>XalanTransform foo.xml foo.xsl foo.out</code></p>
-<p>Omit the third argument to write the transformation result to the console. See also: <link idref="usagepatterns"
- anchor="xalantransformer">Using the XalanTransformer class.</link>.</p>
-</s2>
-
-<anchor name="xalantransformercallback"/>
-<s2 title="XalanTransformerCallback">
-<p>What it does: Return transformation output in blocks to a callback function, which writes the output to a file.
- This sample illustrates the use of a callback function to incrementally process a transformation result, that is to begin
- working with the transformation result before the transformation has been completed. See <link idref="usagepatterns"
- anchor="incremental">Processing output incrementally</link>.</p>
-<p>You can run it from the XalanTransformerCallback subdirectory with</p>
-<p><code>XalanTransformerCallback foo.xml foo.xsl [foo.out]</code></p>
-<note>If you omit the third argument, the transformation result is written to the console.</note>
-</s2>
-
-</s1>
+<?xml version="1.0" standalone="no"?>
+<!--
+ * 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.
+-->
+
+<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd" [
+<!ENTITY % entity-c-values SYSTEM "../entities-c.ent" >
+%entity-c-values; ]>
+
+<s1 title="&xslt4c; Samples">
+<ul>
+ <li><link anchor="getstarted">Samples to help you get started</link></li>
+ <li><link anchor="rebuilding">Rebuilding a Sample application</link></li>
+ <li><link anchor="apachemodulexslt">ApacheModuleXSLT</link></li>
+ <li><link anchor="compilestylesheet">CompileStylesheet</link></li>
+ <li><link anchor="documentbuilder">DocumentBuilder</link></li>
+ <li><link anchor="externalfunctions">ExternalFunctions</link></li>
+ <li><link anchor="parsedsourcewrappers">ParsedSourceWrappers</link></li>
+ <li><link anchor="serializenodeset">SerializeNodeSet</link></li>
+ <li><link anchor="simpletransform">SimpleTransform</link></li>
+ <li><link anchor="simplexpathapi">SimpleXPathAPI</link></li>
+ <li><link anchor="simplexpathcapi">SimpleXPathCAPI</link></li>
+ <li><link anchor="streamtransform">StreamTransform</link></li>
+ <li><link anchor="threadsafe">ThreadSafe</link></li>
+ <li><link anchor="tracelisten">TraceListen</link></li>
+ <li><link anchor="transformtoxercesdom">TransformToXercesDOM</link></li>
+ <li><link anchor="usememorymanager">UseMemoryManager</link></li>
+ <li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
+ <li><link anchor="xalantransform">XalanTransform</link></li>
+ <li><link anchor="xalantransformercallback">XalanTransformerCallback</link></li>
+</ul>
+
+<anchor name="getstarted"/>
+<s2 title="Samples to help you get started">
+<p>Each of the subdirectories in the &xslt4c; samples directory contains the source files for a
+ sample application. The executables for the samples are in the build subdirectory, which should be on the system
+ path.</p>
+<p>With most of the samples, you can use the following procedure:</p>
+<ol>
+ <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows)<br/><br/></li>
+ <li>Run the sample from the command line (as indicated below)<br/><br/></li>
+ <li>Examine the application source files. You may also want to modify the source files. Remember that if you
+ modify a .cpp file, you must rebuild the executable and place it on the path before you can run the
+ modified application.</li>
+</ol>
+<note>Each sample application looks for input files in the current directory, the directory from
+ which you run the application. The input files are in the samples subdirectory along with the sample source
+ files. For the UNIX builds, application executables are in the bin subdirectory. For the Windows32 build, the
+ application executable is in the bin subdirectory (&xslt4c-dist;-<my_Windows_distribution>\bin). To run a
+ sample, be sure the executable is on the path, and run it from the samples subdirectory that contains the input
+ files.</note>
+<note>The most of the samples are implemented without providing a pluggable memory manager. The <link anchor="simpletransform">SimpleTransform</link> sample illustrates,
+ in addition to a simple transformation, the usage of the processor with memory manager</note>
+
+</s2>
+
+<anchor name="rebuilding"/>
+<s2 title="Rebuilding a Sample application">
+<p>Instructions for rebuilding the samples differ depending on whether you are using the binary package or the source
+package. </p>
+<p>For Windows users, the Xalan Visual C++ workspace contains project configurations for building
+ each of the samples. Users who have downloaded the source package, can find the XalanICU.dsw workspace
+ file under:<br/><br/> <code>&xslt4c-dist;-src\src\xalanc\Projects\Win32\VC6</code>
+ <br/><br/> and XalanICU.sln solution file under:<br/><br/>
+ <code>&xslt4c-dist;-src\src\xalanc\Projects\Win32\VC7.1</code>
+
+ <br/><br/> Users who have downloaded the binary package, should use the Samples.dsw workspace file
+ located under: <br/><br/>
+ <code>&xslt4c-dist;-<my_Win32_distribution>\Samples\Projects\Win32\VC6</code><br/><br/>
+ or the Samples.sln solution file for .NET V7.1 users, located under: <br/><br/>
+ <code>&xslt4c-dist;-<my_Win32_distribution>\Samples\Projects\Win32\VC7.1</code><br/><br/>
+</p>
+<p>The Makefile that comes with the UNIX distributions include targets for rebuilding one or all of
+ the sample applications. To rebuild one or more sample applications from the UNIX source package,
+ go to the &xslt4c-dist;-src directory and run<br/><br/>
+ <code>gmake <ref>Target</ref></code><br/><br/>
+ where <ref>Target</ref> is <code>Samples</code> (all the samples), <code>ApacheModuleXSLT</code>,
+ <code>CompileStylesheet</code>, <code>DocumentBuilder</code>, <code>ExternalFunctions</code>,
+ <code>ParsedSourceWrappers</code>, <code>SerializedNodeSet</code>, <code>SimpleTransform</code>,
+ <code>SimpleXPathAPI</code>, <code>SimpleXPathCAPI</code>, <code>StreamTransform</code>,
+ <code>ThreadSafe</code>, <code>TraceListen</code>, <code>TransformToXercesDOM</code>,
+ <code>UseStylesheetParam</code>, <code>XalanTransform</code>, or
+ <code>XalanTransformerCallback</code>.</p>
+<p>To rebuild the samples from the UNIX binary package, go to the ../samples directory of your installation,
+ run the runConfigure utility for your target platform, and then run gmake. For example, AIX users would
+ issue the following command:<br/><br/>
+ <code>./runConfigure -p aix -c xlc_r -x xlC_r</code><br/>
+ <code>cd samples</code><br/><br/>
+ <code>gmake <ref>Target</ref></code><br/><br/>
+ where <ref>Target</ref> can be Samples (for building all samples), or the individual sample name as
+ listed above.</p>
+<note>For information on building Apache Module, see <link idref="samples"
+ anchor="apachemodulexslt">ApacheModuleXSLT</link></note>
+</s2>
+
+<anchor name="apachemodulexslt"/>
+<s2 title="ApacheModuleXSLT">
+<note>This sample must be built with the Apache Web server, and the &xslt4c; distribution files do not include a binary
+ for ApacheModuleXSLT. Assuming you have installed the Apache server on your platform, you can use Visual C++ on Windows to
+ build ApacheModuleXSLT.dll, or the Makefile on UNIX to build xslt_module (with the appropriate library suffix).</note>
+
+<p>What it does: runs as an Apache module on an Apache Web server; performs transformations and returns the output to a Web
+ browser. You configure Apache to respond to a given URL request for an output file (html or txt file in the configuration below)
+ by applying an xsl stylesheet file to an xml document file (both with the specified name in a given location) and returning
+ the transformation output to the client.</p>
+<p>This sample also illustrates use of the XalanTransformer class and the C API defined in src/XalanTransformer/XalanCAPI.h. It returns
+ transformation output in blocks to a callback function, which enables the browser to start displaying the result before the transformation
+ has been completed.</p>
+<note>You may need to adjust the Visual C++ or Makefile settings to locate the required Apache header files. As shipped, the Visual C++
+ project file looks in \Apache Group\Apache\src\include, and the UNIX Makefile looks in usr/lib.</note>
+<p>To build the Apache module, follow the instructions in <link idref="buildlibs" anchor="winbldenv">Steps for doing a Windows
+ build</link> or <link idref="buildlibs" anchor="unixbldenv">Steps for doing a UNIX build</link>. For UNIX platforms, you do the build with<br/>
+ <code>gmake ApacheModuleXSLT</code>.</p>
+
+<s3 title="Setting up and using ApacheModuleXSLT">
+<p>To use ApacheModuleXSLT, do the following:</p>
+<ol>
+ <li>(UNIX only) Be sure the Xalan and Xerces libraries are on your library path (you can accomplish this by copying them to
+ /usr/lib; see <link idref="getstarted" anchor="path">Setting up the path/library path</link>), and copy the Apache module to
+ /usr/lib/apache.<br/><br/></li>
+ <li>Add LoadModule and (UNIX only) AddModule entries to the Apache configuration file: httpd.conf.<br/><br/>
+ Windows: <code>LoadModule xslt_module &xslt4c-dist;-<my_Windows_distribution>\bin\ApacheModuleXSLT.dll</code><br/><br/>
+ UNIX: <code>AddModule mod_xslt.c</code><br/>
+ and<br/>
+ <code>LoadModule xslt_module /usr/lib/apache/mod_xslt.<ref>xx</ref></code><br/><br/>
+ where <ref>xx</ref> is the appropriate library suffix for the UNIX platform ("so" or "a").<br/><br/></li>
+ <li>Add a <Location> entry to httpd.conf that indicates where xml/xsl file pairs are to be found, and what target file extensions
+ to recognize. We suggest the following:<br/><br/>
+ <code><Location /xslt></code><br/>
+ <code>AddHandler mod_xslt .html</code><br/>
+ <code>AddHandler mod_xslt .txt</code><br/>
+ <code></Location></code><br/><br/>
+ This <Location> element instructs the module to respond to requests for <ref>xxx</ref>.html and <ref>xxx</ref>.txt files in the
+ in the xslt subdirectory (under the document root; see next item) by applying the <ref>xxx</ref>.xsl stylesheet to <ref>xxx</ref>.xml
+ (both in that directory) and returning the transformation result to the browser.<br/><br/>
+ For example, a request for foo.html instructs the module to apply foo.xsl to foo.xml and return the result.<br/><br/>
+ Note: It is up to the stylesheet to apply the appropriate xsl:output method to the output. Whether the user specifies html or txt is, of
+ itself, immaterial.<br/><br/></li>
+ <li>Put xml/xsl file pairs in the <Location> subdirectory (xslt in the example)) under the document root directory specified in
+ httpd.conf by the DocumentRoot and <Directory> settings. Alternatively, you can modify these settings to point to
+ &xslt4c-dist;-<my_UNIX_distribution>/samples/ApacheModuleXSLT, which includes an xslt subdirectory with xml/xsl file pairs
+ (foo.xml/xsl, apachemod.xml/xsl).<br/><br/></li>
+ <li>Start the Apache server.<br/><br/></li>
+ <li>From a Web browser, call the module with a URL as follows:<br/>
+ <code>http://<ref>serverName</ref>/xslt/<ref>xxx</ref>.html</code><br/>
+ where <ref>serverName</ref> is the Apache server (such as www.myServer.com) and <ref>xxx</ref> is the name of an xml/xsl pair of files
+ (such as foo.xml and foo.xsl) in the xslt subdirectory under the DocumentRoot directory.<br/><br/>
+ For example,<br/>
+ <code>http://www.myServer.com/xslt/apachemod.html</code><br/>
+ instructs ApacheModuleXSLT to apply the apachemod.xsl stylesheet to the apachemod.xml XML document (both files in the xslt directory
+ under the Apache DocumentRoot directory) and return the transformation result to the browser.</li>
+</ol>
+</s3>
+</s2>
+
+<anchor name="compilestylesheet"/>
+<s2 title="CompileStylesheet">
+<p>What it does: Use a compiled stylesheet to perform a series of transformations.</p>
+<p>You can run it from the CompileStylesheet subdirectory with</p>
+<p><code>CompileStylesheet</code></p>
+<p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p>
+</s2>
+
+<anchor name="documentbuilder"/>
+<s2 title="DocumentBuilder">
+<p>What it does: Use a DocumentBuilder to programmatically construct an XML document, apply the foo.xsl stylesheet to
+ this document, and write the ouput to foo.out.</p>
+<p>You can run it from the DocumentBuilder subdirectory with</p>
+<p><code>DocumentBuilder</code></p>
+</s2>
+
+<anchor name="externalfunctions"/>
+<s2 title="ExternalFunctions">
+<p>What it does: implement, install, and illustrate the usage of three extension functions. The functions return a
+ square root, a cube, and a string with the current date and time. The sample stylesheet (foo.xsl) gets the area
+ of a cube and units of measurement from an XML document (foo.xml), computes the length of each side
+ of a cube and the volume of the cube, and enters the date and time of the transformation. The output appears in
+ foo.out.</p>
+<p>Run this sample from the ExternalFunctions subdirectory with</p>
+<p><code>ExternalFunctions</code></p>
+<p>See also: <link idref="extensions">Extension Functions</link>.</p>
+</s2>
+
+<anchor name="parsedsourcewrappers"/>
+<s2 title="ParsedSourceWrappers">
+<p>What it does: performs a transformation with input in the form of a pre-built XercesDOM or XalanSourceTree.</p>
+<p>Run this sample from the ParsedSourceWrappers subdirectory with</p>
+<p><code>ParsedSourceWrappers</code></p>
+<p>See transformXercesDOM() and transformXalanSourceTree() as called by transform() in ParsedSourceWrappers.cpp.</p>
+</s2>
+
+<anchor name="serializenodeset"/>
+<s2 title="SerializeNodeSet">
+<p>What it does: Serialize the node set returned by the application of an XPath expression to an XML document.</p>
+<p>Run this sample from the SerializeNodeSet subdirectory with</p>
+<p><code>SerializeNodeSet <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p>
+<p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context
+ node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node. The SerializeNodeSet
+ directory contains the same foo.xml sample source file as the preceding examples.</p>
+</s2>
+
+<anchor name="simpletransform"/>
+<s2 title="SimpleTransform">
+<p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and writes the
+ output to foo.out. The source for this sample has been modified to demonstrate the usage of the new pluggable
+ memory management feature.</p>
+<p>You can run it from the SimpleTransform subdirectory with</p>
+<p><code>SimpleTransform</code></p>
+<p>See also: <link idref="usagepatterns" anchor="xalantransformer">Basic procedures for performing XSL
+ transformations</link>.</p>
+</s2>
+
+<anchor name="simplexpathapi"/>
+<s2 title="SimpleXPathAPI">
+<p>What it does: Use the XPathEvaluator interface to evaluate an XPath expression from the specified context node of
+ an XML file and display the nodeset returned by the expression.</p>
+<note>You can use this sample as an aid when you want to find out what a given XPath expression returns from a
+ given context node in an XML file.</note>
+<p>Run this sample from the SimpleXPathAPI subdirectory with</p>
+<p><code>SimpleXPathAPI <ref>XMLFile</ref> <ref>ContextNode</ref> <ref>XPathExpression</ref></code></p>
+<p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref> is the location path to the context
+ node, and <ref>XPathExpression</ref> is an XPath expression to apply to that context node.</p>
+<note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the
+ nodeset returned by the expresssion.</note>
+<p>The XPathWrapper subdirectory contains an XML file named xml.foo (part of it appears below).</p>
+<source>
+<?xml version="1.0"?>
+<doc>
+ <name first="David" last="Marston">Mr. Marson</name>
+ <name first="David" last="Bertoni">Mr. Bertoni</name>
+ ...
+ <name first="Paul" last="Dick">Mr. Dick</name>
+</doc>
+</source>
+<p>You can try command lines like</p>
+<p><code>SimpleXPathAPI foo.xml /doc name/@last</code></p>
+<p>and</p>
+<p><code>SimpleXPathAPI foo.xml / '//name[position()="4"]/@first'</code></p>
+<note>If a SimpleXPathAPI argument includes characters (such as *) that the shell interprets incorrectly, enclose the argument
+ in double quotes.</note>
+<p>See also: <link idref="usagepatterns" anchor="xpath">Working with XPath expressions</link>.</p>
+</s2>
+
+<anchor name="simplexpathcapi"/>
+<s2 title="SimpleXPathCAPI">
+<p>What it does: Use the XPathEvaluator C interface to evaluate an XPath epxeression and display the string value returned
+ by the epxression.</p>
+<note>Keep in mind that the string value returned by an XPath expression is the string value of the first node in the nodeset
+ returned by the epxresssion.</note>
+<p>Run this sample from the SimpleXPathCAPI subdirectory with</p>
+<p><code>SimpleXPathCAPI <ref>XMLFile</ref> <ref>XPathExpression</ref></code></p>
+<p>where <ref>XMLFile</ref> is an XML source file, and <ref>XPathExpression</ref> is an XPath expression to apply to the XML
+ source file. The SimpleXPathCAPI subdirectory contains an XML file named xml.foo identical to foo.xml in the preceding
+ example.</p>
+<p>You can try command lines like</p>
+<p><code>SimpleXPathCAPI foo.xml /doc/name[3]</code></p>
+</s2>
+
+<anchor name="streamtransform"/>
+<s2 title="StreamTransform">
+<p>What it does: The StreamTransform class processes character input streams containing a stylesheet and an XML document, and
+ writes the transformation output to a character output stream. This sample illustrates the process for working with stylesheets
+ and documents that you assemble in memory.</p>
+<p>You can run it from the SimpleTransform subdirectory with</p>
+<p><code>StreamTransform</code></p>
+</s2>
+
+<anchor name="threadsafe"/>
+<s2 title="ThreadSafe">
+<p>What it does: Multiple threads use a single compiled stylesheet (StylesheetRoot) and DOM source tree (XalanNode) to perform
+ transformations concurrently. The application tracks the progress of the threads in messages to the console, and each thread
+ writes its own output file. Imagine a server application responding to multiple clients who happen to request the same
+ transformation.</p>
+<p>You can run it from the ThreadSafe subdirectory with</p>
+<p><code>ThreadSafe</code></p>
+<p>See also: <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>.</p>
+</s2>
+
+<anchor name="tracelisten"/>
+<s2 title="TraceListen">
+<p>What it does: Trace events during a transformation; the transformation uses birds.xsl to transform birds.xml and writes the
+ output to birds.out.</p>
+<p>You can run it from the TraceListen subdirectory with</p>
+<p><code>TraceListen <ref>traceFlags</ref></code></p>
+<p>where <ref>traceFlags</ref> is one or more of the following:</p>
+<p> <code>-tt</code> (Trace the templates as they are being called)</p>
+<p> <code>-tg</code> (Trace each result tree generation event)</p>
+<p> <code>-ts</code> (Trace each selection event)</p>
+<p> <code>-ttc</code> (Trace the template children as they are being processed)</p>
+<p>These flags are also available in the <link idref="commandline">command-line utility (TestXSLT)</link>.</p>
+<p>The core of this example is the following fragment:</p>
+<source>
+// Set up a diagnostic writer to be used by the TraceListener...
+XalanStdOutputStream theStdErr(cerr);
+XalanOutputStreamPrintWriter diagnosticsWriter(theStdErr);
+// Make sure that error reporting, which includes any TraceListener
+// output does not throw exceptions when transcoding, since that could
+// result in an exception being thrown while another exception is active.
+// In particular, characters that the TraceListener writes might not be
+// representable in the local code page.
+theStdErr.setThrowTranscodeException(false);
+
+// Set up the TraceListener...
+// traceTemplates, traceTemplateChildren, traceGenerationEvent,
+// and TraceSelectionEvent are booleans set by the command line.
+TraceListenerDefault theTraceListener(
+ diagnosticsWriter,
+ traceTemplates,
+ traceTemplateChildren,
+ traceGenerationEvent,
+ traceSelectionEvent);
+
+// Add the TraceListener to the XSLT processor...
+theProcessor.setTraceSelects(traceSelectionEvent);
+theProcessor.addTraceListener(&theTraceListener);
+
+// Perform the transformation
+....
+</source>
+</s2>
+
+<anchor name="transformtoxercesdom"/>
+<s2 title="TransformToXercesDOM">
+<p>What it does: Performs a simple transformation but puts the result in a Xerces DOMDocument</p>
+<p>Run this sample from the TransformToXercesDOM subdirectory with</p>
+<p><code>TransformToXercesDOM <ref>XMLFile</ref> <ref>XSLFile</ref></code></p>
+<p>where <ref>XMLFile</ref> is a source XML file, and <ref>XSLFile</ref> is the XLST input file. The program will use
+ <ref>XSLFile</ref> to transform the input file <ref>XMLFile</ref> using Xerces DOM as the output destination.</p>
+<p>See the FormatterToXercesDOM usage in the sample code.</p>
+</s2>
+
+<anchor name="usestylesheetparam"/>
+<s2 title="UseStylesheetParam">
+
+<p>What it does: Performs a transformation using top-level stylesheet parameters. There are three supported types of parameters. One is a text string. A second is a number of type double. A nodeset or parsed document can also be used.</p>
+
+<p>You can run it from the UseStylesheetParam subdirectory with</p>
+
+<p><code>UseStylesheetParam <ref>xmlfile</ref> <ref>stylesheet</ref> <ref>outfile</ref> [options]</code></p>
+
+<p>where the options are:</p>
+
+<p><code> -s key "'String-Value'"</code><br/>
+<code> -n key Number</code><br/>
+<code> -d key "Document-URL"</code></p>
+
+<p>The files used by the sample program and the top-level parameter nodesets for this illustration are to be in working directory in which the sample program runs.</p>
+
+<p>Using the sample program:</p>
+
+<p><code>UseStylesheetParam foo.xml foo.xslt foo.out \<br/>
+ -s stringA "'This is a test string value'" \<br/>
+ -n numberA 123.012345 \<br/>
+ -d parmA "parmA.xml" \<br/>
+ -d parmB "parmB.xml"</code></p>
+
+<p>The <ref>parmA.xml</ref> and <ref>parmB.xml</ref> are parsed and converted to nodesets. The stylesheet <ref>foo.xslt</ref> merges the contents of <ref>foo.xml</ref> and the parameters into the <ref>foo.out</ref> file.</p>
+
+<p>The source sample is implemented in C++. Another example is implemented in 'C' using the XalanCAPI library <ref>TestCAPIparm.c</ref>. The usage interface for both is the same.</p>
+
+<p>See also: <link idref="usagepatterns" anchor="params">Setting stylesheet parameters</link>.</p>
+</s2>
+
+<anchor name="xalantransform"/>
+<s2 title="XalanTransform">
+<p>What it does: XalanTransform uses the XalanTransformer class and the associated C++ API to apply an XSL stylesheet
+ file to an XML document file and write the transformation output to either an output file or to a stream. XalanTransform
+ takes command-line arguments for the XML document to be transformed, the XSL stylesheet to apply, and an optional output
+ file argument. If you omit the third argument, XalanTransform writes the transformation output to a stream that is sent to
+ standard out (the console).</p>
+<p>You can run XalanTransform from the XalanTransform subdirectory with</p>
+<p><code>XalanTransform foo.xml foo.xsl foo.out</code></p>
+<p>Omit the third argument to write the transformation result to the console. See also: <link idref="usagepatterns"
+ anchor="xalantransformer">Using the XalanTransformer class.</link>.</p>
+</s2>
+
+<anchor name="xalantransformercallback"/>
+<s2 title="XalanTransformerCallback">
+<p>What it does: Return transformation output in blocks to a callback function, which writes the output to a file.
+ This sample illustrates the use of a callback function to incrementally process a transformation result, that is to begin
+ working with the transformation result before the transformation has been completed. See <link idref="usagepatterns"
+ anchor="incremental">Processing output incrementally</link>.</p>
+<p>You can run it from the XalanTransformerCallback subdirectory with</p>
+<p><code>XalanTransformerCallback foo.xml foo.xsl [foo.out]</code></p>
+<note>If you omit the third argument, the transformation result is written to the console.</note>
+</s2>
+
+</s1>
Modified: xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/secureweb.xml
URL: http://svn.apache.org/viewvc/xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/secureweb.xml?rev=1293790&r1=1293789&r2=1293790&view=diff
==============================================================================
--- xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/secureweb.xml (original)
+++ xalan/c/branches/XalanDocs/xalan/java/trunk/xdocs/sources/xalan-c/secureweb.xml Sun Feb 26 09:12:45 2012
@@ -1,394 +1,394 @@
-<?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="XML Security Overview">
-<ul>
-<li><link anchor="xsov_xmlParser">XML Parser Threats</link></li>
-<li><link anchor="xsov_resolvEntity">Resolving External Entities</link></li>
-<li><link anchor="xsov_trustEntity">Trusted External Entities</link></li>
-<li><link anchor="xsov_piThreat">Processing Instruction (PI) Threats</link></li>
-<li><link anchor="xsov_soapThreat">SOAP Simple Object Access Protocol</link></li>
-<li><link anchor="xsov_wsdlThreat">WSDL Web Service Description Language</link></li>
-<li><link anchor="xsov_uriThreat">URI Uniform Resource Identifiers</link></li>
-<li><link anchor="xsov_urlThreat">URL Uniform Resource Locators</link></li>
-<li><link anchor="xsov_malUtfStrings">Malformed UTF-8 and UTF-16 Strings</link></li>
-<li><link anchor="xsov_canonicalXML">Canonical XML Issues</link></li>
-<li><link anchor="xsov_xhtmlWorkaround">XHTML Output Mode - Workaround</link></li>
-</ul>
-
-<br/>
-<p><em>This document goes well beyond XSLT. Use it as a general reference.</em>
-</p>
-<p>There are numerous security issues and problems that are
-endemic to the XML architecture.
-I will try to identify some of the most common issues and threats
-and describe some mitigation strategies.
-</p>
-<p>The biggest threat issue is a matter of trust.
-How well do you trust your sources of XML data?
-What are the tools that can help increase the trust?
-</p>
-<p>Most Web Service communications uses HTTP over standard TCP ports.
-The HTTP protocol on standard TCP ports has free access through business firewalls.
-How well do your proxy servers handle the Web Service security issues
-required for your applications?
-</p>
-<p>How well are your resource identifiers protected?
-How well do your applications cope with resource identifier spoofing?
-Can your resource identifiers be trusted by outside clients?
-Can you trust the credentials of your clients?
-</p>
-<p>Will the SOAP interface for your Web Service send error messages
-to an untrusted Web Service address?
-</p>
-<p>Is your WSDL interface description file readily available for download,
-thus enabling persons with malicious intent to create targeted attacks on your Web Services?
-</p>
-<p>Can you trust the client credentials that use your Web Service application?
-</p>
-<p>There are numerous security issues that are not directly involved in
-the markup of XML or its processing.
-These issues relate to infrastructure.
-</p>
-<p>Can you trust your DNS (Domain Name Service) and reduce its vulnerability to hijacking?
-</p>
-<p>Are your web servers hardened against known application vulnerabilities?
-</p>
-<p>Are your applications hardened against
-cross site scripting and SQL injection?
-</p>
-<p>Can your client applications trust the scripts
-that are transmitted as web pages?
-</p>
-<p>Can your web server trust the scripts that are submitted?
-</p>
-<p>Is application data sanitized before being consumed by your applications?
-</p>
-
-<anchor name="xsov_xmlParser"/>
-<s2 title="XML Parser Threats">
-
-<p>This list will help you find the XML threat vectors that need to be addressed.
-Some vectors cannot be easily resolved.
-</p>
-<ul>
-<li>Resolving External Entities</li>
-<li>Implicit Trust of Internal DTD</li>
-<li>Resource Identifier Spoofing</li>
-<li>Malformed UTF-8 and UTF-16</li>
-<li>Secure the trust of external DTD descriptions</li>
-<li>Secure the trust of external Schema definitions</li>
-<li>Secure the trust of entity import and include constructs</li>
-<li>Configuration of Entity Resolver Catalogs</li>
-</ul>
-</s2>
-
-<anchor name="xsov_resolvEntity"/>
-<s2 title="Resolving External Entities">
-
-<p>The XML1.0 and XML1.1 standards specify a <code>DOCTYPE</code> format.
-The processing may uncover significant entity resolver deficiencies.
-</p>
-
-<p><code><!DOCTYPE name PUBLIC "public-id" "system-id" [internal-DTD]></code><br/>
-<code><!DOCTYPE name SYSTEM "system-id" [internal-DTD]></code>
-</p>
-<p>XML Parsers MUST process the <code>[internal-DTD]</code> if it exists.
-</p>
-<p>XML Parsers MAY process the external <code>"system-id"</code> if it can be found.
-</p>
-<p>XML Parsers MAY process the external <code>"public-id"</code> if it can be found.
-</p>
-<p>XML Parsers MAY prefer either the <code>"public-id"</code> or <code>"system-id"</code>
-if both are specified.
-</p>
-<p>XML Parsers MAY ignore both the <code>"public-id"</code> and <code>"system-id"</code>
-if present.
-</p>
-<p>Declaring a parameter entity notation <code>"%entity;"</code>
-in the <code>[internal-DTD]</code> and expanding the content within the
-<code>[internal-DTD]</code> will force the XML parser to import the content
-referenced by the <code>"%entity;"</code> notation.
-</p>
-<p>Declaring a general entity notation <code>"&entity;"</code> in the
-<code>[internal-DTD]</code> and expanding the content within the body of
-the XML document will force the XML parser to import the content referenced
-by the <code>"&entity"</code> notation.
-</p>
-<p>The default method of resolving external entities is by resolving entity
-name strings relative to DNS named hosts and/or path names relative to the
-local computer system. When receiving XML documents from an outside source,
-these entity reference locations may be unreachable, unreliable, or untrusted.
-</p>
-<p>Web Service SOAP XML documents MUST NOT have <code>DOCTYPE</code> definitions.
-SOAP processors should not process DOCTYPE definitions.
-The conformance is implementation dependent.
-</p>
-<p><jump href="http://www.w3.org/TR/soap">http://www.w3.org/TR/soap</jump>
-</p>
-</s2>
-
-<anchor name="xsov_trustEntity"/>
-<s2 title="Trusted External Entities">
-
-<p>The <ref>OASIS XML Catalogs</ref> specification, if implemented by an application,
-can specify a set of external entities that can be trusted by mapping known
-identifiers to local or trusted resources. A secure application should
-not trust entity identifiers whose resources cannot be localized and secured.
-</p>
-<p><jump href="http://www.oasis-open.org/committees/entity">http://www.oasis-open.org/committees/entity</jump>
-</p>
-<p>A similar method can be designed specifically for each application.
-</p>
-<p>A trusted application may need to pre-screen any entity definitions in XML
-before passing the information into the core of the application.
-</p>
-<p>A trusted application should install some type of entity resolving catalog
-or database that can be trusted.
-</p>
-</s2>
-
-<anchor name="xsov_piThreat"/>
-<s2 title="Processing Instruction (PI) Threats">
-
-<p>Processing instructions are a mechanism to send specific information
-into an application. A common processing instruction is a
-stylesheet declaration.
-This information is part of an XML document and comes usually
-after the XML header and before the root element.
-</p>
-<p>A stylesheet declaration may cause an application to look for an
-untrusted XSLT stylesheet to use for transformation of the
-following root element. A standard exists for associating style sheets with XML documents.
-</p>
-<p><jump href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</jump>
-</p>
-<p>Examples in the xml-stylesheet recommendation describes how to use the
-processing instruction to associate CSS stylesheets for XHTML.
-Applications that use XSLT transformations will interpret the
-xml-stylesheet processing instruction as the location of a
-XSLT transformation stylesheet.
-</p>
-<p>As more processing instructions become standardized and in common use,
-their threat of misuse increases.
-</p>
-</s2>
-
-<anchor name="xsov_soapThreat"/>
-<s2 title="SOAP Simple Object Access Protocol">
-
-<p>The SOAP specification explicitly forbids the transport of
-DOCTYPE definitions and PI processing instructions.
-</p>
-<p>The SOAP specifies a transport envelope that encapsulates
-an XML message for transport. SOAP can also handle various
-transmission status indicators implying confirmation of delivery,
-error messages, and queue status messages.
-SOAP transports can be loosely coupled and intermittent.
-SOAP is used extensively in the design and deployment of Web Service architectures.
-A companion Web Service specification is WSDL, the Web Service Definition Language.
-</p>
-<p>The SOAP protocol as widely deployed by Microsoft and other vendors
-is based on specifications that predate the adoption
-by the <jump href="http://www.w3.org">World Wide Web Consortium (W3C)</jump>.
-SOAP is not based on Microsoft technology.
-It is an open standard drafted by UserLand, Ariba, Commerce One, Compaq,
-Developmentor, HP, IBM, IONA, Lotus, Microsoft, and SAP.
-<jump href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP 1.1</jump>
-was presented to the W3C in May 2000 as an official Internet standard.
-</p>
-<p>The original <jump href="http://www.w3.org/TR/soap11">SOAP 1.1</jump> standard
-is associated with this URI namespace prefix.
-</p>
-<p><code>http://schemas.xmlsoap.org/soap/</code>
-</p>
-<p>There are significant changes in naming conventions since SOAP 1.1
-was adopted by W3C as a recommended standard.
-The current iteration is <jump href="http://www.w3.org/TR/soap12">SOAP 1.2</jump>
-and is associated with this URI namespace prefix.
-</p>
-<p><code>http://www.w3.org/2003/05</code>
-</p>
-<p>The basic security threat to the SOAP architecture is
-the ability to spoof Web Service addresses and telling a
-SOAP server to respond to a rogue Web Service address
-when a <code>mustUnderstand</code> attribute is processed
-and an error indication is raised.
-</p>
-<p>Other intelligence that can be obtained might be the
-location of a public accessible WSDL definition
-of the messages being transported by SOAP,
-thus allowing additional malware attacks to be automatically generated.
-</p>
-</s2>
-
-<anchor name="xsov_wsdlThreat"/>
-<s2 title="WSDL Web Service Description Language">
-
-<p>WSDL is known as the Web Service Description Language.
-The WSDL XML document is a an interface description that can be transformed
-into various programming languages.
-Such transformed interface descriptions are recognized as
-Java Interfaces and C++ Virtual Classes.
-</p>
-<p>The original <jump href="http://www.w3.org/TR/wsdl">WSDL 1.1</jump> standard
-is associated with this URI namespace prefix.
-</p>
-<p><code>http://schemas.xmlsoap.org/wsdl/</code>
-</p>
-<p>The current <jump href="http://www.w3.org/TR/wsdl20">WSDL 2.0</jump> standard
-is maintained by W3C in their namespace with prefix.
-</p>
-<p><code>http://www.w3.org/</code>
-</p>
-<p>The WSDL can provide a template for generating a compliant Web Service systems
-for multiple and hetrogeneous platforms.
-</p>
-<p>A WSDL document that can benefit developers can also be used by malware
-and hackers to taylor specific threats against targeted Web Services.
-</p>
-<p>The SOA (Service Oriented Architecure),
-SAAS (Software As A Service),
-PAAS (Platform As A Service) are families of
-Web Services used as interfaces into what is
-generally known as Cloud Computing.
-</p>
-</s2>
-
-<anchor name="xsov_uriThreat"/>
-<s2 title="URI Uniform Resource Identifiers">
-
-<p>The URI does not need to specify the location of a resource.
-It merely provides a resource name. A catalog, database,
-or other mechanism is used to map URIs to resource locations.
-</p>
-<p>The security issue here is that most URIs are used with a
-DNS (Domain Name Service) to find a host and path to a resource.
-The URI is then treated as a URL (Uniform Resource Locator).
-</p>
-<p>The mitigation of these threats requires diligence of the
-application architects to ensure an appropriate level of trust
-for the URIs and URLs used in their applications.
-</p>
-<p>The transmission media is inherently untrusted.
-Often SOAP bindings and HTTP transports are used.
-Web Service addressing is readily spoofed.
-</p>
-</s2>
-
-<anchor name="xsov_urlThreat"/>
-<s2 title="URL Uniform Resource Locators">
-
-<p>See: <link anchor="xsov_uriThreat">URI Uniform Resource Identifiers</link>
-</p>
-</s2>
-
-<anchor name="xsov_malUtfStrings"/>
-<s2 title="Malformed UTF-8 and UTF-16 Strings">
-
-<p>Public Key Infrastructure (X.509) certificates are leased from a
-certificate authority or are self-signed.
-The distinguished names and parts thereof are usually rendered in unicode.
-</p>
-<p>The value of zero is not a valid Unicode character.
-It is possible to create non-zero UTF-8 and UTF-16 sequences that equate to zero,
-which is not allowed.
-Some rogue hackers have successfully obtained wild-card PKI (X.509) certificates
-by prepending a UTF-8(zero) in a distinguished name when applying for a certificate.
-Such a certificate could be used to successfully sign anything.
-</p>
-<p>Applications should not blindly accept UTF-8 and UTF-16 strings
-without verifying the proper encoding for those strings.
-Contents that equate to bad Unicode character values should be denied.
-</p>
-</s2>
-
-<anchor name="xsov_canonicalXML"/>
-<s2 title="Canonical XML Issues">
-
-<p>Canonical XML is a tranformation of an XML document into a
-canonical form useful for signing.
-This is used in some Web Service security implementations.
-</p>
-<p>There are several areas where Canonical XML will create XML documents
-that have severe application problems.
-</p>
-<p>The number values are rendered in Base-10 as decimal fractions.
-The computations performed by computers are usually in Base-2 floating point arithmetic.
-You therefore have truncation or roundoff issues when converting between
-decimal fractions and Base-2 fractions.
-</p>
-<p>The canonical process may collapse whitespace and transform
-multi-character line endings to single-character line endings.
-When whitespace is significant, the canonical issues for signing can cause problems.
-</p>
-<p>It is possible to create XHTML documents that will not work with some browsers.
-The empty <a/> anchor element is not allowed by many browsers,
-therefore <a></a> is required.
-A standard XML canonical process may collapse elements with no content into empty elements.
-The empty paragraph<p/> is disallowed. The <p></p> is supported.
-</p>
-<p>The World Wide Web Consortium (W3C) has additional detailed discussion of
-<jump href="http://www.w3.org/TR/C14N-issues/">canonicalization issues</jump>.
-</p>
-</s2>
-
-<anchor name="xsov_xhtmlWorkaround"/>
-<s2 title="XHTML Output Mode - Workaround">
-
-<p>The Xalan-C/C++ library currently has no XHTML output mode.
-Since XHTML is to be well-formed XML, the desire is to use the XML output method.
-</p>
-<p>XHTML is based on HTML version 4.
-</p>
-<p>Empty elements declared by HTML-4 should have a space before the
-trailing '/>' markup (i.e. <br /> and <hr />).
-XML output mode does not normally have this space when using
-the <xsl:element name="br" /> in your stylesheet.
-Most modern browsers are ok with no space, but viewing the
-browser source shows a warning condition.
-</p>
-<p>Non-empty elements declared by HTML-4 should not be rendered as empty XML elements.
-If there is no content, the elements should be rendered with both a start-tag and end-tag
-(i.e. <a name="xxx"></a>) instead of an XML empty-element.
-XSLT processors usually create an empty-element
-(i.e. <a name="xxx"/>) when the element being defined has no content
-other than attributes.
-</p>
-<p>For XSLT processors creating XML documents for XHTML,
-you can create what looks like an element with no content by including
-the &#8204; character
-(a zero-width non-joining character often known as &zwnj;)
-as the element text content.
-This also allows transitional browsers the ability to find the end tag.
-</p>
-<p><source> DTD <!ENTITY zwnj "&#8204;">
-
- <a name="marker">&zwnj;</a></source>
-</p>
-<p>Transitional XHTML is not usually well-formed XML.
-It becomes a mix of HTML version 4 and XML markup.
-Strict XHTML is required to be well-formed XML.
-</p>
-</s2>
+<?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="XML Security Overview">
+<ul>
+<li><link anchor="xsov_xmlParser">XML Parser Threats</link></li>
+<li><link anchor="xsov_resolvEntity">Resolving External Entities</link></li>
+<li><link anchor="xsov_trustEntity">Trusted External Entities</link></li>
+<li><link anchor="xsov_piThreat">Processing Instruction (PI) Threats</link></li>
+<li><link anchor="xsov_soapThreat">SOAP Simple Object Access Protocol</link></li>
+<li><link anchor="xsov_wsdlThreat">WSDL Web Service Description Language</link></li>
+<li><link anchor="xsov_uriThreat">URI Uniform Resource Identifiers</link></li>
+<li><link anchor="xsov_urlThreat">URL Uniform Resource Locators</link></li>
+<li><link anchor="xsov_malUtfStrings">Malformed UTF-8 and UTF-16 Strings</link></li>
+<li><link anchor="xsov_canonicalXML">Canonical XML Issues</link></li>
+<li><link anchor="xsov_xhtmlWorkaround">XHTML Output Mode - Workaround</link></li>
+</ul>
+
+<br/>
+<p><em>This document goes well beyond XSLT. Use it as a general reference.</em>
+</p>
+<p>There are numerous security issues and problems that are
+endemic to the XML architecture.
+I will try to identify some of the most common issues and threats
+and describe some mitigation strategies.
+</p>
+<p>The biggest threat issue is a matter of trust.
+How well do you trust your sources of XML data?
+What are the tools that can help increase the trust?
+</p>
+<p>Most Web Service communications uses HTTP over standard TCP ports.
+The HTTP protocol on standard TCP ports has free access through business firewalls.
+How well do your proxy servers handle the Web Service security issues
+required for your applications?
+</p>
+<p>How well are your resource identifiers protected?
+How well do your applications cope with resource identifier spoofing?
+Can your resource identifiers be trusted by outside clients?
+Can you trust the credentials of your clients?
+</p>
+<p>Will the SOAP interface for your Web Service send error messages
+to an untrusted Web Service address?
+</p>
+<p>Is your WSDL interface description file readily available for download,
+thus enabling persons with malicious intent to create targeted attacks on your Web Services?
+</p>
+<p>Can you trust the client credentials that use your Web Service application?
+</p>
+<p>There are numerous security issues that are not directly involved in
+the markup of XML or its processing.
+These issues relate to infrastructure.
+</p>
+<p>Can you trust your DNS (Domain Name Service) and reduce its vulnerability to hijacking?
+</p>
+<p>Are your web servers hardened against known application vulnerabilities?
+</p>
+<p>Are your applications hardened against
+cross site scripting and SQL injection?
+</p>
+<p>Can your client applications trust the scripts
+that are transmitted as web pages?
+</p>
+<p>Can your web server trust the scripts that are submitted?
+</p>
+<p>Is application data sanitized before being consumed by your applications?
+</p>
+
+<anchor name="xsov_xmlParser"/>
+<s2 title="XML Parser Threats">
+
+<p>This list will help you find the XML threat vectors that need to be addressed.
+Some vectors cannot be easily resolved.
+</p>
+<ul>
+<li>Resolving External Entities</li>
+<li>Implicit Trust of Internal DTD</li>
+<li>Resource Identifier Spoofing</li>
+<li>Malformed UTF-8 and UTF-16</li>
+<li>Secure the trust of external DTD descriptions</li>
+<li>Secure the trust of external Schema definitions</li>
+<li>Secure the trust of entity import and include constructs</li>
+<li>Configuration of Entity Resolver Catalogs</li>
+</ul>
+</s2>
+
+<anchor name="xsov_resolvEntity"/>
+<s2 title="Resolving External Entities">
+
+<p>The XML1.0 and XML1.1 standards specify a <code>DOCTYPE</code> format.
+The processing may uncover significant entity resolver deficiencies.
+</p>
+
+<p><code><!DOCTYPE name PUBLIC "public-id" "system-id" [internal-DTD]></code><br/>
+<code><!DOCTYPE name SYSTEM "system-id" [internal-DTD]></code>
+</p>
+<p>XML Parsers MUST process the <code>[internal-DTD]</code> if it exists.
+</p>
+<p>XML Parsers MAY process the external <code>"system-id"</code> if it can be found.
+</p>
+<p>XML Parsers MAY process the external <code>"public-id"</code> if it can be found.
+</p>
+<p>XML Parsers MAY prefer either the <code>"public-id"</code> or <code>"system-id"</code>
+if both are specified.
+</p>
+<p>XML Parsers MAY ignore both the <code>"public-id"</code> and <code>"system-id"</code>
+if present.
+</p>
+<p>Declaring a parameter entity notation <code>"%entity;"</code>
+in the <code>[internal-DTD]</code> and expanding the content within the
+<code>[internal-DTD]</code> will force the XML parser to import the content
+referenced by the <code>"%entity;"</code> notation.
+</p>
+<p>Declaring a general entity notation <code>"&entity;"</code> in the
+<code>[internal-DTD]</code> and expanding the content within the body of
+the XML document will force the XML parser to import the content referenced
+by the <code>"&entity"</code> notation.
+</p>
+<p>The default method of resolving external entities is by resolving entity
+name strings relative to DNS named hosts and/or path names relative to the
+local computer system. When receiving XML documents from an outside source,
+these entity reference locations may be unreachable, unreliable, or untrusted.
+</p>
+<p>Web Service SOAP XML documents MUST NOT have <code>DOCTYPE</code> definitions.
+SOAP processors should not process DOCTYPE definitions.
+The conformance is implementation dependent.
+</p>
+<p><jump href="http://www.w3.org/TR/soap">http://www.w3.org/TR/soap</jump>
+</p>
+</s2>
+
+<anchor name="xsov_trustEntity"/>
+<s2 title="Trusted External Entities">
+
+<p>The <ref>OASIS XML Catalogs</ref> specification, if implemented by an application,
+can specify a set of external entities that can be trusted by mapping known
+identifiers to local or trusted resources. A secure application should
+not trust entity identifiers whose resources cannot be localized and secured.
+</p>
+<p><jump href="http://www.oasis-open.org/committees/entity">http://www.oasis-open.org/committees/entity</jump>
+</p>
+<p>A similar method can be designed specifically for each application.
+</p>
+<p>A trusted application may need to pre-screen any entity definitions in XML
+before passing the information into the core of the application.
+</p>
+<p>A trusted application should install some type of entity resolving catalog
+or database that can be trusted.
+</p>
+</s2>
+
+<anchor name="xsov_piThreat"/>
+<s2 title="Processing Instruction (PI) Threats">
+
+<p>Processing instructions are a mechanism to send specific information
+into an application. A common processing instruction is a
+stylesheet declaration.
+This information is part of an XML document and comes usually
+after the XML header and before the root element.
+</p>
+<p>A stylesheet declaration may cause an application to look for an
+untrusted XSLT stylesheet to use for transformation of the
+following root element. A standard exists for associating style sheets with XML documents.
+</p>
+<p><jump href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</jump>
+</p>
+<p>Examples in the xml-stylesheet recommendation describes how to use the
+processing instruction to associate CSS stylesheets for XHTML.
+Applications that use XSLT transformations will interpret the
+xml-stylesheet processing instruction as the location of a
+XSLT transformation stylesheet.
+</p>
+<p>As more processing instructions become standardized and in common use,
+their threat of misuse increases.
+</p>
+</s2>
+
+<anchor name="xsov_soapThreat"/>
+<s2 title="SOAP Simple Object Access Protocol">
+
+<p>The SOAP specification explicitly forbids the transport of
+DOCTYPE definitions and PI processing instructions.
+</p>
+<p>The SOAP specifies a transport envelope that encapsulates
+an XML message for transport. SOAP can also handle various
+transmission status indicators implying confirmation of delivery,
+error messages, and queue status messages.
+SOAP transports can be loosely coupled and intermittent.
+SOAP is used extensively in the design and deployment of Web Service architectures.
+A companion Web Service specification is WSDL, the Web Service Definition Language.
+</p>
+<p>The SOAP protocol as widely deployed by Microsoft and other vendors
+is based on specifications that predate the adoption
+by the <jump href="http://www.w3.org">World Wide Web Consortium (W3C)</jump>.
+SOAP is not based on Microsoft technology.
+It is an open standard drafted by UserLand, Ariba, Commerce One, Compaq,
+Developmentor, HP, IBM, IONA, Lotus, Microsoft, and SAP.
+<jump href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP 1.1</jump>
+was presented to the W3C in May 2000 as an official Internet standard.
+</p>
+<p>The original <jump href="http://www.w3.org/TR/soap11">SOAP 1.1</jump> standard
+is associated with this URI namespace prefix.
+</p>
+<p><code>http://schemas.xmlsoap.org/soap/</code>
+</p>
+<p>There are significant changes in naming conventions since SOAP 1.1
+was adopted by W3C as a recommended standard.
+The current iteration is <jump href="http://www.w3.org/TR/soap12">SOAP 1.2</jump>
+and is associated with this URI namespace prefix.
+</p>
+<p><code>http://www.w3.org/2003/05</code>
+</p>
+<p>The basic security threat to the SOAP architecture is
+the ability to spoof Web Service addresses and telling a
+SOAP server to respond to a rogue Web Service address
+when a <code>mustUnderstand</code> attribute is processed
+and an error indication is raised.
+</p>
+<p>Other intelligence that can be obtained might be the
+location of a public accessible WSDL definition
+of the messages being transported by SOAP,
+thus allowing additional malware attacks to be automatically generated.
+</p>
+</s2>
+
+<anchor name="xsov_wsdlThreat"/>
+<s2 title="WSDL Web Service Description Language">
+
+<p>WSDL is known as the Web Service Description Language.
+The WSDL XML document is a an interface description that can be transformed
+into various programming languages.
+Such transformed interface descriptions are recognized as
+Java Interfaces and C++ Virtual Classes.
+</p>
+<p>The original <jump href="http://www.w3.org/TR/wsdl">WSDL 1.1</jump> standard
+is associated with this URI namespace prefix.
+</p>
+<p><code>http://schemas.xmlsoap.org/wsdl/</code>
+</p>
+<p>The current <jump href="http://www.w3.org/TR/wsdl20">WSDL 2.0</jump> standard
+is maintained by W3C in their namespace with prefix.
+</p>
+<p><code>http://www.w3.org/</code>
+</p>
+<p>The WSDL can provide a template for generating a compliant Web Service systems
+for multiple and hetrogeneous platforms.
+</p>
+<p>A WSDL document that can benefit developers can also be used by malware
+and hackers to taylor specific threats against targeted Web Services.
+</p>
+<p>The SOA (Service Oriented Architecure),
+SAAS (Software As A Service),
+PAAS (Platform As A Service) are families of
+Web Services used as interfaces into what is
+generally known as Cloud Computing.
+</p>
+</s2>
+
+<anchor name="xsov_uriThreat"/>
+<s2 title="URI Uniform Resource Identifiers">
+
+<p>The URI does not need to specify the location of a resource.
+It merely provides a resource name. A catalog, database,
+or other mechanism is used to map URIs to resource locations.
+</p>
+<p>The security issue here is that most URIs are used with a
+DNS (Domain Name Service) to find a host and path to a resource.
+The URI is then treated as a URL (Uniform Resource Locator).
+</p>
+<p>The mitigation of these threats requires diligence of the
+application architects to ensure an appropriate level of trust
+for the URIs and URLs used in their applications.
+</p>
+<p>The transmission media is inherently untrusted.
+Often SOAP bindings and HTTP transports are used.
+Web Service addressing is readily spoofed.
+</p>
+</s2>
+
+<anchor name="xsov_urlThreat"/>
+<s2 title="URL Uniform Resource Locators">
+
+<p>See: <link anchor="xsov_uriThreat">URI Uniform Resource Identifiers</link>
+</p>
+</s2>
+
+<anchor name="xsov_malUtfStrings"/>
+<s2 title="Malformed UTF-8 and UTF-16 Strings">
+
+<p>Public Key Infrastructure (X.509) certificates are leased from a
+certificate authority or are self-signed.
+The distinguished names and parts thereof are usually rendered in unicode.
+</p>
+<p>The value of zero is not a valid Unicode character.
+It is possible to create non-zero UTF-8 and UTF-16 sequences that equate to zero,
+which is not allowed.
+Some rogue hackers have successfully obtained wild-card PKI (X.509) certificates
+by prepending a UTF-8(zero) in a distinguished name when applying for a certificate.
+Such a certificate could be used to successfully sign anything.
+</p>
+<p>Applications should not blindly accept UTF-8 and UTF-16 strings
+without verifying the proper encoding for those strings.
+Contents that equate to bad Unicode character values should be denied.
+</p>
+</s2>
+
+<anchor name="xsov_canonicalXML"/>
+<s2 title="Canonical XML Issues">
+
+<p>Canonical XML is a tranformation of an XML document into a
+canonical form useful for signing.
+This is used in some Web Service security implementations.
+</p>
+<p>There are several areas where Canonical XML will create XML documents
+that have severe application problems.
+</p>
+<p>The number values are rendered in Base-10 as decimal fractions.
+The computations performed by computers are usually in Base-2 floating point arithmetic.
+You therefore have truncation or roundoff issues when converting between
+decimal fractions and Base-2 fractions.
+</p>
+<p>The canonical process may collapse whitespace and transform
+multi-character line endings to single-character line endings.
+When whitespace is significant, the canonical issues for signing can cause problems.
+</p>
+<p>It is possible to create XHTML documents that will not work with some browsers.
+The empty <a/> anchor element is not allowed by many browsers,
+therefore <a></a> is required.
+A standard XML canonical process may collapse elements with no content into empty elements.
+The empty paragraph<p/> is disallowed. The <p></p> is supported.
+</p>
+<p>The World Wide Web Consortium (W3C) has additional detailed discussion of
+<jump href="http://www.w3.org/TR/C14N-issues/">canonicalization issues</jump>.
+</p>
+</s2>
+
+<anchor name="xsov_xhtmlWorkaround"/>
+<s2 title="XHTML Output Mode - Workaround">
+
+<p>The Xalan-C/C++ library currently has no XHTML output mode.
+Since XHTML is to be well-formed XML, the desire is to use the XML output method.
+</p>
+<p>XHTML is based on HTML version 4.
+</p>
+<p>Empty elements declared by HTML-4 should have a space before the
+trailing '/>' markup (i.e. <br /> and <hr />).
+XML output mode does not normally have this space when using
+the <xsl:element name="br" /> in your stylesheet.
+Most modern browsers are ok with no space, but viewing the
+browser source shows a warning condition.
+</p>
+<p>Non-empty elements declared by HTML-4 should not be rendered as empty XML elements.
+If there is no content, the elements should be rendered with both a start-tag and end-tag
+(i.e. <a name="xxx"></a>) instead of an XML empty-element.
+XSLT processors usually create an empty-element
+(i.e. <a name="xxx"/>) when the element being defined has no content
+other than attributes.
+</p>
+<p>For XSLT processors creating XML documents for XHTML,
+you can create what looks like an element with no content by including
+the &#8204; character
+(a zero-width non-joining character often known as &zwnj;)
+as the element text content.
+This also allows transitional browsers the ability to find the end tag.
+</p>
+<p><source> DTD <!ENTITY zwnj "&#8204;">
+
+ <a name="marker">&zwnj;</a></source>
+</p>
+<p>Transitional XHTML is not usually well-formed XML.
+It becomes a mix of HTML version 4 and XML markup.
+Strict XHTML is required to be well-formed XML.
+</p>
+</s2>
</s1>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org