dleslie 00/02/01 14:06:30
Modified: docs extensions.xml Log: Still rough, but a major revision and ready for tech review. Revision Changes Path 1.3 +481 -361 xml-xalan/docs/extensions.xml Index: extensions.xml =================================================================== RCS file: /home/cvs/xml-xalan/docs/extensions.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- extensions.xml 2000/01/21 21:09:38 1.2 +++ extensions.xml 2000/02/01 22:06:30 1.3 @@ -7,22 +7,32 @@ <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"> <s1 title="&xslt4j; Extensions"> - - <s2 title="Introduction"> -<p>For those situations where you would like to augment the functionality of XSLT with calls to a procedural language, &xslt4j; supports the creation and use of extension elements and extension functions.</p> -<p>You can set up &xslt4j; components to define extension elements and extension functions that call Java classes and Javascript scripts. In your XSL stylesheets, you can then use extension components to set script properties, for example, and extension functions to return values. &xslt4j; also provides a predefined "java" extension namespace that you can use to interact directly with Java objects.</p> -<p>Furthermore, &xslt4j; ships with a propriatary extension that you can use to redirect the output of an XSL transformation to multiple files. This extension is implemented in the org.apache.xalan.xslt.extensions.Redirect class. Suggestions for extensions to add in future releases are more than welcome.</p> -</s2> +<ul> +<li><link anchor="intro">Introduction</link></li> +<li><link anchor="supported-lang">Supported languages</link></li> +<li><link anchor="basic-pattern">The basic pattern</link></li> +<li><link anchor="setup-runtime">Setting up the runtime environment</link></li> +<li><link anchor="basic-syntax">Syntax</link></li> +<li><link anchor="ext-elements">Using an extension element</link></li> +<li><link anchor="ext-functions">Using extension functions</link></li> +<li><link anchor="java-namespace">Alternative: using the predefined java extension namespace</link></li> +<li>Examples: <link anchor="ex-basic">basic JavaScript example</link>, <link anchor="ex-redirect">the Redirect extension</link>, <link anchor="ex-java-namespace">using the java namespace</link>, <link anchor="ex-java">using a Java Hashtable</link>, <link anchor="ex-javascript">using a JavaScript array</link></li> +</ul><anchor name="intro"/> + <s2 title="Introduction"> + <p>For those situations where you would like to augment the functionality of XSLT with calls to a procedural language, &xslt4j; supports the creation and use of extension elements and extension functions. An extension (a collection of elements and functions) inhabits a namespace, either a namespace you declare and designate as an extensions namespace, or the predefined java namespace that &xslt4j; provides.</p> + +<p><em>Extension elements</em> Unlike a literal result element, which the stylesheet simply transfers to the result tree, an extension element performs an action. For example, you can use the Redirect extension elements shipped with &xslt4j; to redirect portions of your transformation output to one or more files. Extension elements may contain attributes, text nodes, other elements, basically any form of the content you can place in an XML element. Extension elements may perform quite sophisticated actions, given that the extension routine has direct access to the XSL processor context object and to the element. In many cases the implementation returns void or null; if it does return a value, that value is placed in the transformation result.</p> + +<p><em>Extension functions</em>You can think of extension functions as extensions to the core library of functions that XPath provides. An extension function passes arguments to the extension and returns a value. You can use extension functions to return values that XSLT can interact with directly (node-set, result tree fragment, string, boolean, and number) as well as values (of any type) that you pass in turn to other extension functions.</p> +</s2><anchor name="supported-lang"/> <s2 title="Supported languages"> -<p>&xslt4j; uses he Bean Scripting Framework (BSF), an architecture for incorporating scripting into Java - applications and applets. Using BSF allows an application to take advantage of scripting while being - independent of any specific scripting language. </p> - <p>To use BSF, you must put two JAR files on the classpath: bsf.jar and bsfengine.jar. For JavaScript support, BSF has been tested with Mozilla Rhino 1.4 R3 js.jar, available from http://www.mozilla.org/rhino. We do not ship js.jar.</p> +<p>&xslt4j; uses the Bean Scripting Framework (BSF), an architecture for incorporating scripting into Java applications and applets. BSF allows an application to take advantage of scripting while being independent of any specific scripting language. To date, we have tested extensions implemented in Java and JavaScript. Other languages with BSF support appear in the table below.</p> +<p>BSF requires two JAR files on the classpath: bsf.jar and bsfengines.jar. These two JAR files are shipped with &xslt4j;, and that is all that is required for Java extensions. The additional JAR files or DLLs required to support extensions in other languages are listed in the table below. These files are available from the sources indicated and are not shipped with &xslt4j;.</p> <table> <tr> <td><em>Language</em></td> <td><em>Version</em></td> - <td><em>Dependencies</em></td> + <td><em>Requirements</em></td> </tr> <tr> <td>Mozilla Rhino<br/><br/></td> @@ -63,52 +73,121 @@ <td>ActivePerl from http://www.activestate.com/<br/><br/></td> </tr> </table> -</s2> -<s2 title="&xslt4j; components"> - -<p>To set up extensions, do the following in an XSL stylesheet:</p> +</s2><anchor name="basic-pattern"/> +<s2 title="The basic pattern"> +<p>The stylesheet below uses an extension element and an extension function to transform each <deadline numdays="<ref>n</ref>"/> element in the XML source into a statement indicating the date by which a customer should receive a response to an enquiry.</p> + +<p>The extension element contains a multiplier attribute, which is used to set a variable in the extension. The extension function computes the deadline, that is the current date plus numdays * multiplier. So for <deadline numdays="3"/> (in the XML source) and <timelapse multiplier="2"/> (in the stylesheet), the extension computes a deadline 6 days from now, and the stylesheet template transform the deadline element into a string along the lines of <code><p>We have received your enquiry and will respond by April 29, 2000 12:07:16 PM EST.</p></code></p> +<note>In case your noticed, the extension function could include both numdays and multiplier as arguments, thus bypassing the need for the extension element. The purpose here is to illustrate the usage pattern for both extension elements and extension functions.</note> +<p>As you review this stylesheet, please note the following:</p> <ol> - <li>Declare the &xslt4j; xslt namespace</li> - <li>Declare a namespace for at least one extension prefix</li> - <li>Use the extension-element-prefixes attribute on the xsl:stylesheet element, a literal result - element, or another extension element to declare the extension namespace as an extension</li> -</ol> -<p>Then you can utilize the extension elements and associated extension functions in your stylesheet -templates.</p> -<p>To implement the extension, define a &xslt4j; component in the xslt namespace. A &xslt4j; component may be embedded within the stylesheet or maintained separately. The component contains the code that is called when the extension elements and functions are used.</p> -<s3 title="&xslt4j; Component Syntax"> -<source><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:lxslt="http://xml.apache.org.xslt" - xmlns:extn1="URI of extension namespace1" - extension-element-prefixes="extn1 extn2"> - - <xsl:template match="..."> - ... - <extn1:element1 att1="value1" att2="value2" ...> - <whatever-the-contents/> - <including-xsl-elements/> - </extn1> - ... - <xsl:value-of select="extn1:function1(arg1,arg2,...,argn)"/> - ... - </xsl:template> - - <lxslt:component prefix="extn1" elements="element1" functions="function1"> - <lxslt:script lang="javascript"> - function element1 (xslProcContext, exensionElement) { - code to do element1, including possibly evaluating the - contents of the element by calling back to the processor + <li>The declaration of the Xalan lxslt namespace, which provides support for the component and + component/script elements:<br/><br/> + <code>xmlns:lxslt="http://xml.apache.org/xslt";</code><br/><br/></li> + <li>The declaration of a namespace for this extension:<br/><br/> + <code>xmlns:my-ext="ext1"</code><br/><br/></li> + <li>The designation of this namespace prefix as an extension prefix:<br/><br/> + <code>extension-element-prefixes="my-ext"</code><br/><br/></li> + <li>The lxslt:component with attributes designating the namespace prefix and the elements and + functions this extension provides.<br/><br/></li> + <li>The lxslt:script subelement with a JavaScript implementation of the extension. For Java + extensions, the lxslt:script element has a src attribute that you set to identify the Java class.</li> + </ol><anchor name="ex-basic"/> +<source><?xml version="1.0"?> +<!--Namespaces are global if you set them in the stylesheet element--> +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; + version="1.0" + xmlns:lxslt="http://xml.apache.org/xslt"; + xmlns:my-ext="ext1" + extension-element-prefixes="my-ext"> + + <!--The component and its script are in the lxslt namespace and define the + implementation of the extension.--> + <lxslt:component prefix="my-ext" elements="timelapse" functions="getdate"> + <lxslt:script lang="javascript"> + var multiplier=1; + // The methods or functions that implement extension elements always take two arguments. + // The first argument is the XSL Processor context; the second argument is the element node. + function timelapse(xslProcessorContext, elem) + { + multiplier=parseInt(elem.getAttribute("multiplier")); + // The element return value is placed in the result tree. + // If you do not want a return value, return null. + return null; } - - function function1 (arg1, arg2, ..., argn) { - code to do function1 + function getdate(numdays) + { + var d = new Date(); + var totalDays = parseInt(numdays) * multiplier; + d.setDate(d.getDate() + totalDays); + return d.toLocaleString(); } - </lxslt:script> + </lxslt:script> </lxslt:component> -</xsl:stylesheet></source> + + <xsl:template match="deadline"> + <p><my-ext:timelapse multiplier="2"/>We have logged your enquiry and will + respond by <xsl:value-of select="my-ext:getdate(string(@numdays))"/>.</p> + </xsl:template> + +</xsl:stylesheet> +</source> +</s2><anchor name="setup-runtime"/> +<s2 title="Setting up the runtime environment"> +<p>To run the preceding example, bsf.jar, bsfengines.jar, and js.jar must be on the class path. Remember that bsf.jar and bsfengines.jar must be on the class path to run any extension. For extensions implemented in a scripting language, see the requirements in <link anchor="supported-lang">Supported languages</link>.</p> +</s2><anchor name="basic-syntax"/> +<s2 title="Syntax"> +<p>You can always use the pattern illustrated above to set up and use extension elements and extension functions. For extension functions implemented in Java, you can also use the java namespace, described in <link anchor="java-namespace">Alternative: using the predefined java extension namespace</link>. Unless you are using the predefined java extension namespace, do the following:</p> +<s3 title="1. Declare the lxslt namespace"> +<p><code>xmlns:lxslt="http://xml.apache.org/xslt";</code></p> +<p>The lxslt namespace provides support for the lxslt:component element and lxslt:script subelement.</p> +<note>You may also use the LotusXSL alias for this namespace: "http://xsl.lotus.com/";.</note> </s3> - -<s3 title="DTD for &xslt4j; Components"> +<s3 title="2. Declare a unique namespace for each extension prefix"> +<p><br/><code>xmlns:<ref>prefix</ref>:<ref>URI</ref></code></p> +<p>The <ref>prefix</ref> identifies the namespace, and <ref>URI</ref> is one of the following:</p> +<ul> + <li>An arbitrary (but unique) string.<br/><br/></li> + <li><code>[class:]<ref>FQCN</ref></code><br/> + where <ref>FQCN</ref> is a Java fully qualified class name. If the extension only involves static class method calls (no instance constructors or instance method calls) precede the class name with <code>class:</code>.<br/><br/></li> + <li>The file name or URL for another document that contains the xslt:component element.</li> +</ul> +<p>If the stylesheet contains an xslt:component element with a prefix attribute set to the extension prefix, the only function of the URI is to provide a unique namespace. If the stylesheet does not contain an xslt:component, the URI must identify a Java class or a document containing the xslt:component.</p> +</s3> +<s3 title="3. Designate the extension prefixes"> +<p>In the stylesheet element:</p> +<p><code>extension-element-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p> +<p>In a literal result element or extension element include the xsl prefix:</p> +<p><code>xsl:extension-element-prefixes="<ref>prefix1 prefix 2 ...</ref>"</code></p> +<p>Keep in mind that where you declare namespaces and designate extension prefixes determines the scope of those namespaces.To make your extensions available throughout the stylesheet, include these settings and attribute in the stylesheet element.</p> +<p>By default, namespace declarations are included in the transformation output. To exclude namespaces from the output, use</p> +<p><code>exclude-result-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p> +<p>in the stylesheet element or</p> +<p><code>xsl:exclude-result-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p> +<p>in a literal result element or extension element.</p> +</s3> +<s3 title="4. Set up an lxslt:component"> +<p>In the scope of the xslt namespace declaration:</p> +<p><code><xslt:component prefix="<ref>prefix</ref>" </code><br/> + <code> functions="<ref>func-1 func-2 ...func-n</ref>"</code><br/> + <code> elements="<ref>elem-1 elem-2 ...elem-n</ref>"></code><br/> + <code> <!--See lxslt:script below--></code><br/> + <code></xslt:component></code></p> +<p>where <ref>func-1 func-2 ... func-n</ref> and <ref>elem-1 elem-2 elem-n</ref> designate the functions and elements the extension provides and the stylesheet uses. You can use the function-available and element-available functions to determine at run time whether a function or element designated in the xslt:component is actually available.</p> +<note>If your extension namespace is a fully qualified class name, you do not need to include the xslt:component. If you do not include it, you cannot use the function-available and element-available functions to determine whether a given element or function is actually available at runtime.</note> +</s3> +<s3 title="5. Set up the lxslt:script element"> +<p>In each xslt:component, you must include an lxslt:script element. If the extension is implemented in Java:</p> +<p><code><lxslt:script lang="javaclass" src="<ref>[class:]FQCN</ref>"/></code></p> +<p>where <ref>FQCN</ref> is the fully qualified class name. If the extension only involves static class method calls (no instance constructors or instance method calls) precede the class name with <code>class:</code>.</p> +<p>If the extension is implemented in JavaScript:</p> +<p><code><lxslt:script lang="javascript" ></code><br/> +<code> <!--The implementation script--></code><br/> +<code></lxslt:script></code></p> +<p>For other scripting languages supported by BSF, use the same approach as for JavaScript. &xslt4j; plans to add support for using the src attribute to identify another document that contains the implementation script; this feature is not yet supported.</p> +</s3> +<s3 title="Implicit DTD for lxslt:component"> <source><!ELEMENT lxslt:component (lxslt:script)> <!ATTLIST lxslt:component prefix CDATA #IMPLIED @@ -121,368 +200,409 @@ lang CDATA #REQUIRED src CDATA #IMPLIED></source> </s3> +</s2><anchor name="ext-elements"/> +<s2 title="Using an extension element"> +<p>Extension elements pass the extension two objects:</p> +<ul> +<li><jump href="apidocs/org/apache/xalan/xslt/XSLProcessorContext.html">org.apache.xalan.xslt.XSLProcessorContext</jump>, which provides access to the XSL processor, the XML source tree, the stylesheet tree, the current context node, and the current mode (if any).<br/><br/></li> +<li>org.w3c.dom.Element, which provides the API for interacting with the extension element.</li> +</ul> +<p>You can use the Element getAttribute(String name) method, for example, to read element attributes.</p> +<s3 title="Implementing an extension element"> +<p>For each extension element in a namespace, the implementation must be a Java method with the following signature, or the scripting language equivalent:</p> +<p><code><ref>Type element</ref>(org.apache.xalan.xslt.XSLProcessorContext, </code><br/> +<code> org.w3c.dom.Element extensionElement)</code></p> +<p>where <ref>Type</ref> designates the return type and <ref>element</ref> is the local part of the extension element name (the element name without the namespace prefix).</p> +<p>If the extension element is implemented in a loosely typed scripting language, such as JavaScript, the arguments and return value are untyped.</p> +<p><em>Caution:</em> The value returned by an extension element is placed in the transformaiton result. If you are not interested in a return value, use a public void Java method or return null from a scripting language function.</p> +</s3> +<s3 title="The Redirect extension"> +<p>The Redirect extension (<jump href = "apidocsorg/apache/xalan/xslt/extensions/Redirect.html">org.apache.xalan.xslt.extensions.Redirect</jump>) is shipped with &xslt4j; (more extensions are on the way!).</p> +<p>A standard XSL transformation involves three parameters: the XML source tree, an XSL stylesheet, and the transformation result tree. Whether, the result tree is output to a file, a character stream, a byte stream, a DOM, or a SAX document handler, the initial transformation sends the entire result to a single target, represented by the <resource-ref idref="XSLTResultTargetDoc"/>.</p> +<p>The Redirect extension supplies three extension elements that you can use to redirect portions of your transformation output to multiple files: <open>, <write>, and <close>. If you use the <write> element alone, the extension opens a file, writes to it, and closes the file immediately. If you want explicit control over the opening and closing of files, use <write> in conjunction with the <open> and <close> elements.</p> +<p>Each of these elements includes a file attribute and/or a select attribute to designate the output file. The file attribute takes a string, so you can use it to directly specify the output file name; The select attribute takes an XPath expression, so you can use it to dynamically generate the output file name. If you include both attributes, the Redirect extension first evaluates the select attribute, and falls back to the file attribute if the select attribute expression does not return a valid file name.</p> +</s3><anchor name="ex-redirect"/> +<s3 title="Example with the Redirect extension"> +<p>Suppose you are outputting the bulk of your result tree to one file, but you want to output the transformation of all <foo> elements and their children to another file. The following example illustrates the basic structure of the XML source:</p> +<source><?xml version="1.0"?> +<doc> + <foo file="foo.out"> + Testing Redirect extension: + <bar>A foo subelement text node</bar> + </foo> + <main> + Everything else + </main> +</doc></source> +<p>This stylesheet redirects part of the output to a secondary file:</p> +<source> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; + version="1.0" + xmlns:lxslt="http://xml.apache.org/xslt"; + xmlns:redirect="org.apache.xalan.xslt.extensions.Redirect" + extension-element-prefixes="redirect"> + + <xsl:template match="/"> + <standard-out> + Standard output: + <xsl:apply-templates/> + </standard-out> + </xsl:template> + + <xsl:template match="main"> + <main> + <xsl:apply-templates/> + </main> + </xsl:template> + + <xsl:template match="/doc/foo"> + <redirect:write select="@file"> + <foo-out> + <xsl:apply-templates/> + </foo-out> + </redirect:write> + </xsl:template> + + <xsl:template match="bar"> + <foobar-out> + <xsl:apply-templates/> + </foobar-out> + </xsl:template> + +</xsl:stylesheet></source> +<p>The standard output is:</p> +<source><?xml version="1.0" encoding="UTF-8"?> +<standard-out> + Standard output: + <main> + Everything else. + </main> +<standard-out></source> +<p>The output redirected to foo.out is:</p> +<source><?xml version="1.0" encoding="UTF-8"?> +<foo-out> + Testing Redirect extension: + <foobar-out>foo subelement text node</foobar-out> + </foo-out></source> +<p>For more information on using the Redirect extension to send output to mulitple files, see <resource-ref idref="RedirectDoc"/>.</p> +</s3> +</s2><anchor name="ext-functions"/> +<s2 title="Using extension functions"> +<p>Extension functions may include arguments of any type and return a value of any type.</p> +<p>XSLT recognizes five data types: node-set, result-tree-fragment, string, boolean, and number. You can use XPath expressions to set variables with values of these types. You can also pass literals for string, boolean, and number arguments. If you want to pass an argument of a type that XSLT does not recognize, use another extension function to return an object of that type. The stylesheet that appears in <link anchor="format-date-stylesheet">Formatting a date</link>, for example uses extension functions to return a Date object and a SimpleDateFormat object, and then uses these objects to call another extension function.</p> +<s3 title="Data type mapping"> +<p>The XSLT data types map to Java data types as follows:</p> + <table> + <tr> + <th>XSLT Type</th> + <th>Java Type</th> + </tr> + <tr> + <td>Node-Set</td> + <td>org.w3c.dom.NodeList</td> + </tr> + <tr> + <td>String</td> + <td>java.lang.String</td> + </tr> + <tr> + <td>Boolean</td> + <td>boolean or Boolean</td> + </tr> + <tr> + <td>Number</td> + <td>double or Double</td> + </tr> + <tr> + <td>Result Tree Fragment</td> + <td>org.w3c.dom.DocumentFragment</td> + </tr> + </table> +<p>For the XSLT boolean and number types, &xslt4j; first looks for a method with the corresponding Java primitive type. If it does not find such a method, it looks for a method with the object type. In the case of the foo:bar(10) static method call, for example, &xslt4j; first looks for bar(double). If it does not find such a method, it looks for for bar(java.lang.Double).</p> +<p>When an extension function is invoked, the arguments are converted as indicated above, and sent to the extension. No conversion takes place for arguments of non-XSLT types.</p> +<anchor name="ext-func-calls"/> +</s3> +<s3 title="Extension function Java calls"> +<p>Use the following syntax to instantiate Java objects and to call methods:</p> +<p><code><ref>prefix</ref>:<ref>FQCN</ref>.new (<ref>args</ref>)</code></p> -<p>For extension namespaces implemented using Java, a special -convenience is supported which allows the programmer to skip the -component specification. This is described later in the semantics -of how a component description is located and loaded.</p> -</s2> +<p>where <ref>prefix</ref> is the extension namespace prefix and <ref>FQCN</ref> is the fully qualified class name of which a new instance is to be created with the <ref>args</ref> constructor arguments (if any).</p> -<s2 title="Locating &xslt4j; Components"> - <p>When &xslt4j; encounters the extension-element-prefixes attribute on a stylesheet, it uses the - following algorithm to find and load the components to handle those extension namespaces:</p> - <ol> - <li> For each extension namespace, search for an <<em>lxslt:component</em>> - element with a <em>prefix</em> attribute whose - value matches the extension namespace prefix. If none is found, proceed to - step 2.</li> - <li>Treat the URI of the namespace as a fully - qualified class name and attempt to - load that class. If the URI starts with - "class:", strip that prefix - before attempting to load the class. If the class - loads, assume the following component description:<br/><br/> - <code> <lxslt:component prefix="prefix-being-searched-for"> - <lxslt:script lang="javaclass" src="namespaceURI"/> - </lxslt:component></code> - <br/><br/>Assume, that is, a component implementation in Java - with a source URL value of the namespace URI - as the fully qualified class name. No elements and functions are defined - - which means that if one were to test this - namespace (via extension-element-available or - extension-function-available) then the tests - would fail. However, if a function or element is - invoked on this extension namespace the call - succeeds or fails depending on whether or not the - requisite functions (as defined below) were - defined by the class.<br/><br/> - </li> - <li>Treat the URI of the namespace as a URL and - attempt to load the component description - from this URL. If found and if the - lxslt:component has a "namespace-uri" - attribute present, it <em>must</em> match the - namespace URI of the extension specified in the - stylesheet. If no "namespace-uri" - attribute is present, the component is assumed to be the - component specification for this namespace. [NOT - FULLY IMPLEMENTED YET - NAMESPACE USAGE ISN'T - CORRECT.] - </li> - </ol> - - <p>The component specification identifies the valid local - parts of the extension namespace. The element and - function local parts are identified separately using the <em>elements</em> - and <em>functions</em> attributes, respectively. The - component specification presents the code that implements - these local parts using a <<em>lxslt:script</em>> - element. The script element can inline the code or refer - to an external source for the code using the <em>src</em> - attribute.</p> - <p>The currently supported languages are: - "javaclass" and "javascript", where - "javaclass" is used to work with an - implementation in Java and "javascript" refers - to Netscape Rhino.</p> - <p>Special case for lang="javaclass": The <em>src</em> - attribute is treated as the fully qualified classname of - the class which handles the extension namespace. If the - name starts with "<em>class:</em>", - then the class is not instantiated and the methods - invoked to handle various local parts (see below) are - assumed to be static. Otherwise, a new instance is - created and used for invoking the appropriate methods as - defined below.</p> - <p>The <em>src</em> attribute is not yet implemented for - languages other than "javaclass".</p> - <p>For each extension element within the namespace, a - function with the following signature must be defined in - the implementation of the component:</p> -<source>Object <localPart> (org.apache.xalan.xslt.XSLProcessorContext, - org.w3c.dom.Element extensionElement)</source> - <p>where <localPart> is the local part of the - extension element name. If the component is implemented - in a loosely typed scripting language such as JavaScript, - then these are untyped arguments to the function and the - return type is unspecified as well. Note that for - lang=="javaclass", methods may be static or - not-static and must be public in order to be accessible.</p> - <p>When an extension element is invoked, the appropriate - function (as identified above) is invoked to handle the - invocation. The entire extension element is given as the - second argument to the function with content, if any, - as-is. Thus, if within an extension element one were to - place elements from the xsl: namespace, then those would - have to be processed by an explicit evaluation request from - the extension element handler. Such invocations are done - via the XSLProcessorContext object. [CALLING BACK INTO - XSLProcessor.java NOT IMPLEMENTED YET.]</p> - <p>For each extension function within the namespace, a - function with the following signature must be defined in - the implementation of the component:</p> - <source> Object <localPart> (Type1 arg1, Type2 arg2, ..., Typen argn)</source> - <p>where <localPart> is the local part of the - extension function name. The type of each argument - depends on what was given within XSLT in the invocation - of the function. Here is the mapping from an XSLT data - type to the Java data types that are used in invoking the - methods:</p> - <table> - <tr> - <th>XSLT Type</th> - <th>Java Type</th> - </tr> - <tr> - <td>Node-Set</td> - <td>org.w3c.dom.NodeList</td> - </tr> - <tr> - <td>String</td> - <td>java.lang.String</td> - </tr> - <tr> - <td>Boolean</td> - <td>boolean or Boolean</td> - </tr> - <tr> - <td>Number</td> - <td>double or Double</td> - </tr> - <tr> - <td>Result Tree Fragment</td> - <td>org.w3c.dom.DocumentFragment</td> - </tr> - <tr> - <td>variable</td> - <td>one of above based on <br/> - type of variable's value</td> - </tr> - </table> - <p>For boolean and number XSLT types, - first all such types are converted to the corresponding - primitive type in Java and the method searched for. If - the method is not found, then a method with the object - types is searched for. For example foo:bar('a'='b', 1, - 'Hello', 2) would first look for a method - bar(boolean,double,String,boolean) and then for - bar(Boolean,Double,String,Double).</p> - <p>If the component is implemented in a loosely typed - scripting language such as JavaScript, then these are - untyped arguments to the function and the return type is - unspecified as well.</p> - <p>When an extension function is invoked, the appropriate - function (as identified above) is invoked to handle the - invocation. Any arguments to the function are first - evaluated and then the resulting values are passed to the - function by first converting them according to the table - listed above.</p> - <p>To control how a stylesheet behaves if an extension is not available, create an xsl:fallback element with - xsl:choose or xsl:if instructions and the element-available and extension-available functions.</p> -</s2> -<s2 title="Special Handling for Extensions into Java"> +<p><code><ref>prefix</ref>:<ref>FQCN.methodName</ref> (<ref>args</ref>)</code></p> -<p>When a qualified function name is invoked, if the -namespace is not already registered as an extension namespace (by -the above mechanism), &xslt4j; treats the URI of the namespace as a fully qualified class -name and attempts to load that class. If the URI starts -with "class:", &xslt4j; strips that prefix before -attempting to load the class. If class loading succeeds, then an -extension namespace implemented in "javaclass" is -assumed with the URI as the value of the src attribute. Note that -no functions are defined - which means that if one were to test -this namespace (via extension-function-available) then the tests -would fail. However, if a function is invoked on this extension -namespace, the call succeeds or fails depending on whether or not the -requisite functions (as defined above) were defined by the class.</p> -</s2> -<s2 title="Predefined Extension Namespace for Java Access"> -<p>&xslt4j; supports a special namespace for convenient -interaction with Java objects. The namespace URI is "http://xsl.lotus.com/java". -This namespace allows the stylesheet author to create new -instances of Java classes and to invoke static and non-static -methods on them. Assuming, the namespace declaration "<em>xmlns:java='http://xsl.lotus.com/java'</em>" -is in scope, the following are supported:</p> -<p>java:<ref>FQCN</ref>.<em>new</em> (<ref>args</ref>)</p> - -<p>where FQCN is the fully qualified class name of which a new -instance is to be created with the given constructor arguments -(if any).</p> - -<p>java:<ref>FQCN.methodName</ref> (<ref>args</ref>)</p> - -<p>where <ref>FQCN</ref> is the fully qualified class name whose -static method "<ref>methodName</ref>" is to be invoked -using the given arguments. </p> - -<p>java:<ref>methodName</ref> (<ref>object</ref>, <ref>args</ref>)</p> - -<p>where <ref>methodName</ref> is the name of the (static or -non-static) method to invoke on <ref>object</ref> with the given -arguments.</p> -</s2> -<s2 title="Passing Nodes to java"> -<p>If you want to pass one or more Nodes to an extension function, set up a Java method to accept an -org.w3c.dom.NodeList (or an org.apache.xalan.xpath.MutableNodeList, which extends NodeList, if you want to modify the Nodes).</p> -<p>When you call an extension function with an argument that constitutes a pattern match for one or more Nodes, the &xslt4j; extension mechanism evaluates this argument as a NodeList, even if only one Node is involved.</p> +<p>where <ref>FQCN</ref> is the fully qualified class name whose static method <ref>methodName</ref> is to be invoked using the <ref>args</ref> arguments. </p> + +<p><code><ref>prefix</ref>:<ref>methodName</ref> (<ref>object</ref>, <ref>args</ref>)</code></p> + +<p>where <ref>methodName</ref> is the name of the method to invoke on <ref>object</ref> with the <ref>args</ref> arguments.</p> +</s3> + +<s3 title="Passing Nodes to java"> +<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-list to an extension function, set up a Java method to accept an +org.w3c.dom.NodeList (or an org.apache.xalan.xpath.MutableNodeList, which extends NodeList, if you want to modify the nodes).</p> <p>Suppose, for example, you have a myExtensions.ProcessNodes class with the following doSomething method:</p> -<p><code>doSomething(org.w3c.dom.NodeList nList)</code></p> -<p>Any of the following extension calls in a stylesheet are syntatically possible:</p> -<p><code>java:MyExtensions.ProcessNodes.doSomething(.) <!-- current node --></code></p> -<p><code>java:MyExtensions.ProcessNodes.doSomething(*) <!-- all nodes in current context--></code></p> -<p><code>java:MyExtensions.ProcessNodes.doSomething(/*) <!-- all nodes --></code></p> -<p><code>java:MyExtensions.ProcessNodes.doSomething(foo/baz) <!-- foo/baz nodes in current context --></code></p> -<p><code>java:MyExtensions.ProcessNodes.doSomething(/foo/baz | /bar/saz) <!-- /foo/baz and /bar/saz nodes --></code></p> -<p>The NodeList is in fact a list of references into the XML document, so keep in mind that getNextSibling(), for example, gets you the next sibling in the document, wich may not be the next Node in the NodeList.</p> -</s2> -<s2 title="Example 1: Named Counter Component in Java"> +<p><code>public static void doSomething(org.w3c.dom.NodeList nList)</code></p> +<p>Assuming you set up this extension in the node-ext namespace, any of the following extension calls from a stylesheet are syntatically possible:</p> +<p><code><!--Process the current node--></code><br/> +<code>node-ext:MyExtensions.ProcessNodes.doSomething(.)</code></p> +<p><code><!--Process all nodes in current context--></code><br/> +<code>node-ext:MyExtensions.ProcessNodes.doSomething(*)</code></p> +<p><code><!-- Process all nodes --></code><br/> +<code>node-ext:MyExtensions.ProcessNodes.doSomething(/*)</code></p> +<p><code><!--Process the foo/baz nodes in current context --></code><br/> +<code>node-ext:MyExtensions.ProcessNodes.doSomething(foo/baz)</code></p> +<p><code><!--Process the/foo/baz and /bar/saz nodes --></code><br/> +<code>node-ext:MyExtensions.ProcessNodes.doSomething(/foo/baz | /bar/saz)</code></p> +<p>The NodeList is in fact a list of references into the XML document, so keep in mind that getNextSibling(), for example, gets you the next sibling in the document, which may not be the next Node in the NodeList.</p> +</s3> +<s3 title="Implementing extension functions"> +<p>For each extension function in a namespace, the implementation must include a Java method with the following signature, or the scripting language equivalent:</p> +<p><code>public <ref> object function</ref>(<ref>args</ref>)</code></p> +<p>where <ref>object</ref> is the return type, <ref>function</ref> is the local part of the extension function name (the function name without the namespace prefix), and <ref>args</ref> correspond to the arguments in the function call.</p> +</s3> +</s2><anchor name="java-namespace"/> +<s2 title="Alternative: using the predefined java extension namespace"> +<p>For extension functions implemented in Java, Xalan provides a java namespace. When you declare and use the java namespace, you do not use an lxslt:component to designate the functions.</p> +<p>The java namespace supports the use of extension functions implemented in Java. You cannot use this syntax with extension elements or with extensions implemented in JavaScript or another scripting language.</p> +<s3 title="Declare the Xalan java namespace"> +<p><code>xmlns:lxslt="http://xml.apache.org/java";</code></p> +<note>You may also use the LotusXSL alias for this namespace: "http://xsl.lotus.com/java";.</note> +</s3> +<s3 title="Use the java namespace when you make extension function calls"> +<p>Use "java" as the prefix with the syntax described in <link anchor="ext-func-calls">Extension function Java calls</link>.</p> +<p>That is all. You do not need to set an extension-element-prefixes attribute, and you do not include an xslt:component element. Given the absence of the lxslt:component element, you cannot use the function-available method to determine at runtime whether a Java method call is actually available. </p> +<p>Using the java namespace clearly involves less setup than using your own namespace, as long as these restrictions are not a probleem. Remember that you always have the option of setting up your own namespace and extra overhead is really minimal.</p> +</s3><anchor name="ex-java-namespace"/> +<s3 title="Example: Formatting a date"> +<p>This example uses extension functions to call the SimpleDateFormat class and the IntDate class. IntDate uses String arguments to set up a Date object:</p> +<source>import java.util.Date; +import java.util.Calendar; + +public class IntDate +{ + public static Date getDate(String year, String month, String day) + { + // Date(int, int, int) has been deprecated, so use Calendar to + // set the year, month, and day. + Calendar c = Calendar.getInstance(); + // Cast each argument to int. + c.set(Integer.parseInt(year),Integer.parseInt(month),Integer.parseInt(day)); + return c.getTime(); + } +}</source> +<p>The template transforms date elements with four attributes. For example, it transforms <code><date format="EEEE, MMM dd, yyyy" year="2000" month="4" day="27"/></code> into <p>Date: Thursday, April 27, 2000.</p>.</p> +<p>As you review this stylesheet, please keep the following in mind:</p> + <ul> + <li>The exclude-result-prefixes stylesheet attribute prevents the java namespace declaration from + appearing in the output.</li> + <li>The XSLT type returned by any LocationPath expression is node-set, so the XSLT string + function is used to convert the format, year, month, and day attribute node-set values to + strings.</li> + <li>The format attribute provides a String argument for constructing a java.text.SimpleDateFormat + object.</li> + <li>The IntDate class uses String values provided by the year, month, and day attributes, to set the + date. XSLT can pass number values, but these are converted into doubles.</li> + <li>The formatter variable holds a SimpleDateFormat object, and the date variable holds a Date object. + XSLT does not understand either of these types, but they are used to call the SimpleDateFormat format + method. In that call, $formatter is the object, and $date is the argument. The syntax for calling + Java constructors and methods is described above in <link anchor="ext-func-calls">Extension function Java calls</link>.</li> + </ul><anchor name="format-date-stylesheet"/> +<source><?xml version="1.0"?> +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; + version="1.0" + xmlns:java="http://xml.apache.org/xslt/java"; + exclude-result-prefixes="java"> + + <!--Other templates for transforming the rest of the XML source documents--> + + <xsl:template match="date"> + <xsl:variable name="year" select="string(./@year)"/> + <xsl:variable name="month" select="string(./@month)"/> + <xsl:variable name="day" select="string(./@day)"/> + <xsl:variable name="format" select="string(./@format)"/> + + <xsl:variable name="formatter" + select="java:java.text.SimpleDateFormat.new($format)"/> -<p>MyCounter.java:</p> + <xsl:variable name="date" + select="java:IntDate.getDate($year, $month, $day)"/> -<source> import java.util.*; + <p>Date: <xsl:value-of select="java:format($formatter, $date)"/></p> + </xsl:template> +</xsl:stylesheet> +</source> +</s3> +</s2> +<s2 title="Examples: using Java and JavaScript to implement the same extension"> +<p>This section contains two examples. The first example uses a Java extension to transform a set of name elements into an alphabetical and numbered list. The second example uses a JavaScript script to do the same. Both examples include equivalent extension elements and an extension function.</p> +<anchor name="ex-java"/> +<s3 title="Java implementation"> +<p>MyCounter.java</p> +<source>mport java.util.*; public class MyCounter { Hashtable counters = new Hashtable (); - public MyCounter () { - } + public MyCounter () + {} - // the context arg is actually a org.apache.xalan.xslt.XSLProcessorContext - public void init (Object context, org.w3c.dom.Element elem) { - String name = elem.getAttribute ("name"); - String value = elem.getAttribute ("value"); + public void init(org.apache.xalan.xslt.XSLProcessorContext context, + org.apache.xalan.xslt.ElemExtensionCall extElem) + { + String name = extElem.getAttribute("name"); + String value = extElem.getAttribute("value"); int val; - try { + try + { val = Integer.parseInt (value); - } catch (NumberFormatException e) { + } + catch (NumberFormatException e) + { e.printStackTrace (); val = 0; } counters.put (name, new Integer (val)); } - public int read (String name) { + public int read(String name) + { Integer cval = (Integer) counters.get (name); return (cval == null) ? 0 : cval.intValue (); } - public void incr(Object context, org.w3c.dom.Element elem) { - String name = elem.getAttribute ("name"); - Integer cval = (Integer) counters.get (name); + public void incr(org.apache.xalan.xslt.XSLProcessorContext context, + org.apache.xalan.xslt.ElemExtensionCall extElem) { + String name = extElem.getAttribute("name"); + Integer cval = (Integer) counters.get(name); int nval = (cval == null) ? 0 : (cval.intValue () + 1); counters.put (name, new Integer (nval)); } -}</source> - -<p>MyFamily.xml:</p> - -<source><?xml version="1.0"?> - +} +</source> +<p>An XML source document:</p> +<source><?xml version="1.0"?> <doc> - <name first="Sanjiva" last="Weerawarana"/> - <name first="Shahani" last="Weerawarana"/> - <name first="Rukmal" last="Weerawarana"/> - <name first="Sashi" last="Weerawarana"/> - <name first="Kamal" last="Fernando"/> - <name first="Ruby" last="Fernando"/> + <name first="David" last="Marston"/> + <name first="David" last="Bertoni"/> + <name first="Donald" last="Leslie"/> + <name first="Emily" last="Farmer"/> + <name first="Jack" last="Donohue"/> + <name first="Myriam" last="Midy"/> + <name first="Paul" last="Dick"/> + <name first="Robert" last="Weir"/> + <name first="Scott" last="Boag"/> + <name first="Shane" last="Curcuru"/> </doc></source> - -<p>Counter.xsl:</p> - -<source><?xml version="1.0"?> - -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:lxslt="http://xsl.lotus.com/" - xmlns:counter="MyCounter" - extension-element-prefixes="counter"> - - <!-- note that the component definition is optional because I - used the fully qualified class name of the implementation - as the URI for this namespace. --> - <lxslt:component prefix="counter" - elements="init incr" functions="read"> - <lxslt:script lang="javaclass" src="MyCounter"/> +<p>The stylesheet:</p> +<source><?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; + xmlns:lxslt="http://xml.apache.org/xslt"; + xmlns:counter="MyCounter" + extension-element-prefixes="counter" + version="1.0"> + + <lxslt:component prefix="counter" + elements="init incr" functions="read"> + <lxslt:script lang="javaclass" src="MyCounter"/> </lxslt:component> - <xsl:template match="/"> + <xsl:template match="/"> <HTML> - <H1>Test for namespace specified Java extension.</H1> - <counter:init name="index" value="1"/> - <p>Here are the names in alphabetical order by last name:</p> - <xsl:for-each select="doc/name"> - <xsl:sort select="@last"/> - <xsl:sort select="@first"/> + <H1>Names in alphabetical order</H1> + <counter:init name="index" value="1"/> + <xsl:for-each select="doc/name"> + <xsl:sort select="@last"/> + <xsl:sort select="@first"/> <p> <xsl:text>[</xsl:text> - <xsl:value-of select="counter:read('index')"/> + <xsl:value-of select="counter:read('index')"/> <xsl:text>]. </xsl:text> - <xsl:value-of select="@last"/> + <xsl:value-of select="@last"/> <xsl:text>, </xsl:text> - <xsl:value-of select="@first"/> + <xsl:value-of select="@first"/> </p> - <counter:incr name="index"/> + <counter:incr name="index"/> </xsl:for-each> </HTML> </xsl:template> -</xsl:stylesheet></source> - -<p>Output:</p> - +</xsl:stylesheet> +</source> +<p>Transformation output:</p> <source><HTML> - <H1>Test for namespace specified Java extension.</H1> - <p>Here are the names in alphabetical order by last name, first name:</p> - <p>[1]. Fernando, Kamal</p> - <p>[2]. Fernando, Ruby</p> - <p>[3]. Weerawarana, Rukmal</p> - <p>[4]. Weerawarana, Sanjiva</p> - <p>[5]. Weerawarana, Sashi</p> - <p>[6]. Weerawarana, Shahani</p> +<H1>Names in alphabetical order</H1> +<p>[1]. Bertoni, David</p> +<p>[2]. Boag, Scott</p> +<p>[3]. Curcuru, Shane</p> +<p>[4]. Dick, Paul</p> +<p>[5]. Donohue, Jack</p> +<p>[6]. Farmer, Emily</p> +<p>[7]. Leslie, Donald</p> +<p>[8]. Marston, David</p> +<p>[9]. Midy, Myriam</p> +<p>[10]. Weir, Robert</p> </HTML></source> -</s2> -<s2 title="Example 2: Named Counter Component Implemented Using Java -XPath Extension Namespace"> - -<p>Counter.xsl:</p> - -<source><?xml version="1.0"?> +</s3><anchor name="ex-javascript"/> +<s3 title="JavaScript implementation"> +<p></p> +<source><?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; + xmlns:lxslt="http://xml.apache.org/xslt"; + xmlns:counter="MyCounter" + extension-element-prefixes="counter" + version="1.0"> + + <lxslt:component prefix="counter" + elements="init incr" functions="read"> + <lxslt:script lang="javascript"> + var counters = new Array(); + + function init (xslproc, elem) { + name = elem.getAttribute ("name"); + value = parseInt(elem.getAttribute ("value")); + counters[name] = value; + return null; + } -<!-- named counter functionality done using java: --> + function read (name) { + // Return a string. + return "" + (counters[name]); + } -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:java="http://xsl.lotus.com/java"> + function incr (xslproc, elem) + { + name = elem.getAttribute ("name"); + counters[name]++; + return null; + } + </lxslt:script> + </lxslt:component> - <xsl:template match="/"> + <xsl:template match="/"> <HTML> - <H1>Test for namespace specified Java extension.</H1> - <xsl:variable name="counter-table" - select="java:java.util.Hashtable.new ()"/> - <!-- do following for side-effect --> - <xsl:if test="java:put ($counter-table, 'index', 1)"/> - <p>Here are the names in alphabetical order by last name, first name:</p> - <xsl:for-each select="doc/name"> - <xsl:sort select="@last"/> - <xsl:sort select="@first"/> + <H1>Names in alphatebical order</H1> + <counter:init name="index" value="1"/> + <xsl:for-each select="doc/name"> + <xsl:sort select="@last"/> + <xsl:sort select="@first"/> <p> <xsl:text>[</xsl:text> - <xsl:value-of select="java:get ($counter-table, 'index')"/> + <xsl:value-of select="counter:read('index')"/> <xsl:text>]. </xsl:text> - <xsl:value-of select="@last"/> + <xsl:value-of select="@last"/> <xsl:text>, </xsl:text> - <xsl:value-of select="@first"/> + <xsl:value-of select="@first"/> </p> - <!-- do following for side-effect --> - <xsl:if test="java:put ($counter-table, 'index', - java:get($counter-table,'index')+1)"/> + <counter:incr name="index"/> </xsl:for-each> </HTML> </xsl:template> -</xsl:stylesheet></source> - -<p>Produces the same results.</p> -</s2> -<s2 title="Example 3: Redirecting transformation output to multiple files"> -<p>For information on using the Redirect extension to send output to mulitple files, see <resource-ref idref="RedirectDoc"/>.</p> +</xsl:stylesheet> +</source> +<p>This stylesheet produces the same output as the preceding example with the Java extension.</p> +</s3> </s2> -</s1> +</s1> \ No newline at end of file
