Defining the Custom XPath Function

External Java classes are bound by encoding the class name part in the namespace URI. The URI for the namespace identifies the class where the external function will be found. The namespace URI must be java: followed by the fully-qualified class name; for example xmlns:date="java:java.util.Date".

The function name maps onto a static Java method with the same name, and must have the same number of parameters as the number of arguments supplied to the XPath function. The return value from the function can either be a DOM Node (or NodeList) or any other value. If not a DOM Node/NodeList, then the value will be converted to a string before being evaluated as part of the XPath expression.

A simple example is,

<assign>
    <copy xmlns:ext="java:com.example.xpath.Random">
        <from expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0">ext:random()</from>
        <to>$myVariable</to>
    </copy>
</assign>

:::java
package com.example.xpath;

/**
 * Returns a random number
 */
public class Random {
    public static int random() {
        java.util.Random randomizer = new java.util.Random();
        int number = randomizer.nextInt();
        return Math.abs(number);
    }
}

Another example (modified version of the SayHello quickstart) would be,

<assign>
    <copy>
        <from xmlns:echo="java:com.example.xpath.Echo">concat('Value=', echo:returnMe($ReceiveSayHelloVar.parameters/tns:input))</from>
        <to part="parameters" variable="ReplySayHelloVar">
            <query queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath1.0"><![CDATA[tns:result]]></query>
        </to>
    </copy>
</assign>

:::java
package com.example.xpath;

public class Echo {
    public static Object returnMe(Object p1) {
        return(p1);
    }
}

Providing Context

The approach described above allows a static Java method to be invoked without any additional context information other than the arguments supplied by the BPEL process. Occasionally it may be useful for the XPath function to have additional context information.

<assign>
    <copy>
        <from xmlns:echo="java:com.example.xpath.Echo">concat('Value=', echo:returnMe($ReceiveSayHelloVar.parameters/tns:input))</from>
        <to part="parameters" variable="ReplySayHelloVar">
            <query queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath1.0"><![CDATA[tns:result]]></query>
        </to>
    </copy>
</assign>

:::java
package com.example.xpath;

import javax.xml.namespace.QName;

public class Echo {
    public static Object returnMe(QName processName, Object p1) {
        return(p1);
    }
}

Installing the Custom XPath Function

The final step is to include the Java class, implementing the XPath function, in the classpath.

As the BPEL engine is a common resource used by any SwitchYard applications that are installed, the Java class needs to be on the classpath for the engine. So it cannot just be included with the SwitchYard application.

First step is to create an AS7 module containing a jar with the Java class. For example, if the module is "com.example.xpath", then create a folder hierarchy under modules for com/example/xpath/main. In this sub-folder, include a file called module.xml with the following content,

<module xmlns="urn:jboss:module:1.0" name="com.example.xpath">
    <dependencies>
        <module name="javaee.api"/>
    </dependencies>
    <resources>
        <resource-root path="example-xpath.jar"/>
    </resources>
</module>

where the example-xpath.jar would also be placed in this 'main' sub-folder, containing the Java implementation of the XPath function.

Second step is to reference the module from the Switchyard BPEL component. Open the modules/org/switchyard/component/bpel/main/module.xml file, and add the new module as shown:

<module xmlns="urn:jboss:module:1.0" name="org.switchyard.component.bpel">

    <resources>
        .....
    </resources>

    <dependencies>
        <module name="com.example.xpath"/>

        .....

    </dependencies>

</module>