Custom XSLT functions in Oracle BPEL and ESB

In the Oracle SOA Suite there is a Custom XSLT function example. You can find it in bpel/samples/demos/XSLMapper/ExtensionFunctions. It is not immediately obvious that this approach of enabling access to static methods on a java class works for transformations in the ESB too. This is because both BPEL and ESB use the same Oracle XSLT processor.

The principle is simple:

• Write a class with a static method to implement the logic you want.
• Use the namespace http://www.oracle.com/XSL/Transform/java/{$classname$} in your XSLT as the namespace prefix.

To illustrate how straight forward this is I'll go through an example that converts HEX to Decimal. So, with a class called xsltfunctions.HEX2DEC the namespace is defined in an XSL file as xmlns:sample = "http://www.oracle.com/XSL/Transform/java/xsltfunctions.HEX2DEC".

The class HEX2DEC has static method called toDecimal:

public static String toDecimal(String hex) {
     String dec = new BigInteger(hex, 16).toString(10);
     return dec;            
}

In the XSL file this method is invoked like this:

<xsl:value-of select="sample:toDecimal('8D56B')" />

Note that the namespace prefix 'sample' is defined as mentioned earlier using the http://www.oracle.com/XSL/Transform/java/ combined with the classname.

So, you could compile the HEX2DEC class, add it to a jar and put that jar in /j2ee/home/applib so that any transform using the custom function in BPEL or ESB will work. It's that simple.

All that's left is to inform JDeveloper of your custom function so that you can easily refer to it in the XSL Mapper to do this you need to do two things:

1. Create an XML file detailing the extension functions you have and tell JDeveloper about it in the "User Defined Extension Functions Config File" field of the XSL Map preferences (Tools->Preferences->XSL Map). This will list the functions in the User Defined Extension Functions section of the XSL Map component palette so you can drag and drop it into the XSLT at design time.
2. Add the class to the JDeveloper classpath so that you can run the transform using the test feature with JDeveloper.

The extension functions XML looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<extension-functions>
<functions xmlns:sample = "http://www.oracle.com/XSL/Transform/java/xsltfunctions.HEX2DEC">

<!-- converts a hex string to a decimal string -->
<function name="sample:toDecimal" as="string">
<param name="hex" as="string"/>
</function>

</functions>
</extension-functions>

To add the class to the JDeveloper classpath involves defining a JDeveloper extension. For JDeveloper 10.1.3.2 the extension needs to be a valid JSR 198 extension. Documentation on this can be found in /doc/extension/ide-extension-packaging.html.

Do this by defining a simple 'extension.xml' like this:
<?xml version="1.0" encoding="UTF-8" ?>
<extension version="1.0" esdk-version="1.0" id="xstlfunctions"
xmlns="http://jcp.org/jsr/198/extension-manifest">
<name>SOAStationXSLTFunctions</name>
<owner>Peter O'Brien</owner>
</extension>

The extension.xml (naming convention for these files) needs to be in the meta-inf folder of the jar containing the classes. The filename for the jar needs to be a combination of the extention id and esdk-version so in this case it would be xsltfunctions.1.0.jar. This jar should then be copied into the /extension directory.

Restart JDeveloper to pick up the changes for both the 'User Defined Extension Functions Config File' and the JDeveloper extension and you're ready to go.