xmlns:xalan="http://xml.apache.org/xalan"

The xalan namespace provides support for the xalan:component element and xalan:script subelement.

The old namespace http://xml.apache.org/xslt is still supported for backward compatibility.

xmlns:prefix=URI

The prefix identifies the namespace, and URI is an arbitrary (but unique) string that matches the value of the prefix attribute of an xalan:component element in the stylesheet.
Example: xmlns:ext1="xyz"

This step is required only if you are using extension elements. If you are using extension functions only, you can skip this step.

In the stylesheet element, write:

extension-element-prefixes="prefix-1 prefix-2 ..."

In a literal result element or extension element include the xsl prefix:

xsl:extension-element-prefixes="prefix1 prefix2 ..."

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.

By default, namespace declarations are included in the transformation output. To exclude namespaces from the output, use

exclude-result-prefixes="prefix-1 prefix-2 ..."

in the stylesheet element or

xsl:exclude-result-prefixes="prefix-1 prefix-2 ..."

in a literal result element or extension element.

In the scope of the xalan namespace declaration:

<xalan:component prefix="prefix"
    functions="func-1 func-2 ...func-n"
    elements="elem-1 elem-2 ...elem-n">
  <!--See xalan:script below-->
</xalan:component>

where func-1 func-2 ... func-n and elem-1 elem-2 ... elem-n 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 xalan:component is actually available.

If the component is implemented in Java, the values of the functions and elements attributes are ignored. The function-available and element-available functions use reflection to examine the actual Java methods.

In each xalan:component, you must include exactly one xalan:script element. If the extension is implemented in JavaScript:

<xalan:script lang="javascript" >
  <!--The implementation script-->
</xalan:script>

For other scripting languages supported by BSF, use the same approach as for JavaScript. The src attribute is also supported in the xalan:script element. If it is present, the script will be loaded from the URL specified in the src attribute. Otherwise the script is taken from the text child of the xalan:script element.

If the extension is implemented in Java, you have three choices for the format of the src attribute in the xalan:script element.

<xalan:script lang="javaclass" src="xalan://FQCN"/>
where FQCN is the fully qualified class name.
Example: <xalan:script lang="javaclass" src="xalan://java.util.Hashtable"/>

<xalan:script lang="javaclass" src="xalan://PJPN"/>
where PJPN is the beginning of or the complete name of a java package.
Example: <xalan:script lang="javaclass" src="java.util"/>

<xalan:script lang="javaclass" src="http://xml.apache.org/xalan/java"/>

The different formats for the value of the src attribute when using Java extensions are more fully explained in Declare the namespace.

For each extension element in a namespace, the implementation must be a Java method with the following signature, or the scripting language equivalent:

Type element(org.apache.xalan.extensions.XSLProcessorContext,
             org.apache.xalan.templates.ElemExtensionCall extensionElement)

where Type designates the return type and element is the local part of the extension element name (the element name without the namespace prefix). In the method signature, you may also use superclasses of the indicated types.

If the extension element is implemented in a loosely typed scripting language, such as JavaScript, the arguments and return value are untyped.

Caution: The value returned by an extension element is placed in the transformation result. If you are not interested in a return value, use a public void Java method or return null from a scripting language function.

Java example: public void myElement
         (org.apache.xalan.extensions.XSLProcessorContext,
          org.apache.xalan.templates.ElemExtensionCall extensionElement)

JavaScript example: function myElement(xslProcContext, element)

The Redirect extension in the extensions library contains three extension elements.

When calling an extension function written in a language other than Java, objects of the following Java classes will always be passed to the extension function:

Any non-XSLT type is passed without conversion.

When calling an extension function written in Java, the extension function signature can specify any of the indicated Java types, as explained below:

When calling extension functions written in Java, Xalan-Java selects the method to call as follows:

1. Xalan-Java selects all methods whose name matches the extension function name as specified in Extension function Java calls.
2. From this list of methods, Xalan-Java determines which methods are qualified.
3. Each qualified method is assigned a score based on the table shown above. To assign the score to a given method, Xalan-Java examines each of the XSLT argument types in the function invocation in the stylesheet. For each argument, the appropriate row in the table above is selected. Then, the corresponding Java parameter type in the method signature in the Java program is scored. Types which appear earlier in the list are given a higher score. That is, the list appears in order of scoring preference from highest to lowest. Types shown in square brackets have equal priority.
4. The method with the highest score is invoked after the arguments are converted to the appropriate type. If more than one method has the highest score, an exception is thrown.

Any extension function written in Java can have a first parameter of type org.apache.xalan.extensions.ExpressionContext. Any method with an ExpressionContext as the first parameter will score higher than any method which does not have an ExpressionContext as a first parameter.

The Xalan-Java extension mechanism examines the class of the value returned from a function and converts the value into an XSLT type according to the following table:

Note that the above test is applied using instanceof so that any subclasses of the classes listed above will be treated the same as the listed superclass. For example, a java.lang.Double will be treated the same as a java.lang.Number and will be converted to an XSLT Number.

The return value conversion can somtimes cause confusion. For example, if your extension function returns an object that is a subclass of NodeIterator, that object will be converted by Xalan-Java to an XSLT Node-Set. If you later attempt to treat that object as a non-XSLT object of your original class and try to invoke a method on that object, your method invocation will fail.

The technique for instantiating Java objects and calling Java methods depends on the format of the extension namespace that was declared. See Declare the namespace for the three different formats of namespace declarations for Java extensions. For each namespace format, the section below describes how to instantiate an object, how to invoke an instance method, and how to invoke a static method. The sections below explain, for each syntax, which methods are qualified for method selection as described in the preceeding section.

Class format namespace

To create an instance of an object: prefix:new (args) where prefix is the extension namespace prefix. A new instance is to be created with the args constructor arguments (if any). All constructor methods are qualified for method selection. Example: <xsl:variable name="myType"        select="my-class:new()"> To invoke an instance method on a specified object: prefix:methodName (object, args) where prefix is the extension namespace prefix and methodName is the name of the method to invoke on object with the args arguments. object must be an object of the class indicated by the namespace declaration. Otherwise, the case shown immediately below will apply. Only instance methods with the name methodName are qualified methods. If a matching method is found, object will be used to identify the object instance and args will be passed to the invoked method. Example: <xsl:variable name="new-pop"      select="my-class:valueOf($myType, string(@population))"> To invoke an instance method on a default object: prefix:methodName (args) where prefix is the extension namespace prefix and methodName is the name of the method to invoke with the args arguments. The first arg, if any, must not be an object of the class indicated by the namespace declaration. Otherwise, the case shown immediately above will apply. Only instance methods with the name methodName are qualified methods. If a matching method is found, a default instance of the class will be created if it does not already exist. Example: <xsl:variable name="new-pop"      select="my-class:valueOf(string(@population))"> To invoke a static method: prefix:methodName (args) where prefix is the extension namespace prefix and methodName is the name of the method to invoke with the args arguments. Only static methods with the name methodName are qualified methods. If a matching method is found, args will be passed to the invoked static method. Example: <xsl:variable name="new-pop"      select="my-class:printit(string(@population))">

Package format namespace

To create an instance of an object: prefix:subpackage.class.new (args) where prefix is the extension namespace prefix, subpackage is the rest of the package name (the beginning of the package name was in the namespace declaration), and class is the name of the class. A new instance is to be created with the args constructor arguments (if any). All constructor methods are qualified for method selection. Example: <xsl:variable name="myType"        select="my-package:extclass.new()"> To invoke an instance method on a specified instance: prefix:methodName (object, args) where prefix is the extension namespace prefix and methodName is the name of the method to invoke on object with the args arguments. Only instance methods of the object with the name methodName are qualified methods. If a matching method is found, object will be used to identify the object instance and args will be passed to the invoked method. Example: <xsl:variable name="new-pop"      select="my-package:valueOf($myType, string(@population))"> To invoke a static method: prefix:subpackage.class.methodName (args) where prefix is the extension namespace prefix, subpackage is the rest of the package name (the beginning of the package name was in the namespace declaration), class is the name of the class, and methodName is the name of the method to invoke with the args arguments. Only static methods with the name methodName are qualified methods. If a matching method is found, args will be passed to the invoked static method. Example: <xsl:variable name="new-pop"      select="my-package:extclass.printit(string(@population))"> Unlike the class format namespace, there is no concept of a default object since the namespace declaration does not identify a unique class.

Java format namespace

To create an instance of an object: prefix:FQCN.new (args) where prefix is the extension namespace prefix for the Java namespace and FQCN is the fully qualified class name of the class whose constructor is to be called. A new instance is to be created with the args constructor arguments (if any). All constructor methods are qualified for method selection. Example: <xsl:variable name="myHash"        select="java:java.util.Hashtable.new()"> To invoke an instance method on a specified instance: prefix:methodName (object, args) where prefix is the extension namespace prefix and methodName is the name of the method to invoke on object with the args arguments. Only instance methods of the object with the name methodName are qualified methods. If a matching method is found, object will be used to identify the object instance and args will be passed to the invoked method. Example: <xsl:variable name="new-pop"      select="java:put($myHash, string(@region), $newpop)"> To invoke a static method: prefix:FQCN.methodName (args) where prefix is the extension namespace prefix, FQCN is the fully qualified class name of the class whose static method is to be called, and methodName is the name of the method to invoke with the args arguments. Only static methods with the name methodName are qualified methods. If a matching method is found, args will be passed to the invoked static method. Example: <xsl:variable name="new-pop"      select="java:java.lang.Integer.valueOf(string(@population))"> Unlike the class format namespace, there is no concept of a default object since the namespace declaration does not identify a unique class.

Please keep in mind that all 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 (as in the syntax examples above) to convert a node-set value to string, and the number() function to convert a node-set value to number (a double).

If you want to pass a node-set to an extension function, set up a Java method to accept an org.w3c.dom.NodeList (or an org.apache.xpath.NodeSet, which implements NodeList, if you want to modify the nodes).

Suppose, for example, you have a myExtensions.ProcessNodes class with the following doSomething method:

public static boolean doSomething(org.w3c.dom.NodeList nList)

Assuming you set up this extension in the node-ext namespace, any of the following extension calls from a stylesheet are syntactically possible:

<!--Process the current node-->
<xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(.)"/>

<!--Process all nodes in current context-->
<xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(*)"/>

<!-- Process all nodes -->
<xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(/*)"/>

<!--Process the foo/baz nodes in current context -->
<xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(foo/baz)"/>

<!--Process the/foo/baz and /bar/saz nodes -->
<xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(/foo/baz | /bar/saz)"/>

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.

For each extension function in a namespace which is implemented in a language other than Java, the implementation must include a method with the following signature, or the scripting language equivalent:

public object function(args)

where object is the return type, function is the local part of the extension function name (the function name without the namespace prefix), and args correspond to the arguments in the function call.

In addition, for extension functions implemented in Java, the implementation may include either a Java method with the signature shown above or one with the following signature:

public object function(org.apache.xalan.extensions.ExpressionContext, args)

Declare the namespace for your extensions using one of the following three formats. The technique for invoking an extension for each format is explained in Extension function Java calls.

class format: xmlns:my-class="xalan://FQCN"

where FQCN is the fully qualified class name.
Examples: xmlns:my-class="xalan://java.util.Hashtable"
                xmlns:my-class="xalan://mypackage.myclass"

package format: xmlns:my-class="xalan://PJPN"

where PJPN is a partial java package name. That is, it is the beginning of or the complete name of a java package.
Examples: xmlns:my-package="xalan://java.util"
                xmlns:my-package="xalan://mypackage"

Java format: xmlns:java="http://xml.apache.org/xalan/java"

The old namespace http://xml.apache.org/xslt/java is still supported for backward compatibility.

Although the namespace declarations for the class and package formats are shown with the xalan:// prefix, the current implementation for those formats will simply use the string to the right of the rightmost forward slash as the Java class name. This format, however, is the preferred format for extension namespace declarations.

The class: prefix which was sometimes required in earlier versions of Xalan-Java is no longer required.

These formats are also available when coding the src attribute of the xalan:script element as explained in Set up the xalan:script element.

Use the declared prefix with the syntax described in Extension function Java calls.

That is all. You do not include an xalan:component element. Using the abbreviated syntax clearly involves less setup than using the xalan:component/xalan:script approach.

We recommend that, for extensions coded in Java, the abbreviated syntax should always be used since the xalan:component/xalan:script constructs add no functionality.

The abbreviated syntax is supported in XSLTC, but the xalan:component/xalan:script constructs are not.

This example uses extension functions to call the SimpleDateFormat class and the IntDate class. IntDate uses String arguments to set up a Date object:

	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(); // Convert each argument to int. c.set ( Integer.parseInt(year), Integer.parseInt(month), Integer.parseInt(day) ); return c.getTime(); } }

The template transforms date elements with four attributes. For example, it transforms <date format="EEEE, MMM dd, yyyy" year="2000" month="4" day="27"/> into <p>Date: Thursday, April 27, 2000.</p>.

As you review this stylesheet, please keep the following in mind:

• The exclude-result-prefixes stylesheet attribute prevents the java namespace declaration from appearing in the output.
• 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 values from node-sets to strings.
• The format attribute provides a String argument for constructing a java.text.SimpleDateFormat object.
• 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.
• 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 Extension function Java calls.

	<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:java="http://xml.apache.org/xalan/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)"/> <xsl:variable name="date" select="java:IntDate.getDate($year, $month, $day)"/> <p>Date: <xsl:value-of select="java:format($formatter, $date)"/></p> </xsl:template> </xsl:stylesheet>

MyCounter.java

	Import java.util.*; public class MyCounter { Hashtable counters = new Hashtable (); public MyCounter () {} public void init ( org.apache.xalan.extensions.XSLProcessorContext context, org.apache.xalan.templates.ElemExtensionCall extElem ) { String name = extElem.getAttribute("name"); String value = extElem.getAttribute("value"); int val; try { val = Integer.parseInt (value); } catch (NumberFormatException e) { e.printStackTrace (); val = 0; } counters.put (name, new Integer (val)); } public int read(String name) { Integer cval = (Integer) counters.get (name); return (cval == null) ? 0 : cval.intValue (); } public void incr ( org.apache.xalan.extensions.XSLProcessorContext context, org.apache.xalan.templates.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)); } }

An XML source document:

	<?xml version="1.0"?> <doc> <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>

The stylesheet:

	<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xalan="http://xml.apache.org/xalan" xmlns:counter="MyCounter" extension-element-prefixes="counter" version="1.0"> <xalan:component prefix="counter" elements="init incr" functions="read"> <xalan:script lang="javaclass" src="xalan://MyCounter"/> </xalan:component> <xsl:template match="/"> <HTML> <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:text>]. </xsl:text> <xsl:value-of select="@last"/> <xsl:text>, </xsl:text> <xsl:value-of select="@first"/> </p> <counter:incr name="index"/> </xsl:for-each> </HTML> </xsl:template> </xsl:stylesheet>

Transformation output:

	<HTML> <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>

	<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xalan="http://xml.apache.org/xalan" xmlns:counter="MyCounter" extension-element-prefixes="counter" version="1.0"> <xalan:component prefix="counter" elements="init incr" functions="read"> <xalan: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; } function read (name) { // Return a string. return "" + (counters[name]); } function incr (xslproc, elem) { name = elem.getAttribute ("name"); counters[name]++; return null; } </xalan:script> </xalan:component> <xsl:template match="/"> <HTML> <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="counter:read('index')"/> <xsl:text>]. </xsl:text> <xsl:value-of select="@last"/> <xsl:text>, </xsl:text> <xsl:value-of select="@first"/> </p> <counter:incr name="index"/> </xsl:for-each> </HTML> </xsl:template> </xsl:stylesheet>

This stylesheet produces the same output as the preceding example with the Java extension.