Calling Non-XSLT Procedures

This last section of the chapter deals with a feature that many EDI translators have: giving the user an option to call their own routines. These are known by various names such as user exits, escape routines, and user functions. In XSLT this feature is referred to as an extension function . The exact method for supporting extension functions isn't standard among all XSLT processors, so you can expect that there are variations. In this section I'll present a simple example of one way it can be done with Xalan, and I'll briefly discuss some approaches for MSXML.

Even when just considering Xalan there are several approaches and variations for supporting extension functions. I present here a fairly simple, basic approach that involves calling a static method in a class that isn't part of a package.

As a sample scenario, let's imagine that we have placed an order and that we want to determine the status of the order. XSLT doesn't know anything about orders or their status, so we'll implement this functionality with an extension function. Our simplified source document looks like this.

Source (Extension.xml)

 <?xml version="1.0" encoding="UTF-8"?> <ExtensionSource>   <Cust>Mike</Cust>   <Bevg>Espresso</Bevg> </ExtensionSource> 

And here's the result we want to produce.

Result (ExtensionResult.xml)

 <?xml version="1.0" encoding="UTF-8"?> <ExtensionResult>   <Customer>Mike</Customer>   <Beverage>Espresso</Beverage>   <OrderStatus>Your espresso is ready, sir.</OrderStatus> </ExtensionResult> 

(May I please have a croissant to go with that?)

The Java method we want to invoke from our stylesheet is getOrderStatus. It resides in a MyExtensions class, as shown here.

MyExtensions Class (MyExtensions.java)

 public class MyExtensions {   public static String getOrderStatus()   {     return "Your espresso is ready, sir.";   } } 

The function returns a Java String object that gets mapped to an XSLT string.

The approach involves three basic steps. We first have to tell Xalan about the extension function. This involves making it part of a specific namespace that Xalan associates with Java. In the stylesheet's root Element we declare the namespace http://xml.apache.org/xslt/java. We assign it a namespace prefix of java, although any syntactically valid prefix would work. Since we've declared this namespace in the stylesheet we'll have to take special action to prevent its declaration from appearing in the result tree. We do this by using the exclude-result-prefixes Attribute discussed earlier in the chapter.

Secondly, we call the function in the appropriate place in the stylesheet. We use it in an XPath expression in the same way that we call a built-in XPath function. In our example we prefix the function name getOrderStatus with the java namespace prefix and the MyExtensions class name . The XPath expression is the value of the select Attribute of an xsl:value-of Element. Through these mechanisms the string returned by the function becomes the content of the Order Status Element.

Finally, when we actually run Xalan, we must be sure that the compiled Java class file (or jar archive if we have it in one) is in our class path .

Here's the stylesheet.

Stylesheet (Extension.xsl)

 <?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0"     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"     xmlns:java="http://xml.apache.org/xslt/java"     exclude-result-prefixes="java">   <xsl:output method="xml" version="1.0" encoding="UTF-8"       indent="yes"/>   <xsl:template match="ExtensionSource">     <ExtensionResult>       <Customer>        <xsl:value-of select="Cust"/>       </Customer>       <Beverage>        <xsl:value-of select="Bevg"/>       </Beverage>       <OrderStatus>        <xsl:value-of             select="java:MyExtensions.getOrderStatus()"/>       </OrderStatus>     </ExtensionResult>   </xsl:template> </xsl:stylesheet> 

The XSLT processor in MSXML 4.0 doesn't support extension functions or elements per se. Support for extensions is provided through embedded script implementations using msxsl:script and external objects using addObject. Consult the MSXML reference for details. If you're using a processor other than Xalan or MSXML's XSLT processor (which msxsl calls), consult its documentation if you want to add your own extensions.