Using the Java EE Service Engine in a Project

This guide provides an overview of the Java EE Service Engine and its relationship with the application server and JBI runtime environment. It includes details that are necessary to start the Java EE Service Engine in a JBI project.

What You Need to Know

These links take you to what you need to know before you use the Java EE Service Engine.

• About the Java EE Service Engine

• Java EE Service Engine Features

• Java EE Service Engine Limitations

• Java EE Service Engine Use Case Scenarios

• Java EE Service Engine as Service Provider and Service Consumer

• Java EE Service Engine Example Scenario

• NetBeans Tooling Support for the Java EE Service Engine

Using the Java EE Service Engine

These links take you to topics containing information about using the Java EE Service Engine in a project.

• Software Requirements and Installation

• Configuring and Starting the Java EE Service Engine

• Administering the Java EE Service Engine

• Java EE Service Engine Deployment Articrafts

About the Java EE Service Engine

The Java EE Service Engine is a JSR 208-compliant JBI runtime component that connects Java EE web services to JBI components. The framework of the Java EE Service Engine is defined by the interconnectivity of GlassFish and the JBI runtime environment, which is installed as part of the application server. The Java EE Service Engine acts as a bridge between the application server and the JBI runtime environment, facilitating interaction between Java EE and JBI components.

Without the Java EE Service Engine, a Java EE component that is deployed as a servlet or Enterprise Java Beans web service can only be accessed from the HTTP SOAP transport. With the application server and JBI runtime environment working together, Java EE components can more readily access an array of binding components for transport or service engines for business logic, processing, transformation, and routing services. Enterprise beans and servlets that are packaged as web services and deployed on the application server are transparently exposed as service providers in JBI environment. Therefore the Java EE components can consume services exposed in JBI environment using the Java EE Service Engine without being aware of the underlying binding or protocol. This in-process communication between components of the application server and JBI runtime components results in increased request processing speed because all component interactions occur within the application server.

The following illustration shows the relationship between the application server, the JBI runtime environment, and the Java EE Service Engine. Acting as either a service provider or as a service consumer, the Java EE Service Engine communicates directly with the Normalized Message Router (NMR) and EJB web services using JAX-WS. The power and versatility of the Java EE web service communication continues to expand when additional JBI components are added to the runtime environment.

The Java EE Service Engine is bundled as part of NetBeans IDE 6.1 Preview with SOA and Project Open ESB. You can download these components from the Sun Developer Network at: http://java.sun.com/downloads.

Java EE Service Engine Features

The features of theJava EE Service Engine are:

• 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.

• Transactions support - 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 - 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.

• Code upgrade to JAX-WS 2.1

• Endpoint enabling through jbi.xml

• Support for RPC/Literal style operations

• Direct invocation of endpoints

• Packaging Java EE applications as part of the composite application

• Cluster support - Enables you to 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.

• Message properties propagation — This new feature supports propagation and reception of Normalized message properties. This feature allows additional properties to be propagated between Java EE components and JBI components. Propagation and reception of these message properties is handled by the Java EE Service Engine. For example, a web service client can pass additional message properties while invoking a JBI endpoint (eg. BPEL endpoints). The endpoint can use these properties and also send back additional properties to the client.

For more information on the Java EE Service Engine Features, see the article Bridging Java EE Web Services and JBI Components.

Java EE Service Engine Limitations

The Java EE Service Engine has the following limitations:

• WSDL 2.0 is not supported.

• The JBI Message Exchange Patterns “Robust In-Only” and “Optional In/Out” are not supported.

Java EE Service Engine Use Case Scenarios

JBI components are typically used to handle high-level business operations. The Java EE Service Engine becomes necessary in situations where complex Java EE-based business logic needs to communicate with JBI components. In these situations, the Java EE Service Engine facilitates the transfer of data between components. Some examples of this data exchange include:

• BPEL Service Engine calling an Enterprise Java Bean (EJB) web service

• Message-driven bean (MDB) or servlet calling a BPEL process

• EJB web service called through a JMS transport using the JMS Binding Component

• Java EE components calling web services using the FTP Binding Component

• Java EE components making web service calls through SMTP transport using the SMTP Binding Component

Java EE Service Engine as Service Provider and Service Consumer

JBI uses the abstract service model as the main basis of component interactions. As with other JBI runtime components, the Java EE Service Engine can act either as a service provider that performs a service, or as a service consumer that invokes a service.

Java EE Service Engine as a Service Provider

The Java EE Service Engine functions as a service provider by enabling an endpoint in the NMR. When a Java EE web service is deployed, the deployment runtime of application server notifies the Java EE Service Engine so that an endpoint is enabled in the NMR of the JBI runtime. The notification enables any component deployed in the NMR to access the Java EE web service. For example, a BPEL application running inside the BPEL service engine can access the Java EE web service by sending a normalized message to the endpoint enabled by the Java EE Service Engine. This way of accessing Java EE web services is an alternative to the normal web service client access defined by JAX-WS.

Java EE Service Engine as a Service Consumer

When a Java EE application needs to access an endpoint of a service provider deployed in the JBI runtime environment, the Java EE Service Engine communicates with the application server and the NMR in the JBI environment. In this case, the Java EE Service Engine normalizes the SOAP message that otherwise would have been used in the JAX-WS communication and sends it to the NMR. This normalized message is handled by a service that has been enabled by a service provider deployed in the JBI runtime environment. The following illustration depicts three JBI binding components acting as service providers, offering application-specific content to external clients.

Java EE Service Engine Example Scenario

The following example shows how the Java EE Service Engine can be used in a business integration.

Scenario Message Flow

The example scenario message flow works as follows:

• 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, the MDB contacts the NMR using the Java EE Service Engine, for the service endpoint that is exposed by the BPEL process.

• When the MDB executes, the BPEL application that is hosted by the BPEL service engine, contacts the NMR to find its partner services.

• In the example, only one partner service, the stateless session bean (JSR 109 web service) is hosted in the same Application Server JVM instance. The JSR 109 web service's is enabled in the NMR by the Java EE Service Engine when the stateless session bean is deployed.

• The stateless session bean then uses Java EE persistence APIs to access the database.

NetBeans Tooling Support for the Java EE Service Engine

To make Java EE web services work with JBI runtime components, deploy Java EE web services as part of a composite application. NetBeans provides full fledged support to create/deploy/manager the Java EE Service Units. NetBeans 6.1 includes additional server resource support for Java EE applications packaged inside composite applications. Java EE projects or components can be deployed through the Service Assembly, or they can be deployed independently with optimization of the intra-JVM communication.

These two deployment methods address the issue of Java EE applications packaged inside composite applications with resource dependencies, such as connection pools or JMS destinations, that are created before deployment. The addition of server resource support for Java EE applications makes resolving resource dependencies easier by combining all the resource dependencies of a Java EE application into a single sun-resources.xml before packaging the information into a .jar or .war file.

For additional information on this tooling support, see the help topic “About JBI and Java EE Web Services” in the NetBeans help.

Software Requirements and Installation

The GlassFish V2 bundles OpenESB JBI runtime, and also includes Java EE Service Engine and HTTP Binding components as the system components.

To use the Java EE Service Engine, install the following software:

• GlassFish ESB ( Installation Instructions) includes the following:

  • GlassFish V2 Update Release 2 (UR2)

  • NetBeans IDE 6.1

  • Open ESB core components

  • Java Business Integration (JBI) service engines

  • Java Business Integration (JBI) binding components

  • Java Business Integration (JBI) component tooling

• JDK (Java Development Kit) 6

You must have the JDK (Java Development Kit) software installed and JAVA_HOME set as an environment variable, prior to installing GlassFish ESB or the installation will halt midway. See Installing the JDK Software and Setting JAVA_HOME in the Open ESB documentation for details.

Configuring and Starting the Java EE Service Engine

The Java EE Service Engine requires no configuration.

The Java EE Service Engine can be started in three ways. It starts automatically whenever a JBI service assembly which contains a Java EE Service Unit is deployed.

Users who work with the service engine in the NetBeans IDE must start the component from the GlassFish V2 application server.

To Start the Java EE Service Engine from the GlassFish V2 Application Server

1. From the NetBeans IDE's main page, in the Services window, expand the GlassFish V2 -> JBI -> Service Engines nodes.

2. Right-click sun-javaee-engine and choose Start from the pop-up menu.

   The following message appears in the Output window:

   Engine sun-javaee-engine has been started.

To Start the Java EE Service Engine from the Admin Console

1. In the NetBeans Services window, log in to the GlassFish Administrator Console by right-clicking your application server and choosing View Admin Console.

   Ensure that the GlassFish application server is running. A green arrow icon next to the server node indicates that the server is running. If the server is not running, right click the server name and choose Start from the pop—up menu.

2. You can also open the Admin Console from your web browser using the correct URL, for example: http://localhost:4848.

   The default log in username isadmin, and the password is adminadmin.

   The Sun Java System Application Server Admin Console opens in a new browser window.

3. On the left pane under the JBI node expand Components and choose sun-javaee-engine.

   The Java EE Service Engine properties page opens.

4. Click on the Start button on the General tab page to start the Java EE Service Engine.

To Start the Java EE Service Engine Using Command Line Interface

1. Navigate to the location where you have installed the GlassFishESB and open the folders glassfish-> bin.

2. Double click asadmin.batfile.

3. At the asadmin command prompt type start-jbi-component sun-javaee-engine.

Installing Java EE Service Engine Using Command Line Interface

The Java EE Service Engine comes installed and configured when the GlassFish application server is installed. If you uninstall the Java EE Service Engine accidentally, you can use the CLI (Command Line Interface) to install it again manually.

Type the following command:

asadmin install-jbi-component [ApplicationServer-InstallDir]/jbi/components/sun-javaee-engine/appserv-jbise.jar

Other Operations Using the Command Line Interface

Using the CLI we can perform many operations.

• 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

• (Optional) To uninstall the Sun Java EE Engine, type:

asadmin uninstall-jbi-component sun-javaee-engine

Administering the Java EE Service Engine

You can administer the Java EE Service Engine instances using the GlassFish Admin Console tools. These tools enable you to monitor and change the Java EE Service Engine's variable values, and suspend, resume, or terminate instances.

To View the General Properties

1. Log in to the GlassFish Administrator Console and on the left pane under the JBI node expand Components and choose sun-javaee-engine

   The Java EE Service Engine properties page opens.

   Here you can view the details of the Java EE Service Engine, Service Units, and perform Start, stop and shut down operations.

   

Java EE Service Engine Log Management

The NetBeans IDE provides the ability to define logging for process activities.

Logging is used to write specified expression values or partner links endpoint reference information to the server log. The log level for the Java EE Service Engine is specified through the GlassFish Admin Console.

To Set the Log Level for the Java EE Service Engine

1. Access the Java EE Service Engine General Properties page.

   For more information see To View the General Properties.

2. Once on the General Properties page, click the Loggers tab.

3. Choose the appropriate log level for the sun-javaee-engine from the drop down list.

   If logging is defined for a process activity, and the log level specified for it corresponds to the log level set for the Java EE Service Engine, after you perform a test run of the process, the selected variable value will be written to the server log file.

   The following levels of logging are available:

   • FINEST

   • FINER

   • FINE

   • CONFIG

   • INFO

   • WARNING

   • SEVERE

   • OFF

   

To View a Log File

1. From the NetBeans IDE's main page, in the Services window, under the Servers node, right-click GlassFish V2 application server node and choose View Server Log from the pop—up menu.

   The GlassFish server log opens in the Output window. The activity message value is included in the log. You can use Search to find the log information. Note that some overhead information is hidden.

2. Another alternate method is to view the server log file is in a text editor and see the full information. Navigate to application server installation directory -> domains/domain1 and open the server.log file with the text editor.

   The information provided in the log includes the following points, divided with the vertical bar:

   • Date and time of the entry

   • Log level

   • Manager type

   • Thread

Java EE Service Engine Deployment Articrafts

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 Java EE Service 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.

As shown in the following illustration, a composite application can contain various service units, where each unit needs 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 units: one unit is deployed into the File Binding Component , and another unit is deployed into the BPEL Service Engine.