Update: Using the JBI JavaEE Service Engine

Previously I wrote about how to use the JBI JavaEE Service Engine to increase performance when orchestrating EJB Services created in Glassfish with the BPEL Service Engine in OpenESB. That was almost 8 months ago and Netbeans and OpenESB have changed a lot and consequently I needed to update it.

So I would like to provide an update using the latest Netbeans (20080402).

Again, if you haven't already, go ahead and download and install OpenESB which includes Netbeans v6 and Glassfish v2.

1. Create an EJB Module
• File > New Project > Category Enterprise > Projects EJB Module
2. Create a new Web Service
• Right click on your EJB Module project
• Choose New > Web Service
• Add a new Operation
3. Create a new BPEL Module
• File > New Project > Category SOA > Projects BPEL Module
4. Create a new BPEL Process
• Right click on your BPEL Module project
• Choose New > BPEL Process
  
5. Create a new SOAP WSDL
• Right click on your BPEL Module project
• Choose New > WSDL Document
• Go through the wizard and for the Binding Type make sure its SOAP
6. Configure your BPEL Process by dragging the SOAP WSDL onto the left side of the BPEL Process.
• Add the standard "buttons" to the BPEL Process Sequence
• Receive
• Assign
• Invoke
• Assign
• Reply
7. Utilize the EJB Web Service in the BPEL Process (this is where things are different than in past versions)
• Right click on the Web Service under the EJB Module and select Generate and Copy WSDL
• Uncheck Do no copy if it is checked.
• Expand your BPEL Module and copy the WSDL into the BPEL Module's src directory.
• Now you should have a copy of the Web Service's WSDL in your BPEL Module.
• Drag this new WSDL onto the right side of the BPEL Process so that we can tie the Invoke call to it.
8. Create a Composite Application
• File > New Project > Category SOA > Projects Composite Application
• Right click on the new Composite Application and select Add JBI Module
• Add both your BPEL Module and EJB Module
• Clean and build the Composite Application (Right click > Clean and Build)
• View your CASA file by double clicking on the Service Assembly file under your Composite Application.
9. Your CASA file should look something like this
10. Now you should be able to start Glassfish and deploy your Composite Application. Now your BPEL Process will utilize the Java EE Service Engine. FYI, do not deploy the EJB Module separately since its included in the Composite Application.
    

Comparing Open Source Web Service Stacks

Here is one of the best articles I have read comparing the various open source web service stacks. Previously I have always referenced this page, which is still an excellent source of information. The author interviews lead developers from each project: Apache Axis2, Apache CXF (previously known as XFire), Spring Web Services, JBoss WS, and Sun's Metro.

First my opinions. Axis1 was one of the first open source stacks available and Axis2 was suppose to be a complete overhaul. From other articles I have read the performance isn't that great and my first use of it wasn't a good experience. I have had really good luck with XFire and really like how it is just a jar that you can include in your WAR. Spring Web Services is really new (they just released version 1.0). I really like the spring products and wouldn't hesitate to try this one. Their documentation is really good and they emphasize a top-down approach (which is honestly the best way, but not the most fun). Not sure why anyone would use JBoss WS if it isn't portable to other containers. Based on their wiki they only state it works in JBoss. Sun's Metro is making a lot of headway and I would recommend it to anyone. It seems to be the most mature in implementing the newer WS-* specifications and boasts the ability to interoperate with .Net services.

Back to the article. Here are some highlights for those not wanting to read the entire article:

1. CXF can support returning JSON
2. Use SXC to improve JAXB performance.
3. Axis2 is the only one supporting WSDL 2.0
4. All except Spring-WS and JBossWS implement WS-Addressing and WS-Reliable Messaging
5. Metro is the only stack with support for WS-AtomicTransaction and WS-Coordination, which are hooked up to J2EE/Java EE transactions.
6. CXF supports REST via annotations similiar to JSR 311. Spring-WS doesn't support REST.
   

Using the JBI JavaEE ServiceEngine

Update April 10th, 2008
An update has been provided on how to use the Java EE SE in the latest version of Netbeans. Please go here to read this update.
----------

In order to familiarize myself with different JBI components I would like to walk through an example using the JBI JavaEE Service Engine written by Sun. So what is the JavaEE Service Engine? It's a highly useful JBI component providing a bridge between the web container (glassfish) and the JBI container (OpenESB), or more specifically the NMR (Normalized Message Router). It's useful because it allows EJBs and Servlets, packaged as web services, to communicate directly with JBI components and vic versa. Consequently, this increases performance since the request/response doesn't have to travel in and out of the HTTP BC and the glassfish Servlet container.

So if you are writing EJB 3.0 web services, you have alot to gain by using BPEL and JBI in general, and you need to look into using the JavaEE SE. The following is a simple example of how to use it.

If you haven't already, first start out by downloading the latest OpenESB installer which includes Netbeans 6.0. Then follow this video tutorial to create a Composite Application consisting of a BPEL process invoking an EJB web service (but not using the JavaEE SE yet). This will help us create our web service and get familiar with BPEL and Netbeans. If you prefer to skip this step I have uploaded the EJB Module, BPEL Module, and Composite Application for convenience. After completing this step your casa file should look like this (in netbeans, right click on the CompositeApplication and click Edit Application Configuration):



Notice there are no endpoints for the JavaEE SE. Here is the sequence of events when running the test included in the HelloBPELCompositeApp:
http client --> inbound HTTP BC --> BPEL SE --> outbound HTTP BC --> Glassfish Servlet Container --> invoke Hello web service --> response.

The next step is to actually utilize the JavaEE SE advantages. This only requires adding the EJB module as a JBI module to the HelloBPELCompositeApp. In JBI you can add multiple JBI Modules (Service Units) to Composite Applications (Service Assembly). In netbeans, right click on HelloBPELCompositeApp and click Add JBI Module. Select Hello, which is the EJB Module. If you expand the JBI Modules directory under HelloBPELCompositeApp, you should see Hello.jar and HelloBPEL.jar. Before we can redeploy we first must modify the casa file to remove the existing connection between the outbound HTTP endpoint and glassfish. Reopen the casa file (in netbeans, right click on the CompositeApplication and click Edit Application Configuration), and highlight the line going between the HelloRole_partnerRole Consumer to the HelloPort Provider. Your casa file should look like this now and this verifies that we are going through the JavaEE SE:



--
April 8th, 2008 Update
Since this post is pretty popular I have an update since this post doesn't work with the latest version OpenESB+Netbeans. Not only do you have to remove the line as described above, but you also need to remove the SOAP Port, otherwise you will receive an "java.net.BindException: Already bound: 8080". So in the image above highlight and delete the HelloPort.

Also in newer versions of Netbeans access to the CASA file is done by double clicking on the Service Assembly file under your Composite Application project.
--

Rebuild HelloBPELCompositeApp by right clicking and choosing Clean and Build. Then undeploy and deploy HelloBPELCompositeApp. Finally rerun the test and it should pass. Again we know the JavaEE SE is being used based off the casa file. The new sequence of events are:
http client --> inbound HTTP BC --> BPEL SE --> JavaEE SE --> invoke Hello web service --> response.

It should be obvious where the performance improvement is located. That is what makes the JavaEE SE so powerful. For convenenice, here is the final netbeans Composite Application project with the modified casa file.

If you are curious to know what netbeans was doing under the covers for us when creating the EJB Module Service Unit here is a quick explanation. In netbeans and File view you can expand the build directory under HelloBPELCompositeApp. Next expand the Hello.jar service unit. There you will see the jbi.xml and an empty sun-resources.xml. The jbi.xml file defines the endpoints the JavaEE SE must activate. These endpoints will be used by the BPEL SE consumer endpoint. Also interesting is it includes a binary of the Hello Service (Hello.class).

Most common WSDL stumbling block

When it comes to helping people debug WSDL issues, the #1 overlooked and misunderstood problem is usually whether to specify type or element as the attribute to the element. If you are creating web services and defining WSDLs you must understand this significant difference as it will effect the consumers of your services.

All my examples and information where referenced from the book Building Web Services with Java. I would highly recommend this book.

Simple WSDL
Let's first begin with snippets from a simple WSDL.

<definitions name="PriceCheck">
 <types>
     <xsd:schema>
         <xsd:element name="sku" type="xsd:string"/>
         <xsd:complexType name="availabilityType"
             <xsd:sequence>
                 <xsd:element ref="sku"/>
                 <xsd:element name="price" type="xsd:double"/>
                 <xsd:element name="quantityAvailable" type="xsd:integer"/>
             </xsd:sequence>
         </xsd:complexType>
         <xsd:element name="StockAvailability" type="availabilityType"/>
     </xsd:schema>
 </types>
 <message name="PriceCheckRequest">
     <part name="sku" element="sku"/>
 </message>
 <message name="PriceCheckResponse">
     <part name="result" element="StockAvailability"/>
 </message>
 <portType>
    <operation name="checkPrice">
     .......
 <binding>
 .......
 <service>
 .......
</definitions>

WSDL Parts
A part element is made up of two properties: the name of the part and the kind of the part. The name property is represented by the name attribute, which must be unique among all the part child elements of the message element. The kind property of the part is defined as either a type attribute (a simpleType or complextType from the XSD schema type system) or an element attribute (also defined by referring to an element defined in the XML schema). You can't use both an element attribute and a type attribute to define the same part.

The choice of using element or type when defining the part is very important. The most common mistake is using the type attribute and referencing an XSD element or using the element attribute and referencing an XSD simpleType or complexType.

Use of element
When you use the element attribute, you're specifying that the SOAP should be precisely that XML element. For example, the PriceCheckRequest example specifies that the XML element named sku must be used as the body of the messsage. Here is a snippet of what the SOAP would look like:

<soap:Envelope>
 <soap:Body>
     <sku>123</sku>
 </soap:Body>
</soap:Envelope>

Note how the SOAP contains exactly the specified sku element. The element attribute should be used to define the type of the part when the Web service is meant to be document oriented (which is defined in the binding). Whenever the element attribute is used, its value must refer to another global XML element defined or imported in an XML schema.

This not only applies to requests but responses as well. For example, here is what the SOAP would look like for PriceCheckResponse:

<soap:Envelope>
 <soap:Body>
     <StockAvailability>
         <sku>123</sku>
         <price>100.0</price>
         <quantityAvailable>12</quantityAvailable>
     </StockAvailability
 </soap:Body>
</soap:Envelope>

Use of type
The PriceCheckRequest could have been built differently, using a part defined with the type attribute, like this:

<message name="PriceCheckRequest">
 <part name="sku" type="xsd:string"/>
</message>

Here is an example of the SOAP using the RPC-style where checkPrice is the name of the operation defined in the WSDL:

<soap:Envelope>
 <soap:Body>
     <checkPrice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <sku xsi:type="xsd:string">123</sku>
     </checkPrice>
 </soap:Body>
</soap:Envelope>

Summary
That is the difference between defining your part as an element or type. The most common style to use is document oriented and therefore the parts must use elements. If you use type in your parts, you need to use the RPC style.

Unfortunately all this isn't well documented. However there is good news. In WSDL 2.0 message and part elements have been removed. Instead you would use the names of the XML element declarations directly in the operations input, output, and fault messages.

My de facto standard on WSDL styles

Here is my de facto standard reference on WDSL styles; bookmark it! When I first started writing Web Services I never knew their were 2 styles and 2 uses, or even that there was a style. As I gradually learned more about WSDLs it was difficult to find a good explanation of the different combinations. This article, written by Russel Butek on IBM developerWorks, explains how you determine which combination of style and use to choose. He provides advantages and disadvantages of each and shows WSDL and SOAP messages for each combination.

Overall when creating a Web Service you have 4 style/use options:

1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal

Along with these four is a recently new pattern which is commonly called document/literal wrapped.

Please read this article if you are unfamiliar with the different styles and uses. In general the most common style used is document/literal wrapped with document/literal in second. Most newer SOAP Stacks actually don't support RPC anymore; for examlpe cxf (aka xfire) and axis2.