Downloading the SOA Design Time for JDeveloper 11G

Oracle Fusion Middleware 11G Release 1 was officially launched by Oracle on the 1st July 2009; included in this release are the 11G version of WebLogic, SOA Suite, WebCenter and Identity Management. You can download all of the required components from http://www.oracle.com/technology/software/products/middleware/index.html.

Installing the Oracle SOA Suite is pretty straight forward; however the one gotcha is the install of JDeveloper 11G does NOT install the SOA Design Time. This is not really an issue as JDeveloper automatically checks for updates (including the SOA Design Time) and will prompt you to download and install them (alternatively select Help->Check for Updates).

However the SOA Design Time is 200+ MB in size. So not a trivial download, particularly if you are installing JDeveloper in multiple environments. Ideally it would be nice to be able to download a local copy of the SOA Design time extension which can then be installed in each environment that is required. Well fortunately you can do this by going to the Oracle JDeveloper product updated center shown below. From here click on the download link for the SOA Oracle Composite Editor (circled below).



To install the design time, within JDeveloper select Help->Check for Updates. Click Next and Select Install from Local File and browse to where you saved soa-jdev-extension.zip. Click Open, click Next and then Finish. JDeveloper will then install the extension; finally restart JDeveloper when prompted.

Arch2Arch Podcasts

The Oracle Technology Network Arch2Arch Podcast brings together architects and other experts from across the Oracle community and beyond to discuss the issues, tools, and technologies that are a daily part of the software architect's ever-changing world. I've always enjoyed these podcasts and find them an extremely useful and convenient source of information.

Their latest podcast, is part one of a two part interview by Bob Rhubart (the host of Arch2Arch) with Antony Reynolds and myself about our book the Oracle SOA Suite Developer's Guide. The interview is truly international with Bob carrying out the interview based in California, Antony in the UK and myself from a hotel room in Sydney, Australia (about 8am in the morning).

It's quite strange hearing yourself speak, but what struck me is how English Antony sounded! Have a listen and see what you think (and whether I’ve picked up an Aussie twang) and whilst you’re their check out some of the other excellent podcasts as well.

Top 5 Insights for Maximizing Returns with SOA

Oracle are hosting a live webcast on some of the key insights gained by customers who have successfully implemented SOA based solutions within their organization.

They will be covering areas such as; building a business case for SOA, strategies for adopting SOA, critical success factors as well as some of the efficiency drivers and cost savings achieved through the deployment of SOA based solutions.

Participating executives include:

• Job Simon, Senior Director, NetApp
• Dan Goerdt, Director, Schneider National Inc.
• Jennifer Briscoe, CTO and VP, Collect America

This is an excellent opportunity to gain some valuable insights into how you can leverage SOA within your own organization.

The webcast is scheduled for April 23 8:00 a.m. PT / 11:00 am ET / 4.00 pm GMT. To register click here.

Writing a 'Singleton' BPEL Process

A typical use case in BPEL is connecting to an external resource / system which only support a single connection at a time. In such a case we need to protect against parallel BPEL instances submitting concurrent requests to that resource.

This implies that we need some way to serialize requests for that resource (probably on a first in first out basis). A common design pattern for achieving this is the Singleton, first documented in the Gang of Four's patterns book (where they use a print spooler as an example).

Now BPEL doesn’t explicitly support the notion of a Singleton, however it does allow you to simulate one, which for the purpose of what we are trying to achieve is good enough.

The basic idea is to have an explicit initiateSingleton operation which is used to instantiate a single process instance, and then have a separate invokeSingleton operation which is used to submit each actual request. The invoke operation is then placed in a loop, so as soon as it’s processed one request it loops back round for the next one.

For this example, I’ve just created a simple process which keeps track of the number of times it’s been called. It takes a single parameter, name and returns a string of the following format:

Hello <name>. You are caller number <count> of this singleton.

Pretty simple, but it illustrates the point. The basic process is shown in the screenshot below:

The first activity in the process is a receive activity, InitiateSingleton, which is used to instantiate the process. We then have a simple assign which just sets the count to zero. The remainder of the process, which handles the invokeSingleton operation is contained within the ProcessRequest scope, which itself is placed inside a while loop, that loops for ever. This contains the following activities:

1. InvokeSingleton – This receives the next request to be processed by the singleton.
2. Wait – This waits for a period of 5 seconds. It is just to simulate going out to an external system. It also enables us to see how multiple requests for the singleton are queued up by the Oracle BPEL PM Server.
3. SetResult – Here we just set the result and increment the count by one.
4. CallbackClient – Finally we just send back the result to the client; before looping back round to process the next request.

Message Correlation

At first glance this all looks deceptively simple, however the complexity comes when you try and call the invokeSingleton operation.

The reason is that when we invoke an operation on a BPEL Process, the message is received by the Oracle BPEL PM Message Handler, depending on the operation it will either invoke a new process to handle it (as with the initiateSingleton operation) or route it through to the appropriate instance of an already running process.

This is where it gets a bit convoluted, when we receive the message for the invokeSingleton operation, even though we only have a single instance of the BPEL process running how does BPEL PM know that it is the correct instance to route the message to? The answer is it doesn’t.

Now under “normal” circumstances, where we have an asynchronous interaction between two processes, Oracle BPEL PM defaults to using WS-Addressing to ensure that messages are successfully routed between two process instances. However in these cases, it’s typical that the interaction between the two processes (say A and B) began by process A initiating process B and passing it details (using WS-Addressing) about itself so that when process B sends back a response it contains sufficient information for it to be routed to the appropriate instance of process A.

However with our Singleton process, any process calling the invokeSingleton operation will have no prior knowledge of that process, so for our purposes we can’t use WS-Addressing to correlate the message.

Fortunately for situations where WS-Addressing isn’t appropriate or available BPEL provides the concept of correlation sets. Essentially correlation sets allow you to use a unique value present in the message body of all exchanged messages (e.g. orderId) to link that exchange of related messages together.

You do this in BPEL by first defining a property which corresponds to the unique value, and then defining a property alias for each message in the exchange, that defines where that property is located within the message. Next you define a correlation set which can consist of one or more properties (see the product documentation or the Oracle SOA Suite Developer's Guide for more details on how to create Correlation Sets).

For our purpose, I’ve defined a simple element called singletonId which is contained in both the initiateSingleton and invokeSingleton operations.

Next we have defined a correlation set SingletonCS which is used in the InitiateSingleton and InvokeSingelton operations.

On the initiateSingleton operation I’ve defined this to initiate the correlation set (see screenshot below), this means whatever value is contained with the singletonId in the start operation must be present in the invokeSingleton operation for it to be routed through to this process instance.

The next part of the problem is to return the response back to the appropriate caller of the process. This at first may seem strange, but recall we may have several processes calling the singleton at the same time, and thus all waiting for a response. We need to ensure that each response is returned to the appropriate instance.

Now you’ve probably already guessed that we need to use correlation sets again (as we have disabled WS-Addressing for this Partner Link). This time the calling process will need to generate a unique key that it passes in the request (requestId) to the singleton. The singleton will then return this in the response to the requester.

If we look at the SingeltonAccessor process, we use the XPath operator generateGUID to generate this value.

Specifying the Reply to Address

So now everything looks fine, so we can go ahead and run the process; well not quite! If you do you will notice that request from the SingeltonAccessor successfully reaches our Singleton process. But for some reason the response from the Singleton never reaches the SingeltonAccessor, in fact if you take a closer examination of the Singleton Audit trail for the callback activity you will see that it actually skipped the callback!

Now it turns out that this is quite a rational behaviour for the simple reason that the Singleton doesn’t actually know where to send its callback to. This is because at design time the caller of an asynchronous process typically isn’t known, and thus the callback address needs to be specified at runt time. In fact if you log into the BPEL Console and examine the WSDL for the call back operation, you will see that the soap:address location for the endpoint is defined as:

http://set.by.caller

Now by default Oracle BPEL PM uses WS-Addressing to handle this, thus when I invoke an asynchronous process, part of the SOAP payload contains a return address for the asynchronous process, however we’ve just disabled WS-Addressing for this message exchange as we are using correlation sets.

So how do we provide the reply to address? Well one way would be to pass this in as part of the request message and then use dynamic partner links to set the replyToAddress.

However a simpler way is to define the replyToAddress property on the partnerlink to point to the reply address. This takes the format:

<wsdl endpoint>/partnerLinkTypeName/[rollName]

So in our case:

http://server:port/orabpel/default/SingletonAccessor/1.0/Singleton/SingletonRequester

Now if we deploy this it should finally work. To run the example, first go into the BPEL Console and initiate the Singleton process (set Singleton Id to "Singleton/1.0").

From the console initiate the SingletonAccessor entering whatever value you like for the name. You could kick off a number of these to see what happens.

Loose Ends

So that all works, however there are two basic problems with this approach:

• Firstly to invoke the Singleton you need to know the value of the SingletonId. This in our case is fixed within the SingltonAccessor process.
• Secondly, the Singleton process will only ever return a result to the SingletonAccessor process (as this is fixed by specifying the replyToAddress). What if we want to call it from another process or web service client?

Actually the solution to this is very straight forward; you use the SingletonAccessor as the entry point for accessing the Singleton. Thus the real client will always call the SingletonAccessor.

Thus the client never needs to know the SingletonId, and secondly as WS-Addressing remains turned on between the “real” client and the SingletonAccesor the client doesn’t need to worry about correlation sets or specifying a replyToAddress.

One final question you may have is how do I prevent multiple instances of the Singleton process being kicked-off by mistake? Well why not try it? You will see that as long as you specify the same value for the SingletonId, BPEL PM will throw a “Conflicting Receive” fault as an equivalent receive activity has already been enabled by the original Singleton.

Conclusion

As we can see, implementing a Singleton within BPEL is relatively straight forward. Whilst this is not a totally clean solution, it does achieve the desired effect.

Click here to download working example.

Oracle SOA Suite Developer's Guide

It's been way too long since I last posted a blog. It's not that I've been too busy to write which would be the normal excuse!

Rather quite the opposite; I've actually been busy writing a book with Antony Reynolds on the Oracle SOA Suite.

We actually finished writing the book back in January, but since then have been busy finishing up the sample application that comes with the book (which we have now completed).

The book itself covers all the key components of the Oracle SOA Suite, namely:


Service Bus (formerly the Aqualogic Service Bus)

BPEL Process Manager

Human Workflow

Business Rules

Business Activity Monitoring

Web Services Manager

Whilst the Oracle SOA Suite Developer's Guide provides an excellent introduction to each of these areas, we’ve tried to avoid being just a reference manual. Instead we have focused the core of the book on how to actually use the Oracle SOA Suite in the implementation of real-world SOA applications. We are very happy with the end result, but would be keen to here your feedback on whether you think we’ve hit the mark.

The book itself is bang up to date with all examples built on version 10.1.3.4 of the Oracle SOA Suite, and covers areas that are not that well documented in the official manuals such as the Workflow Service API, BPEL Fault Management Framework, etc.

So now the books is finished, I’ll actually have some more time, so expect to see a few more blogs in the next couple of months :-)

Invoking EJB's from Oracle ESB using WSIF

A common requirement with the Oracle ESB is to use it to invoke one or more EJBs; one way to do this is to create a standard SOAP service from an existing EJB using the wizards in JDeveloper.

Whilst this is straight forward, it has the disadvantage that you introduce the overhead of using SOAP/HTTP as well as losing the ability to invoke the EJB as part of a wider transaction.

An alternative approach to SOAP, is to use WSIF (Web Services Invocation Framework) which allows us to expose the EJB through a standard WSDL interface but bind to it a run time using native bindings (i.e. RMI) as opposed to SOAP. This provides us with significantly improved performance and enables us to include the invocation of the EJB within a distributed transaction.

This document covers how to go invoke an EJB 3.0 from the ESB via WSIF. For the purpose of this document, we will create a simple EJB (Greeting) with a single method helloWorld. However to make this example a bit more a bit more realistic, we will pass in a complex type Person, which has the properties title, firstName and lastName.

Note: For the sake of this example, we have assumed you have created an application with JDeveloper containing a single project called Greeting.

Creating the WSIF WSDL File

Before you can invoke an EJB via WSIF you need to create a WSDL file which contains the appropriate binding information required by the WSIF framework to invoke the EJB.

There are two basic approaches you can take:

• Contract First – With this approach we start with by defining an abstract WSDL document which defines the service and its corresponding operations and then write an EJB which implements this contract. This EJB will typically act as a wrapper to one or more existing EJBs.

• EJB First – Here we start with one or more EJB and create a WSDL interface based on the EJB and it’s operations, and then the ESB or BPEL to assemble these operations into a meaningful service.

For the sake of this article we are going to take the contract first approach as this is generally accepted as best practice. In order to do this we will need to carry out the following steps:

• Define the abstract WSDL for the required service
• Implement and deploy the corresponding EJB
• Add the WSIF bindings for the EJB to our abstract WSDL.
• Implement and Deploy an ESB project to invoke the EJB

We cover each of these steps in detail below.

Define Abstract WSDL File

The first step is to define a simple abstract WSDL file to describe your services, for our purpose we have defined the following:


At first glance there is nothing here to indicate that the WSDL is for a service to be implemented using an EJB. The only thing worth mentioning is that we have defined our XML schema elements for our input and outputs parameters in a separate file, which we have imported into our WSDL document.

The reason for doing this it that at a later stage we will need to generate Java classes based on the XML Schema, and separating out the schema makes this process slightly simpler, especially if you need share the Schema between multiple EJBs.

The schema for Person.xsd is as follow:


Note: We have defined all our parameters as elements and NOT complexTypes since the Oracle ESB will complain if you try and use a WSDL which uses complexTypes in its message definitions.

Implement Session EJB

The next step is to implement a corresponding stateless session EJB to implement our Greeting service. The simplest way to do this in JDeveloper is right click your Greeting project and select New. This will bring up the ‘Gallery’ as shown below. Browse to the Business Tier-> EJB section and select Session Bean (as shown below) and click OK.

Figure 1 - Creating a Session Bean

This will launch the Create Session Bean Wizard. In Step 1, select ‘Enterprise Java Beans 3.0(J2EE 5.0)’ as the version of EJB you wish to use and click next.

In step 2; specify the EJB Name, i.e. Greeting, Keep the default settings for the Session EJB 3.0 options (as shown below) and click ‘Next’.

Figure 2 – Specify EJB Name and Options

Next specify the bean class name. This will have already been defaulted based on the EJB Name you specified in the previous step (i.e. it will have appended bean to it). Leave the class name as is, but specify the package name as appropriate. In our case we set the package name to com.bpelpeople.ejb and then click next.

Figure 3 – Specify Class Name

Finally specify that you want the EJB to implement a remote, local and web service endpoint interface (as shown below). Then hit ‘Finish’ to generate your EJB.

Figure 4 – Specify EJB Interfaces

For each operation defined in our WSDL file we should create the equivalent method in our EJB. For each method we need to define its input and return parameters. For operations or method that return simple XML types (e.g. xsd:string, xsd:integer) we can use the equivalent type in Java.

However for complex types, such as our Person element we need to implement the appropriate classes required for serialization/de-serialization between java and xml.

Using schemac to generate serialization/de-serialization classes

As part of the SOA Suite, Oracle provides the schemac utility (bundled with BPEL PM) which you can use to generate the serialization/de-serialization classes. To use this utility open the BPEL Developer Prompt and then run the following command:

schemac –noCompile –sourceOut < dir=""> < file="">

This will generate the source Java for serialization/de-serialization classes for the specified schema file (e.g. Person.xsd in our case) and places these within the specified source directory. Within JDeveloper you will need to import these classes into you project containing your EJB.

You will notice that for each element, schemac will generate three classes (e.g. Person, IPerson and PersonFactory); we will use the actual concrete class (i.e. Person) for the input parameter to our method.

So for our Greeting EJB we have defined the following method:

Setting Project Classpath

Once you have imported the generated Java classes into your project, in order to compile them you will need to add the orabpel.jar file to your project classpath, this is located at:

$SOA_HOME/bpel/lib/orabpel.jar

Create Deployment Descriptor

Finally we need to create a deployment descriptor for our EJB, within the Application Navigator right click on our Greeting project and select ‘New’. From the gallery, browse to General -> Deployment Profiles and select ‘EJB Jar File’. This will bring up the Create Deployment Profile window.


Figure 7 – Specify Deployment Profile Name

Specify a profile name, i.e. ‘Greeting’ in our example and click ‘OK’. This will launch the ‘EJB JAR Deployment Profile Properties’ window, as shown below.


Figure 8 – EJB JAR Deployment Profile Properties

Specify a name for the application, in our case we have chosen ‘GreetingApp’ (note: you will need to make a note of this value as you will use it when defining the WSIF Binding for your service) and click ‘OK’.


Note: you will need to define an Application Server connection to the OC4J instance to which you want to deploy your EJB first.

Deploying the EJB

You can now use JDeveloper to deploy your EJB, however before doing this you should define an Application Server connection with JDeveloper to the oc4j instance on which the SOA Suite is deployed (e.g. oc4j_soa).

You are now ready to deploy your EJB. You can now use the deployment file you just created to deploy your EJB. Right click on this file and select deployTo-> oc4j_soa (where oc4j_soa is the name of your application server connction).

As part of the deployment process, JDeveloper will bring up the Configure Application window. However if you click ‘OK’ and follow the standard deployment process, you will need to include the orabpel.jar within your .ear file. This can be a bit cumbersome, particularly if you have several EAR files to deploy.

The other option is to deploy your application as a child of the orabpel application. By designating orabpel as the parent application, your EJB will inherit the set of shared libraries imported by the parent including orabpel.jar. To do this select ‘GreetinApp’ within the ‘Configure Application’ window and then select orabpel as the parentApp as show below in figure 9.


Figure 9 – Setting the Parent Application

Then click ‘ok’ and JDeveloper will complete the deployment of our EJB.

Adding WSIF Bindings

Now that we have written and deployed our EJB we are ready to add the WSIF bindings to our abstract WSDL file to enable it to be called from the ESB.

Modify Definitions Element

Within the <definitions> element of your WSDL file you need to add the following namespaces:

• xmlns:ejb=”http://schemas.xmlsoap.org/wsdl/ejb/”
• xmlns:format="http://schemas.xmlsoap.org/wsdl/formatbinding/"

The ejb namespace allows the binding of WSDL operations to methods on an EJB class. The format namespace adds support for mapping Java types to XML Schema definitions.

Add Bindings Element

This is where we bind our service to an EJB rather than a standard SOAP service. For our example, the WSDL <binding> element is defined as follows:

Ejb Binding

<ejb:binding> should be the first element within our <bindings> tag and identifies that this is service is bound to an EJB rather than a SOAP service.

Type Definitions

Next, you need to map the XML Schema elements used within the WSLD message definitions to the Java types used in the method invocations for your EJB.

The <format:typemapping> element will contain one <format:typemap> for each xml schema element that we need to map, it has two attributes encoding and style both of which should be set to ‘Java’ to indicate that we are mapping to Java classes.

The <format:typemap> element has two attributes, typeName which hold the name of the xml schema element that we are mapping and formatType which contains the class name of the Java class to which we are mapping it.

In our example, we have specified two type mappings one between our Person element and the corresponding class that we generated using schemac, and the other between the Return element and the java.lang.String class.

Method Mapping

The final step is now to map the EJB method calls onto the WSDL operations. This is done using the <ejb:operation> tag to identify which EJB method should be used to support a given operation

This element has the following attributes:

• methodName – which should be set to the equivalent method within the EJB.
• interface – which should be set to ‘remote’.
• parameterOrder – which should be set to name of the <part> contained with the input message for the operation.
• returnPart – which should be set to the name of the <part> contained with the output message for the operation.

Add Services Binding

Finally we have to add the element to our WSDL to specify where to locate the service. This looks pretty normal, except that instead of a <soap:address> element, we need to specify an <ejb:address> element.

This contains one attribute jndiName; which specifiec the JNDI Name of the deployed EJB. In our example the <service> element is defined as follows:

Calling your EJB from ESB

We are now ready to invoke our EJB from within our ESB. To do this, create a SOAP Service based on our WSDL file within your ESB project in the normal way (note you will need to import the Schema into your ESB project first).

However before registering your ESB project you will need to define the following endpoint properties on your service:

• java.naming.factory.initial - This is used to specify the initial context factory and should be set to com.evermind.server.rmi.RMI InitialContextFactory.
• java.naming.provider.url - Used to specify the URL for the EJB provider, the structure of this is covered below.
• java.naming.security.principal - Specifies the user id to be used to invoke the EJB and should be set to the appropriate value (e.g. oc4jadmin)
• java.naming.security.credentials - Specifies the corresponding password to be used to invoke the EJB and should be set to the appropriate value (e.g. welcome1).

This is so that the ESB is able to locate and invoke the EJB at run time.

java.naming.provider.url

Specifies the URL for the provider (or application) which contains our EJB, this takes the form:

opmn:ormi://<hostname>:<opmn request port>:<oc4j container>/<application>

Where

• <hostname> is the host on which the Oracle Application Server is deployed.
• <opmn request port> is the runtime port for OPMN requests on the Oracle Application Server (e.g. 6003).
• <oc4j container> is OC4J container to which we have deployed our EJB Application (e.g. oc4j_soa).
• <application> is the name of the application in which our EJB is deployed, we specified this as part of our deployment descriptor (i.e. GreetingApp).

Unfortunately JDeveloper won’t allow you to specify these specific properties, so you will need to enter the .esbsvc file outside of JDeveloper.

To do this first close down JDeveloper (otherwise you can get sync issues) and then open the appropriate .esbsvc file in your favourite text editor and specify the endpoint properties at the end of this file as follows:



Once done, you can open up JDeveloper and deploy your ESB project.

Deploy EJB Classes to ESB Engine

Before we can call the EJB from the ESB, we must first deploy the remote interface class of our EJB (Greeting.class) and our Java serialization/de-serialization classes to the ESB engine, the simplest way to do this is to copy the java classes into the directory:

<soa_home>\bpel\system\classes

Once done you will need to re-start the SOA Suite so that it picks up the classes.

Deploy Patch to ESB

Finally if you are using 10.l.3.3 of Oracle SOA Suite you will need to install patch 6314009 which is available at metalink.oracle.com.

SOA Down Under

Well it's been a while since I posted my last blog, and since then a lot has happened!!

On a personal note, I have moved half way round the world, re-locating from the UK to Melbourne, Australia. As you can imagine the process of tearing down your life on one side of the world and then rebuilding it on the other side is quite a time consuming but strangely cathartic activity (as well as leaving little time for blogging).

I've now been in Melbourne for 4 months and am absolutely loving it. I'm still with Oracle, but now working in Product Management for Oracle Fusion Middleware.

From a middleware perspective Oracle has announced the acquisition of BEA as well as released a technical preview of the Oracle SOA Suite 11g the next generation of the Oracle SOA Suite. No doubt I will be writing more about these in future blogs.

Well now that the dust has started to settle (in terms of my move to Australia), I plan to get back to blogging on a more regular basis, so if you have any requests then by all means let me know. In the meantime I'm currently writing one on how to call EJB's via WSIF for the ESB so look out for that one soon!!