GlassFish Server

Implementing a BPEL Process on GlassFish ESB

Note : Source XSD files for this project can be found here. Create 2 XSD files from the attached word document content.

I’ve been a .NET developer for a good few years now.  I’m familiar with OOP concepts and the .NET architecture and recently I’ve had the language / framework itch.  I’ve always wondered why Java remains such a popular language for rich client, web and embedded systems and decided, finally to jump into Java.

My initial thoughts where how similar in syntax C# is with Java.  There are of course small differences and Java appears to only have about 70% of the language features that C# / .NET offers, but for .NET developers, Java syntax and language features could really be picked up over a weekend.  The architecture of the JVM should be an initial read also.

Once I felt comfortable with the differences in the language, the differences in J2SE, J2EE and J2ME and how the component / container architecture of 2JEE works (JSPs, Servlets, EJBs etc), I was very keen to jump into the area I know and enjoy developing the most, integrating systems via messaging.  For this task I’m using OpenESB, a business integration platform similar to BizTalk (deploying OpenESB applications to the GlassFish Server instead of the Biztalk Server).

The key word here is OPEN.  The platform is entirely based on open standards such as XML, SOAP, WS-*, Java and Java’s SOA /  Business Integration approach called JBI (Java Business Integration).  Now the title of this blog is GlassFish ESB,  this is an edition released as part of the GlassFish Application Server that includes the core Open ESB engine and allows integrated and easy design with the NetBeans IDE.

I should stop for a moment and clarify what ESB is all about.  This acronym stands for Enterprise Service Bus.  The enterprise service bus concept is a kind of middleware architecture approach that provides a central messaging (including message brokering and routing), process orchestration /execution and message transformation (mediation) platform that allows software and systems of varying types to communicate across the enterprise using open standards, most importantly XML and SOAP.   Biztalk, Websphere, Business Integration Server (by Seeburger), MuleESB, JBossESB etc are all types of ESB.

Deploying a basic BPEL process.

The GlassFish server and Open ESB core components are installed with the NetBeans IDE install if you download the installer from the OpenESB website.  At the time of writing, Open ESB runs on GlassFish 2.2, but I’ve not managed to install to v3 of GlassFish.  To illustrate the ease of use and how quickly you can deploy a BPEL process to GlassFish, we will create a small BPEL module that receives a message from a SOAP endpoint, follows a simple BPEL process and returns a response message to the endpoint.  This is the standard first ‘example’ from the OpenESB site and forms a simple Loan Application process.

Create a new ESB Project

First, you need to launch the NetBeans GlassFish ESB IDE (integrated development environment) and create a new project. Select the BPEL Module project and select ‘next’.  Specify the project name as bpLoanApplication and leave ‘Set As Main Project’ ticked. Once the project has loaded, take a look at the Process Files directory. We will be adding the message schemas, WSDL and BPEL process file in here.

So, we need to define the request and response message structures using XSD files and then build a WSDL file using these message XSD’s to allow a service client consuming this process to understand the structure of the request message to send.  XSD files represent the XML schema of the message and includes important information such as element names and element data types. Here is our request message schema:

Import both XSD files included in the source files (Tutorial Files > jbiConcepts > Service Registry > LoanRequestMsgs) into the project.  These represent the request and response messages.

Create WSDL File

Next we need to create the WSDL file that the service consumer will read using the standard url?WSDL link.  WSDL is the web service description language and its mission is to describe to consuming clients what operations the web service offers so that the client can determine what it needs to do to interact with the service.  In the projects window, right click the ‘Process Files’ directory and select ‘Add’, choose ‘WSDL Document’.  The wizard will open and you can specify the WSDL file name (loanApplication.wsdl) and select ‘Next’ to move onto the main Configuration screen where you will define the Input and Output message parts.  You can select nodes from the already imported request and response XSD files and NetBeans will auto detect the data types of the message elements.  Once you  have specified the inbound and outbound message structures and specified a port name, you can select ‘Finish’ and the WSDL file is added to the process files folder.

Create and configure the BPEL Process

Now that we have our messages and WSDL contract, we need to create the BPEL process and associate the inbound and outbound messages with the process.  Again add a new file to the ‘Process Files’ directory and choose ‘BPEL Process’.  You will see the default process diagram appear in the design area.  Using the Palette on the left, drag Send, Receive and Assign shapes to the process diagram as illustrated below.  Receive and Send actions should be self explanatory, but the Assign action will map data values from the request message to the response message.

Next, drag a ‘Partner Link’ onto the left hand side as per the above and call it ‘plApplicant’.  This partner link will represent the logical message entry and exit point to the process.  This partner link will be associated with a SOAP endpoint later on.  Lets now configure our partner link and message send/receive actions.  Double click the partner link and a properties window will open up to allow you to associate the WSDL file created earlier.  Using the WSDL, the partner link type can be specified.  Once the partner link has been configured, we need to configure the Receive message action; double click the Receive action and in the properties window  you can now associate the recently created Partner Link name, the Operation name (the request operation specified in the WSDL) and the creation of a local variable that will represent the message within the process (ApplyForLoan). Leave ‘Create Instance’ ticked.

We need to also configure the Response action here.  Double click it and in the opened dialog again specify the single partner link and partner link operation as well as specifying a variable for the outbound message (ApplyForLoanOut, See below).  We do this as we will be mapping data from the inbound message variable to the outbound.

Assign values to the response message

Now that we have created our process structure, a logical partner link which will link the process to an endpoint of some kind and our Request and Response message handlers, we can now map the inbound message data elements to the outbound message.  This is done using the ‘Assign’ action placed in the centre of the process.  Double click it to open up the assignment mapper interface.  The mapper interface allows you to map values (message elements) from the request variable we created earlier, which contains the inbound message to the outbound message variable we specified, which again contains the outbound message schema.  In short, you create a relationship between source and target nodes (message elements) and if necessary can perform a group of ‘transformation logic’ actions on the pane in the centre of the mapper.  In this example, I am just create two static string values that will be mapped to the outbound message.  You do however have the ability to run some XSL transformations on the data, run some Java code on the data and using Operators and Filtering functions can perform decision based transformation.  Those familiar with the BizTalk Orchestration Designer will recognise these as Functoids.

Once you have completed your map, save it and close it.  You are now ready to build the ‘process’ part of the application also known as the BPEL Module.  Right click the ‘bpLoanApplication’ project and select ‘Build’. The build.xml output window will show you are the results of the build.  You may see a warning that warns that certain message elements are not used, this is fine as its only an example and we are not using all parts of the message.

Creating a host application for our BPEL module

Now that we have created our BPEL Module, we need to host it in a Composite Application.  We do this by creating a new composite application project that will host our initial bpLoanApplication module.  Select ‘New Project’, choose ‘SOA’ then select ‘Composite Application’ – call it ‘caLoanApplication’.  This will a new project to the project window, ensure this is now the main project. When the project loads, you will see an empty design surface that is awaiting WSDL ports and one or more JBI modules, which in our case is our BPEL Module.  Using the palette, select a SOAP binding from the binds list and drag it to the WSDL ports area on the left.  Note that will will not be able to configure the endpoint until the caLoanApplication project is built.

Next, we need to drag our BPEL module to the centre part of the design surface so that a message sent to the SOAP endpoint will be sent to the BPEL process we have designed.  The great thing here is that you don’t have to go out searching on the disk for the modules .jar file, just select the still open bpLoanApplication project and drag into the centre of the design surface – a nice new bpLoanApplication module will appear.   Now its time to build, right click caLoanApplication and select ‘Build’.  This build has now created a relationship with the JBI module bpLoanApplication and you may notice that under the caLoanAppication JBI modules folder, there is now a new JBI module called bpLoanApplication.jar.  Now that the project has a relationship with our JBI module, we can now configure the SOAP endpoint.  Right click the new SOAP endpoint and select properties, select the … next to interface name and select the only listed interface you see in the drop down (this is the logical port we created in the BPEL process earlier).  Provide an endpoint name and an endpoint path on your web server; this is the link between the logical WSDL port and an endpoint.  For this example I use http://localhost:${HttpDefaultPort}/loanApplication/loanApplicationEP as my endpoint address as I’m running this test locally (and no kids, clicking the link won’t work).

Almost done… Drag the connector from the now configured WSDL SOAP endpoint to the bpLoanApplication JBI Module.  We now have a way of receiving the message via SOAP, sending it to the JBI BPEL process and a way to get a response back to the calling SOAP endpoint.  Your composite application surface should look like this:

Great. Now all that is left to do is deploy it to your GlassFish server.  Right click the caLoanApplication and select ‘Deploy’.

Nice work…