The Case Study

In this article I will develop a sample application based on a fictional scenario that shows how we can leverage BPEL and binding components in our development. Here is the scenario; there is a sample store which takes orders from its customer trough a web service. Order will enter into a business process, business process stores the order to local database and checks the order shipping cost, if shipping cost is greater than 1000, the order should be sent to a supplier that handles orders greater than 1000. This supplier has a JMS queue to receive orders. The order shipping cost will be written to an xml file as the second supplier monitors if it is lower than 1000.

Requirements:

You will need: most recent version of NetBeans 5.5.1 and Enterprise pack 5.5.1, basic knowledge of Java and NetBeans IDE.

The following 8 steps are necessary to complete the sample scenario:

• Create BPEL module project.

• Create a Web service from PURCHASE_ORDER table which is present in NetBeans bundled JavaDB sample Database.

• Create PlaceOrder, SaveToFile and SendToJMS WSDLs.

• Create BPEL process.

• Create Composite Application project.

• Use CASA editor to configure service assemblies.

• Configure application server resources.

• Test the application.

• Conclusion.

Creating the BPEL Module Project

Click the New Project icon and select the Service Oriented Architecture category; in the projects list, select the BPEL Module and click next; enter OrdersBP as project name and click Finish.

Creating web service from database

NetBeans provides some wizards to create a web service from database table; the generated web service can perform CRUD operation on selected table.

To create a web service from database right click on OrdersBP project and from pop-up menu select File > New > File/Folder...; select Service Oriented Architecture category and in the file type tree select WSDL from Database..., click Next. Type Orders as file name and advance to next step. In this page you should select database that you want to generate a web service from one of its tables; select the sample data source from the list as shown in Figure 1. Username and password for database is app/app if you have not provided NetBeans with them until now.

As you can see in the wizard page you can add a table from available list to the selected list; just add PURCHASE_ORDER table to selected list and click Next. Now you will see a page that asks you to select table that you want to generate CRUD operation for it as web service operations.

For now we can just select one table for each wsdl file but in next versions you can select more tables and in this page you can determine which of CRUD operations for which tables you want to be included in the web service. Choose Purchase_Order table and proceed to the next page; this page will ask you about JNDI name for a connection pooling that is configured to provide connections for the same database that you select its table in previous step, type jdbc/soa_sample as JNDI name; we will configure jdbc/soa_sample data source and the connection pooling later.

Figure1: select sample data source to create wsdl from one of its tables.

Figure 2: choosing Purchase_Order table to create a wsdl from it.

Creating PlaceOrder, SaveToFile and SendToJMS WSDLs..

If you remember the scenario, one of the requirements was communication with the client to receive orders using a web service and the other one was saving the order into a file or sending it as JMS message to a JMS Queue.

To communicate with client we will create a web service starting from creating its wsdl. So right click on OrdersBP node and select New > WSDL Document... type PlaceOrder for its name and make sure to check import XML schema file(s). We need to import the XSD file to use its definition for order type in our web service. To import the XSD file click Browse and select srcPURCHASE_ORDER.xsd and proceed to the next step. In this step we need to define what is our input message content or type and whether we have output message and fault message for our web service or not.

For input part: change message part name to inputOrder. We should change the message element to PURCHASE_ORDER element that is created by NetBeans during previous steps. Click on change button in right side of xsd:string; Select Element Or Type window will open, select PURCHASE_ORDER Element as shown in Figure 4.

Figure 4: Select element type for inputOrder

We need to change output message type to the same type that we selected for the input message; so follow the same procedure and change output message type to PURCHASE_ORDER; make sure that you change the part name to outputOrder, click Next, select Document Literal as Binding Subtype and click Finish.

Now we need to create the two other WSDLs which will connect our BPEL process to File Binding Component and JMS Binding Component. Creating these two files is very simple. I will explain a procedure to create one of them and you create the other one yourself.

To create SendToJMS WSDL Right click on OrdersBP node and select New > WSDL Document... type SendToJMS.wsdl in the name field and make sure import XML schema file(s) check boxes have been checked, import srcPURCHASE_ORDER.xsd as you did for former WSDL file and proceed to the next step.

Both of File and JDBC WSDLs have a one way operation because we do not need an output value from them so select One-Way Operation as operation type. Change message part name to inputOrder and change Element or Type to PURCHASE_ORDER as you did for previous wsdl. Click Next, select Document Literal as Binding Subtype and click Finish.

You may ask yourself what was all of those Binding Subtype available in its combo box, indeed each of the types stands for a Binding Component in Glassfish application server integrated ESB. You can choose any of those Binding type right when you create the WSDL or you can edit it in CASA editor which gives you easier configuration panels.

To create SaveToFile.wsdl you should follow the same procedure that you followed to create SendToJMS.WSDL. Just make sure that you change the file name to SaveToFile.wsdl.

Creating the BPEL process file

As you read earlier in this article we use BPEL to weave our web services and create a more coarse grained business process over them. By now we create three web services which perform some fine grained tasks like inserting data into database, sending messages to JMS and etc; Now we want to create a BPEL process using these web services to perform order processing.

To create BPEL process, in the Projects window, expand the OrdersBP project node and right click on Process Files node, choose New > BPEL Process. Enter OrderProcess as file name in the New BPEL Process wizard opened window and click Finish. BPEL editor which is one of the bright features of enterprise pack will open and let you design your BPEL. IF Properties and Palette windows are not opened so activate them from Windows menu.

Now we should add some partner link to our BPEL process, partner links allows BPEL process to communicate with other web services and indeed it allows us to use those web services in BPEL process elements. We need to create four partner links for four web services that we created in previous steps. To create a partner link for the PlaceOrder web service, Drag and Drop PlaceOrder.wsdl from project windows to BPEL designer, a window will opens that let you customize partner link creation, change its name to PlaceOrderPL and click OK and its finished.

Now our BPEL process should wait until a customer call it with the PlaceOrder web service. So BPEL process should wait until it receives a message from its partner link. From Palette drag and drop a Receive element into OrderProcess in BPEL designer. By Selecting receive element you will see a small envelop appears in its right side, select that envelop and connect it to PlaceOrderPL. By double clicking on the receive element, Property editor window will open click on Create button to create a variable which will carry our order from PlaceOrder web service into the process, accept defaults, select OK for new input variable window again press OK for Property editor. Your Designer should show something similar to figure 5.

Figure 5: BPEL designer after adding first receive and first partner link.

Now we should add a partner link for Orders web services so drag and drop Orders.wsdl from project windows to BPEL designer; Create New Partner Link window will opens, change name field to OrdersPL and click on Swap Roles button to swap partner link role to jdbcPortTypeRole.

For using previous partner link we used a Receive element to receive messages from it but now we are going to send our messages to this partner link so add an Invoke from Palette to BPEL designer. We want to invoke insert operation of OrdersPL so connect Invoke element to insert operation of OrdersPL. We need to send our order to this operation so we need some variables to carry our order from BPEL process to double click on invoke element, create a new input and output variable and for both of them accept default settings. Click OK to close the property editor.

Now we have an Invoke element which will invoke Insert operation for us, also we have a variable which will carry our order information to Insert operation. But we need to assign real data to that variable before it can deliver them to Insert operation. Real order data is stored into variable that we defined to receive element in previous step. Assigning variables to each other is responsibility of Assign element in BPEL. So Drag and Drop an assign element from palette between Receive1 and Invoke1 elements; now select Assign1 element and BPEL Mapper will open. Connect variables as shown in Figure 6.

Figure 6: BPEL Mapper when mapping variables for assign1 element

Up to this step, we have received a message from PlaceOrder web service and we store it into database. Now we should decide where we should send the order; if it’s shipping cost is more than 1000, then we have to send it to the JMS queue for first supplier and if it is not that costly shipping we can send it to xml file for second supplier. Here we need to decide based on a condition; so we should use a decision making statement like IF which its markup element is provided in BPEL standard and NetBeans has it in its BPEL palette.

Drag and drop an IF element from Structured Activities category of palette right after Invoke 1. Select IF element and BPEL Mapper will open, here we can make our Boolean expression based on variables that we have and tens of functions that BPEL Mapper let us use visually. From Operators select a Greater Or Equal, Its icon will appear in middle space of BPEL Mapper. Now connect it to PlaceOrderOperationIn.inputOrder.SHIPPING_COST in left pane and the result in right pane as shown in figure 7.

Figure 7: Creating IF condition for shipping cost.

Select IF Element and in Properties window click on the change button of Condition property. Condition property editor will open; change it according to figure 8.

Figure 8:If condition property editor.

If you are a fan of visual editor and you don’t like to use textual editor even to edit a condition then instead of using property editor that is shown in figure 8 you can add a Number Literal and then link it to any2 in Greater Equal operator; but using condition editor gives you more flexibility to write your condition using sophisticated XPath statements.

Now we have our decision making statement in place, what we need is a call to appropriated web service in each branch of IF statement. In case that if condition return true then we should send the purchase order to JMS queue and in case that order shipping cost is less than $1000 then we have to send it to the XML file. For both of these operations we need to have partner link to their web services and invoke element to invoke those web services. To involve SaveToFile web service Drag and Drop the SaveToFile.wsdl from Projects window to BPEL editor, Create New Partner Link window will appear. Change partner link name to SaveToFilePL and click on Swap Roles button to change the role of invoker and receiver. Now that we have partner link in place we need to invoke its operation; so drag and drop an Invoke element into BPEL editor.Make sure to put Invoke element in false branch (branch in right side) of IF statement. Connect it to SaveToFilePL partner link. Now we should define input and output variables; so double click on invoke element and create input and output variables with default settings.

Now drag and drop the SendToJMS.wsdl from Projects window to BPEL editor as we should add latest partner link to our BPEL process. Create New Partner Link window will appear, Change its name to SendToJMSPL and click on Swap Roles button. To invoke SendToJMS operation drags and drop an Invoke element into BPEL editor. Make sure to put Invoke element in true branch (branch in left side) of IF statement. Connect it to SendToJMSPL partner link and to create variables double click on invoke element and create input and output variables with default settings.

We have two new Invoke elements and variables that carry our information; what we need is to assign some value to these variables. Select Assign1 element in BPEL designer, BPEL Mapper will appear; from right side connect PlaceOrderOperationIn.inputOrder to SendToJMSOperationIn.inputOrder variable in left side to determine what we want to send to JMS queue. Again from right side connect PlaceOrderOperationIn.inputOrder to SaveToFileOperationIn.inputOrder variable in left side to determine what will be stored in our XML file. BPEL Mapper should look like figure 9.

Figure 9: BPEL Mapper after mapping all variables in BPEL process.

Now That the Business process finishes and we want to send reply to initiator in order to confirm that his/her shipping order has been placed. We send back the same order that we received as a confirmation to initiator. So drag and drop a Reply element right before Process End element, connect it to PlaceOrderPL. Now we should define variables and assign what is going to be send as reply; so double click on newly created Reply element and create a normal response output variable with default options.

Now we should assign the original order to this variable, so select Assign1 element in BPEL designer; BPEL Mapper will appear, from right connect PlaceOrderOperationIn.inputOrder to PlaceOrderOperationOut.outputOrder variable in left side now BPEL Designer should be similar to figure 10.

Figure 10: BPEL designer after completing the design.

Create Composite Application project

Composite application is our means to create service assembles. These service assemblies will be deployed into our ESB service engines based on their type. Now that we have a BPEL process and we want to deploy it into our ESB we need to create a composite application project to hold our BPEL project module.

From the IDE's main menu, choose File > New Project. The New Project wizard opens, select Service Oriented Architecture and in the Projects list, select the Composite Application. Proceed to next step and in the Project Name field, type OrdersCA and click Finish.

Now we need to add our BPEL module to this composite application so in the Projects window, right-click on OrdersCA and choose Add JBI Module from the pop-up menu; when Select Project dialog box opens select OrdersBP project you created earlier in this article and click Add Project JAR Files. Your Projects window should look like figure 11 if you expand all nodes.

Figure 11: Projects window after expanding all nodes.

Now we can use CASA editor to configure and change our service assemblies. Before going any further, right click on OrdersCA and select Build from pop-up menu. This will initiate OrdersCA.casa file with the current configuration and elements.

To configure CASA, right click on OrdersCA node in projects window and select Edit, you will see something similar to figure 12. This is CASA editor and you can use it to configure your binding components, service units and endpoints.

Figure 12: CASA editor before configuring components binding.

As you can see in the picture, SendToJMS and SaveToFile are connected to SOAP binding components which is not what we need; delete both SaveToFilePort and SaveToJMSPort from WSDL Ports section. We will add one JMS and one File Binding Component to this part in order to configure using them with SaveToFile and SendToJMS web services.

To Add and configure File Binding Component drag and drop a fie element from Palette into WSDL Ports section of CASA editor then connect SaveToFile consumer endpoint to the newly dropped File BC's Provider endpoint. CASA editor will give a name to your newly dropped File BC. The name can be something like casaPort1. Select casaPort1; Navigator window has to show casaPort1 elements. If Navigator window is not visible open it from Windows > Navigator menu. Navigator should be similar to figure 13.

Figure 13: Navigator window when casaPort1 (File Binding Component) is selected.

In figure 13 you can see two important elements of casaPort1 marked with Number 1 and Number 2. When you select any of these elements, Properties windows will show customizable property of these elements. File:address element which is marked with number 1 lets you configure file path. This path will be used whether a File BC acts as provider or as consumer. Change the path if it is not suitable for you. file:message element which is marked with number 2 lets you customize how your BC will interact with the file when it acts as consumer or provider. For more information about File BC look at resources section.

To configure SendToJMS web service end point, drag and drop a jms element from Palette into WSDL Ports section of CASA editor; then connect SendToJMS consumer endpoint to newly dropped JMS BC’s Provider endpoint. CASA editor will give a name to your newly dropped JMS BC the name can be something like casaPort2. Select casaPort2, Navigator window should show casaPort2 elements. If navigator window is not visible open it from Windows > Navigator menu. Navigator should be similar to figure 14.

Figure 14: Navigator window when casaPort2 (JMS Binding Component) is selected.

As you can see in figure14 jms:address which is marked as number one let you configure connectionURL, username and password. To view and modify properties that are exposed for this element you can use Properties window. For now JMS BC just support SUN MQ. Assuming that you do not changed usename, password and port number of your SUN MQ server; so you have to use settings that are included in table 1.

Elements that are marked with number 2, let you configure how BC should handle your message and deliver it to JMS queue or topic. To select general options of JMS binding component you can use jms:operation element. This element allows you to select topic/queue that you want to use and other JMS connection properties like transaction, delivery mode, time out and etc. If you specify an already created queue (from application server admin console for example) your messages will be delivered to that queue, otherwise Sun MQ will create a temporary queue and save your messages there. Make sure that you have selected jms:message which is marked as number 2 and have changed its textPart property to inputOrder from Properties window.

Table 1: Setting required to configure casaPort2 (JMS binding component).

Configuring application server resources

If you remember, we have used a data source in our initial steps, now we need to create that data source in order to be able to proceed to the next step which is testing our application. To create application server resources open Runtime window in NetBeans IDE and expand Servers node and look for a Green arrow nearby Sun Java System Application Server 9; if green arrow was there, it means that your server is started, otherwise start the server by using provided pop-up menu. After starting application server right click on it and select View Admin Console.

Login with your username and password (admin/ adminadmin by default) then from left side navigation tree select Resources> JDBC> Connection Pools. Whenever the connection pooling page is opened click on the new button and file in information similar to figure 15.

Figure 15: Creating connection pool wizard.

Now, click next and click finish buttons. Now you should see a table that contains several row, each row identifies a connection pooling that is defined in our application server. Click on soa_sample_pool which is our newly created connection pooling and select Addition Properties tab. Here you should see a table with tens of property value rows; remove all properties and make sure that you have just left properties like figure 16. (Property names and some values are case sensitive)

Figure 16: required properties in connection pool advanced tab

We have a connection pooling ready to be used but before we can use a connection pooling we need to define a JNDI entry for it. We know JNDI entry for connection pooling as data source. To define a data source for soa_sample_pool , from left tree navigate to Resources> JDBC> JDBC Resources. Click on the new button; make sure that field values are similar to figure17.

Figure 17: JDBC resource creation.

Click on OK button. Now you are ready to proceed to latest step in this article.

Testing composite application

NetBeans provides a good mechanism to test your Composite application, indeed you just select which method of which end point you want to test and NetBeans will generate SOAP message that you can customize if required and then NetBeans send this message to end point and let you see the result.

Before proceeding to next step, deploy your project.

For using NetBeans provided facilities to test your composite application in Project windows expand OrdersCA composite application and right click on Test node, from pop-up menu select New Test Case... A wizard will opens to help you create your test case for this application, Give your test case a name and click on next button. Expand OrdersBP-Process Files node and select PlaceOrder.wsdl. Click on Next button and Select PlaceOrderOperation then click Finish.

NetBeans will create a test case for your web service. This test case consists of an input and output messages and several messages that are produced as the result of the test case execution. As I said earlier this test case helps you to send a soap message to the web service and check its reply. You can perform some simple load tests over your web service methods using these test cases.

Double click on input.xml and change its content with listing 1.

<soapenv:Envelope xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tab="http://j2ee.netbeans.org/xsd/tableSchema">