Sun Java EE Engine: Bridging Java EE Web Services and JBI Components

In addition to providing in-process bidirectional communication between the Java EE and JBI environments, the Sun Java EE Engine provides the following features:

• Java EE service units - Using Java EE service units, end users can deploy and manage a composite application as a single entity: a JBI service assembly.
  
  
• Transaction support - This feature enables Java EE web services and JBI services to participate in a single transaction. For example, a BPEL process can call an EJB bean that updates a database, all in the same transaction.
  
  
• Security support - This feature enables separate JBI components to make use of a single authentication mechanism. In practice, a user signs on once, and the JBI system propagates the security credentials to the various JBI components as needed.
  
  
• Cluster support - With this feature, you can deploy a Java EE service unit to an application server cluster. When the JBI service assembly is deployed to the cluster, the Java EE service units are also deployed to each server instance in the cluster.

The following sections discuss these features in more detail.

Java EE Service Units

As shown in Figure 1, your composite application could contain various pieces, with each piece needing to be deployed into the proper component of the JBI environment. For example, if the application needs to read input from a file and execute a BPEL process, then your composite business application contains at least two pieces: one piece is deployed into the File binding component (BC), and another piece is deployed into the BPEL service engine (SE).

To make the deployment process easier, the JBI specification defines a service assembly, which is a single archive that bundles various pieces of a business application. In JBI terminology, the individual pieces in the service assembly are referred as service units. Using this JBI service assembly, all the pieces of your composite business application can be deployed at once, and you don't need to deploy the individual pieces of your application separately.

A composite business application can contain Java EE applications. Users prefer to deploy and manage composite applications as a single entity and would prefer not to deploy the Java EE applications separately from the JBI service assembly. Java EE service units can make Java EE applications part of the JBI service assembly, enabling them to be deployed and managed as one entity.

By definition, a Java EE service unit is a Java EE application that can be bundled as part of the JBI service assembly. So, when the JBI service assembly is deployed, the Sun Java EE Engine takes care of deploying any Java EE applications that are bundled in the service assembly. In addition, any life cycle operation that is applied to the JBI service assembly (start, stop, undeploy, and so on) results in the same life cycle operation being applied to the bundled Java EE applications.

The difference between a normal Java EE application and the Java EE Service unit is that the latter contains an additional descriptor file named jbi.xml. This JBI runtime descriptor describes the services provided and consumed by a Java EE application in the JBI environment.

Java EE service units can be of two types, as shown in Figure 2:

• Service unit - Contains a Java EE application archive and the jbi.xml descriptor.
  
  
• Dummy service unit - Contains only the jbi.xml descriptor.

Figure 2: Java EE Service Units

The following examples should help you understand the different types of Java EE service units.

Example: Service Unit Containing a Java EE Application Archive That Provides Services to the JBI Environment

When a Java EE service unit contains a Java EE application archive that provides services to the JBI environment, the Java EE application archive contains one or more Java EE web services.

The Sun Java EE Engine deploys the archive to the application server during the deployment of the service assembly. The deployment of the archive is no different from the normal deployment accomplished through the asadmin deploy archive command, with the addition of a property value to identify the application as part of the JBI service assembly.

Note that custom deployment configuration properties can also be specified in vendor-specific deployment descriptors. For example, if database tables need to be created during the deployment, the requirement can be specified in the sun-ejb-jar.xml file as shown in the following code example.

Code Example 1

<sun-ejb-jar>
<enterprise-beans>
....
<cmp-resource>
<create-tables-at-deploy>true</create-tables-at-deploy>
</cmp-resource>
....
</enterprise-beans>
</sun-ejb-jar>

Consider the following web service example. It is a skeleton of a simple web service that retrieves employee information from a Human Resources database.

Code Example 2

package com.mycompany.department.hr;

import javax.ejb.Stateless;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebParam.Mode;
import javax.jws.WebService;
import javax.xml.ws.Holder;{.ws OK here--not .jws?]

@Stateless()
@WebService()
public class HumanResourceEJB {

    @WebMethod
    public void getEmployeeInformation(@WebParam(name = "employeeID", mode=Mode.IN)
                           String employeeID,
                           @WebParam(name="joiningDate", mode=Mode.OUT) 
                           Holder<String> joiningDate,
                           @WebParam(name = "currentGrade", mode=Mode.OUT)
                           Holder<String> currentGrade,
                           @WebParam(name = "currentSalary", mode=Mode.OUT)
                           Holder<String> currentSalary,
                           @WebParam(name = "gradeWhenJoined", mode=Mode.OUT)
                           Holder<String> gradeWhenJoined,
                           @WebParam(name = "salaryWhenJoined", mode=Mode.OUT)
                           Holder<String> salaryWhenJoined) {
        // TODO write your implementation code here:
        // Get the employee information from HR database and return.
    }
}

The Web Services Definition Language (WSDL) file for the above web service is shown in the following code example.

Code Example 3

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions targetNamespace="http://hr.department.mycompany.com/" 
   name="HumanResourceEJBService" 
   xmlns:tns="http://hr.department.mycompany.com/" 
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
   xmlns:wsu=
   "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
   xmlns="http://schemas.xmlsoap.org/wsdl/">

  <types>
    <xsd:schema>
      <xsd:import namespace="http://hr.department.mycompany.com/" 
                  schemaLocation="HumanResourceEJBService_schema1.xsd"/>
    </xsd:schema>

  </types>
  <message name="getEmployeeInformation">

    <part name="parameters" element="tns:getEmployeeInformation"/>
  </message>
  <message name="getEmployeeInformationResponse">

    <part name="parameters" element="tns:getEmployeeInformationResponse"/>

  </message>
  <portType name="HumanResourceEJB">

    <operation name="getEmployeeInformation">
      <input message="tns:getEmployeeInformation"/>

      <output message="tns:getEmployeeInformationResponse"/>
    </operation>

  </portType>
  <binding name="HumanResourceEJBPortBinding" type="tns:HumanResourceEJB">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>

    <operation name="getEmployeeInformation">
      <soap:operation soapAction=""/>
      <input><soap:body use="literal"/></input>

      <output><soap:body use="literal"/></output>

    </operation>
  </binding>
  <service name="HumanResourceEJBService">
    <port name="HumanResourceEJBPort" binding="tns:HumanResourceEJBPortBinding">

      <soap:address location="REPLACE_WITH_ACTUAL_URL"/>

    </port>

  </service>
</definitions>

To make this web service accessible to the various JBI components, you need to enable it in the JBI environment with a description in the descriptor file jbi.xml, as shown in the following code example.

Code Example 4

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi xmlns="http://java.sun.com/xml/ns/jbi" 
        xmlns:ns0="http://hr.department.mycompany.com/" version="1.0">
<services binding-component="false">

<provides endpoint-name="HumanResourceEJBPort" 
                   interface-name="ns0:HumanResourceEJB" 
                   service-name="ns0:HumanResourceEJBService"/>

</services>
</jbi>

Note that you typically don't need to code descriptor files by hand because they are easily generated by tools such as the NetBeans IDE Enterprise Pack.

The Java EE application and the JBI descriptor file can now be bundled inside the JBI service assembly. When you deploy and start the service assembly in the application server, the Java EE application is also deployed and started. At the same time, the endpoints specified in the JBI descriptor file are also enabled in the NMR, and the web service becomes available to all the JBI components.

Example: Service Unit Containing a Java EE Application Archive That Consumes Services Exposed by Other JBI Components

In this situation the Java EE application archive contains one or more Java EE web service clients. The Java EE application is deployed in the same way as in the previous case.

The jbi.xml file contains the list of endpoints that will be consumed. The following simple code example shows a jbi.xml file that identifies consuming the Human Resources web service.

Code Example 5

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi xmlns="http://java.sun.com/xml/ns/jbi" 
     xmlns:ns0="http://hr.department.mycompany.com/" version="1.0">
<services binding-component="false">
<consumes endpoint-name="HumanResourceEJBPort" 
          interface-name="ns0:HumanResourceEJB" 
          service-name="ns0:HumanResourceEJBService"/>

</services>
</jbi>

Example: Dummy Service Unit That Provides Services to JBI

If a web service is already running inside the application server, and it needs to be made available to the JBI environment, then you can create a dummy service unit composed of only the jbi.xml file.

For example, if the HumanResourceEJB bean in Code Example 4 is already deployed in the application, then it can be enabled in the NMR simply by placing the jbi.xml file shown in Code Example 4 inside the dummy service unit.

Example: Dummy Service Unit That Consumes the Services Exposed by Other JBI Components

If there is already a web service client running inside the application server and it needs to access the JBI service, then you can create a dummy service unit with only a jbi.xml file.

The contents of the jbi.xml file are similar to the sample shown in Code Example 5.

All these types of Java EE service units can be created and added to the JBI service assembly easily with the NetBeans IDE Enterprise Pack.

Transaction Support

Transactions are an important part of the business logic for any enterprise application. With the transaction support in the Sun Java EE Engine, Java EE web services and JBI services can participate in a single transaction. For example, a BPEL process can call an EJB bean that updates the database, all in the same transaction.

The propagation of a transaction across JBI components is defined in the JBI specification. A standard message exchange property (MessageExchange.JTA_TRANSACTION_PROPERTY_NAME) is used to propagate the transaction. The following figures illustrate details of how the Sun Java EE Engine handles a transaction.

Java EE web service invoking a JBI service (refer to Figure 3):

1. A transaction is started in the Java EE application.
   
   
2. Within the transaction boundary, a JBI service is invoked.
   
   
3. The Sun Java EE Engine suspends the transaction associated with the incoming request.
   
   
4. The suspended transaction is set in the message exchange using the property MessageExchange.JTA_TRANSACTION_PROPERTY_NAME, and the message is delivered to the NMR.
   
   
5. The service exposed by the JBI component is invoked within the same transaction context. In the event of a failure, the JBI component marks the transaction to roll back.
   
   
6. The JBI component sends back the response after setting the transaction in the message exchange.
   
   
7. The Sun Java EE Engine receives the message from the NMR.
   
   
8. After retrieving the transaction from this message, the transaction is resumed.
   
   
9. The response is sent back to the Java EE application.
   
   
10. The Java EE application completes the remaining portion of the business logic and commits or rolls back the transaction based on the status of the transaction.

Figure 3: Transaction Propagation From Java EE to JBI

JBI service invoking a Java EE web service (refer to Figure 4):

1. The JBI component starts a transaction and invokes a Java EE web service.
   
   
2. The Sun Java EE Engine receives the message from the NMR.
   
   
3. The Sun Java EE Engine retrieves the transaction from the message exchange using the property MessageExchange.JTA_TRANSACTION_PROPERTY_NAME and resumes the transaction.
   
   
4. The Java EE web service is invoked within the same transaction context.
   
   
5. The Java EE application returns the response.
   
   
6. The Sun Java EE Engine suspends the transaction.
   
   
7. The suspended transaction is set in the message exchange, and the transaction is delivered to the NMR.
   
   
8. Finally, the response is given back to the JBI component, which commits or rolls back the transaction based on the status of the transaction.

Figure 4: Transaction Propagation From JBI to Java EE

Security Support

As with transactions, the JBI specification also defines a way by which different JBI components can make use of a single authentication mechanism. As a result, a user need only sign on once, and the JBI system propagates the security credentials to various JBI components for authorization.

To achieve this single-sign-on capability, the JBI specification defines a property javax.jbi.security.subject that is used to set the security subject in the normalized message. The Sun Java EE Engine acts as an intermediary between the application server and the JBI runtime.

Security propagation when a Java EE application invokes a JBI service (refer to Figure 5):

1. The client enters login credentials, resulting in an authentication.
   
   
2. From within the Java EE application, a JBI service is invoked in the same security context.
   
   
3. The Sun Java EE Engine intercepts the invocation and delivers a normalized message to the NMR after setting the security context in the message. The Sun Java EE Engine uses the property javax.jbi.security.subject to set the security subject in the message.
   
   
4. The actual service is invoked by the JBI component, which performs the authorization and then invokes the service.
   
   
5. The result of the invocation is returned as a response. The JBI component again sets the security context in the response message.
   
   
6. The Sun Java EE Engine receives the message from the NMR and retrieves the security subject from the message. This subject is set in the current security context of the thread.
   
   
7. Finally, the response is returned to the Java EE application.

Figure 5: Security Propagation From Java EE to JBI

Security propagation when a JBI service invokes Java EE web service (refer to Figure 6):

1. The client authentication is performed in the JBI component.
   
   
2. A Java EE web service is invoked from the JBI service that is deployed in the JBI component.
   
   
3. The Sun Java EE Engine receives the message from the NMR and retrieves the security subject from the message. This subject is set in the current security context of the thread.
   
   
4. The Java EE web service is invoked with the security context. The authorization in this case is done by the EJB/Servlet container before it invokes the web service.
   
   
5. A response is returned from the application.
   
   
6. The Sun Java EE Engine intercepts the response and sets the current security subject in the normalized message. The message is delivered to the NMR.
   
   
7. Finally, the response is given to the JBI service.

Figure 6: Security Propagation From JBI to Java EE

The Sun Java EE Engine is cluster aware, enabling you to deploy a Java EE service unit to an application server cluster. When a JBI service assembly is deployed to a cluster, the Java EE service units are also deployed to the cluster.

The Sun Java EE Engine has been developed as part of Project GlassFish. When the GlassFish application server is installed, the Sun Java EE Engine is also installed. You can view and administer the Sun Java EE Engine through the application server's GUI (graphical user interface) and CLI (command-line interface).

Here are some of the interfaces that are often used.

To View the Sun Java EE Engine:

GUI:

1. Log in to GlassFish application server's administration console.
2. Go to Common Tasks > JBI > Components > sun-javaee-engine

CLI:

Type the following command:
asadmin show-jbi-service-engine sun-javaee-engine

To Administer the Sun Java EE Engine:

GUI :

1. Log in to the GlassFish application server's administration console.
2. Go to Common Tasks > JBI > Components
3. Select sun-javaee-engine.
4. Perform the required operation such as Start, Stop, Shut Down, Uninstall.

CLI :

• To start the Sun Java EE Engine, type:
  asadmin start-jbi-component sun-javaee-engine
• To stop the Sun Java EE Engine, type:
  asadmin stop-jbi-component sun-javaee-engine
• To shut down the Sun Java EE Engine, type:
  asadmin shut-down-jbi-component sun-javaee-engine
• To uninstall the Sun Java EE Engine, type:
  asadmin uninstall-jbi-component sun-javaee-engine

To Install the Sun Java EE Engine Manually:

The Sun Java EE Engine comes installed and configured when the GlassFish application server is installed. If you uninstall the Sun Java EE Engine accidentally, you can use either the GUI or the CLI to install it again manually.

GUI:

1. Log in to the GlassFish application server's administration console.
2. Go to Common Tasks > JBI > Components.
3. Click the Install button and click the Browse button.
4. Select ApplicationServer-InstallDir/jbi/components/sun-javaee-engine/appserv-jbise.jar
5. Click the Next button and the Finish button in the next window.

CLI:

Type the following commands:
asadmin install-jbi-component ApplicationServer-InstallDir/jbi/components/sun-javaee-engine/appserv-jbise.jar
asadmin start-jbi-component sun-javaee-engine

This section explains one business integration scenario in which the Sun Java EE Engine can be used.

In the example shown in Figure 7, the client application, acting as a web service, sends a message to a message queue. The message is picked up by a message-driven bean (MDB). Upon receiving the message, and by using the Sun Java EE Engine, the MDB contacts the NMR for the service endpoint that is exposed by the BPEL process.

Figure 7: Sun Java EE Engine Use Case

When the MDB executes, the BPEL application, hosted by the BPEL service engine, contacts the NMR to find its partner services. In the example, there is only one partner service: a stateless session bean (JSR 109 web service) that is hosted in the same Application Server JVM instance. The JSR 109 web service's endpoint is enabled in the NMR by the Sun Java EE Engine when the stateless session bean is deployed. The stateless session bean then uses Java EE persistence APIs (JPA) to access the database.

A known limitation of the Sun Java EE Engine is that it supports only InOut and InOnly message exchange patterns of JBI. This limitation is not a disadvantage in normal use because you can implement almost any composite application using only these two patterns.

• JBI specification (JSR 208)
• JBI in GlassFish — Binod's blog entry
• Java EE Service Engine: Bridging Java EE and JBI — Binod's blog entry
• ServiceMix on GlassFish: Java EE and JBI integration — Bhavanishankar's blog entry
• Implementing Service-Oriented Architectures (SOA) with the Java EE 5 SDK — online article
• GlassFish Project
• GlassFish Project - JBI based Java EE Service Engine home page
• NetBeans SOA Documentation Page
• Java EE SDK — contains Sun Java System Application Server, Sun's supported distribution of GlassFish
• Java EE home page — for articles, tutorials, tips, documentation, code samples, downloads, and more.
• The Aquarium — the GlassFish Community blog
• Sun Java System Application Server page — with links to the GlassFish Community site
• Java Training and Certification — professional development to enhance your skills
• Developer Support — online incident-based programming advice, telephone product support, developer training courses, service plans
• Sun Java System Application Server Support