Gentle Introduction to GlassFish ESBopen-esb.net/files/OpenESB Documents/Papers... · Tutorial...

- 1 of 138 -

SUN MICROSYSTEMSGentle Introduction to GlassFish ESB

Version 1.2August 3, 2009

Please send feedback to: [email protected]

- 2 of 138 -

Table of Contents

Introduction .................................................................................................................................. 4

Scenario ........................................................................................................................................ 4

Approach ....................................................................................................................................... 5

Environment ................................................................................................................................. 6

Tutorial Format ............................................................................................................................. 6

Project 0: Installing SoftwareDownloading JDK 6 ........................................................................................................... 7Installing the JDK ............................................................................................................... 7Downloading GlassFish ESB ........................................................................................... 7Installing GlassFish ESB .................................................................................................. 8Starting GlassFish ESB ................................................................................................... 11Checking for NetBeans Updates ..................................................................................... 12Checking for Installed JBI Components .......................................................................... 13Exploring Details for a JBI Component ........................................................................... 14Downloading HermesJMS ............................................................................................... 15Installing HermesJMS ........................................................................................................ 15Configuring HermesJMS ................................................................................................... 16Exploring Tutorials on the NetBeans Website ............................................................... 21

Project 1: Determining Loan RateCreating the EJB Project ................................................................................................... 22Creating the Web Service ................................................................................................. 22Building the Project ............................................................................................................ 25Deploying the Project ......................................................................................................... 25Checking for Deployed Modules ...................................................................................... 26Exploring the Generated WSDL and XSD ...................................................................... 26Testing the Web Service .................................................................................................. 28Above and Beyond: Using the Java Debugger .............................................................. 29

Project 2: Calculating Loan PaymentCreating the Web Application Project .............................................................................. 31Creating the Web Service ..................................................................................................31Building the Project ............................................................................................................ 33Deploying the Project ......................................................................................................... 33Exploring the Generated WSDL and XSD ...................................................................... 33Testing the Web Service .................................................................................................. 35Checking for Deployed Modules ...................................................................................... 36Above and Beyond: Using the Server Log to Debug Java Code ................................. 37

- 3 of 138 -

Project 3: Quoting a LoanCreating the BPEL Project .................................................................................................38Creating a BPEL Process ................................................................................................ 39Adding Receive and Reply Elements ............................................................................... 40Building an XML Schema ................................................................................................. 41Building the WSDL Document ...........................................................................................46Adding a Partner Link ........................................................................................................48Validating the BPEL Process ...........................................................................................52Adding Invoke Elements .....................................................................................................53Importing XSD and WSDL Documents ........................................................................... 54Adding Assign Elements ....................................................................................................58Validating the BPEL Process ...........................................................................................63Building the Project ............................................................................................................. 63Creating a Composite Application ....................................................................................64Deploying a Composite Application ................................................................................. 66Checking for Deployed Service Assemblies and Service Units ....................................67Testing the Composite Application ...................................................................................68Above and Beyond: Exploring CASA Editor and Java EE Service Engine .................70Verifying the Hosting JBI Component .............................................................................. 70Viewing Endpoint Statistics ............................................................................................... 72Specifying the Java EE SE to Host a Service Unit ......................................................... 74Above and Beyond: Using the BPEL Debugger ............................................................. 80Setting a Breakpoint ........................................................................................................... 80Enabling the Debugger .......................................................................................................80Stepping Through BPEL Statements ............................................................................... 81

Project 4: Building a User InterfaceCreating the Web Application Project ............................................................................. 82Laying Out the Web Page ................................................................................................. 82Creating a Web Service Client ......................................................................................... 85Finding the Endpoint Address for a BPEL Process ....................................................... 85Find the Port Number for a JBI Binding Component .......................................................86Building the Project ........................................................................................................... 93Deploying the Project ........................................................................................................ 93Testing the User Interface ................................................................................................. 95Above and Beyond: Exploring the Ant Build Facility ....................................................... 96

Project 5: Storing Loan Quotes in a DatabaseCreating the Database ...................................................................................................... 100Accessing the GlassFish Admin Console ....................................................................... 103Creating a JDBC Connection Pool .................................................................................. 104Testing Connectivity Between GlassFish and Java DB ................................................ 105Creating a JDBC Resource ............................................................................................ 106Creating a WSDL Based on a Database Table ............................................................ 107Interacting with a Database via the Database Binding Component .............................110Exploring Packaging in the CASA Editor ........................................................................ 113Running a Test Case ........................................................................................................ 114

Project 6: Sending Loan Quotes to a JMS QueueAdding an Invoke to Access JMS ......................................................................................116Creating a WSDL Based Upon a JMS Queue ................................................................ 116Testing Queuing of Loan Quotes .......................................................................................122Above and Beyond: Logging in a BPEL Process ........................................................... 124Clearing the Log Display ....................................................................................................126

Summary ........................................................................................................................................ 127 Self-Assessment .......................................................................................................................... 129

- 4 of 138 -

Introduction Open ESB is open source software built atop the Java Business Integration (JBI) architecture as specified in the JSR 208 specification. Open ESB forms the basis for new technology that is being productized by Sun in its GlassFish ESB and Java CAPs offerings. GlassFish ESB provides a subset of Open ESB features. The purpose of this tutorial is to provide a comprehensive, hands-on introduction to the exciting features of JBI using GlassFish ESB. Here are the topics we'll explore:

- Web services based upon EJB modules and web applications- XML schema creation and WSDL development - BPEL orchestration of web services using the BPEL service engine- Deployment and testing of a composite application- Web user interface design- Storing data in a database table via the JDBC binding component- Reading and writing messages to a JMS queue via the JMS binding component

You will tackle these by focusing on six mini-projects that come together to provide a small, proof-of-concept, composite application for a fictitious business called Larry's LoanMart.

Scenario Larry's LoanMart Corporation is a mid-market financial institution operating in the Pacific Northwest. The enterprise is owned and managed by Larry Lohan. He has bought into the notion of using SOA for strategic IT advantage. He wants his IT staff to more deeply understand SOA by seeing web services and composite application building in action. So, he has sanctioned a small proof-of-concept (POC) project that is to feature these areas:

Determine Loan Rate: The risk analysis heuristics can be complex. However, for this POC, it isn't important to use a real rules engine since seeing the web services concepts in action is to be the focus. Therefore, the logic implemented by the web services will be trivial. We are to use a stateless EJB to provide the logic for loan rate determination.

Calculate Loan Payment: Another web service is to take inputs of loan amount, interest rate and period and calculate monthly payment amount. The equation to calculate a payment is well-known in financial circles. This web service will implement that algorithm. We are to use a web application to provide the logic for payment calculation.

Loan Quoting: This Business Process Execution Language (BPEL) process is to orchestrate the two web services mentioned above. It will accept loan type, amount and period as inputs and enforce sequential execution of the two services to deliver a monthly loan payment as output. At runtime, the BPEL service engine provides WS-BPEL 2.0 execution support. The basic loan quoting application will be extended twice. First, we'll utilize the JDBC binding component so we can store loan quotes to a database. Next, we'll use the JMS binding component to write and then read messages on a JMS queue. User Interface: To test the loan quoting BPEL process, we'll build a quick browser-based user interface using JavaServer Pages (JSP) hosting Java Server Faces (JSF) components to interact with the loan quote process via a web service interface.

- 5 of 138 -

Approach We'll tackle the scenario in a sequence of 5 projects that build upon each other. The following illustration communicates the building block nature of each project:

The numbers map to the project numbers used in the tutorial. We'll start off in projects 1 and 2 by building the two fundamental web service building blocks of our scenario. In Project 1, we'll create an EJB-based web service to determine the interest rate for the loan quote. In Project 2, we'll create a servlet-based, web service to calculate the monthly loan payment amount.

In Project 3, we'll orchestrate the two web service building blocks into an application that generates a loan quote. Project 4 puts a user-friendly, browser-based GUI on our application. Projects 5 and 6 store the loan quote to the data base and a JMS queue, respectively.

Before tackling these 6 projects, you'll use Project 0 to make sure that all the software you need is installed and configured.

- 6 of 138 -

Environment You'll need a modern computer with at least 2GB of RAM (the more the merrier) and about 1GB of free disk space. Although the JDK and NetBeans work on a broad range of operating systems, I'll assume that you are using Windows XP. Since the products are written in 100% pure Java, you will likely be successful with another operating system, but the instructions in this tutorial were tested on a Windows XP (SP3) laptop.

You'll need to have JDK 6 and the latest GlassFish ESB installed. Download the latest JDK from http://java.sun.com/javase/downloads/index.jsp and install it. I had good luck with JDK 6 Update 10.

You will also need GlassFish ESB. Download and install the latest GlassFish ESB build from: https://open-esb.dev.java.net/Downloads.html. Project 0 will help you with download and installation steps. I last tested this tutorial with the GlassFish ESB v2.1. Please use GlassFish ESB v2.1 or later as you work through the tutorial. It will make it easier to troubleshoot if you are using a recent version of the software.

Tutorial Format In the pages that follow, you'll see a 3-column format. In the first column, we'll include headings to act as mileposts to remind you of the purpose of the steps in the section. Hopefully, these headings will also be helpful later as you use this document as a reference. Each heading is listed in the table of contents to help you find a section quickly.

In the second column, we've included detailed, step-by-step guidance on the keystrokes and mouse clicks required to accomplish the tasks. Along the way, you will find illustrations so you can compare what you see on your screen to what we intend. Text that you will be entering is displayed in red italics. I hope you will copy and paste from this document to keep the typing to a minimum.

In the third column, you'll find narrative in green text that provides background to the steps listed in the second column. I have included some conceptual topics, informal advice and some deeper technical tips here. I call it the “buddy column” as it lets me “chat” with you about what you are doing as if two friends were sitting together at the keyboard. Having these sorts of comments in a separate column hopefully keeps the second column more concise while providing some deeper learning insights.

Download-ing JDK 6

Installing the JDK

Download-ing GlassFish ESB

Download and install the JDK (not JRE) before you install GlassFish ESB. If you don't have JDK 6, go to http://java.sun.com/javase/downloads/index.jsp and download it.

Once the JDK has downloaded, install it by double-clicking on the downloaded exe file and following the prompts. I accepted all the defaults during JDK installation.

Go to the OpenESB home page at:https://open-esb.dev.java.net/ Find the Download option and click on it to move to the download page.

Select the latest GlassFish ESB V 2.1 release by selecting the download for your particular platform:

The download window appears. Click the Save File button to download the software.

I downloaded JDK 6 Update 10 by clicking on the Download link. I selected the jdk-6u10-windows-i586-p.exe for download.

You'll find installation instructions at: http://java.sun.com/javase/6/webnotes/install/index.html

- 7 of 138 -

Project 0: Installating Software

In this project, we'll download the JDK and GlassFish ESB software and then, install it. Next, we will download, install and configure the HermesJMS tool.

http://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/VerifyItem-Start/jdk-6u10-windows-i586-p.exe?BundledLineItemUUID=eBFIBe.o.PAAAAEdSRpaJtTk&OrderID=jFNIBe.o5ZIAAAEdPhpaJtTk&ProductID=mU9IBe.pkJgAAAEb7aMQVbLE&FileName=/jdk-6u10-windows-i586-p.exe

Installing GlassFish ESB

Once the download has finished, find the downloaded file and double-click to start installation. Then, click Run. You'll see:

Click Run to proceed. You'll see this window:

Click Next to continue.

I double-clicked on glassfishesb-full-installer-windows.exe.

Uninstalling GlassFish ESB is easy too. Just click on uninstall.exe in the netbeans install directory.

• You will be prompted whether the uninstaller should also remove the GlassFish application server installation also.

• If you want to completely uninstall all GlassFish ESB-related software, toggle on this check box before pressing the Uninstall button.

- 8 of 138 -

The license statement appears. Respond to the license and click Next to continue:

The prompt JDK and NetBeans prompts appear:

The install wizard should find your JDK 6 installation. If not, use the Browse button and navigate to where it is installed. Accept the default for the NetBeans directory. Click Next to proceed.

You see that the installer found JDK 6 Update 10 on my machine. It works well!

- 9 of 138 -

The GlassFish application server-related prompts appear:

Accept the defaults. Click Next.

The configuration summary window appears:

Click Install. You'll see a play-by-play as the software is installed.

You may already have a something installed that uses port 8080. If you don't expect to have both your new GlassFish ESB and your existing port 8080 application running at the same time, you could just accept the defaults.

Here is a nice summary showing the JBI service engines and binding components that are distributed with GlassFish ESB.

My screen shot is from my GlassFish ESB v2 installation. If you are using GlassFish ESB v2.1, you'll see the Scheduler BC listed here also. Scheduler BC was the only new JBI component added with v2.1.

- 10 of 138 -

Starting GlassFish ESB

Watch the progress bar to see when the installation is complete. When the installation is finished, you'll see:

Click Finish to complete the installation process.

A registration page will appear in your browser asking you to register your GlassFish ESB.

Start GlassFish ESB by using the Start / All Programs / GlassFish ESB menu sequence.

It will probably take about 8-10 minutes to complete the installation.

I encourage you to register so you can become part of the community of users and receive important updates about the technology as it evolves.

You can also start it by running the start_netbeans.bat file in C:\GlassFishESBv21 directory.

- 11 of 138 -

Checking for NetBeans Updates

Once NetBeans has started, if you have Internet connectivity, the software might check to see if updates are available. You may see a pop-up message like this:

When this appears, click on the pop-up message and follow the steps to update your NetBeans. You'll see a list of updates like this displayed as the updates are downloaded:

If you don't see the pop-up message indicating that updates have been found, use the Help / Check for Updates menu bar option to initiate an update check.

If you don't have Internet connectivity, try to connect sometime soon. It is nice to have the latest updates.

You may not see any plug-ins listed. This indicates that your NetBeans is up-to-date.

You may be prompted to restart NetBeans after the updates have been downloaded and installed. A restart is required to complete plug-in installation.

- 12 of 138 -

Checking for Installed JBI Compo-nents

When the installation is finished, go to the Services panel and start the GlassFish application server by right-clicking on the GlassFish V2 node under Servers and selecting Start .

Once GlassFish has started, check to see the JBI service engines and binding components that are packaged with the GlassFish ESB download by expanding the GlassFish V2 hierarchy:

You see here that we have four service engines to host logic and six communication proxies (binding components) in the GlassFish ESB runtime.

You can find more components to add by going to the OpenESB components library at: https://open-esb.dev.java.net/Components.html

The SOA middleware that ships with GlassFish ESB is based upon the Java Business Integration 1.0 (JSR 208) standard. JBI specifies how to extend an integration platform by adding additional components. JBI specifies a container model for integration. There are two types of components that are found in a JBI container: service engines and binding components. Both are mini-containers.

Service engines (SEs) host business logic and binding components (BCs) act as proxies to the outside world (facilities outside the JBI container).

Loose coupling among SEs and BCs is provided by an in-memory bus called the Normalized Message Router (NMR). SEs are shown at the top and BCs at the bottom:

You'll probably won't ever write a service engine or a binding component. You'll write applications that are deployed to the mini-containers.

The easiest way get all 40+ available JBI components is to download the latest OpenESB build instead of the GlassFish ESB build. The GlassFish ESB distribution includes only those JBI components that are in released status. Many of the 40+ JBI components in OpenESB are in “incubator” status. See: https://open-esb.dev.java.net/Components.html.

- 13 of 138 -

Exploring a Details for a JBI Component

It's nice to know how to see the current state and properties for a JBI component. A component can be in three states: shutdown, started or stopped.

Right-click on the sun-bpel-engine node and select Properties:

Explore the properties to see the current version of the component. During troubleshooting, it may be helpful to turn up the logging verbosity so you can see more debugging detail:

JBI components have a life cycle:

Shutdown – Unavailable indefinitely

Started - Ready to accept messages:

Stopped - Temporarily unavailable, but can become started quickly with a command to start:

Notice that you can condition the logging level for a JBI component. The default, as shown here, is INFO level. For debugging purposes, it is often helpful to set a more verbose logging level to see more detailed messages in server.log (GlassFish stdout)

- 14 of 138 -

Download-ing HermesJMS

Installing HermesJMS

In this tutorial, we will want a convenient way to look at the contents of JMS queues. HermesJMS is an open source tool that I think you will find quite handy. Let's download it.

Go to the Hermes JMS homepage at:

Find the link to the latest stable version and click on the link to go to Sourceforge:

Download the Hermes installer to your desktop:

After, selecting the Download link, select the jar file containing the binary distribution to download it to your desktop:

When download is complete, open a command window, make your desktop the current directory and start the installer:

For cut and paste convenience, here is the command:java -jar hermes-installer-1.13.jar

The install wizard appears. I clicked through the steps taking all the defaults.

You'll find complete installation instructions at: http://www.hermesjms.com/confluence/display/HJMS/Installing

- 15 of 138 -

http://www.hermesjms.com/confluence/display/HJMS/Home

Configuring HermesJMS

In order to use the tool with our environment, we need to do some configuration. Let's do that here now.

Make sure your JAVA_HOME property is set to point to your JDK 6 installation.

Use Start / All Programs / HermesJMS / Hermes to start HermesJMS on Windows. You can also start it by executing the hermes.bat file in the C:\Program Files\HermesJMS\bin\ directory. The HermesJMS window displays.

Right-click on sessions and select New / New session:

The Preferences window appears. Change the value of the Session field from <new> to: JavaMQ

Click on the Providers Tab at the bottom of the window.

Right-click in the Providers tab window and select Add Group.

If you have trouble starting HermesJMS, make sure your JAVA_HOME variable is set appropriately since it is used in the hermes.bat file that starts the program. My JAVA_HOME is set to: C:\Program Files\Java\jdk1.6.0_10

- 16 of 138 -

For Classpath group name, enter: JavaMQClasspathGroup

Click OK.

Right-click on the Library control and select Add JAR(s):

Navigate to your GlassFish ESB imq/lib directory.

Choose the following jar files:● fscontext.jar● imq.jar● imqadmin.jar● imqbroker.jar● imqjmx.jar● imqutil.jar● imqxm.jar● jaxm-api.jar● jhall.jar● jms.jar

For me, that's C:\GlassFishESBv21\glassfish\imq/lib

Use Ctrl-click to select all the files at one time before clicking Open.

- 17 of 138 -

Click Open. When prompted, allow Hermes to scan for connection factories by clicking the Scan button.

When Hermes is done scanning, it lists all the jar files that will be added to its library:

Click Apply to record your library selections.

Select OK to close the Preferences window. The savvy reader will wonder in a moment while we are closing the Preferences window here just to open it up again right away. We'll, that's just how I got things to work! It seems that HermesJMS has a few rough edges. I found that if you don't follow this sequence, things just don't work smoothly. Bear with me.

- 18 of 138 -

We need to configure the JavaMQ session so it can interact with the GlassFish JMS messaging broker.

Expand the sessions hierarchy, right-click on JavaMQ and select the Edit option:

The Preferences window appears again.

In the Sessions tab (the default), select JavaMQClasspathGroup from the Loader pull-down menu:

Select com.sun.messaging.QueueConnectonFactory from the Class pull-down menu:

Click the Apply button to record your changes.

Click OK to close the Preferences window.

- 19 of 138 -

We need to configure access to the LoanQuoteQueue we'll use later in the tutorial. So, right-click on JavaMQ and select New / Add queue:

Add a queue with Name: LoanQuoteQueue Press Enter to record the name. Click OK to finish configuring access to the queue.

Expand the JavaMQ node and see that LoanQuoteQueue appears:

The two sample entries (examples.xml and fix.xml) still appear in the hierarchy under JavaMQ. Right-click on each and select Delete to remove them from the list.

Now that the JavaMQ session is established and the LoanQuoteQueue we'll need is configured, we can interact with the Java MQ message broker to view messages in destinations, truncate destinations and delete all messages. These capabilities will come in very handy later in the tutorial.

Exit HermesJMS by using the File / Exit menu sequence.

Remember to press Enter after adding or editing a field. Otherwise, your data entry may not “stick.”

- 20 of 138 -

Exploring Tutorials on the NetBeans Website

Once GlassFish ESB is installed with its NetBeans IDE in place, if you have web access, you might spend a few minutes familiarizing yourself by pursuing a few of the “Getting Started” tutorial links at: http://www.netbeans.org/kb/index.html

The Getting Started links are highlighted above.

When you have a good feel for the NetBeans environment, you are ready to move on.

If you haven't started GlassFish ESB yet, I start it from the Windows desktop using the Start / All Programs / GlassFish ESB menu options.

If you don't have web access right now and are unable to explore the Getting Started links, that's OK. You can proceed in this tutorial. Later, you can view the website material.

- 21 of 138 -

Creating the EJB Project

Creating the Web Service

If you haven't started GlassFish ESB, do so now. We will create a separate project for each of the major activities in this tutorial. Let's create our first project.

Select File / New Project from the menu bar. The New Project wizard window appears.

Choose Java EE as the category and EJB Module for the project type. Then, click Next.

For Project Name, enter DetermineLoanRate For Project Location, enter: C:\MyTutorial

Click Next.

Accept the rest as defaults by clicking Finish. The DetermineLoanRate project appears:

A best practice for creating a Web service is to define the interface to the service before creating the implementation. So, first, we should create an XML Schema Definition (XSD) document that defines the data types used in the messages. Then, you should build a Web Service Description Language (WSDL) document that imports the XSD and fully defines the interface to your Web service.

Start / All Programs / GlassFish ESB menu option. In less than a minute, the IDE is ready to use.

We'll be deploying atop the GlassFish Java EE-compliant application server. EJBs are a good choice to use to deploy business logic like determining a loan rate.

If the directory doesn't exist already, it is automatically created for you.

Copy the text in red and paste it into the tool to keep this from becoming a typing exercise.

Note that we are deviating from “best practices” here. We are just going to leap into the Web service implementation without creating its interface first.

- 22 of 138 -

Project 1: Determining Loan Rate

In this project, we'll create an EJB module to contain logic to determine the interest rate we'll offer for a particular loan type. As mentioned in the Scenario section earlier, the implementation logic will be trivial by design. Later, Larry's IT organization plans to plug-in a sophisticated rules engine in place of our implementation. So, the implementation will change, but its public interface won't. We'll expose our EJB module as a web service endpoint that can accept SOAP input and deliver SOAP output.

We will consciously follow a more expedient path here by creating the implementation and letting NetBeans generate the interface (XSD and WSDL) for us. Our justification for the shortcut is that we want to quickly get to a Web service we can test and build upon. Later (Project 3), you'll get a chance to build an interface definition the “right way.”

On the DetermineLoanRate node in the Projects panel, right-click and select New / Web Service. The New Web Service wizard window appears.

For Web Service Name, enter DetermineRateService and for package, enter rate Click Finish. Your new Web service has been added to the project and the Source view appears:

Select the Design control to switch the display back to the design mode. The Design canvas appears:

If this is the first time you have used the New / Web Service feature, you may need to go the File / New / Other route to find the Web Service option. To keep the interface simpler, sometimes menu options are included under “Other” until you first use them.

Here we are creating a new Web service from scratch instead of basing it on an existing session EJB.

If you are new to annotations in Java SE 5 and beyond, the @ statements look funny. They are there to support automated code generation by the Java environment. @WebService and @Stateless results in the generation of all boilerplate code for stateless session EJBs and Web service stubs, respectively.

- 23 of 138 -

Click on the Add Operation button to create an operation for our Web service to implement. The Add Operation wizard window appears.

For Name, enter getRate

For Return Type, enter double

In the Parameters tab, use the Add button to specify an input argument with Name of loanType and Type of java.lang.String (the default):

Click OK to finish creating the interface for the getRate operation.

Notice that getRate operation appears in the Design view canvas:

Expand the Web Services hierarchy in the Projects panel to see that your getRate operation has been added.

Type “double” into the Return Type field. There is a Browse button there you can use to select an object type, but it won't help you with double as it is a language primitive.

- 24 of 138 -

Building the Project

Deploying the Project

Click on the Source control again to switch back to Java code view and make the implementation of the getRate method look like this:

For easy copy and paste, here's the code for body of the getRate() method shown above:

if (loanType.equals("HOME")) return 7.0;else if (loanType.equals("AUTO")) return 10.0;else return 15.0;

Use the Alt-Shift-F short-cut to reformat the code.

Save All your work.

Build the project, by right-clicking on the DetermineLoanRate node in the Projects panel and selecting the Clean and Build option. If things go well, you'll see the message “BUILD SUCCESSFUL” in the Output panel.

Deploy this EJB module to the GlassFish application server by right-clicking on the DetermineLoanRate node in the Projects panel and selecting the Deploy option. You should see the “BUILD SUCCESSFUL” message when your EJB module has been deployed.

The code to copy and paste is included below the screen shot.

Alt-Shift-F is a short-cut for the Source / Format menu option.

If the Output panel isn't visible, use the Window / Output / Output menu bar option to display it at the bottom of the window.

It will take a bit longer for your first deployment since GlassFish will be automatically started before deployment begins.

Notice that messages also appear in the status area at the bottom right side of the NetBeans window.

- 25 of 138 -

Checking for Deployed Modules

Exploring the Generated WSDL and XSD

After deployment is complete, check to see that the module was successfully deployed by clicking on the Services tab and expanding the hierarchy as shown below:

Click on the Projects tab so you can see your project hierarchy.

Find your DetermineRateService under the Web Services node. Right-click on it and select the Properties option to display the Properties window. At the bottom, note that WSDL has been generated and is available at a URL:

Drag your mouse over this URL to highlight it and use Ctrl-C to copy it to the clipboard. Click on the Close button.

In a browser window, paste the URL you just copied. You'll see the generated WSDL. This describes the interface to your new service. However, some key information is stored somewhere else and is just referenced here.

If the module doesn't appear, you may need to right-click on EJB Modules and select Refresh.

You can close the DetermineRateService.java panel at the right by clicking on the “X” on its tab:

That will clean up some of the clutter.

WSDL (Web Services Description Language) is an XML document that describes the interface to a Web service. If a service consumer has access to the service provider's WSDL, it has access to all it needs to know to communicate with the Web service.

The interface hides the implementation details allowing the provider to, for example, change the implementation from an EJB module to a web application. As long as the interface remains the same, the client won't notice a difference.

- 26 of 138 -

That other source is the XML schema document referenced in the <types> section highlighted below:

Copy the URL from the <types> section (see above) into a new browser window to see the input and output data structures involved in this Web service's interface definition. Here is the URL to paste:http://localhost:8080/DetermineRateServiceService/DetermineRateService?xsd=1

You'll see the XSD displayed:

Here we see the data definition details indicating that our Web service expects to receive a getRate data structure containing a loanType string and is to reply with a getRateResponse data structure containing an attribute called return of type double.

This detail could have been included in the WSDL document, but it is a best practice to pull out data type definitions into a separate XML Schema Definition (XSD) document like this so they can be reused in several WSDL documents.

- 27 of 138 -

Testing the Web Service

Finally, let's test the Web service. Right-click on the DeterminRateService node and select Test Web Service. A browser window appears.

Enter AUTO and select the getRate button:

The browser window redisplays and you'll see the SOAP request sent and the response returned. Based on the Java code we included in the getRate method earlier, we would expect a 10.0 loan rate:

Feel free to run additional tests with loan type of HOME and BOAT. We would expect HOME loan rate to be 7.0 and BOAT (or anything except AUTO or HOME) to be 15.0.

Note at the top of the test page, you will find the WSDL File link that that provides an easy way to display the WSDL.

Make sure you click on the getRate button instead of just pressing Enter. Otherwise, the tester may respond with “cannot find method null”

Also note that AUTO is all upper case.

NetBeans did a lot for us. It completely generated the XSD and the WSDL documents based on what we specified in our Java implementation for the getRate method. In Project 3, we'll build XSD and WSDL documents ourselves. For Project 1 and Project 2, it's nice to “cheat” by letting NetBeans create them for us.

- 28 of 138 -

Above and Beyond: Using the Java Debugger

A good IDE must have good debugger support. Let's take a quick look at how to use the Java debugger on the Java code we wrote that implements the DetermineRateService Web service.

To turn on debugging for the module, right-click on DetermineLoanRate in the Projects panel, and select the Debug option. Wait a bit as the environment is configured for debugging.

Double-click on your DetermineRateService under the Web Services node to display the implementation. It may already be displayed in the editor. Click on the Source control to show the Java source code.

Right-click on the first if statement and select the Toggle Line Breakpoint option:

You'll see that the line is highlighted in red indicating that a breakpoint is set:

Use the browser's Back button in the test web page and test your web service again like you did before. After pressing the getRate button, watch the Java code. You'll see the breakpoint line highlighting change to green when execution reaches this point:

Watch the Output panel as the module is configured for debugging. This can take a minute. You'll know when the debugger is ready as you'll see the debugging controls appear at the top of the panel:

You can also just double-click in the margin to the left of the statement to toggle a breakpoint setting.

Setting and clearing a breakpoint works as a toggle. If a breakpoint is set, double-click on the red icon in the left margin to clear it.

- 29 of 138 -

Notice at the top of the window. The debugging controls are active now:

Click the Step Over control shown above and you'll see execution move down to the next statement.

Find the Local Variables tab in the Debugging window and explore it. For example, I entered “AUTO” as the loan type so the Local Variables debug panel shows that loanType has the value of “AUTO.”

You are probably already familiar with debuggers. So, play around a bit. For example, go to the Watches panel and create a new watch point for the loanType variable.

When you are done exploring, you can Step Over until the end of the method or simply select the Finish Debugger Session control.

If the Debugging window isn't visible, use the Window / Debugging menu bar option to display specific debugging panels.

You will right-click in the Watches panel and select New Watch. For a Watch Expression, enter loanType.

- 30 of 138 -

Creating the Web Application Project

Creating the Web Service


Choose Java Web as the category and Web Application for the project type. Then, click Next.

For Project Name, enter CalculateLoanPayment and make sure you store it in Project Location: C:\MyTutorial Click Next.

Accept all the defaults by clicking Finish to end the wizard dialog. The CalculateLoanPayment project appears in the Projects panel. You will also see the beginnings of an index.jsp page appear. Close it.

On the CalculateLoanPayment node, right-click and select New / Web Service. The New Web Service wizard window appears.

For Web Service Name, enter CalculatePaymentService

For package, enter payment and click Finish. You'll see the new service added to the Projects panel.

As you did in Project 1, click on the Design control to enter Design mode and select the Add Operation button to begin creating a new method. The Add Operation wizard window appears.

For Name, enter: getPayment

For Return Type, enter: double

You can close the index.jsp page since we won't be using this in our tutorial. To close the index.jsp editor, just click the “X” in its tab:

As with Project 1, we aren't going to create our Web service “the right way” here since we aren't going to formally define the interface (XSD and WSDL) prior to delving into the implementation. To get to testing quicker, we'll let NetBeans generate the interface for us.

We could have based our service on an EJB, but, for just for variety, we'll use a servlet as the implementation behind this Web service interface.

A client of a Web service can't tell the difference between different underlying implementations. That's the beauty of “information hiding” that separates interface from implementation.

- 31 of 138 -

Project 2: Calculating Loan Payment

In the last project, we created an EJB module that determines the loan interest rate. We surfaced the getRate method as a web service operation. In this project, we'll build functionality to calculate a loan payment. Just for variety, we'll implement this capability as a servlet-based web service endpoint rather than as an EJB. It's good practice to implement business logic like this in an EJB container, but sometimes you just have a web container and using a servlet as an endpoint is just fine. The steps will be very similar as we'll define the Java implementation for the web service and let NetBeans create the XSD and WSDL XML documents for us.

In the Parameters tab, use the Add button three times to specify the following input arguments:● interestRate (double)● amount (double)● period (int)

Click OK to finish specifying the interface to the getPayment operation. Click on the Source control to enter Source mode. A skeleton implementation has been created.

Implement the getPayment method as shown below:

Here is the code for cut and paste purposes:

Use the Alt-Shift-F shortcut to reformat the code.

Save All your work.

Use the drop-down list box in the Type column to select the double and int data types.

The code to add is provided below the screen shot for easy copy and paste.

If you want more room in the Java code editor panel, just double-click on the CalculatePaymentService.java tab and the panel expands:

To return the panel to its original size, double-click the tab again.

- 32 of 138 -

double rate = (interestRate / 12) / 100;int months = period * 12;return amount * (rate * Math.pow(1 + rate, months) / (Math.pow(1 + rate, months) - 1));



Exploring the Generated WSDL and XSD

Compile the Web service, by right-clicking on the CalculateLoanPayment node and selecting the Clean and Build option. If things go well, you'll see “BUILD SUCCESSFUL.”

Deploy the web module to the GlassFish server by right-clicking on the CalculateLoanPayment node and selecting the Deploy option. You should see the “BUILD SUCCESSFUL” message.

As we did in Project 1, let's explore the WSDL and XSD documents that were automatically created for us by NetBeans.

Click on the Projects tab again and find your CalculatePaymentService under the Web Services node in the the CalculateLoanPayment project.

Right-click on it and select Properties to display the properties window.

At the bottom of the window, notice that the WSDL is available at a URL:

Drag your mouse over this URL and use Ctrl–C to copy it to the clipboard. Select the Close button on the Properties window.

In a browser window, browse to the URL you just copied. You'll see the generated WSDL. This describes the interface to your service:

Watch the Output window for feedback.

If Clean and Build results in an error message indicating that a directory can't be deleted, just use the Build option instead.

- 33 of 138 -

As you did in the last project, find the line that imports the XML schema definition defining the input and output messages:

Copy this URL into another browser window to see the rest of the Web service's data type definitions:

The XSD is imported here.

Here are the two message types based upon the two elements in the XSD.

The port type provides an interface definition showing that a getPayment operation is available that expects an input message and delivers and output message based upon the message types above.

The concrete portion of the WSDL binds the getPayment operation to SOAP as a protocol.

Copy: http://localhost:8080/CalculateLoanPayment/CalculatePaymentServiceService?xsd=1

Here we have two complex types that are defined. These become the basis for two elements. The first complex type defines inputs (interestRate, amount and period). The second defines the return value, a double.

- 34 of 138 -

Testing the Web Service

Let's test the Web service. Right-click on the CalculatePaymentService node in the Projects panel and select the Test Web Service option. A browser window appears.

Enter the following inputs in this order:● interestRate: 10.0● amount: 100000.00● period: 15

Click the getPayment button.

This is all the same “dance” as we learned in the first project. We created the Web service implementation and let NetBeans create the XSD and WSDL documents for us.

The test page doesn't indicate which data entry field maps to which input parameter. However, you do see that the data types are double, double and int respectively. Refer to the getPayment complex type in the XSD to see the order of the parameters.

- 35 of 138 -

Checking for Deployed Modules

You'll see the SOAP Response:

Click on the Services tab so we can see that the web application (CalculateLoanPayment) has been deployed successfully:

Close the CalculatePaymentService.java panel and any other editor panels before moving on the the next project where we'll create a BPEL process to orchestrate our two web services.

Notice the JBI node in the hierarchy. Before we are done with this tutorial, our composite applications will be deployed the the JBI framework that is hosted by GlassFish.

A quick way to close all tabbed panels is to right-click on one and select the Close All Documents option.

- 36 of 138 -

Above and Beyond:Using the Server Log to Debug Java Code

At the end of Project 1, we briefly explored the Java debugger. Here, we'll visit a less sophisticated debugging technique – writing output to standard out, the GlassFish log file. It's a simple and effective way to watch execution details.

In the Projects panel, double-click on the CalculatePaymentService under the Web Services node of the CalculateLoanPayment project. The implementation appears in the editor in Source mode.

Right before the return statement, enter (copy and paste) this line of code: System.out.println("****** In CalculatePaymentService");

Let's add another debug statement using NetBeans nifty “code template” facility. Position your edit cursor on a blank line right after the statement you just added (press Enter to get a new blank line).

Type sout and, then, real quickly hit the Tab key. Notice that the editor has added the “System.out.println("");” template code Delete the two double quotes (“”) and add (copy and paste) the following in between the parenthesis:

Save All your work.

Deploy the CalculateLoanPayment project again.

Test your web service again entering the following inputs again:● interestRate: 10.0● amount: 100000.00● period: 15

Watch the GlassFish V2 panel of the Output window to see the debug statements appear.

The GlassFish log file is server.log. Mine is stored in: C:\GlassFishESBv21\glassfish\domains\domain1\logs

When this statement is executed, the text “****** In CalculatePaymentService” will appear in the GlassFish log.

This feature is called “code template abbreviations.” It's easy to mess up at first if you don't hit Tab quickly enough. Just delete sout and try again.

In the Projects panel, use the Deploy option on CalculateLoanPayment. You don't have to Clean and Build before every Deploy since NetBeans will Clean and Build if it needs to when you deploy.

To test, right-click on the web service name and select Test Web Service.

- 37 of 138 -

"Interest rate is: " + interestRate + " and amount is: " + amount + " and period is: " + period

Right-click in the Output window and select Clear before doing a test run. So, the log statements you see are from your last test. The previous lines don't clutter the window.

Creating the BPEL Project

Select File / New Project. The New Project wizard window appears.

Choose SOA as the category and BPEL Module for the project type. Then, click Next.

For Project Name, enter QuoteLoan and click Finish.

The QuoteLoan project appears in the Projects panel:

You'll see that there are no files in the Process Files folders yet. So, it is a “hollow” project until we create a BPEL module.

Well, is it really hollow? Click on the Files tab to see a file systems view of the project:

I recommend that you close all the tabbed windows that may still appear from the past two projects so we start fresh here. Just click the “X” in their tabs

According to the Merriam-Webster dictionary, “architecture” is “the manner in which the components of a computer or computer system are organized and integrated “

Building atop this definition, we can view SOA as a “manner” or style of creating and/or reusing loosely-coupled and interoperable services that can be orchestrated together to achieve a particular objective. Although SOA doesn't imply a particular technology set, the most popular form for services today is XML-based Web services described by WSDL. The orchestration vehicle of choice is BPEL (Business Process Execution Language).

The structure is all setup, complete with Ant targets, to accept and process project files.

- 38 of 138 -

Project 3: Quoting a Loan

In our first two projects, we built web services to handle independent steps in our loan quotation process. The first web service, DetermineLoanRate, an EJB module, takes in a loanType argument (like HOME or CAR) and delivers an interest rate as output. Our second web service, CalculateLoanPayment, a web application, takes in interestRate along with amount and period. It produces a calculated monthly payment amount.

We want to get these two web services to work in a sequence. In other words, we want to “orchestrate” them. When it comes to SOA, orchestration is often what Business Process Execution Language (BPEL) is all about. So, we'll build a BPEL module here that executes our two web services in sequence.

Creating a BPEL Process

Return to the Projects panel,right-click on QuoteLoan and select New / BPEL Process.

For File Name, enter QuoteLoanProcess and click Finish.

The BPEL Editor appears in the right panel:

Notice that a skeleton process appears with Process Start and Process End elements.

Click on the Source control at the top of the editor panel to see the generated BPEL statements:

Click the Design control to view the diagram again.

Notice that we now have two BPEL processes in the project. We have QuoteLoanProcess that we created above and we also have one named quoteLoan. The quoteLoan process was created for us automatically when we created the BPEL module.

Delete the quoteLoan process from your project by right-clicking on it in the Projects panel and selecting the Delete option. We'll do our work in our new QuoteLoanProcess instead.

BPEL is Business Processing Execution Language. With Web services, it's purpose is to orchestrate a collection of services that perform tasks required to fulfill a business objective.

BPEL is a higher-level language than Java and it seeks to get closer to the business policy it serves. BPEL is XML-based and has a very restrictive framework employing a handful of operations that guide state transitions among a collection of loosely-coupled services.

Instead of working with objects having methods and attributes, the BPEL “programmer” utilizes constructs like:– <receive>: blocks waiting

for a message to arrive– <reply>: sends a reply to

a message received via a receive

– <invoke>: initiates a one-way or a request-response interaction with a portType provided by a partner

– partner: a service that interacts with our BPEL process

– portType: a collection of operations that a service can execute.

– <assign>: maps values to variables used in a service utilized by BPEL process

The constructs in angle brackets are actual BPEL statement types. We'll use all of these in this project.

- 39 of 138 -

Adding Receive and Reply Elements

When in Design mode, you'll see the BPEL palette panel appear to the right of the process editor:

Often, a BPEL business process starts with a receive element and ends with a reply element. So, let's put these two “bookends” in place.

From the Palette panel, drag a Receive icon into the design canvas and drop it on the orange circle right after Process Start:

A receive icon labeled Receive1 is added to the canvas.

Double-click on the the Receive1 label and rename to StartQuoteLoan

Now add a reply element by dragging Reply icon from the palette onto the canvas. Drop it to the orange dot (insertion point) below your StartQuoteLoan receive node:

If you don't see this palette, use the Windows / Palette menu bar option to display it.

Starting with <receive> and ending with <reply> designates a standard request/reply message exchange pattern.

<receive> lets us bring data into our business process that we can use in subsequent steps.

You can switch over to the Source view of the process to see the <receive> statement that has been added.

<reply> allows us to return results to the caller.

- 40 of 138 -

Building an XML Schema

A reply icon labeled Reply1 is added to the canvas.

Double click on the the Reply1 label and rename to ReturnLoanQuote

Before we define the steps inside the business process, let's specify the inputs the process is to receive when it is invoked and the outputs it is to produce when it is finished. We'll define an XML schema to specify the data types. Then, we'll build a WSDL atop it to define the public interface.

On the QuoteLoan node, right-click and select New / XML Schema. If you don't see the option, use the New / Other / XML menu path to find XML Schema. Click Next.

For File Name, enter LoanQuoteSchema and select Finish. The LoanQuoteSchema.xsd file is added to your project and the editor appears at the right.

Enter Design mode by clicking on the Design control:

We need to define two Complex Types, one for inputs and one for outputs:

Right-click in the Complex Types area of the design panel and select Add / Complex Type:

A newComplexType node appears below.

The careful reader will note that we renamed the reply node “ReturnLoanQuote” which doesn't match up with “StartQuoteLoan,” the label on the corresponding receive node. That's OK. These labels are purely descriptive. Perhaps “ReturnQuoteLoan” would have been a better match?

Now, you'll see these two BPEL statements in the Source view:- <receive name="StartQuoteLoan" createInstance="yes"/> - <reply name="ReturnLoanQuote"/>

Exposing a business process is a lot like exposing a Web service. Our business process needs to “be wrapped” as a Web service so it can be called just like DetermineRateService and CalculatePaymentService. For those two Web services, we had WSDL documents that specified the interfaces. We let NetBeans create the WSDL (and the imported XSD document) for us. Here, we'll create the WSDL and XSD documents manually.

XSDs define simple and complex types. Complex types allow elements in their content and may carry attributes, while simple types can't contain element content and cannot store attributes.

- 41 of 138 -

Double-click on the new node and rename it LoanQuoteInput

With your cursor atop LoanQuoteInput, right-click and select Add / Element:

A newElement node appears. Double-click on it to rename it to loanType

With the loanType node highlighted, find the Properties window and look for the Definition property:

Click the ellipsis icon (see above) and set the Definition property for loanType to Built-In Types / string.

Add two additional elements under LoanQuoteInput and set their Definition properties:• amount (Built-In Types / double)• period (Built-In Types / int)

The “pros” use the Shift-e shortcut.

If the Properties panel isn't visible, use the Window / Properties menu bar option to display it.

So, we'll have three elements: loanType (string), amount (double) and period (int).

- 42 of 138 -

Here is the completed LoanQuoteInput complex type definition:

Now, let's define the output side of the public interface for our BPEL process. Use what you learned above to create a LoanQuoteOutput complex type.

Add two elements:• description (Built-In Types / string)• monthlyPayment (Built-In Types / double)

At this point, your XSD should look like this:

Save All your work.

To create the complex type, right-click on the Complex Types area and select Add / Complex Type. Rename it by double-clicking on it.

To add an element, right-click on the LoanQuoteOutput complex type and select Add / Element.

To specify data types, click on the element and find the Definition property. Use the appropriate Built-In Types as illustrated.

.

If you are curious, switch over to the Source view to take a look at the XML that NetBeans generated for you.

It sure is nice not to have to code in raw XML, isn't it?

- 43 of 138 -

Now, we need to add two top-level elements to our schema to represent the incoming request and outgoing response data types. These elements will be based on the complex types we just defined.

In Design mode, right-click in the Elements area at the top of the design panel. Then, select Add / Element:

A newElement node appears.

Double-click on the new node and rename it to LoanQuoteRequest

For its Definition property, set it to Complex Types / LoanQuoteInput:

Right-click in the Elements area again and select Add / Element. Another newElement node appears.

Double-click on the new node and rename it to LoanQuoteResponse

For its Definition property, set it to Complex Types / LoanQuoteOutput.

Save All your work.

Elements this time, not Complex Types.

If you are curious, check out the Schema view of this XSD. You'll see a hierarchical tree view that might be easier to explore.

Save often. It's better to be safe than sorry. Ctrl-S should become a habit.

- 44 of 138 -

Here is how the completed LoanQuoteSchema should look:

Switch over to Source mode to see the completed XSD document:

This XSD document defines the data types that we will pass into and send out from our business process.

We'll import it into the WSDL document we'll create next so that our Web service has the data definitions in needs.

You can give the editor more screen real estate by double-clicking on the LoanQuoteSchema.xsd tab:

To return the editor panel to its original size, double-click the tab again.

- 45 of 138 -

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://xml.netbeans.org/schema/LoanQuoteSchema" xmlns:tns="http://xml.netbeans.org/schema/LoanQuoteSchema" elementFormDefault="qualified"> <xsd:complexType name="LoanQuoteInput"> <xsd:sequence> <xsd:element name="loanType" type="xsd:string"/> <xsd:element name="amount" type="xsd:double"/> <xsd:element name="period" type="xsd:int"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="LoanQuoteOutput"> <xsd:sequence> <xsd:element name="description" type="xsd:string"/> <xsd:element name="monthlyPayment" type="xsd:double"/> </xsd:sequence> </xsd:complexType> <xsd:element name="LoanQuoteRequest" type="tns:LoanQuoteInput"/> <xsd:element name="LoanQuoteResponse" type="tns:LoanQuoteOutput"/></xsd:schema>

Building the WSDL Document

To check your XSD for errors, click on the Schema control to enter Schema mode. Then, find the Validate XML control and click it. You may need to resize the window. Look for any errors in the Output panel.

With the XSD in place, we have defined the data types for our WSDL. Now, we can now build our WSDL interface definition for our BPEL Process.

Right-click on the QuoteLoan project node and choose New / WSDL Document. The New WSDL Document wizard window appears.

For File Name, enter LoanQuoteWSDL

Toggle on the Concrete WSDL Document radio button to indicate that we want to specify protocols and physical end point addresses.

Leave SOAP as the selected Binding, but, in the Type drop-down menu, select Document Literal.

Click Next.

In the Input section, rename part1 to InputPart

For the Element Or Type value for InputPart, click on the ... icon and select the LoanQuoteRequest element (not the complex type):

Click OK to record your type selection.

Check the XML check tabbed panel in the Output panel to search for good news:

We are using Document / Literal since it has become the most popular combination of message type and encoding in the Web services arena.

If you specify Document, you are stating that the body of the SOAP document will contain one or more child elements (parts) and that no formatting rules are to be applied. The content of the elements can be whatever the sender and receiver have agreed upon.

If you specify RPC as the message style, you are indicating that the body contains an element that provides a name of a method that is to be invoked. Furthermore, this element will have a child element for each parameter that is to be passed along with the method call.

In choosing a serialization format, you have two choices: SOAP Encoding and Literal. If you select SOAP Encoding, you are adopting rules from the SOAP 1.1 spec on how data structures are serialized before transmission over the wire. This serialization format is usually associated with the RPC message style. If you choose Literal, the data in the message body is to be serialized using an XML schema. In other words, you are controlling the format and are not defaulting to a set of rules in the SOAP spec.

- 46 of 138 -

In the Output section, rename part1 to OutputPart

For its Element Or Type, select the LoanQuoteResponse element (not complex type):

Click Next. The Concrete Configuration wizard step executes:

Just click Finish to accept the defaults.

You new WSDL appears in the Projects panel under the QuoteLoan hierarchy.

Now that we have the interface defined in WSDL, let's return to the QuoteLoanProcess.bpel design canvas and use the interface definition to build a BPEL partner link.

We'll reference the XSD in the WSDL creation wizard so it is included in the <types> section to define data types.

To find the BPEL design canvas, double-click on the QuoteLoanProcess.bpel node in the QuoteLoan hierarchy in the Projects tab.

- 47 of 138 -

Adding a Partner Link

Find the tab for you BPEL process panel and click on it to see the process. From the Projects panel, drag the LoanQuoteWSDL.wsdl node onto the left side of the BPEL design canvas as shown below:

When you finish the drag and drop, a partner link appears on the canvas.

Rename it by double-clicking on the default PartnerLink1 name and entering: QuoteLoanPartnerLink

You may ask: What is the difference between dragging to the left side or the right grayed side? Good question. In dragging the WSDL to either the left or right grayed area, we will be creating a partner link.

A partner link represents a channel through which our business process can communicate to “the outside world” via the interface specified in the WSDL. Here, the “outside world” is any client that wants to call our business process. Ultimately, in this tutorial, that client will be a user interface we'll generate with NetBeans in the next project.

A partner link in a BPEL model has a partnerRole attribute. This indicates whether or not the BPEL process is implementing the web service that is being called “through the channel.”

OK, back to the left / right discussion. If we create a partner link on the left side (as we are doing here), we are indicating that our BPEL process is the implementer of the web service endpoint. The partnerRole will be “myRole” to indicate that the BPEL process is claiming responsibility for the implementation. If we had created the partner link on the right, we would the partnerRole would identify the external web service endpoint that we will interact with (likely using an <invoke>).

- 48 of 138 -

Click on the StartQuoteLoan receive node in the design canvas. An edit icon (pencil) appears above the node:

Click the edit icon to display the receive node's Property Editor window.

Fill-in the fields as shown below. You will need to use the Create button to specify the Input Variable.

Select the Ok button.

You'll see that the StartQuoteLoan receive node is “wired up to” its partner:

Now, we need to connect our receive and reply elements to our partner link “channel” so that the <receive> can be invoked and bring data in and so our <reply> can deliver the response back to the client.

To create the Input Variable, just click the Create button and accept the defaults.

You may notice that elements may be highlighted in red as you build your model. This indicates that the model is in an incomplete state. We'll fix things as we go.

- 49 of 138 -

Switch over to Source view for your BPEL process:

You will find that the following <receive> BPEL statement has been created for you:

Switch back to Design mode. Here is where we stand so far:

We need to “wire up” the reply node to our WSDL interface too. So, click on the ReturnLoanQuote reply node and see the edit icon appear above it:

BPEL code generation happens in the background as you work in the design canvas.

Here is a helpful debugging tip. When you are in Source mode looking at the BPEL statements, you may not see line numbers listed down the left margin. That isn't a problem until you are in the think of a troubleshooting session and you see an error message in the GlassFish V2 Output panel identifying a particular BPEL statement number where an error occurred.

You'll want to go into the Source mode and see the line numbers. Toggle them on using the View option on the menu bar:

- 50 of 138 -

<receive name="StartQuoteLoan" createInstance="yes" partnerLink="QuoteLoanPartnerLink" operation="LoanQuoteWSDLOperation" xmlns:tns="http://j2ee.netbeans.org/wsdl/QuoteLoan/LoanQuoteWSDL" portType="tns:LoanQuoteWSDLPortType" variable="LoanQuoteWSDLOperationIn"/>

Click the edit icon (pencil) to display the Property Editor window.

Fill-in the fields as shown below. As you did for the Input Variable earlier, you'll use the Create button to specify the Output Variable here:

Select the Ok button.

Now, your BPEL process design canvas should look like this:

Save All your work.

Remember to create the Output Variable. Just click the Create button and accept the defaults.

We have specified that our BPEL process responds to a request/reply message exchange.

- 51 of 138 -

Validating the BPEL Process

Both the request and reply nodes are now “wired up” to the partner link that defines the inputs and outputs for our business process.

Switch over to the Source view to see the <reply> statement that was created for you by NetBeans:

Let's check to make sure that NetBeans is producing well-formed XML BPEL constructs as a result of our work on the modeling canvas.

Select the Validate XML icon at the top of the canvas pane:

When you will likely see:

Notice that this is a warning, not an error. It is just reminding you that you identified an input variable for data to come into the StartQuoteLoan receive node and you haven't used it yet. That's no problem as we are still in the middle of building our process. Move on.

You might want to switch over to the Source view to see the <reply> statement that was created for you by NetBeans.

Great. Now our business process can be called (via the <receive>) and return results (via the <reply>) and we did all this BPEL work by manipulating BPMN icons on a design canvas. Cool!

You may need to resize the window and /or scroll to the right a bit to find the Validate XML icon.

This is the input variable for our StartQuoteLoan <receive> element you specified when you created QuoteLoanPartnerLink.

- 52 of 138 -

<reply name="ReturnLoanQuote" partnerLink="QuoteLoanPartnerLink" operation="LoanQuoteWSDLOperation" xmlns:tns="http://j2ee.netbeans.org/wsdl/QuoteLoan/LoanQuoteWSDL" portType="tns:LoanQuoteWSDLPortType" variable="LoanQuoteWSDLOperationOut"/>

Adding Invoke Elements

Once execution of the process begins at our StartQuoteLoan receive element, we want to execute two activities in sequence:• The DetermineRateService service to deliver

the interestRate• The CalculatePaymentService service to

determine the monthlyPayment and build a description.

The way you “call” an outside service in BPEL is to insert an invoke element into your model and wire it up to a “channel” -- a partner link.

So, from the palette, drag an Invoke operation into your model and drop it at the orange dot right above the ReturnLoanQuote reply activity:

The Invoke1 element is added to the model. Double-click on the Invoke1 label and rename the element to DetermineRate

Just as we configured the receive node with its partner link, we need to configure the DetermineRate invoke node.

First, we need to create a partner link (a channel) to the DetermineRateService Web service.

This is to be a “channel” to talk through to get out to our DetermineRateService that we created in Project 1.

- 53 of 138 -

Importing XSD and WSDL Documents

However, before we can add the partner links to our BPEL model, we need to make our WSDLs and XSDs (for our two web services) available to the BPEL process. To make them available, they need to be “imported” into the QuoteLoan project.

To “import” the WSDL (and related XSD) that describes the interface to the DetermineRateService web service, find the web service under the DetermineLoanRate / Web Services hierarchy, right-click on DetermineRateService and select the Generate and Copy WSDL option. The Generate and Copy WSDL window appears.

For the destination, select the src directory under QuoteLoan and click OK:

Look under the Process Files node for QuoteLoan to see that both the WSDL and its associated XSD have been copied.

Perform the same steps to Generate and Copy WSDL for the CalculatePaymentService web service in the CalculateLoanPayment project. When you are finished, you will see that the WSDL and XML documents for this web service also appear under Process Files for the QuoteLoan project.

Collapse the hierarchies in the Projects panel for DetermineLoanRate and CalculateLoanPayment as we won't be selecting nodes there for a while.

- 54 of 138 -

Drag the DetermineRateServiceService.wsdl from under QuoteLoan/Process Files and drop it onto the right side of the BPEL canvas:

The Create New Partner Link window appears.

For Name, enter DetermineRatePartnerLink

Click Ok to accept the defaults. The partner link node appears on the canvas:

Now we need to “wire up” this partner link to our DetermineRate invoke activity.

Why the big deal about dragging to the right instead of the left side of the model? Good question. It's an important one.

Dragging to the left or right determines the “role” the partner link is to play. If we drag it to the right side, “My Role” will be utilized. If we drag it to the left side, “Partner Role” is specified.

Partner links can be thought of as “tunnels” through which a business process interacts with the world outside the BPEL model. “My Role” says that the process implements the interface being exercised through the “tunnel.” If “Partner Role” is specified instead, that means that an outside partner is implementing the interface.

The bottom line is:– If your business process

is being called from the outside, the partner link will be on the left side and “My Role” is specified.

– If your business process is calling out to a partner “on the outside,” the corresponding partner link will be on the right side and “Partner Role” is specified.

And now for the bottom, bottom line ... you could drag all your partner links to one side other the other, but you would have to manually select “My Role” or “Partner Role” in the pop-up dialog box for the partner link. NetBeans frees you from having to worry about this as it sets the role based on whether you dragged to the right or to the left side of the model.

- 55 of 138 -

Click the DetermineRate invoke element. Click the edit icon (pencil) above it. The Property Editor window appears. Fill it in as shown below:

Once you select Ok, this partner link is wired to its associated invoke activity in the design canvas:

Now that the invoke statement is fully specified, you might want to switch over to the Source view to see it:

Now, let's add another invoke activity to our model for our second Web service (CalculatePayment). Return to the Design view.

As you did before, from the palette, drag an Invoke operation into your model and drop it on the orange dot right above the ReturnLoanQuote reply element.

As before, to create the Input and Output Variables, just click the Create button and accept the defaults.

Now our <invoke> (named DetermineRate) can “talk out” to the DetermineRateService via the “channel” provided by the partner link.

- 56 of 138 -

<invoke name="DetermineRate" partnerLink="DetermineRatePartnerLink" operation="getRate" xmlns:tns="http://rate/" portType="tns:DetermineRateService" inputVariable="GetRateIn" outputVariable="GetRateOut"/>

The Invoke1 activity is added to the model. Double- click on the Invoke1 label and rename the activity to CalculatePayment

To create a partner link for our CalculatePayment Web service, we need to perform the same steps as we just did for DetermineRate. So, drag the CalculatePaymentServiceService.wsdl from under QuoteLoan/Process Files and drop it onto the right side of the BPEL canvas below the DetermineRatePartnerLink

As before, the Create New Partner Link window appears. For Name, enter CalculatePaymentPartnerLink and select Ok to accept the defaults.

Now we need to “wire up” this partner link to our CalculatePayment invoke activity:

Click the CalculatePayment invoke activity. Click the pencil icon above it. The Property Editor window appears. Fill it in as shown below:

Once you select Ok, this partner link is now wired to its associated activity in the design canvas.

Save All your work.

Again, use the Create buttons to specify names for the Input and Output Variables. Just accept the default names.

- 57 of 138 -

Adding Assign Elements

Your BPEL model should now look like this:

Our two web services need inputs in order to perform their function. The input data structures are defined in their associated partner links as input variables. We need to map values to the specified inputs. In BPEL, you do mappings with Assign nodes.

Drag an Assign node from the Palette and drop it on the orange circle immediately before the DetermineRate activity.

Double-click on the Assign1 label and rename it to AssignRateDeterminationInput

Now our BPEL process can “talk” to both of the Web services. They are using the interface described in WSDL documents and talking through the “channels” provided by the partner links.

Our two Web services will get their inputs from the input provided by the client of our BPEL process. The inputs will be delivered through the QuoteLoanPartnerLink “channel” via the WSDL that we defined earlier in this project.

The Assign palette item is in the Basic Activities section of the palette panel.

- 58 of 138 -

Double-click on AssignRateDeterminationInput and see the Mapper panel display:

As shown above, expand the LoanQuoteWSDLOperationIn node in the left panel (the “from” panel) to show the variables contained in the InputPart.

Also, expand the GetRateIn node in the right panel (the “to” panel) to show the parameters for GetRateIn.

In the Mapper, outputs are on the left and inputs appear at the right. So, drag and drop from LoanQuoteWSDLOperationIn.InputPart.loanType to GetRateIn.parameters.loanType:

Leave the Mapper and return to the Design mode by clicking the Design control on the canvas window.

- 59 of 138 -

Drag in another Assign node and drop it on the orange circle immediately before the CalculatePayment activity node. Double-click on the Assign1 label, and rename it to AssignPaymentCalculationInput

Double-click on the new AssignPaymentCalculationInput node and see the Mapper panel again.

Drag and drop to map outputs (on the left) to inputs (on the right):

Switch back to Design mode.

Now we'll add one more Assign element so we can map values to the outputs of our business process.

So, drag in another Assign node and drop it immediately before the ReturnLoanQuote reply node.

Rename the new assign node to AssignResults

If you have trouble renaming the Invoke element, right-click and select Properties to display the Properties window. Change the name there by editing the Name property.

If you are curious, switch over to the Source view to see the the <assign> statement. As we do the value mappings, you'll see <copy> statements added inside the <assign>.

Again, to rename the Assign, you might need to right-click and select Properties to display the Properties window. Change the name there by editing the Name property.

- 60 of 138 -

interestRate (GetRateOut.parameters.return --> Variables.GetPaymentIn.parameters.interestRate)amount (LoanQuoteWSDLOperationIn.InputPart.amount --> Variables.GetPaymentIn.parameters.amount)period (LoanQuoteWSDLOperationIn.InputPart.period --> Variables.GetPaymentIn.parameters.period)

Double-click on the new AssignResults node to see the Mapper display.

Drag and drop to map “froms” (inputs on the left) to “tos” (outputs on the right):

This copies the calculated monthly payment amount generated by the CalculatePaymentService into the monthlyPayment variable that our business process is to return.

Now, let's build a text string to populate the description variable in LoanQuoteWSDLOperationOut.OutputPart. We'll concatenate some variable values along with some static text like this:<loan type> + " loan for amount of " + <amount>

This will let us produce a description like “AUTO loan for amount of 10000.00”

Click on the description node in the right side of the mapper. A blue highlight area appears to show the insertion point for the mapper:

The BPEL Mapper window has some features that help you create additional BPEL constructs. We'll play with String / Concat to give you a feel for how the mapper can generate additional BPEL statements for you.

- 61 of 138 -

Select the Concat operation from the String menu option at the top of the BPEL Mapper panel.

A Concat node is added to the Mapper canvas in the blue insertion area for the description node.

Wire up the loanType variable to the first part of the concatenated string:

Double click on the second String slot and enter the loan for amount of (include a leading a trailing space) text:

Finish up the concatenation by adding the amount value as shown below:

Don't forget to “wire up” the Concat's return String to LoanQuoteWSDLOperationOut.OutputPart.description so that the result of our concatenation is mapped to our output variable as shown above.

Our mappings are complete. Return to the Design mode and Save All your work.

Notice that we didn't need to do any casting of amount from double to String for the Concat. Sometimes when you validate or deploy, you'll see data type mismatch warnings, but they are just warnings. You can ignore them since the castings are typically properly handled automatically.

Don't forget the leading and trailing spaces. Without them, the words in our concatenated description will run together with the variable data.

To activate the String slot for editing, just double-click on it. Don't forget to include the leading and trailing spaces.

You don't enter any single quotes or double quotes. The quotes (shown here) are inserted by the editor.

- 62 of 138 -

Validating the BPEL Process


With all the mappings complete, let's validate our business process by selecting Validate XML control at the top of the design window.

If you have a BPEL process that's free from syntax errors, you see a “0 Error(s), 0 Warning(s)” message in the XML check panel.

Let's build the project by right-clicking on the QuoteLoan project node and selecting Clean and Build. When you see the “BUILD SUCCESSFUL” message, we are ready to move on.

You may notice that there is no Deploy option available for this type of project. In our next step, we'll include or BPEL module project in a composite application and deploy it there.

Click on the Files tab to take a look at all that was just generated for you:

Click on the Projects tab so we can create a composite application and deploy it for testing.

Or just use Build if you receive a message that a directory can't be deleted.

You may be curious what Clean and Build did here. Probing into the build directory in the file system where your project is being stored, you'll see that a all your XSDs and WSDLs have been collected together. Also, a jbi.xml file has been created. So, NetBeans is already anticipating deployment to a JBI environment.

Take a peek inside that file to see the definitions of what this BPEL process contracts to provide and what it intends to consume.

To find where files like jbi.xml are being stored, right-click on your project node in the Projects panel and select Properties. Look in the Project Folder property.

- 63 of 138 -

Creating a Composite Application

To be able to test our QuoteLoan BPEL process in the next project, we need to create a composite application, add the BPEL project to it and deploy it.

So, create a new composite application by selecting File / New Project / SOA / Composite Application

Click Next and enter QuoteLoanApplication for Project Name.

Click Finish and the new composite application appears in the Projects panel:

We need to add our QuoteLoan BPEL module to this new composite application.

So, right-click on QuoteLoanApplication and select select Add JBI Module. The Select Project window appears. The CASA (Composite Application Service Assembly) Editor appears.

In the Select Project window, click on QuoteLoan and select then click the Add Project JAR Files button.

In the CASA editor, you'll see that your QuoteLoan project has been added to the canvas:

To assemble the application, click the Build Project (hammer) control at the top of the CASA editor.

The “composite applications” topic is a very hot one today. It's an appeal for building applications out of a collection of separate, self-contained sub-assemblies. Each sub-assembly shields consumers from its implementation by providing a well-defined public interface. This holds great promise for better quality and quicker time to market if the IT industry can build more of its business solutions using a composite application approach.

When you add your QuoteLoan project to the new composite application, you'll see the CASA (Composite Application Service Assembly) editor appear.

You might want to take a moment to read about it using the online help facility:– Find the Help item on the

main window menu bar– Select the Help Contents

option– In the Search tab, enter

casa in the Find field.

Could could right-click on QuoteLoan and select Build also, but I find this Build Project control convenient.

- 64 of 138 -

The CASA editor assembly canvas refreshes to show the service units that could be identified for the QuoteLoan project:

We see that our BPEL module is being invoked by a SOAP request, but we don't see how the DetermineRatePartnerLink and CalculatePaymentPartnerLink are going to consume our two web services.

So, drag in two soap WSDL Bindings from the palette and drop them onto the WSDL Ports area:

Wire up the partner links:

We see the purple Consume endpoints, but no corresponding green Provide endpoints.

- 65 of 138 -

Deploying a Composite Application

Now, we need to provide endpoint information for the two new WSDL ports.

Right-click on the casaPort1 WSDL port (the one connected to DetermineRatePartnerLink) and select Properties.

For Location, click on the ... icon and enter:

For Endpoint Name, enter: DetermineRatePort

Select Close to record the property changes.

Right-click on the casaPort2 WSDL port (the one connected to CalculatePaymentPartnerLink) and select Properties.

For Location, click on the ... icon and enter:

For Endpoint Name, enter: CalculatePaymentPort

Select Close.

Save All your work.

Right-click on the QuoteLoanApplication node in the Projects panel and select the Clean and Build option. Of course, you could use the Build Project tool also like you did earlier. Watch in the Output window for the “BUILD SUCCESSFUL” message.

Right click on the QuoteLoanApplication node and select the Deploy option. Watch in the Output window for the “BUILD SUCCESSFUL” message.

Before we move on to Project 4 where we create a user interface to call our QuoteLoanApplication, let's use NetBean's testing facility to perform some unit testing.

Notice that these two Location values match the service names in the WSDL document for each web service.

The Endpoint Name values match port names in the WSDL documents, but they don't have to match. It just makes for better docu-mentation for the service assembly.

If you copy and paste these Location URLs into a browser and append ?wsdl at the end, you'll see the WSDL displayed.

You can also deploy your composite application by clicking on the Deploy Project tool:

- 66 of 138 -

http://localhost:8080/CalculateLoanPayment/CalculatePaymentServiceService

http://localhost:8080/DetermineRateServiceService/DetermineRateService

Checking for Deployed Service Assemblies and Service Units

Let's see what a deployed composite application looks like from the JBI framework point of view. Click on the Services tab and expand the Servers / GlassFish V2 node to find the JBI node.

Expand the JBI node to find see that one service assembly containing two service units has been deployed:

Here is how the QuoteLoanApplication service assembly appeared in our CASA Editor:

The three WSDL ports are represented by the QuoteLoanApplication-sun-http-binding service unit. The BPEL QuoteLoan JBI module in the CASA Editor is represented by the QuoteLoanApplication-QuoteLoan service unit.

If you right-click on a service unit and select Properties, you'll see what JBI component (SE or BC) it will be deployed into. For example, QuoteLoanApplication-QuoteLoan is deployed into the sun-bpel-engine.

Just like for deployed service units (above), if you right-click on a WSDL Port or a JBI Module and select Properties, you'll see what JBI component it will be deployed into.

- 67 of 138 -

Testing the Composite Application

Let's build a test case for our application to feed it a loan type, an amount and a period and see if it delivers the description and monthly payment amount we expect.

In the Projects panel under the QuoteLoanApplication node, click on the Test node select New Test Case:

The New Test Case wizard window appears.

For Test Case Name, enter HomeLoanTestCase Select Next. You are prompted to select a WSDL document upon which to base the test.

Expand QuoteLoan – Source Packages and select LoanQuoteWSDL.wsdl:

Click Next. When prompted for an operation to test, select LoanQuoteWSDLOperation and click Finish.

An XML editor appears with an input document. You'll see three fields delimited by “?” symbols. Fill-in those fields with test data:

Save All your work

Run the test case by right-clicking on HomeLoanTestCase in the Projects panel and selecting Run.

For convenient copy and paste, here is the request body for the text case.

Use Alt-Shift-F to reformat the XML after you copy and paste it.

- 68 of 138 -

<loan:LoanQuoteRequest> <loan:loanType>HOME</loan:loanType> <loan:amount>250000.00</loan:amount> <loan:period>15</loan:period> </loan:LoanQuoteRequest>

The first time you run a new test, the expected output is empty so you will always see a message “The expected output for the test case is empty ...” dialog window message. Just click Yes to acknowledge it.

Run the test again.

You should see the following output indicating a successful test:

Double-click on this latest test output (the top one) to view the XML output returned by our composite application. You'll see that a description and payment were delivered correctly:

Look for the monthlyPayment and description fields.

We know that application has passed unit testing.

Troubleshooting Note: If the test case doesn't complete within a reasonable time (30 seconds), rebuild and redeploy the composite application. Then, rerun your test case.

In the next project we will create a browser-based user interface to exercise our composite application.

This may feel a little goofy. Sometimes you run a test case and are sure that it is successful, but you see “Failed” appended to the end of the time stamp. When you understand how the tester decides on success vs. failure, it make sense. Here is the secret. When you run a test, the generated response is compared with whatever is in the Output. The first time through, the Output is empty, so the test fails. That pop-up window comes up and if you respond with Yes, the latest result is copied into Output. Then, as you run again (without changing your inputs), the test passes (no “Failed”) thereafter.

If you run with a new set of input, the test will “Fail” since the latest result doesn't match the current contents of Output. If you want the latest result to be the new “primo” / successful / desired output, right-click on the latest result name and select the Use as Output option:

The latest result is copied into Output.

- 69 of 138 -

Above and Beyond:Exploring CASA Editor and Java EE Service Engine

Verifying the Hosting JBI Component

When we were creating the QuoteLoanApplication composite application, I mentioned CASA, the Composite Application Service Assembly editor. CASA offers a graphical model showing how service units come together into service assemblies that are deployed to the JBI-compliant runtime.

You can always see the composition of your composite application by double-clicking on Service Assembly under QuoteLoanApplication. The CASA editor appears:

We see that our application has just one module.

Right-click on the QuoteLoan icon and view its Properties to see that it is to be deployed to the BPEL Service Engine. Here is where it will be hosted at runtime.

Check the value for the Component Name property.

- 70 of 138 -

If you also check the Properties for each of the WSDL ports, you'll find that they will be deployed to the HTTP Binding Component:

We have already deployed the QuoteLoanApplication. Let's look at the Services tab to see how it was deployed:

A quick check of the Properties for the service units (as shown above) verifies that they are deployed to service engines and binding components as specified in CASA.

Look for the value in the Target Name property.

- 71 of 138 -

Viewing Endpoint Statistics for a JBI Component

You may have heard that, with the JBI architecture, the “Java EE application server becomes just another service engine.” See that the Java EE service engine (SE) is in the list of installed SEs.

Start the sun-javaee-engine in the Services panel by selecting it, right-clicking and choosing Start.

View what is deployed to it by accessing its endpoint statistics. In the Services panel, right-click on sun-javaee-engine and select Show Endpoint Statistics.

Hummm ... The Endpoint Statistics window indicates that there has been no activity. See the Received Dones column. We ran our test case at least once successfully, so Received Dones should not be 0.

The DetermineLoanRate web service is implemented as an EJB and the CalculateLoanPayment web service runs as a servlet. These are Java EE artifacts. Why don't they get deployed to sun-javaee-engine?

I like to say this since it drives home the point that JBI extends Java EE so we can tackle more with server-side Java.

If the JBI component is not started, you can't view its endpoint statistics.

- 72 of 138 -

Close the Endpoint Statistics window.

Let's explore that by packaging up our two web services and the BPEL module into a new composite application (QuoteLoanApplication2). We'll do some module configuring in the CASA Editor this time instead of just taking the defaults. Our end result with be deploying one of our web services into the sun-javaee-engine.

Return your focus to the Projects panel and create a new composite application by selecting File New Project / SOA / Composite Application.

Click Next and enter QuoteLoanApplication2 for Project Name.

Click Finish and the new composite application appears in the Projects panel. You'll see a blank CASA Editor canvas appear.

Find the QuoteLoan node in the Projects panel, click and drag it into the JBI Modules area of the CASA Editor canvas:

Last time we added QuoteLoan to a composite application, we right-clicked and selected the Add JBI Module option. Being able to drag and drop provides an alternative that you may like better.

- 73 of 138 -

Specifying the Java EE SE to Host a Service Unit

Build your QuoteLoanApplication2 project and watch as the CASA editor panel reloads:

We have the same configuration we started out with for QuoteLoanApplication. Let's tweak it to get the Java EE Service Engine involved.

To solicit the involvement of the Java EE service engine (SE), drag the DetermineLoanRate node from the Projects panel and drop it onto the JBI Modules area of the CASA canvas. Then, Build QuoteLoanApplication2 again to see:

Just click on the Build Project tool:

Here we specify that the DetermineLoanRate module is to run inside the Java EE SE.

Ah, there's the JavaEE service engine. It will “house” the DetermineLoanRate service.

- 74 of 138 -

Notice that DetermineLoanRate is now a separate module (service unit) in our composite application (service assembly). The QuoteLoan BPEL service unit will “talk” directly with the DetermineLoanRate service unit without using a HTTP/SOAP binding component (WSDL Port).

As with QuoteLoanApplication, we see that our BPEL module is being invoked by a SOAP request, but we don't see how the CalculatePaymentPartnerLink is going to consume our two web services.

So, as before, drag a soap WSDL Binding from the palette and drop it onto the WSDL Ports area and wire up the partner link:

Now, we need to provide endpoint information for the new WSDL port.

As we did in QuoteLoanApplication, right-click on the casaPort1 WSDL port and select Properties.

For Location, enter:

For Endpoint Name, enter: CalculatePaymentPort

Select OK and then click on Close.

Save All your work.

“Service Unit” and “Service Assembly” are JBI terms. They are packaging and runtime artifacts much like war, ejb-jar and ear files are for Java EE.

Communications between the BPEL process and DetermineLoanRate can occur directly across the normalized message router (NMR) now without going out of the JBI container and back in via the HTTP binding component.

- 75 of 138 -

http://localhost:8080/CalculateLoanPayment/CalculatePaymentServiceService

Here is our final service assembly design for QuoteLoanApplication2:

Build QuoteLoanApplication2. Watch for the “BUILD SUCCESSFUL” message in the Output panel.

We won't deploy it yet. Move on to do a little exploration of the service units first.

Click on the Build Project (hammer) tool.

- 76 of 138 -

Let's explore where these modules (service units) will be deployed. Right-click on the QuoteLoan service unit to see (by the Component Name property) that this is still being deployed to the BPEL Service Engine:

Click Close to dismiss the Properties window.

Now, check out the Properties for the DetermineLoanRate module to see that it will be deployed to the Java EE Service Engine:


It's no surprise that it is still going to the BPEL SE since we added it the same way to the CASA Editor canvas.

The BPEL service engine is named “sun-bpel-engine.”

Great. Now, the Java EE Service Engine (sun-javaee-engine) has a role in delivering our composite application.

- 77 of 138 -

Deploy your QuoteLoanApplication2 by clicking on the Deploy Project tool at the top of the canvas.

Watch the Output panel to see that deployment will fail. If you scroll up in the build.xml Output window, I expect you to see the following error:

So, undeploy QuoteLoanApplication, your original composite application, by right-clicking on it in the Projects panel and selecting Undeploy.

Deploy your QuoteLoanApplication2 again. This time, deployment succeeds.

Let's verify how the modules got deployed. In the Services panel, expand the hierarchy like this:

You'll have to scroll a long way to the right in the Output panel to find the error message.

Our problem is that we already have an application deployed that matches the Location specified for soap:address in LoanQuoteWSDL. This is the basis for the partner link for our QuoteLoanProcess BPEL model.

- 78 of 138 -

LoanQuoteWSDLPort,Consumer'' cannot be activated because: an active endpoint deployed in composite application

So, QuoteLoan has been deployed, as before, to the BPEL Service Engine and DetermineLoanRate will now be executed by the Java EE Services Engine.

In the Services panel, look under the Applications / EJB Modules node and see that the QuoteLoanApplication2-DetermineLoanRate EJB module has been deployed. It will be used instead of DetermineLoanRate (our original EJB module).

The CalculateLoanPayment, under the Web Applications hierarchy, will still be used in QuoteLoanApplication2. However, it won't run in the Java EE Service engine since we didn't specify it as its own separate module in the CASA editor.

In summary, let's revisit our earlier questions:“Why don't they [modules like DetermineLoanRate and CalculateLoanPayment] get deployed to the Java EE Service Engine?”

The answer: We need to specify them in the CASA Editor as separate service units. We did that for DetermineLoanRate this time.

You could check endpoint statistics like you did in the “Viewing Endpoint Statistics for a JBI Component” section earlier, but until you run a test case, all values will still be zero.

We could build a test case and use it to test QuoteLoanApplication2 like we did the original one, but, instead, let's move on. Let's reset things back to our original state with QuoteLoanApplication deployed and our new one undeployed.

1. Right-click on QuoteLoanApplication2 and select Undeploy.

2. Right-click on DetermineLoanRate project and select Deploy to make sure our EJB module is an active web service endpoint.

3. Right-click on QuoteLoanApplication and select Deploy.

Rerun your HomeLoanTestCase to verify we are back to a working QuoteLoanApplication.

The original DetermineLoanRate is still displayed and is still accessible on port 8080. However, QuoteLoanApplication2-DetermineLoanRate is what runs inside the Java EE Service Engine and it is accessible via the HTTP SE on port 9080.

The particularly inquisitive reader will question:“DetermineLoanPayment is running in the Java EE SE. CalculateLoanPayment is not. What's the difference? After all, they are both running in GlassFish!”

The answer might help you better understand how a JBI container works and may reveal some important performance considerations.

If your logic runs inside a service engine (BPEL SE, Java SE SE, etc.) and that logic needs to collaborate with logic running in another SE, the communication doesn't have to go outside the container and back in through a binding component to be routed by the NMR (normalized message router) to the other SE. So, a call from our QuoteLoan BPEL module can be dispatched by the NMR directly to DetermineLoanPayment. However, for logic running outside the container, like for CalculateMonthlyPayment, communication goes out through the HTTP BC and back into the NMR before the collaboration can occur.

- 79 of 138 -

Above and Beyond: Using the BPEL Debugger

Setting a Breakpoint

Enabling the Debugger

We saw in Project 1 how to watch Java code execution using the Java Debugger. Let's explore the BPEL Debugger here.

Display your QuoteLoanProcess in the BPEL Editor and enter Design mode.

Set a debugging breakpoint on the first assign element by right-clicking on AssignRateDeterminationInput and selecting the Toggle Breakpoint option:

A little red box appears at the top of the assign element to indicate that a breakpoint has been set.

Turn on debugging for the composite application by right-clicking on QuoteLoanApplication in the Projects panel and selecting the Debug (BPEL) option. A debug session is initialized.

Run your test again by right-clicking on HomeLoanTestCase and selecting the Run option.

Look at the BPEL modeling canvas to see that the first element is highlighted in green. This indicates that execution is stopped at the breakpoint.

Click the Source control to view the BPEL statements. Scroll down to the first <assign> statement to see that it shows execution stopped also:

Double-click on QuoteLoanProcess.bpel in your QuoteLoan project hierarchy in the Projects panel.

You'll know the debugger is working when the debug controls appear above the BPEL editor.

- 80 of 138 -

Stepping Through BPEL Statements

You can stay in the Source mode or return to the Design mode. The debugging controls appearing at the top of the panel work in either mode:

I suggest that you click on the Design control to return to Design mode.

Use the Step Over control (shown above) to move through the BPEL process one statement at a time.

Explore the Debugging area as you step through the process. You may find the Local Variables tab the most interesting:

You can exit the debugger by selecting the Finish Debugger control or by merely stepping through the end of the BPEL model.

Congratulations! You have a working BPEL process that orchestrates two web services. You have been testing it using the composite application test facility.

Let's move on to the next project and see how to invoke the BPEL model from a client that you write. Our client will be a browser-based user interface.

Switch back and forth between the Design and Source modes as you step through with the debugger.

If you can't see the Debugging Window, use the Window item on the main window and find the Debugging option.

- 81 of 138 -

Creating the Web Application Project

Laying Out the Web Page


Choose Java Web as the category and Web Application for project type. Then, click Next.

For Project Name, enter LoanQuoteUI and click Next.

On the Server and Settings step, click Next (not Finish!).

Toggle on the “Visual Web JavaServer Faces” check box. Then, select Finish.

The LoanQuoteUI project appears in the Projects panel. Notice that Page1.jsp design canvas appears along with a widget palette. If the palette does not appear at the right-side of the window, use the Window / Palette menu bar option to display it.

Drag four Labels and one Button from the palette and drop them onto the Page1.jsp canvas to build this much of the user interface:

To change the default label text, just click on it twice and enter the desired text.

If you don't move on by clicking Next to the last wizard window, you won't have the web interface framework we'll use loaded into your new web project.

We could build the user interface as a stand-alone Java application or even as a JavaFX Script project. Both are supported by NetBeans. However, let's build a traditional web page and use JSP (JavaServer Pages) and JSF (JavaServer Faces) to present a user interface to our back-end application.

For copy and paste convenience, here are the text labels:- Loan Type:- Amount:- Period:- Calculated Monthly Payment:

- 82 of 138 -

Project 4: Building a User Interface

In our last project, we built a BPEL module to orchestrate two web services. While testing the process, we used the built-in, test case facility for composite applications. In this project, we'll create our own browser-based user interface to call our BPEL process.

Add three Text Fields to the layout to the right of their corresponding labels.

Use the Window / Properties menu bar option to display the Properties panel. Change the id property of these user-editable text fields to:● typeTextField● amountTextField● periodTextField

Add a Label (so the user can't type in it) with an id ofpaymentLabel to the right of your “Calculated Monthly Payment:” label.

Relabel the button to Calculate by changing its text property in the Properties panel:

On the three data entry textField widgets and on the label that is to display the payment amount, add a “binding attribute” by clicking on each of the four widgets (typeTextField, amountTextField, periodTextField and paymentLabel) and selecting the option shown below:

To align the labels, select them all, right-click and use the Align option. Also try out the Align / Snap to Grid option.

Changing the id values will make for more descriptive, maintainable code in the button handler we'll create in a moment..

If accidentally double-click on the button when wanting to rename it, you end up in the Java code. Just click on the Design button to view the layout again.

There are two portions to a JSP page that uses JSF. There is the JSP syntax and the “backing bean” Java code. The result of Add Binding Attributes will become clearer in a moment when we peek at the generated JSP syntax.

- 83 of 138 -

Save All your work.

Click on the JSP control at the top of the layout panel to see the JSP syntax that was automatically created for you based upon the widgets you added to the design canvas. Your “Add Binding Attribute” actions added the syntax highlighted below:

Note that these binding statements reference Page1. Click on the Java control at the top of the layout panel to see the “backing bean” Java code for the Page1 class. The relationship between the JSP syntax and the Java backing bean is described by the JSF specification.

Click on the Design control to return to Design mode.

- 84 of 138 -

Creating a Web Service Client

Finding the Endpoint Address for a BPEL Process

We need to specify an action handler for the Calculate button so we can invoke the QuoteLoan business process and return the monthly payment to display in the paymentLabel field.

The QuoteLoan business process is available as a Web service. We just need some client-side code to call it. So, we'll create a Web service client and then exercise the client from inside our button handler.

NetBeans tooling can easily create the client-side code to call the QuoteLoan business process as a web service. We just need to know where the web service endpoint is. In other words, how is our BPEL process “listening” for a SOAP/HTTP request?

To begin answering that question, remember the LoanQuoteWSDL we created in Project 3 to “wrap” our BPEL process so we could call it via SOAP? That WSDL worked well since our HomeLoanTestCase was able to use it when we tested our QuoteLoanProcess.

So, double-click on LoanQuoteWSDL.wsdl under Process Files for QuoteLoan so we can take a look at the endpoint address:

See (above) that the soap:address is specified as:

JSF components bring capabilities from Java Swing rich client programming to web UI design. Components like buttons can have action handlers containing code that is executed when the user interacts with the component. JSF utilizes JSP client-side code to invoke the action handler code that runs inside the web container (server-side).

A web client is JAX-WS code that is generated to shield you from dealing with the details (Java / XML marshaling and unmarshaling) that goes on in communications between the client (service consumer) and server (service provider).

- 85 of 138 -

http://localhost:${HttpDefaultPort}/LoanQuoteWSDLService/LoanQuoteWSDLPort

Finding the Port Number for a JBI Binding Component

Notice that instead of referencing a particular port, the WSDL is using an environment variable (${HttpDefaultPort}) that the NetBeans tooling automatically fills in for inter-module communication within a composite application. Our LoanQuoteUI is a stand-alone web application and is not part of a composite application. So, LoanQuoteUI won't benefit from any automatic substitution of an environment variable. We need to know the answer to this question: What is the actual port where the endpoint is “listening?”

Let's chase down the answer by first answering another question: Where in the JBI container is that SOAP endpoint deployed? If we knew the port number for the JBI component that hosts the endpoint, we'd know the actual port number to use to replace ${HttpDefaultPort}.

Double-click on Service Assembly under QuoteLoanApplication to display the service assembly in the CASA Editor:

- 86 of 138 -

The endpoint is represented by the SOAP WSDL Port labeled LoanQuoteWSDLPort. Right-click on it and select Properties:

We can see in the Component Name property that this WSDL port (SOAP endpoint) is deployed to the sun-http-binding JBI component. That's the HTTP binding component, one of 40+ JBI components from the OpenESB project.

Now, if we just knew what port the sun-http-binding component “is listening on,” we'd have our actual port number for the endpoint for our web services call for our QuoteLoan process.

To explore all the available JBI components, see: https://open-esb.dev.java.net/Components.html

- 87 of 138 -

To find out where the sun-http-binding component is listening, go to the Services panel, find it in the list and access its Properties:

Notice that the Default HTTP Port Number is set to 9080. Bingo!

So to reach this SOAP web service endpoint:

we use this URL:

Check to see that we got it right by including ?wsdl on the end of the URL and using your web browser to view the endpoints WSDL:

- 88 of 138 -

http://localhost:${HttpDefaultPort}/LoanQuoteWSDLService/LoanQuoteWSDLPort

http://localhost:9080/LoanQuoteWSDLService/LoanQuoteWSDLPort

http://localhost:9080/LoanQuoteWSDLService/LoanQuoteWSDLPort?wsdl

You'll see the following WDSL document verifying that your endpoint to QuoteLoan is “alive” at port 9080:

With the URL of our WSDL endpoint in hand, we are ready to build our web service client.

In the Projects panel, right-click on the LoanQuoteUI project in the Projects panel and select the New / Other / Web Services / Web Service Client option. Click Next to start the wizard.

- 89 of 138 -

Click on the WSDL URL radio button. Then, paste in the URL to the WSDL you just displayed:

Click Finish to start the generation for the client-side artifacts.

The WSDL is accessed and the new Web service client appears in your project under Web Service References:

Notice that you can't double-click on your new web service reference and display anything in the code editor. What NetBeans has done for you is to collect what it needs to generate the JAX-WS client-side code to marshal and unmarshal XML and Java objects.

NetBeans makes it easy for you to use this client code (see upcoming steps) without having to worry about how to create it our how marshaling and unmarshaling works.

- 90 of 138 -

http://localhost:9080/LoanQuoteWSDLService/LoanQuoteWSDLPort?wsdl

Now (finally!), we can create our button handler code that uses this Web service client.

In the Page1.jsp Design mode, double-click on the Calculate button to display the source code for the empty handler:

We'll add the some code here to exercise the web service client that we just created.

Click in the body of the code after the comments. Press Enter to make a blank line.

On the blank line, right-click and select Web Service Client Resources / Call Web Service Operation. In the pop-up window, select the LoanQuoteWSDLOperation and then select OK.

The client code to access the QuoteLoan BPEL process as a web service per the WSDL interface is added to your button handler:

Web Service Client Resources is the last option in the pop-up menu.

- 91 of 138 -

This gives us the skeleton code to allow our button handler to exercise the QuoteLoan BPEL process via a web services call. Now, we need to fill-in the details.

Replace the entire button handler by copying and pasting the following statements to make your button handler code look like this:

Again, use Alt-Shift-F to reformat (“pretty print”) your Java code.

Save All your work.

Use Alt-Shift-F to reformat your code.

The skeleton code you just saw is in what we'll copy and paste below. It's just easier to copy and paste the entire method than it is to insert pieces here and there.

As the highlighted comments statements indicate, here are the key steps in the code:

1. Establish communication channel

2. Get data entered into the user interface fields

3. Populate the data structure used to communicate through the channel

4. Exercise the Web service provider via the channel

5. Populate the user interface widget with the result from the Web service call

- 92 of 138 -

public String button1_action() { try { // Get port org.netbeans.j2ee.wsdl.quoteloan.loanquotewsdl.LoanQuoteWSDLPortType port = service.getLoanQuoteWSDLPort(); // Retrieve values in text fields on UI String loanType = (String) typeTextField.getText(); String amountString = (String) amountTextField.getText(); String periodString = (String) periodTextField.getText(); double amount = Double.valueOf(amountString); int period = Integer.valueOf(periodString); org.netbeans.xml.schema.loanquoteschema.LoanQuoteInput inputPart = new org.netbeans.xml.schema.loanquoteschema.LoanQuoteInput(); // Populate inputs inputPart.setLoanType(loanType); inputPart.setAmount(amount); inputPart.setPeriod(period); // Call web service org.netbeans.xml.schema.loanquoteschema.LoanQuoteOutput result = port.loanQuoteWSDLOperation(inputPart); System.out.println("Result = " + result); // Update UI with web service result double monthlyPayment = result.getMonthlyPayment(); String monthlyPaymentString = String.valueOf(monthlyPayment); paymentLabel.setValue(monthlyPaymentString); } catch (Exception ex) { paymentLabel.setValue("Error"); System.out.println("****** " + ex.getMessage()); System.out.println("****** " + ex.getCause()); } return null; }



Build (compile and package the artifacts) the project, by right-clicking on the LoanQuoteUI node and selecting Clean and Build.

We need to deploy our web application so we can test it. For the previous deployments, we would have just right-clicked on the project name and selected the Deploy option. This time, we are instead going to deploy from the GlassFish Admin Console. This alternative gives us a chance to see the nice integration between the NetBeans IDE and the underlying GlassFish Enterprise Server administration.

Make sure your GlassFish server is up and running.

To begin deployment, go to the Services panel and invoke the GlassFish Admin Console by right-clicking on GlassFish V2 and selecting the View Admin Console option:

A web page displays challenging you for authentication.

For User Name, enter: admin

For Password, enter: adminadmin

Here I am steering you toward a new way to deploy your web application. Using the approach you already know (right-clicking and selecting the Deploy option) is tempting. However, I have two reasons to prescribe the GlassFish Console alternative. First, I want you to experience the GlassFish Admin Console. Second, preparing for testing LoanQuoteUI using the right-click Deploy option may not work. Deployment might work without error, but you may experience an error during testing.

It seems that we have introduced a bug in recent releases of GlassFish ESB that can bite us here. Using the GlassFish Console to deploy is an effective workaround.

This hurdle may be addressed by the time you use this tutorial, but in case it isn't, here I have documented the alternative for LoanQuoteUI that has worked for me every time. So, please use the GlassFish Admin Console approach for now.

These are the default credentials to login as an administrator to the GlassFish Admin Console. I bet you didn't change them when you installed GlassFish ESB.

- 93 of 138 -

Our LoanQuoteUI application is a web application. So, under the Applications hierarchy at the left, click on the Web Applications node. Notice that CalculateLoanPayment is a web application that has already been deployed:

To deploy the LoanQuoteUI application, click on the Deploy button. The Deploy Enterprise Applications/Modules display appears.

In the Location (Packaged file to be uploaded to the server) field, browse to the C:\MyTutorial\LoanQuoteUI\dist directory and select the LoanQuoteUI.war file:

Click the OK button to deploy the .war file. When deployment is finished, the list of deployed web applications redisplays:

Your LoanQuoteUI application is ready for testing.

- 94 of 138 -

Testing the User Interface

Now, we can use our LoanQuoteUI web application to exercise our QuoteLoan BPEL process.

Right-click on the LoanQuoteUI node and select Run. A web page appears showing the user interface you designed.

Enter loan quote data in the three text boxes, as shown below, and select the Calculate button:

After you select the Calculate button, the payment should appear in the Calculated Monthly Payment text box as shown above. If you see “Error” instead, check the GlassFish V2 Output panel for error messages. If the error isn't obvious, backtrack to rerun your HomeLoanTestCase again to make sure QuoteLoanApplication still works. Then, revisit your steps in building the web service client and in calling it from the button handler.

If it bothers you to initially see the default value “Label” in the field to display the monthly payment, you can edit it's text property and delete the default “Label” value. Rebuild and redeploy after the change.

Remember that the Loan Type value is case-sensitive so “AUTO” and “auto” aren't the same. Also note that, unlike the web service testing pages, Amount does not have to be a decimal number. “22000” works just fine. That's because of this statement in your button handler:double amount = Double.valueOf(amountString);

- 95 of 138 -

Above and Beyond: Exploring the Ant Build Facility

When you select menu options like Run, Clean and Build and Undeploy and Deploy, NetBeans invokes the Ant build facility behind the scenes. For each project you create, NetBeans provides an elaborate set of Ant tasks for it. Let's explore the Ant task for your LoanQuoteUI project.

Click on the tab for the File panel (second tabbed window as shown below) and expand the LoanQuoteUI hierarchy :

The build.xml file contains a collection of Ant tasks that it can be invoked. Double-click on build.xml to display the tasks in the editing window.

Ant is an Apache-sponsored open source tool to automate software builds. It is similar to the popular make facility in C and C++. Ant is written in Java and is very popular in Java development circles. Ant uses an XML document to describe the dependencies in a build process.

You might enjoy the quick overview of Ant at Wikipedia: http://en.wikipedia.org/wiki/Apache_Ant

- 96 of 138 -

Read through the comment lines at the top of build.xml. These highlighted lines are interesting:

Notice that the comment lists -post-dist as a target that we might want to implement in order to insert some activity just after an archive is built. Let's add a simple implementation:

Scroll down to the bottom of the file right before the </project> tag, press Enter to add a blank line and then and implement -post-dist to perform the following echo output statement:

For easy copy and paste, here is the text:

Save your work.

Test your new -post-dist target by returning to the Projects panel right-click on the LoanQuoteUI project and select Build. Watch the LoanQuoteUI (dist) Output window for the message:

The echo statement is a simple Ant primitive that allows us to write text to standard out. Notice that we are outputting the value of a variable (dist.jar.dir) here.

- 97 of 138 -

<target name="-post-dist"> <echo>****** Am running my post-dist ant target. The directory for jars is: ${dist.jar.dir}</echo></target>

Return to the Files panel and scroll down to find the -post-dist target in the hierarchy (it is grayed out) under build.xml. Double-click on it. It takes you to the insertion you made earlier at the bottom of build.xml. Neat havigation support.

Now, find the run target in the hierarchy and double-click on it. The target displays, but notice that you are now in the build-impl.xml file now (not build.xml).

Scroll to the top of this build-impl.xml file and notice:

So, you don't make your changes in build-impl.xml! All your Ant target work will be done in build.xml.

Now, you may ask, what if I want to override the run task specified in build-impl.xml? Let's do it.

Double-click on the run target in the build.xml hierarchy. This positions your cursor in the build-impl.xml file as we just saw.

Highlight the entire target and copy (Ctrl-C) it:

Return to the bottom of the build.xml file (not build-impl.xml) where you added the -post-dist target earlier and paste the copied run target below your -post-dist target. Edit it by adding the <echo> statement highlighted below so that your run target looks like this:

Save All your work.

Now, if you return to the build.xml hierarchy in the left panel, find “run” and double-click on it again, your edit cursor will be positioned at the overridden version of the run target (in build-impl.xml) instead of at original one (still in build.xml). Cool!

Danger, danger. You shouldn't edit this file.

Above is the completed run target for your copy and paste convenience.

Use Alt-Shift-F to reformat the XML after you edit it.

- 98 of 138 -

<target depends="run-deploy,run-display-browser" description="Deploy to server and show in browser." name="run"> <echo>****** Am running my overridden run ant target. </echo></target>

Save your work.

Return to the Projects view and run your LoanQuoteUI project (right-click on LoanQuoteUI and select Run). Watch the LoanQuoteUI (run) Output window to see that your overridden tag is executed:

To learn more about tailoring the Ant-based build facility, use the Help / Help Contents menu bar option and search the online help for build.xml:

Notice in our run task that we are still honoring the “depends” clause so that the tasks identified there (like run-deploy) are still executed ahead of our addition (the echo).

- 99 of 138 -

Creating the Database

Before we can use the Database binding component to insert a row into a table, we have some setup and configuration work to do.

NetBeans ships with a relational database called Java DB. We'll create a new database in Java DB where we can store our LoanQuotes table.

To create the database, click on the Services tab. Expand the Databases node to display Java DB and and existing connections:

Right-click on the Java DB node and select Create Database. The Create Java DB Database window appears.

Java DB is based upon the Apache Derby open source project. You may know the technology from an earlier name – Cloudscape. Java DB ships as part of the Java JDK so it is an official part of the Java platform.

- 100 of 138 -

Project 5: Storing Loan Quotes in a Database

In the last project, we completed our loan processing scenario by adding a browser-based user interface to drive the BPEL process to generate loan quotes. In this project, we'll go above and beyond the basic requirements by storing our loan quotes in a database table. We'll exercise this capability by extending our BPEL process with a new invoke/assign pair and a partner link based upon a WSDL that reflects the structure of our database table. The Database Binding Component will do the JDBC work for us with Java DB, our database of choice here.

Fill-in the window as shown:

Select OK.

When MyTutorialDB has been created, you will see the following connection added to the list in the Services panel:

Let's connect to the database now so we can create our LoanQuote table. Right-click on this new connection and select Connect.

Expand the jdbc:derby:...MyTutorialDB node and note that no tables currently exist under the Tables node:

Right-click on the jdbc:derby:...MyTutorialDB node and select Execute Command. An SQL command window appears. Enter the following SQL statements to create our table to store loan quotes:

For copy and paste convenience:

Database Name: MyTutorialDB

User Name: admin

Password: admin

Don't change the default Database Location. Your location is based on where you installed GlassFish ESB, so your location may not match mine.

It is an empty database.

The statements are provided for copy and paste below.

- 101 of 138 -

For copy and paste convenience, here are the statements:

create table loanquote (recordid INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY, loantype VARCHAR (20), amount NUMERIC (15,2), period INTEGER, payment NUMERIC (15,2)) ;

Execute the statements by clicking on the Run SQL icon at the top of the SQL command window:

In the SQL Command execution Output window, you should see good news:

To verify that the table was created successfully, click on the Tables node select Refresh. The LOANQUOTE table should be listed:

To view its contents, right-click on LOANQUOTE and select View Data. Of course, the new table is empty right now.

The “PRIMARY KEY GENERATED ALWAYS AS IDENTITY” allows us to have Java DB automatically assign a unique sequence number to the key column.

Don't forget to copy the trailing semi-colon.

The lower panel is where rows would appear if we had loan quotes stored.

- 102 of 138 -

Accessing the GlassFish Admin Console

With the table in place in Java DB, our next step is to let GlassFish know about our database. We'll need to perform two configuration steps in the GlassFish Admin Console: ● Define a JDBC connection pool ● Create a JDBC resource with a JNDI name

that utilizes our new connection pool

We will do our configuration in the GlassFish administration console. To display the admin console, select the View Admin Console option in the Services panel as shown below:

A browser page will appear prompting you for a user name and password. Use the following defaults:● User Name: admin● Password: adminadmin

Select the Login button to continue.

I find the integration the Services tab provides with the GlassFish runtime very handy.

If GlassFish isn't started, you'll need to start it before you can access the Admin Console.

These are the default values from the installation procedure. If you don't remember changing them in the install dialog, these credentials will work for you.

- 103 of 138 -

Creating a JDBC Connection Pool

Find the Connection Pools option under Resources / JDBC and click on it to display existing connection pools:

Click on the New button to create a new connection pool. Fill-in the first wizard window like this:

Click Next.

Scroll to the bottom and fill-in the following:● User: admin● DatabaseName: MyTutorialDB● Password: admin● ServerName: localhost● PortNumber: 1527

For cut and paste, Name: MyTutorialPool

- 104 of 138 -

Testing Connectiv-ity Between GlassFish and Java DB

Click Finish to store the values. You will see that MyTutorialPool has been added to the Connection Pools list.

Click on MyTutorialPool to see the Edit Connection Pool window. Click on the Additional Properties tab to delete some of the parameters we don't need.

Use the check boxes and Delete Properties button to delete all unnecessary parameters so that your properties list looks like this:

Use the Save button to store your changes.

Return to the General tab and find the Ping button. Click on Ping to test GlassFish's ability to connect with your MyTutorialDB:

“Ping Succeeded” indicates that your GlassFish connection pool can find your MyTutorialDB database. Don't move on until this works.

The Finish button is in the upper-right corner of the page.

This step is important. I have found that if I leave some of the default properties hanging around, GlassFish is unable to connect to my Java DB.

If you don't see Ping Succeeded”, recheck your connection pool properties, save and Ping again.

- 105 of 138 -

Creating a JDBC Resource

Our second GlassFish configuration step is to create a JDBC resource with a JNDI name that maps to our MyTutorialDB. Click on the JDBC Resources node as shown below:

Click on the New button to create a new JDBC Resource as shown below:

Click OK. Your new JDBC resource is added to the list.

GlassFish is now all set to service your application's needs for access to your MyTutorialDB Java DB data store via the JDBC data source with the JNDI name of jdbc/MyTutorial.

For cut and paste, the JNDI Name is: jdbc/MyTutorial

Java Naming and Directory Interface (JNDI) is an API that provides naming and directory functionality to Java applications. Applications use JNDI to lookup and gain access to various components like JDBC resources. So, the JNDI lookup name for our database resource is jdbc/MyTutorial

- 106 of 138 -

Creating a WSDL Based on a Database Table

Now, we can revisit our QuoteLoan BPEL process from Project 3 and add the capability to store loan quote data to the database.

Find your QuoteLoanProcess BPEL process in your QuoteLoan project and display it in the modeling canvas:

Drag a new invoke from the palette into the model right before the ReturnLoanQuote element at the bottom of the model. Rename the new invoke element StoreLoanQuote

This invoke element needs to call out of the BPEL process to our database. We'll need a partner link to “get out of our process,” but what should be on the other end of that interaction? Well, our database ... but it will be the Database binding component that will be our proxy.

All partner links are based on a WSDL. So, we need to create a WSDL that will reference the Database binding component.

The BPEL process is named QuoteLoanProcess.bpel and is under the Process Files hierarchy for QuoteLoan.

We'll just add a new <invoke> element at the end of the BPEL model.

Make sure you are in Design mode.

Here is how we left the model at the end of Project 3.

Partner links provide “channels” to communicate with the world outside the BPEL service engine. The underlying WSDL document specifies details about how to use the “channel.”

To learn more about the Database binding component see its page on the OpenESB site at: http://wiki.open-esb.java.net/Wiki.jsp?page=DatabaseBC

- 107 of 138 -

To create the WSDL, right-click on QuoteLoan in the Projects panel, and select New / WSDL Document.

For File Name, enter LoanQuoteDBWSDL

At the WSDL Type field, toggle on the Concrete WSDL Document option.

For Binding, select DATABASE from the drop-down list.

Make sure that Type is set to Table. Select Next.

From the URL drop-down list, select your MyTutorial [admin on ADMIN] data source. Click Next.

The Available Tables list shows your table:

Select LOANQUOTE and then the “>” button to move the table into the Selected Tables list.

Click Next to move on in the wizard sequence. The Select Operation Specific Attributes step appears. If the window is blank, see the note to the right.

Select Next to accept the defaults. The Enter JNDI Name window appears. If the window is blank, see the note to the right.

The WSDL wizard will read your database schema and create a WSDL based upon the table you specify.

There may be a potential gotcha here in GlassFish ESB v2.1. You may not be able to enter either Operation Specific Attributes or the JNDI Name at this point in the wizard. The wizard may just offer blank windows.

If this occurs for you, just proceed by clicking Next and then Finish. When the WSDL has been created, manually edit the following portion of your WSDL and input the JNDI name:

- 108 of 138 -

Enter your JNDI name as: jdbc/MyTutorial

Select Finish to complete the initial creation of the WSDL based upon your database table.

LoanQuoteDBWSDL.wsdl appears under QuoteLoan and its contents display in the WSDL editor.

Expand its structure. Find the jdbc:input node for insert in the Bindings section shown below. Then, right-click and select Properties:

You need to change two properties here.

Change the paramOrder property to read: LOANTYPE,PAYMENT,PERIOD,AMOUNT

Change the sql property to read:


Save All your work.

This matches the JNDI name we specified earlier when we established our JDBC resource in GlassFish.

We don't include RECORDID in the paramOrder since we will not be passing in a value. Instead, in the SQL statement, we hard-code DEFAULT as the value.

DEFAULT corresponds to this portion of the CREATE TABLE statement we specified earlier: recordid INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY

- 109 of 138 -

insert into LOANQUOTE (LOANTYPE,RECORDID,PAYMENT,PERIOD,AMOUNT) values (?,DEFAULT,?,?,?)

Interacting with a Database via the Database Binding Component

Now that we have a WSDL document that defines the interface to our LOANQUOTE database table, we can create a partner link in our BPEL process that our new StoreLoanQuote invoke element can use to store our data.

Return to your QuoteLoanProcess BPEL modeling canvas.

Drag the LoanQuoteDBWSDL.wsdl document you just created from the Projects panel and drop it to the right side of the BPEL canvas below the existing CalculatePaymentPartnerLink:

A new partner link is added. Rename it to: DBAccessPartnerLink

The Database binding component will act as our communications proxy to Java DB.

To rename, double-click on the default name (PartnerLink1) and replace it.

- 110 of 138 -

Associate StoreLoanQuote invoke you added earlier with the DBAccessPartnerLink by clicking the StoreLoanQuote invoke element's pencil icon and completing the wizard pop-up window as shown:

Click OK and you will see the StoreLoanData invoke associated with the partnerlink:

Now we need to map data from the model into the inputs required by the StoreLoanQuote invoke. So, drag and drop an assign element from the palette and drop it right above StoreLoanQuote.

Rename the new assign element (Assign1) to: PrepareForStoring

Click on the invoke element and the pencil icon will appear above it.

Notice that the partner link exposes five database operations included in the underlying WSDL. We'll just use insert in this tutorial. Update and delete database operations are probably familiar to you. Find maps to the standard Select statement.

The pollrecords may be new. For pollrecords, the Database binding component polls the specified table in the database and, as soon as a record is available, it constructs a message and sends it to through the partner link to a BPEL receive or invoke, for example.

- 111 of 138 -

Double-click on the PrepareForStoring element and complete the mappings as shown here:

Save All your work.

Move to the Source view and select the Validate XML icon to check the generated BPEL syntax for errors. You may see several warning messages:

The first one indicates that the InsertOut variable is not being used. That's OK. We are assuming that the database insertion went smoothly, so we aren't doing anything with the return value that the Database BC provides.

The other warnings indicate that we didn't explicitly cast data types and that automatic casting will be done for us. That's OK. They are all benign warnings. Move on.

Clicking on your target (the output on the right) of the mapping first is key to efficient and frustration-free mapping. That isn't as important here as we aren't adding any BPEL operators like Concat to our mappings, but finding the target first is a good habit to get into.

Of course, in the “real world,” you would use a BPEL exception handler and respond to this possible situation.

- 112 of 138 -

Exploring Packaging in the CASA Editor

Rebuild your QuoteLoan project.

Rebuild your QuoteLoanApplication project.

Redeploy QuoteLoanApplication.

Let's take a quick peek at the packaging for QuoteLoanApplication to see that the Database binding component is now being utilized.

To view the service assembly in CASA, double-click on Service Assembly under the QuoteLoanApplication node in the Projects panel:

Notice that a DATABASE WSDL Port has been added to the service assembly. View its properties to see that it will be serviced by the Database binding component (sun-database-binding):


Right-click on QuoteLoan and select Clean and Build.

Right-click on QuoteLoanApplication and select Clean and Build.

Right-click on QuoteLoanApplication and select Deploy.

Always watch the Output window for the “BUILD SUCCESSFUL” message before moving on.

To display the properties, right-click on the WSDL Port and select the Properties option from the pop-up menu.

- 113 of 138 -

Running a Test Case

Let's run our test again and see if a record is written to the database table. Find your HomeLoanTest under QuoteLoanApplication, right-click it and select Run:

Check the output for the test result. It should be the same as the last time your ran the test case:

Return to the Services panel to find your Java DB connection so we can see if a record was inserted into the LOANQUOTE table:

Watch the Output panel for feedback.

No surprises here.

- 114 of 138 -

Select the View Data option to see that a row has been added to your LOANQUOTE table:

Our new invoke worked! It “called out” of the BPEL engine via the partner link to the Database binding component which interacted with Java DB.

Let's revisit the CASA editor service assembly layout and do a quick review of what we just saw happen:

Due to the way we created the table (create table loanquote (recordid INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,) and our assignment of DEFAULT to recordid in the insert operation, Java DB automatically assigns a sequential value to the recordid column.

If your test case fails, individually retest your two web services by right-clicking on the web service and selecting Test Web Service.

- 115 of 138 -

1. We ran our test case which sent a SOAP document to the LoanQuoteWSDLPort. 2. LoanQuoteWSDLPort delivered the document to the QuoteLoanPartnerLink on the left side of our BPEL model. 3. BPEL execution continued to to the DetermineRate invoke statement and it used the DetermineRatePartnerLink (on the right side of the model) to send a SOAP request to the DetermineRateServicePort.4. DetermineRateServicePort delivered the rate to the model via the DetermineRatePartnerLink. 5. BPEL execution reached the CalculatePayment invoke and it used the CalculatePaymentPartnerLink to send a SOAP request to the CalculatePaymentServicePort.6. CalculatePaymentServicePort delivered the payment to the model via the CalculatePaymentPartnerLink. 7. BPEL execution reached the StorePayment invoke and it used the DBAccessPartnerLink to send a SOAP request to the JDBC port. which did the insert into our Java DB table.8. BPEL execution reached the reply statement and use the QuoteLoanPartnerLink to return a SOAP document to the test case via the LoanQuoteWSDLPort.

Adding an Invoke to Access JMS

Creating a WSDL Based Upon a JMS Queue

In order to appreciate the fruits of our efforts in this project, you'll need a way to view the contents of a JMS queue to which we'll write a message. In Project 0, you'll find steps to download, install and configure HermesJMS. Unless you'll be using another tool, make sure you have HermesJMS ready to use before proceeding. See Project 0.

Let's revisit our QuoteLoan BPEL process and add a capability to send loan quote data to a JMS queue after we write it to our database.

Find your QuoteLoanProcess BPEL process in the QuoteLoan project and display it in the modeling canvas. Drag a new invoke from the palette into the model right before the ReturnLoanQuote element at the bottom of the model. Name it: QueueLoanQuote

This invoke element needs to call out of the BPEL process to the JMS binding component. As with our database “call out” in the last project, we'll need a partner link to “get out of our process.” On the other end of the communication, we'll have the JMS binding component acting as a proxy to the Java MQ JMS message broker that is built into GlassFish.

So, we need to create a WSDL as the basis for our partner link and that WSDL will reference the JMS binding component. Let's create our WSDL. Right-click on QuoteLoan in the Projects panel, and select New / WSDL Document

For File Name, enter LoanQuoteQueueWSDL

Toggle on the Concrete WSDL Document radio button at the WSDL Type field.

We'll add an <assign> and <invoke> pair. The <assign> will populate the text message and the <invoke> will interface with the JMS queue via the JMS binding component.

Double-click on QuoteLoanProcess to display it in the BPEL editor.

It's highlighted in red since we haven't wired it up to a partner link yet.

So, it is the same “dance” as last project. It's just that we have a different communication proxy (binding component).

I bet that, like me, you probably have a bunch of windows open and there are tabs galore in the middle window. I like to clean up periodically by going onto one of those tabs (like QuoteLoanApplication.casa), right-clicking on it, and selecting the Close All Documents option. If something needs to be saved, you will be prompted. It sure reduces the clutter!

- 116 of 138 -

Project 6: Sending Loan Quotes to a JMS Queue

In the last project, we exercised the Database binding component to store a record of a loan quote in a database table. Here, we'll explore another common requirement – writing messages to JMS queues. We will use the JMS binding component to add a simple loan quote text message to a queue. Then, we'll use the HermesJMS tool, that you installed in Project 0, to verify that our JMS queue integration is successful.

For Binding, select JMS from the drop-down list.

For Type, select Send from the drop-down list.

Click Next to advance the wizard.

For Connection URL, enter: mq://localhost:7676

For User Name, enter: admin

For Password, enter: admin

For Message Type, the default (text) is fine. Click Next to advance the wizard.

For Destination, specify LoanQuoteQueue

Click Finish to accept the default Destination Type (Queue) and to end the wizard sequence. Your new LoanQuoteQueueWSDL.wsdl file displays in the WSDL editor.

Spend a few moments using the Properties panel to explore the following WSDL sections:

• Messages / JMSInputMessage / part1: Notice that the message sent to the JMS queue will contain a single string field name part1

• Port Types / JMSOutPortType / JMSOutputOperation: See that the interface exposes only one port and that this port will expect our part1 as input

• Bindings / JMSOutBinding / JMSOperation / jms:operation: Find that its destination is the LoanQuoteQueue

• Bindings / JMSOutBinding / JMSOperation / input1 / jms:message: Notice that the message to be placed on the queue is a text message (not XML, or map or any other kind that the JMS API allows) and that message will be from the part1 section of input1 message

It will be a one-way (out) interaction since we are simply writing to the queue. Later in this project, we'll create another application that reads from the queue. That will be a one-way interaction also. It fact, it will be based on this very same WSDL.

It's great that the wizard helped you fill-in all these details. Editing each of these values in the Property window can be tedious.

- 117 of 138 -

Click on the Validate XML icon to see if we missed any required configuration.

Save All your work.

Return your focus to the QuoteLoanProcess BPEL canvas. The QueueLoanQuote invoke we added earlier needs a corresponding partner link. With the WSDL we just created, we can create that partnerlink. Our new WSDL document provides the basis.

Drag and drop the LoanQuoteQueueWSDL.wsdl node from the Projects panel to the right side of the BPEL canvas below DBAccessPartnerLink:

The new partner link appears. Rename it QueueAccessPartnerLink

Hopefully, you'll see:

Double-click on the partner link name to rename the element,

- 118 of 138 -

Link the QueueLoanQuote invoke element to this new partner link by clicking the pencil icon above QueueLoanQuote and filling-in the pop-up window as shown below:

Click OK to link the invoke element to the partnerlink:

Add an assign node ahead of the QueueLoanQuote invoke so we can establish the content of the JMSOutOperationIn variable. Rename it PrepareForQueuing

Notice that there is no Output Variable to specify as this is a one-way message exchange pattern. In the input variable, we put what we want the JMS binding component to send. We don't expect any output back.

Ins and outs can be a bit confusing. Think of the Input and Output variables from the perspective of the partner link and, ultimately, the target JBI component (JMS binding component here). What seems like “output” from the BPEL process perspective is really “input” to the partner link and the JBI component. So, you ins and outs perspective should be from the perspective of what's on the other end of the “channel” you are specifying with your partner link.

This is where we will assemble the text message that the invoke will place on the queue.

- 119 of 138 -

Double-click on the new PrepareForQueuing assign to display the Mapper. Create the mappings:

Save All your work.

From Design mode, validate the BPEL process. Ignore the warning about our not using the InsertOut variable. We are still naively assuming that the database insert always succeeds.

Clean and Build the QuoteLoan project.

Clean and Build the QuoteLoanApplication project.

Deploy the QuoteLoanApplication project.

Let's briefly explore the structure of the service assembly in the CASA Editor before we test the BPEL process to see if it outputs to our JMS queue.

Here is some detailed help:

Click first on the part1 (under Variables) in the output (right side). That gives you a blue insert area within which to build the concatenation.

Select a Concat operator from the String menu to add it to the blue insert area.

Select Current Date & Time from the Date & Time menu to add it to the insert area.

You'll need to move things around a bit. Wire up the Current Date & Time to the first String slot in the Concat.

Use the String menu to add four String Literal elements for the labels (like Loan Type).

Wire up the field values as shown.

Don't forget to wire up the bottom String node of the Concat to the part1 element of JMSOutputOperationIn. Otherwise, your concatenation won't be assigned to the partner link's part1 input variable.

- 120 of 138 -

Testing Queuing of Loan Quotes

View the service assembly in the CASA Editor again to see that a JMS WSDL Port has now been added to your service assembly:

Rerun your HomeLoanTestCase in QuoteLoanApplication. several (three or four times):

Right now, it's a mystery whether our new QueueLoanQuote actually wrote a text message to our JMS queue. So, let's check the GlassFish admin console to see that the LoanQuoteQueue was created when we ran our test cases.

In your browser, go to GlassFish Admin Console: http://localhost:4848/

Log in if you need to:● userName: admin● password: adminadmin

To see the service assembly, double-click on Service Assembly under the QuoteLoanApplication node.

If you check the Properties for the JMS WSDL port, you'll see that it will be hosted by the JMS binding component (sun-jms-binding).

You could also go to the Admin Console by right-clicking on the GlassFish V2 node in the Services panel and selecting View Admin Console option.

- 121 of 138 -

Expand the Configuration node at the left and check the Java Message Service's Physical Destinations:

Notice LoanQuoteQueue. So, the queue was created when we ran the test, but did our message get added to the queue?

To check, we'll use the HermesJMS tool that you installed and configured in Project 0.

- 122 of 138 -

Use the Windows Start / All Programs / HermesJMS / Hermes sequence to start HermesJMS.

Since we have already configured HermesJMS in Project 0, we can expand the sessions / JavaMQ hierarchy and see our queue:

Double-click on LoanQuoteQue to see its contents:

If you click on a row representing one of the messages, you can see it's contents in the lower panel.

Since we see the messages, we have confidence that the addition of the QueueLoanQuote invoke in our BPEL process worked. Success!

Flush the queue by selecting all the message rows , right-clicking and choosing the Delete option. Click the Refresh now control to update the display.

Exit HermesJMS by using the File / Exit option.

If you don't have HermesJMS installed and configured, go to Project 0 to learn how to get it up and running.

To select multiple rows, use Ctrl-click on each.

- 123 of 138 -

Above and Beyond: Logging in a BPEL Process

Debuggers are are nice, but sometimes they are overkill. For example, maybe you just want to dump a text message out to the GlassFish log file when BPEL process execution gets to a particular point. As a Java programmer, you may be familiar with sprinkling System.out.println(“message here”); throughout your code. It is nice to know how to do that for your BPEL.

Return to the Design mode for your QuoteLoanProcess.bpel BPEL process.

Let's assume that it would be handy to write out a message like this to the GlassFish log file each time a loan quote is processed:

Auto loan quoted with monthly payment: 250.21

Let's add this logging capability to our business process, so single-click on the ReturnLoanQuote reply element at the bottom of the model.

Find the Logging control at the top of the editor canvas and click on it to enter Logging mode.

Expand the nodes on the left that represent variables whose contents can be sent to the log. Expand the nodes on the right. They represent where and how to deliver the log messages

Click on the LOG_onComplete / info node on the right to display the blue entry area as shown above.

We'll watch for the messages to appear in GlassFish standard out (stdout). That's the server.log file.

The tooling will refer to these logging statements as traces.

The Logging canvas looks very similar to the Mapper that we have used for our assign statements.

- 124 of 138 -

Use a String / Concat element to perform the mappings as shown below to build your log message and send it out when the logging level is a info level or greater:

The text to concatenate is:

loan quoted with monthly payment:

Save your work and return to the Design mode.

Validate your BPEL model and save your work. You may see a warning error about the InsertOut variable not being used. That's OK. We are assuming that all database inserts will be done correctly, so we aren't checking the return value from the insert operation on the DBAccessPartnerLink.

Notice the blue icon next to the ReceiveMessages element indicating that logging (tracing) statements have been added:

This is a nice reminder to you on where you have placed your debugging/logging statements. These are often temporary insertions done during development. You'll likely remove many of these before going into production.

You see that you can add messages before (onStart) or after (onComplete) an element executes.

“Info” is one 7 log levels that can be set in the GlassFish logging system. “Info” is the default for most GlassFish subsystems. So, if we assign a message to the “Info” level, we'll see it in the log file without doing any configuration of the logging facility.

This will copy the queue message to the GlassFish log file as long as the GlassFish logging level is set at info level or above.

- 125 of 138 -

Clearing the Log Display

Clean and Build your QuoteLoan project.

Clean and Build your QuoteLoanApplication.

Deploy QuoteLoanApplication.

Rerun your HomeLoanTestCase.

Look at the bottom of the GlassFish log (server.log file) now by scrolling through the GlassFish V2 tabbed panel in the Output window to see your message:

Clearing the log display periodically is a good debugging tip. It makes it easier to see what just happened.

Find the GlassFish V2 Output panel, right-click and clear its contents so you see the latest results of your next run:

Run your HomeLoanTestCase again and you see only the latest results. Success! We verified that QuoteLoanApplication is writing messages to the LoanQuoteQueue and we learned about logging in the BPEL tool.

Watch the Output panel for any error messages.

- 126 of 138 -

● We started out by working through the installation and configuration of the JDK, GlassFish ESB and HermesJMS.

● We then began pondering a tiny proof-of-concept (POC) project for a fictitious financial firm that demonstrates loan quoting by orchestrating two Web services:○ One service determines an interest rate

given the loan type ○ Another service calculates a loan payment

amount given the interest rate, amount and loan period.

● We tackled the POC in phases across several NetBeans projects.

● In our first project, we created DetermineRateService as an EJB module that takes a loan type in and generates an interest rate as output. We tested it using the NetBeans-generated test page.

● For the second project, we created CalculatePaymentService as a web application. This service takes three input arguments (amount, rate and period) and produces a loan payment amount as output. We again tested it using the NetBeans-generated test page.

● In our third project, we created a BPEL process called QuoteLoanProcess to orchestrate the serial execution of our two Web services.

In an “above and beyond” opportunity, we explored using the Java debugger.

In another “above and beyond” segment, we saw hot to output messages to the server log to help debug Java code.

- 127 of 138 -

Summary

We covered a lot of ground in these six projects. Thanks for hanging in there. Here are the highlights.

● In order to call our QuoteLoanProcess, we needed a WSDL interface. Creating the interface was a two-step process. First, we defined the data types in an XML schema. Then, we built the WSDL document (importing the XSD type information) that became the public interface for the process.

● Our implementation of the BPEL process did not involve any Java. Instead, we used the graphical editor to "draw out" a business process from which NetBeans generated the appropriate BPEL syntax.

● We created a composite application called QuoteLoanApplication and added our QuoteLoanProcess to it. We then deployed it to the application server's JBI environment. We created a test case to test the application. The BPEL service engine hosted our BPEL module at runtime.

● In the fourth project, we built a web application called LoanQuoteUI to provide a browser-based GUI to exercise the QuoteLoanProcess. We were introduced to auto-generation of client side code required to exercise the Web service that wraps QuoteLoanProcess.

● In the fifth project, we added the capability to our BPEL process to write out a loan quote record to a Java DB database table using the Database binding component.

● In the sixth project, we extended the BPEL process again by writing loan quote records to a JMS queue by using the JMS binding component.

“Above and beyond” segments explored two topics. First, we worked with the CASA Editor to deploy a service unit to the Java EE service engine. Next, we worked with the BPEL debugger.

In “Above and Beyond” for Project 4, we investigated how NetBeans uses Ant tasks for compilation, packaging and deployment. We added a new task and modified an existing one.

“Above and Beyond” here let us add logging statements to elements in our BPEL model.

- 128 of 138 -

- 129 of 138 -

Self-Assessment

Anything worth doing well is worth measuring, especially learning. It's the best investment you can make. So, take a moment to test yourself on what you have learned about Open ESB, NetBeans, GlassFish and JBI-based, composite application building.

If you have questions about the answers provided below, please send me an email at ([email protected]). I would enjoy hearing from you.

1. Explain the driving philosophy behind Java Business Integration (JBI)? JBI is to do for integration what Java EE did for applications development for server-side Java.

Java EE defined two standard containers (web and EJB) and a set of services that each container must provide. JBI defines a container environment for integration that hosts service engines to house application logic and binding components to provide communications proxeis to interact with resources outside the JBI container. Java EE helped reduce vendor lock-in and specified an overall architecture for monolithic, enterprise-class, server-side Java applications. Similarly, JBI addresses vendor lock-in and encourages an ecosystem for integration where vendors compete on implementation rather on “secret sauce.”

2. What are the three fundamental elements of the JBI container architecture and what is the role of each of them?

The three fundamental elements are: Normalized Message Router (NMR), Service Engines (SEs) and Binding Components (BCs). SEs provide mini-containers where the logic of an application is housed while BCs act as communication proxies to resource outside the JBI container. Between SEs and BCs, JBI prescribes an in-memory bus, called the NMR, that assures loose-coupling. The NMR acts as a intermediary so that SEs don't directly communicate with other SEs or BCs.

3. What is the role for a Java EE application server in a JBI architecture?

The JBI 1.0 specification, JSR 208, is careful not to require an application server. So, a vendor implementing a JBI container can do so atop just Java SE, for example. The Open ESB team initially decided they would enjoy the power of having a web container and an EJB container “under the hood,” so they began building atop GlassFish. However, there are JBI implementations that do not require a GlassFish implementation. Sun has shared some of their work in the Open ESB community. The Apache ServiceMix project has done substantial work on JBI atop just the Java SE JVM.

4. Identify what Java EE components can provide implementations for web services? Both servlets and stateless session EJBs can provide implementations that are surfaced as

web service endpoints.

- 130 of 138 -

5. What defines the interface to a web service?

A web service is defined in an XML document in a form called Web Service Description Language (WSDL). A WSDL interface definition provides abstract characteristics that are logical in nature and concrete attributes that define protocols and physical addresses.

6. What does best practice tell us about where we should define data types used in a web service interface definition?

Data type definition may be done inside the WSDL interface definition document in its <types> section. However, a best practice is to instead define data types in a separate XML Schema Definition (XSD) document that can be referenced in the <types> section of the WSDL document. This keeps the data types definitions separate and allows multiple WSDL documents to utilize the same, shared data type definitions.

7. How can you easily test a web service you have created in NetBeans?

Once you have deployed the web service, you can right-click on it in the Projects panel and select Test Web Service. A browser page appears allowing you to provide inputs, send the request to the web service and see the results. This built-in testing facility works well if parameters are simple data types like strings or numbers. If inputs are XML structures, use the soapUI plug-in that can be downloaded from the plug-in center. It allows you to use complex structures (XML documents) for questions and responses.

8. What is the main role for BPEL in a SOA-based application?

Although BPEL started out as a higher level, programming language for business analysts, it seems to have been “hijacked” by the web service community to fill the role of orchestrating invocations of web services. The name of the latest BPEL spec. alludes to the “hijacking.” The “WS” in “WS-BPEL 2.0” stands for “web services.”

9. What BPEL construct do you create in order to support communications outside the BPEL service engine and what XML document underlies the definition of this BPEL construct?

A partner link provides a “communications channel” or “portal” to the world outside the BPEL container. A partner link is based upon a Web Services Definition Language (WSDL) XML document that defines the interface provided by the partner link.

10. [Fill in the Blank] Testing a BPEL process in NetBeans is often just like calling a ____________________. You just send a __________ - formatted message over _______________________.

Testing a BPEL process in NetBeans is often like calling a “web service.” You just send a “SOAP”-formatted message over “HTTP.”

- 131 of 138 -

11. [True or False] A BPEL process can be directly invoked by receipt of a message on a JMS queue.

True. You can invoke/initiate a BPEL process via arrival of a message on a JMS queue. Just, create a WSDL that specifies a one-way message exchange. In the concrete portion of the WSDL, specify that the JMS is the type of the one-way exchange.

12. What is a message exchange pattern (MEP) and what two MEPs are supported by NetBeans tooling.

A message exchange pattern (MEP) is a style of interaction between a consumer and a provider. The two styles supported by NetBeans and JBI include request/response and one-way.

13. What Java technology automatically takes care of the marshaling and unmarshaling of XML during web service invocation?

The core technology for marshaling and unmarshaling between XML and Java objects is provided by JAXB (Java API for XML Binding) technology. It is used by Open ESB encoders/decoders to allow a developer to easily map to and from XML documents.

14. You need a browser-based user interface to call a BPEL process from a button handler for a JSP-based web page. What do you need to do in NetBeans in order to create the required communication facility between the web page and the BPEL process.

You need to create a web service client resource in your project by pointing NetBeans at the WSDL for the destination web service. The web service client is the JAX-WS client-side stubs to facilitate the remote interaction. Next, you insert a “Call Web Service Operation” into your button handler. This addition inserts code into your editor that handles the execution of the client-side stubs (web service client). Finally, you specify the data in your handler that will be passed to the web service through the client-side stubs.

15. You build a BPEL module containing a BPEL process that references a couple of simple EJB-based web services. In assembling your composite application, you just add a single JBI module (the BPEL module). What JBI service engines (SEs) will be used at runtime?

The BPEL SE will host execution of the BPEL process while the two EJB-based web services will not execute in a service engine. Instead, they will execute as just EJB modules in the GlassFish application server. If you want the EJBs to execute in the Java EE SE. you would individually add their EJB modules to the composite application.

- 132 of 138 -

16. [True or False] A typical developer is probably going to have to write at least one JBI component within the first six months of using Java CAPS 6 JBI technology on a real project.

False. A typical application developer will use JBI components (service engines and binding components) created by the JBI container vendor or a third-party. Java EE programmers don't create web containers or EJB containers. JBI components are infrastructure like these Java EE containers. The typical developer creates applications whose service assemblies are deployed the the mini-containers that SEs and BCs provide. These SEs and BCs are supported by an infrastructure vendor like Sun.

17. What BPEL construct is used to exercise a request/response message exchange with a web service through a partner link and what BPEL construct is used to gain access to the result that the web service provides?

You use an <invoke> element to initiate communication with the web service hosted outside the BPEL engine. After an <invoke>, you typically have an assign statement that retrieves the result passed back through the partner link's output variable.

18. Explain how to utilize the NetBeans BPEL debugger in order to analyze a misbehaving model?

In the Projects panel, find the composite application that contains the BPEL module where you created the BPEL process. Right-click on the composite application and select the Debug (BPEL) option. Then, display your BPEL process in the editor and toggle on one or more breakpoints. Finally, in the Projects panel, find your test case under your composite application, right-click and select the Debug option. This will send the test case request to the BPEL engine and execution will stop at the first breakpoint.

19. How can you add logging/tracing statements to your BPEL model in order to assist in troubleshooting and where does the output display?

In Design mode of the BPEL editor, click on the element where the logging/tracing statement should be inserted. Then, click the Logging tool to enter logging mode. Use the loggin mapper's Concat operation to add the output message to the appropriate logger level.

20. Inside your BPEL-driven application that interfaces with a JMS queue, how do you configure the details required to log into the message broker and access the right queue?

These physical details (like port number, ID and password) are specified in the concrete portion of the WSDL that underlies a partner link in a BPEL model.

- 133 of 138 -

21. What convenient NetBeans feature makes it easy to build the WSDL document describing the interface to a particular database table?

When you are creating a new WSDL, the wizard prompts you for the binding type for the concrete portion of the WSDL. If you select DATABASE/Table, the wizard will allow you to select a URL for a connection to the database. Then, the wizard will prompt you to select the table from the schema it has retrieved from the database. The wizard creates an XSD document to match the layout of the selected database table. That XSD is referenced in the <types> section of the newly created WSDL document.

22. How do you temporarily disable a composite application that you have already deployed?

A composite application is deployed as a service assembly to the JBI framework. Service assemblies are listed in the Services panel under GlassFish V2 / JBI / Service Assemblies hierarchy. To temporarily disable a service assembly, right-click on it and select Stop.

23. What is the role of the CASA Editor in building a composite application in NetBeans?

To paraphrase the online help system, The Composite Application Service Assembly (CASA) editor provides a visual interface to assemble a composite application. The editor allows you to interactively modify the application deployment configuration.

24. Where on the web do you go if you need to download a JBI component? After you download it, how do you install it in NetBeans?

To find a JBI component for Open ESB, go to the download page at https://open-esb.dev.java.net/Downloads.html. Find the Components section. It may be labeled “v2 Compatible Components” or “Components build for v2.1,” for example. Choose the section that matches the release of GlassFish ESB you are using. Click the “Choose component(s)” button to view a list of all the components. Then, click the “download” link next to component you need. Once the component jar file is downloaded, install the component in NetBeans by executing the jar file on in a command window (java -jar path-to-jar).

25. You have a new JBI component installed. What else might you have to download and install in order to be able to use it in NetBeans?

For many (most?) JBI components, NetBeans plug-ins are provided to extend the NetBeans IDE with powerful design time tooling that makes it easier to utilize an installed JBI component. If you install a component as discussed in question 24, the NetBeans plug-ins are installed as the JBI component is installed.

26. What build facility is used extensively in NetBeans in order to do compilation, packaging and deployment?

Apache's Ant is the build facility. To read about how it is used in NetBeans, go to the online help (Help / Help Contents menu bar option) and search for “Ant.” Find the section titled “Working with Ant” in the search results.

- 134 of 138 -

27. During troubleshooting, you want to investigate the BPEL statements that NetBeans has created as you used the graphical model editor. How do you see these statements? What happens to the graphical model if you make changes to these BPEL statements?

You can see the generated BPEL statements by clicking on the Source control at the top of the BPEL editor. If you make a change to the BPEL source statements, they will be immediately reflected in the graphical, Design mode.

28. In NetBeans, how can you watch GlassFish's log file (standard out or stdout) as you troubleshoot?

Find the GlassFish V2 tabbed panel in the Output area. If you can't see the Output area, use the Window / Output / Output menu sequence to display it. If the GlassFish V2 tabbed panel does not appear in the Output, go to the Services panel, right-click on the GlassFish V2 / View Server Log option.

29. You can't find the palette window during BPEL modeling or JSP/JSF page layout. How can you display the palette in NetBeans?

Use the Window menu bar option and select the Palette option there.

30. What database product is packaged with NetBeans and how would you quickly create a test database and table to use in your unit testing?

Java DB is packaged with NetBeans It is also packaged as part of the Java Standard Edition. To create a test database in NetBeans, right-click on the Databases node in the Services panel and select the Create Database option. Specify login credentials. The execute your SQL table create statements from the NetBeans SQL interface.

31. In order to utilize the JDBC binding component to access your database, what two configuration steps need to be done in the GlassFish administration console?

You need to first establish a JDBC connection pool so that GlassFish can “talk” to your database. Next, you must create a JDBC datasource that utilizes that connection pool. That datasource will have a JNDI lookup name that you use in configuring the WSDL that defines the linkage to the Database binding component.

32. You want to test your use of the JMS binding component in your composite application. What configuration steps do you need to do in GlassFish in order to prepare the message broker and queue.

You don't need to do anything. All the configuration is done in the WSDL that describes the interface to the JMS Broker. At runtime, if the queue does not exist, it is automaticially created for you by the message broker.

- 135 of 138 -

33. What is a NetBeans “plug-in” and how do you update your NetBeans with the latest plug- ins?

NetBeans is an extensible GUI framework. The NetBeans IDE is built atop the NetBeans framework. The IDE can be extended by adding modules called “plug-ins.” The latest plug-ins are conveniently available from the plug-in center that is accessible via the Tools / Plugins menu option. You can also download a plugin (one or more NetBeans Module (nbm) files)) and install them using the Plugins window.

34. Explain how you can see a list in NetBeans of all JBI components that are installed in your runtime environment.

Go to the Services panel and expand the JBI hierarchy under GlassFish V2. Under the Service Engines node, you'll find all the installed SEs. Under Binding Components, you'll see all the installed BCs.

35. Explain the terms “service unit” and “service assembly” and how they map to the notion of a composite application. What NetBeans tooling allows you to investigate your service units and service assemblies?

The JBI 1.0 specification says that service units are component-specific artifacts that are installed into an engine or binding. The spec says that services assemblies are groupings of service units and that a deployment descriptor is provided to detail which JBI components are to house which service units. So, as you create a BPEL module in NetBeans, you are building a service unit. As you add that BPEL modules and other modules to a composite application, the composite application defines a service assembly. In the Services panel, under the JBI hierarchy, you can expand the Service Assemblies node and see all deployed service assemblies. If you expand an individual service assembly, you'll see its service units.

36. You just copied and pasted a bunch of Java code into a method. How do you pretty-print (reformat it based upon language structure) in the editor so it is easier to read?

Use the Source / Format menu bar option or just use the Alt-Shift-F keyboard shortcut.

37. What application servers can host a NetBeans-created, packaged and deployed SOA composite application?

NetBeans creates SOA composite applications that are deployable to a JBI runtime. NetBeans tooling assumes that that JBI runtime is hosted atop the GlassFish application server. NetBeans doesn't provide tooling for a JBI runtime atop any other application server.

38. How do you check in NetBeans if your EJB-based web service actually got deployed to the runtime environment?

In the Services panel, expand the Servers / GlassFish V2 / Applications / EJB Modules hierarchy and look for your module there.

- 136 of 138 -

39. Describe how to initiate the Java debugger in NetBeans so you can step through the implementation of a web service operation.

First, right-click on your module in the Projects panel and select Debug to deploy the module in debug mode. Second, set a breakpoint in the source code of you web service. Third, right-click on your web service in the Projects panel and select Test Web Service. Enter test values for input parameters and send the input message. Execution will pause in your web service code at the breakpoint you set.

40. During a Java or BPEL debugging session, you have found your problem while stepping through the statements. How would you immediately end the debugging session?

Find the red square icon (Finish Debugger Session) at the top of the editor and click on it to end debugging.

41. You have quickly created a web service in NetBeans without first creating the interface definition. In other words, you have let NetBeans create the interface definition for you based upon the implementation you provided. You have deployed the web service and tested it, but you want to view the interface definition. You can't find it in the project. How do you view it?

Find your web service under the Web Services node in the Project panel. Right-click on your web service name and select Properties. At the bottom of the Properties window, you'll see the URL to access the WSDL. Copy it to the keyboard buffer and paste it into your browser to see the WSDL for the web service.

42. Describe how NetBeans code templates make it easier to type boilerplate statements like System.out.println(””);

According to the NetBeans online help, “You can reduce the number of keystrokes when you are typing code by typing abbreviations to generate code from templates. The abbreviation is expanded into the template after you press the Tab key.” You can find the templates that are in place by using the Tools / Options menu bar option and entering Editor mode on the Options window. Scroll down the list of abbreviations to see that sout is associated with expanded text of System.out.println(“${cursor}”)'

43. What role does the <reply> construct have in BPEL and why might you have a BPEL model without a reply?

The <reply> allows a BPEL process to send back output to the initiating client in a request/response message exchange pattern. You wouldn't have a <reply> if the BPEL process was an in-only, one-way message exchange.

- 137 of 138 -

44. Why is WS-I Basic Profile important and give an example of how NetBeans helps you honor WS-I Basic Profile.

There are three particularly key specifications that underlie web services. These include: WSDL, SOAP and UDDI. All three specifications are comprehensive and complex. It has been difficult for all vendors to implement them in their entirety. In addition, the specifications are open to conflicting interpretations. The result is that web service clients developed on one vendor's technology may not be compatible with a web service atop another vendor's infrastructure. To enhance the probabilities that clients and services can interoperate, the WS-I Basic Profile focuses on a subset of the WSDL, SOAP and UDDI specifications and provides clear rules on how they are to be interpreted. If a client and a service are WS-Basic Profile compliant, there is good reason to expect them to be able to work together. You can see NetBeans enforcement of WS-I Basic Profile in creating a SOAP-based WSDL. If you select Document Literal (instead of RPC Literal or RPC Encoded) but then specify a message structure that is not based upon Complex Types and Elements, you'll see an error message indicate that rule R2204 has been violated.

45. How can you find out if you have created a syntactically correct and well-formed WSDL or XSD document?

Use the Check XML and Validate XML controls above the editor panel.

46. What is the role of the Mapper tool in NetBeans' BPEL editor and what BPEL construct are you building when you are using the Mapper?

The Mapper is used the map values from one variable to another. Behind the scenes, the BPEL editor is creating <copy> statements.

47. What is the main virtue of running Java EE-related implementations in the Java EE service engine rather than running them in the standard GlassFish web or EJB containers?

Performance is enhanced if Java EE programming artifacts like web services based servlets or EJBs are run in the Java EE SE. The enhancement is due to not having to utilize binding components to access these capabilities. Instead, the communication stays inside the JBI container and exchange is made immediately across the NMR without having to “come in from the outside” and utilize a binding component to pass the message to the NMR.

48. What NetBeans tool do I use to specify that a Java EE-related implementation should run in the Java EE service engine?

Use the CASA Editor to drag the web or EJB module onto the assembly canvas. When the composite application is assembled, you'll see that CASA assigns these components to the Java EE service engine.

- 138 of 138 -

49. You see an error message identifying a line number in your BPEL process where execution failed. You bring up the BPEL editor in NetBeans to analyze the BPEL statements, but you don't see any line numbers displayed in Source mode. How do you turn on the line number display?

Click on the View menu bar option and toggle on the Show Line Numbers option.

50. You think you have done your configuration of GlassFish correctly so that the JDBC binding component can talk to your database. Before moving into your work utilizing the JDBC binding component, how do you quickly test to see if GlassFish can talk to your database?

At the Connection Pool panel in the GlassFish Admin Console, select your connection pool and test it by clicking the Ping button. If GlassFish can “see” your database through your connection pool, you'll see a message indicating that the ping was successful. Then, you are ready to create a JDBC resource for that connection pool and to use it in your application.

I hope you enjoyed this tutorial experience and appreciate your interest in GlassFish ESB, OpenESB, Java CAPS, NetBeans and/or GlassFish.

Please provide feedback on this tutorial to: [email protected].

Date post:	04-Apr-2018
Category:	Documents
Upload:	votram
View:	224 times
Download:	6 times