18 May 2010

Sorting data using xsl:sort

In SOA 11g, there is a new XSL-Construct for sorting the input nodes. This is a basic XSLT construct (element) which was missing earlier.
As the w3 standard defines, this construct cannot be used independently, but can be used along with xsl:for-each(or xsl:apply-templates)
It is used to sort the input data based upon some id or text(called as sort-key).
This can be very useful functionality in scenarios where one needs to process some data in a specific sequence.

To use this construct inside a transform activity, add a for-each construct first. Do the required mapping.
Then right-click the for-each and select sort




A dialogue box will open. Add the details like sort-order, data-type for sorting. Click OK.




The construct still shows a big red balloon. To complete the things, just map the appropriate source element to this construct.
Note that one sort construct adds only one parameter. To have sort on basis of more than one parameter, additional sort constructs need to be added.
The source code will show entry of the sort similar to :

<xsl:sort select="tns:age" order="descending" data-type="number"/>

Test and verify.  In the example below, I have added two sort statements first for age (descending) and then for id (ascending) :





Note that xsl:sort supports 5 attributes which are :
1. select : Specifies the string which can be used as sort-key
2. lang : Specifies the language for the sort key
3. data-key : Specifies the data type to be used while sorting. Possible values are text, number or a qualified name (either a prefixed name or unprefixed name)
4. order : Specifies the order of sorting. Possible values are ascending, descending
5. case-order : Used in case of data-key="text". Possible values are lower-first or upper-first

Changing password for a user

To change password for a user in Oracle Weblogic server :
1. Login to Weblogic administration console (http://<hostname>:<port>/console)
2. Navigate to Security Realms. Select the default realm. This will be myRealm unless there are more than one realms created.
3. In the Settings page, go to Users and Groups > Users
4. Select the user for which you want to change the password.
5. Go to passwords tab. Type new password, confirm it and save.

14 May 2010

Using Custom XPATH Functions


Custom XPath functions provide a great way of handling functionality which cannot be performed using standard set of available functions. Oracle SOA suite comes with many functions which include standard XPath functions as well as SOA and BPEL XPath extension functions. However, many times a situation comes where we wish that so and so function was available.
In such case, arguably custom XPath is the best way to deal with.

In the following steps, a very simple example is taken and implemented as custom XPath function which can be used inside BPEL processes  in a typical Oracle SOA Composite.

Example Discussed : A  function getSum which takes input two numbers are returns their sum.

Main steps are : 
1) Implementing the function logic ( using java.class )
2) Creating a jar file which contains the class and configuration details.
3) Associating the created function with JDeveloper.
4) Associating the function with SOA Suite.

Implementing the function logic

1) Oracle provide a interface "oracle.fabric.common.xml.xpath.IXPathFunction" which can be implemented to create custom classes
This is present in a jar file named "fabric-runtime.jar" which can be found at any of following locations:
<MIDDLEWARE_HOME>\jdeveloper\soa\modules\oracle.soa.fabric_11.1.1
<MIDDLEWARE_HOME>\Oracle_SOA1\soa\modules\oracle.soa.fabric_11.1.1

The logic for the function is incorporated in a java class by implementing this interface.

So in Jdeveloper, create a empty(generic) project. Go to project properties and in "Libraries and Classpath" add this jar file by clicking "Add Jar/Library"



 2) Create a new java class file in the project with name as getSum and package as my.custom.
Also select main method which we would use to test the class.


3) In the java class, implement the IXPathFunction interface and the method Call as shown below.
Also add the code in the main method for testing :





4) Test the code and make sure it works fine.

Creating jar file :

1) On your desktop (anywhere) create a new folder and inside this create a folder called code. In this folder create two folders src and META-INF
2) In src folder , copy the java file with correct package. In META-INF , we put the configuration file.
 A configuration file is the one which actually associates the Java class with the JDeveloper as well  as SOA Suite. Based upon the type of component, the name of the file differs.
For implementation in BPEL, name is ext-bpel-xpath-functions-config.xml (note that for XSLT also name if different)
3) Create a configuration file in META-INF folder with name as ext-bpel-xpath-functions-config.xml. Add following to file:




4) In the main folder, where have two folders - src and META-INF , create a build file (build.xml) which will have tasks for compiling the java code and creating a jar file
The jar file must have the META-INF folder in it along with the class files. A sample build file which I used is shown below:


 5) Run ant and create the Jar file.

 Associating the created function with JDeveloper :

1) Place the jar file at some standard place on your machine.
2) In JDeveloper, open Tools > Preferences and go to SOA. Add the jar file.


3) Restart the JDeveloper.
4) Create a new SOA project with BPEL , add assign activity.
In the assign activity, create a copy operation and select Expression on input side. In expression builder select "User Defined Extension Functions".The function will appear like this :


5) Function has signature mf:myFunction1() and can be used like: mf:myFunction1("10","20" )  (Note the double quotes around the  numbers)
6) Use the function , save and compile the project. While saving, it might show blue line below the function signature, ignore it.

Associating the function with SOA Suite :

1. Go to the location <MIDDLEWARE_HOME>\user_projects\domains\<DOMAIN_NAME>\lib and put the jar file here.
2. Restart the server. On restarting the Weblogic server, the command prompt log will show a message that the jar file is picked up.
3. Deploy the project in JDeveloper and Test.



About the configuration file :

As described above,for using custom XPath functions, we need to have a configuration file. The details about this file can be found in Developer's Guide for SOA suite.
However, for sake of  completeness of article, the points are discussed in brief :
1. This file is a XML file and needs to be placed in a folder named META-INF immediately inside the jar file.
2. Name of the file depends on the the usage as below : (Reference : Table B2 in Developer's Guide)

Name of the component Name of  config file
BPEL Process  ext-bpel-xpath-functions-config.xml
Mediator  ext-mediator-xpath-functions-config.xml
Transformations  ext-mapper-xpath-functions-config.xml
Human workflow  ext-wf-xpath-functions-config.xml
Generic (All compoents)  ext-soa-xpath-functions-config.xml


3. The file must follow the  schema given in the Developer's guide.

4. Following are the main elements in the file: (Reference : Table B1 in Developer's Guide)

Element Description
className Name of the main class which implements the function logic
return Return type. Possible values are string, number, boolean, node-set, tree.
params list of input arguments for function. There is one line per argument . Each parameter specifies the details like name, type using attributes


A POC for the above example be downloaded from here.

03 May 2010

Adding preference properties in 11g

The main question to ask here is how to get and set the preference properies..?

Well, in SOA 10g versions , this was hardly a question. This was very simple and straightforward in 10g.
In 11g with weblogic server at core,  this is still simple, but not so straightforward.

Getting value of a preference property :

1. Create a composite with BPEL.

2. Go to composite.xml file.
Add a property with name as bpel.preference.myprop1 to the BPEL component definition and set value as 100


Note : The preference properties should always start with prefixes 'bpel' and 'preference' .
So name for a property ABC will actually be  bpel.preference.ABC


3. In the BPEL process, add a Assign activity and use the standard ora:getPreference function as in 10g
Assign activity code looks like this :



Note that even though the preference property name is bpel.preference.myprop1 , it is accessed using
ora:getPreference('myprop1'). Also remember to put single quotes as the funciton ora:getPreference expects a String input.


4. Deploy and run the composite. Instance will show that output variable has value as 100.

Setting value of a preference property :

1. Go to enterprise manager. Navigate to 'System MBean Browser' by right-clicking soa-infra > Administration > System MBean Browser

 
Note that this is for 11.1.1.1 . For R1 PS-1 or R1 PS-2 , this might be different

2. In 'System MBean Browser' page, search for a MBean with name "oracle.soa.config" and select the first search.Alternately, go to 'Configuration MBeans' > 'Application Defined MBeans' > 'oracle.soa.config'
Inside this Managed Bean, go to 'Server:soa_server1' > SCAComposite > Composite Name > 'SCAComposite.SCAComponent' > BPEL process name.
(BPELProcess1 in this example)



3.  MBeans are Java objects which  provide a way of managing resources. Each system MBeans's interface has 3 facades - Attributes for setting properties , Operations for methods that can be invoked on that MBean and  Notifications that can be used to send event alerts. Out of these the attributes  contain the preference properties.
 Click the property attribute to open the properties for this BPEL. On this page, preference property 'myprop1' will be visible.



4. Update the property to new value. Click 'Apply' and then 'Return' to go back to the attributes page.
New properties can also be added but keep in mind the naming standard.

5. After updating the property, go back to composite and test the process to verify the new value.
 
POC for the same can be downloaded from here.

Reading a properties file in BPEL

To read a properties file from BPEL, we can use Java Embedding.
In the java activity, we can read the property and assign the values to BPEL variables using 'setVariableData' function.

Lets have a simple POC to do the same :
1. Create a properties file say "TestProp.properties" and add some properties.


2. Create a simple composite with Async BPEL process and add a Java-embedding activity after Receive activity.

3. Open the Java embedding activity and add following code :



Note that the location for file is set in the first line.

4. Save and close the activity. Open the BPEL source and go to line where the Java embedding is present.
Add following Java import statements  before the code for java embedding activity.


<bpelx:exec import="java.io.*"/>
<bpelx:exec import="java.util.*"/>


After adding this , the code snippet looks like this :






5. Save, Deploy, Test.
Make sure that properties file is present and it actually contains the property 'myName'
Otherwise one needs to change the code a bit  to handle these scenarios. (Simply add a check to see if value is null)

Sample code for this POC can be downloaded from here .