XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (62 page)

The language specification says nothing about how extension functions are written, and how they are linked to the stylesheet. The notes that follow are provided to give an indication of the kind of techniques you are likely to encounter.

In the case of Java, several processors have provided a mechanism in which the name of the Java class is contained in the namespace URI of the function, while the name of the method is represented by the local name. This mechanism means that all the information needed to identify and call the function is contained within the function name itself. For example, if you want to call the Java method
random()
in class
java.lang.Math
to obtain a random number between 0.0 and 1.0, you can write:

Unfortunately, each processor has slightly different rules for forming the namespace URI, as well as different rules for converting function arguments and results between Java classes and the XPath type system, so it won't always be possible to make such calls portable between XSLT processors. But the example above works with both Saxon and Xalan.

This example calls a static method in Java, but most products also allow you to call Java constructors to return object instances, and then to call instance methods on those objects. To make this possible, the processor needs to extend the XPath type system to allow expressions to return values that are essentially wrappers around external Java objects. The XSLT and XPath specifications are written to explicitly permit this, though the details are left to the implementation.

For example, suppose you want to monitor the amount of free memory that is available, perhaps to diagnose an “out of memory” error in a stylesheet. You could do this by writing:

Again, this example is written to work with both Saxon and Xalan.

There are two extension function calls here: the call on
getRuntime()
calls a static method in the class
java.lang.Runtime
, which returns an instance of this class. The call on
freeMemory()
is an instance method in this class. By convention, instance methods are called by supplying the target instance as an extra first parameter in the call.

Another technique that's used for linking an extension function is to use a declaration in the stylesheet. Microsoft's processors use this approach to bind JavaScript functions. Here is an example of a simple extension function implemented using this mechanism with Microsoft's MSXML3/4 processor and an expression that calls it.

This is not a particularly well-chosen example, because it could easily be coded in XSLT, and it's generally a good idea to stick to XSLT code unless there is a very good reason not to; but it illustrates how it's done.

Sometimes you need to change configuration files or environment variables, or call special methods in the processor's API to make extension functions available; this is particularly true of products written in C or C++, which are less well suited to dynamic loading and linking.

In XSLT 2.0 (this is a change from XSLT 1.0), it is a static error if the stylesheet contains a call on a function that the compiler cannot locate. If you want to write code that is portable across processors offering different extension functions, you should therefore use the new
use-when
attribute to ensure that code containing such calls is not compiled unless the function is available. You can test whether a particular extension function is available by using the
function-available()
function. For example:

Extension functions, because they are written in general-purpose programming languages, can have side effects. For example, they can write to databases, they can ask the user for input, or they can maintain counters. At one time Xalan provided a sample application to implement a counter using extension functions, effectively circumventing the restriction that XSLT variables cannot be modified in situ. Even the simple
Math:random()
function introduced earlier has side effects, because it returns different results each time it is called. However, extension functions with side effects should be used with great care, because the XSLT specification doesn't say what order things are supposed to happen in. For example, it doesn't say whether a variable is evaluated when its declaration is first encountered, or when its value is first used. The more advanced XSLT processors adopt a lazy evaluation strategy in which (for example) variables are not evaluated until they are used. If extension functions with side effects are used to evaluate such variables, the results can be very surprising, because the order in which the extension functions are called becomes quite unpredictable. For example, if one function writes to a log file and another closes this file, you could find that the log file is closed before it is written to. In fact, if a variable is never used, the extension function contained in its definition might not be evaluated at all.

Before writing an extension function, there are a number of alternatives you should consider:

• Can the function be written in XSLT, using an
  
  element?
  
• Is it possible to supply the required information as a stylesheet parameter? Generally this provides a cleaner and more portable solution.
  
• Is it possible to get the result by calling the
  document()
  function, with a suitable URI? The URI passed to the
  document()
  function does not have to identify a static file; it could also invoke a web service. The Java JAXP API allows you to write a
  URIResolver
  class that intercepts the call on the
  document()
  function, so the
  URIResolver
  can return the results directly without needing to access any external resources. The
  System.Xml
  namespace in the Microsoft .NET framework has a similar capability, referred to as an
  XmlResolver
  .
  

Extension Instructions

An extension instruction is an element occurring within a sequence constructor that belongs to a namespace designated as an extension namespace. A namespace is designated as an extension namespace by including its namespace prefix in the
extension-element-prefixes
attribute of the

element, or in the
xsl:extension-element-prefixes
attribute of the element itself, or of a containing extension element or literal result element. For example, Saxon provides an extension instruction

to perform looping while a condition remains true. There is no standard XSLT construct for this because without side effects, a condition once true can never become false. But when used in conjunction with extension functions,

can be a useful addition.