Saxonica.com

Writing extension functions in Java

Extension functions may be implemented in Java.

Java extension functions can be used whether you are running on the Java platform or the .NET platform. In both cases, the class (in the form of Java bytecode) must be on the classpath used for dynamic loading. For use on .NET, it is also possible to compile the Java code into a .NET assembly using the IKVMC compiler, in which case it behaves in the same way as an extension function written in any other .NET language and compiled into MSIL: see Writing extension functions under .NET

An extension function is invoked using a name such as prefix:localname(). The prefix must be the prefix associated with a namespace declaration that is in scope. The namespace URI is used to identify a Java class, and the local name is used to identify a method, field, or constructor within the class.

The command line option -TJ is useful for debugging the loading of Java extensions. It gives detailed information about the methods that are examined for a possible match.

There are various ways a mapping from URIs to Java classes can be established. The simplest is to use a URI that identifies the Java class explicitly. The namespace URI should be "java:" followed by the fully-qualified class name (for example xmlns:date="java:java.util.Date"). The class must be on the classpath.

For compatibility with other products and previous Saxon releases, Saxon also supports certain other formats of URI. The URI may be a string containing a "/", in which the fully-qualified class name appears after the final "/". (for example xmlns:date="http://www.jclark.com/xt/java/java.util.Date"). The part of the URI before the final "/" is immaterial. The format xmlns:date="java.util.Date" is also supported.

The Saxon namespace URI http://saxon.sf.net/ is recognised as a special case. In most cases it causes the function to be loaded from the class net.sf.saxon.functions.Extensions but in a few cases, such as saxon:evaluate, the function is recognized by the compiler as if it were a built-in function. The various EXSLT namespaces are also recognized specially.

In XSLT it is also possible to set up a mapping from a URI to a Java class using a saxon:script declaration in the stylesheet. This declaration can also name a Java archive, which means the class does not have to be on the classpath. The saxon:script mechanism is not widely used and may be withdrawn in a future release.

The rest of this section considers how a Java method, field, or constructor is identified. This decision (called binding) is always made at the time the XPath expression is compiled. (In previous Saxon releases it was sometimes delayed until the actual argument values were known at run-time).

There are three cases to consider: static methods, constructors, and instance-level methods. In addition, a public field in a class is treated as if it were a zero-argument method, so public static fields can be accessed in the same way as public static methods, and public instance-level fields in the same way as instance-level methods.

Next