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.
Read more...

JAX-WS & JAXB rock and roll...

During his Wednesday keynote at the JavaOne conference last week, Oracle Senior Vice President Thomas Kurian unveiled the next-generation architecture for Oracle Fusion Middleware. The 11g Technology Preview of JDeveloper and OC4J are currently available. Also available are some nifty tutorials and demos like Web Services Development in Oracle JDeveloper which shows off some great JEE 5 features like JAX-WS and JAXB 2.0. Although the latter is not really focused on much in the tutorial, it is the basis of what gets your java objects to and from XML.

What these two standards bring to the table from a web service development point of view is a more lightweight POJO oriented way of developing services. They will not make for better SOA in the enterprise though. In fact, they may even make things worse since a poorly designed interface can easily get a false SOA badge of credibility amongs the uninitiated by being exposed as a web service. Enough with the rant already, on with the example...

I thought it would be interesting to expand upon the bottom up HelloService tutorial by making things a bit more complicated with some old world technology: Dice. The Dice class in this example has a roll(List) operation that rolls the dice (plural of die) passed to it and returns the result. So there are really only two classes in this example:

• Die represents (you guessed it) a die. It has two properties, number of sides and value.
• Dice provides the collective operation of rolling dice.

This is the Die source:

package soastation.jaxwsdice;

public class Die {
protected int numberOfSides;
protected int value;
public Die() {
this(6); //Default number of sides is Six;
}
public Die(int sides) {
if (sides < 2)
throw new throw new IllegalArgumentException();
this.numberOfSides = sides;
}
public int getNumberOfSides() {
return numberOfSides;
}

public int getValue() {
return value;
}

public void roll() {
int rollValue = (int) (this.getNumberOfSides() * Math.random()) + 1;
if (rollValue > this.getNumberOfSides())
rollValue -= 1;
this.value = rollValue;
}
}

Note that the number of sides property is immutable and the value defaults to zero until the die is first rolled. It would seem natural to extend something like Integer to hold the 'value'. This can't be done in Java as these classes (Number, Integer, BigInteger, etc) are immutable so changing the value on every roll is not a runner. Besides, Integer is final so can't be extended anyway.

You'll probably also note the lack of comments on the code too. Tell me if you are for or against comments in code!

Here is the Dice source:

package soastation.jaxwsdice;

import java.util.Iterator;
import java.util.List;

public class Dice {

public List roll(List dice) {
Iterator diceIterator = dice.iterator();
while (diceIterator.hasNext()) {
Die die = diceIterator.next();
die.roll();
}
return dice;
}
}

The rest of the steps are identical to the HelloService example (which you can also get to from the Build Web Service link on the Start page of the JDeveloper 11 Technology Preview ).

1. Add an @WebService annotation to the Dice class
2. In the code fix menu select Configure project for web services
3. Choose the Java EE 1.5 option and press OK
4. Add an @WebMethod annotation to the roll method
5. Right click on Dice service (note that the icon has changed) and select Test Web Service
6. Gaze in awe at the handy HTTP Analyzer with Web Service support. That's all you can do at this stage because JAX-WS doesn't know what to do with the Die class.
   

This is where JAXB really comes into play. We want the properties of the Die object to be properly represented in the web service. Lets make the number of sides an attribute and the value of the Die appear as the value of the element. Do this by:

1. Add @XmlAttribute(name="sides") to the numberOfSides field.
2. Add @XmlValue to the value field.

Now you can test the web service again by right clicking on the Dice service in the Applications Navigator and selecting Test Web Service. In the HTTP Analyzer window you can enter the details of each die you want to roll. By clicking on the plus sign you can add more die to the SOAP request. The value attribute is in the schema but has no relavance to the operation (unless you want to implement a LoadedDie object?). Actually, you could leave the number of sides blank too as it will default to 6.

This example takes advantage of convention over configuration features of JEE 5. The property inspector in JDeveloper 11g Technology Preview provides some great tooling around the annotations. It is worth playing with it to see the extent of configuration possible.

We can improve the WSDL and XML representations with annotations. In the Dice class add a @WebResult(name="die") annotation to the roll method so that the result is not called 'result' by default. Also, in the roll method arguments add @WebParam(name="die") annotation so that the die element does not get call 'arg0' by default.

These JAX-WS and JAXB annotations make the web service and XML representation of the java operation and classes much more suitable. Of course these simple examples only scratch the surface of what can be achieved. It is a good idea to get familiar with capabilities of both technologies.

Let me know how you get on.
Read more...