<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="extensibility" page="functions" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Writing reflexive extension functions in Java</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Writing reflexive extension functions in Java"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Writing reflexive extension functions in Java</h1>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">This section applies to Saxon-PE and Saxon-EE only</div>
<p>Reflexive extension functions written in Java map the namespace of the XPath function name to a
Java fully-qualified class name, and the local name of the function to a Java method or field name.</p>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">Java extension functions can also be used when you are running on the
.NET platform, provided the class implementing the function is a standard class in the OpenJDK class
library (which covers nearly all the classes defined in the JDK). In other cases,
you should 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 CIL:
see <a class="bodylink" href="../extensibility/dotnetextensions.xml">Writing extension functions under .NET</a>
</div>
<p>An extension function is invoked using a name such as <code>prefix:localname()</code>.
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.</p>
<p>There are a number of extension functions supplied with the Saxon product: for details, see
<a class="bodylink" href="../extensions/intro.xml">Extensions</a>. The source code of these methods, which
in most cases is extremely simple, can be used as an example for writing
other user extension functions. It is found in class <code>net.sf.saxon.functions.Extensions</code>.</p>
<p><b>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.</b></p>
<p class="subhead">Identifying the Java Class</p>
<p>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 <code>xmlns:date="java:java.util.Date"</code>).
The class must be on the classpath. </p>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">For compatibility with other products and previous Saxon releases, Saxon <b>at user request</b> 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 <code>xmlns:date="http://www.jclark.com/xt/java/java.util.Date"</code>). The part of
the URI before the final "/" is immaterial.
The format <code>xmlns:date="java.util.Date"</code> is also supported.
To permit this extended syntax for namespaces, you need to set a property on the Configuration:
<code>config.setConfigurationProperty(FeatureKeys.ALLOW_OLD_JAVA_URI_FORMAT, true)</code>. The flag can also
be set in the configuration file.</div>
<p>The Saxon namespace URI <code>http://saxon.sf.net/</code> is recognised as a special case. In most cases it causes the
function to be loaded from the class <code>net.sf.saxon.functions.Extensions</code> but in a few cases,
such as <code>saxon:evaluate</code>, the function is recognized by the compiler as if it were a built-in function.
The various EXSLT namespaces are also recognized specially.</p>
<p>In XSLT, the system function <code>function-available(String name)</code> returns true if there appears
to be a method available with the right name. The function also has an optional second argument to test whether
there is a method with the appropriate
number of arguments. However, it is not possible to test whether the arguments are of appropriate types.
If the function name is "new" it
returns true so long as the class is not an abstract class or interface, and so long as it has at least
one constructor.</p>
<p class="subhead">Identifying the Java constructor, method, or field</p>
<p>The local name used in the XPath function call determines which constructor, method, or field of the Java
class is invoked. 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). </p>
<ul>
<li content="para">
<p>If the local name is <code>new</code>, a constructor is invoked. If several constructors are available,
the one that is chosen is based on the number and types of the supplied arguments.</p>
</li>
<li>
<p>In other cases, the system looks for a matching method or field.</p>
<p>Firstly, the name must match, after converting hyphenated names to camelCase, which is done by removing any
hyphen in the XPath name and forcing the immediately following character to upper case.
For example the XPath function call <code>to-string()</code> matches the Java method
<code>toString()</code>; but the function call can also be written as <code>toString()</code> if you prefer.</p>
<p>Secondly, the number of arguments must match, after taking into account that (a) if the Java method expects
a first argument of class <code>net.sf.saxon.expr.XPathContext</code> then this will be supplied automatically
by the system and does not correspond to any explicit argument in the XPath function call, and (b) when invoking
an instance-level (non-static) method or field, the XPath function call must supply an extra first argument, which
identifies the target object for the invocation.</p>
<p>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.</p>
</li>
<li content="para">
<p>If there are several matching methods, the one that is chosen is determined by comparing
the static types of the supplied arguments with the required types in the method signature. See
<a class="bodylink" href="../extensibility/functions/choosing-overload.xml">Choosing among overloaded methods</a>.</p>
</li>
</ul>
<ul>
<li>
<p><a class="bodylink" href="functions/choosing-overload.xml">Choosing among overloaded methods</a></p>
</li>
<li>
<p><a class="bodylink" href="functions/staticmethods.xml">Calling Static Methods in a Java Class</a></p>
</li>
<li>
<p><a class="bodylink" href="functions/constructors.xml">Calling Java Constructors</a></p>
</li>
<li>
<p><a class="bodylink" href="functions/instance-methods.xml">Calling Java Instance-Level Methods</a></p>
</li>
</ul>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="functions/choosing-overload.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
