Configuring Java CAPS JBI Components for GlassFish Clustering

Configuring the BPEL Service Engine for Clustering

You can configure the BPEL SE for GlassFish clustering on the same or different machines. You can also configure the SE for high availability and failover at the component level on a standalone GlassFish server. This topic describes configuring the BPEL SE on a GlassFish cluster. For information on standalone configuration for high availability and failover, see Configuring Components for Standalone High Availability and Failover.

When the BPEL SE is installed and configured in a clustered environment and one engine fails, any in-process business process instances are taken over by one of the remaining engines and the process is completed. When the failed engine recovers, it continues to process new requests. Clustering for the BPEL SE leverages the persistence and recovery features of the SE, so persistence must be enabled for the BPEL SE on each cluster instance.

Failover is also supported for business processes configured for correlation. When correlated messages are processed in a clustered environment, the load balancer or binding component routes the correlating message to any BPEL SE in the cluster. If the BPEL SE to which the message was routed does not own the correlating business process instance, the instance is routed to the engine that received the correlated message (regardless of which engine began processing the initial message). Processing is then completed on the engine that received the correlated message.

The BPEL Service Engine (SE) is dependent on the following shared library, which must be added to the cluster before the BPEL SE is added to the cluster.

Sun WSDL Extension Library

Note –

The following restrictions apply to BPEL SEs installed in a cluster.

All BPEL constructs work in a clustered environment with the exception of event handlers.
Reply activities are only supported in a clustered environment if the service is consumed by another business process (as in a sub-process scenario).
The servers in a cluster need to be on the same time zone in order to detect whether an instance has failed.

Setting Up the BPEL Database

In order to use the BPEL SE in a clustered environment, you need to create a database, and then create and configure two connection pools and two data sources (to handle both XA and non-XA activities). All engines in the cluster must be configured to use this database. The database should be highly available because a database failure constitutes a single point of failure in the cluster. Automatic database, connection pool, and data source creation is not available from the clustered instances.

Tip –

If you already created the database tables, connection pools, and JDBC resources, you can re-use them for the cluster instances by just changing the target for the JDBC resources from the default server to your cluster (described in step 3 below).

For more information about creating connection pools and JDBC resources, see Chapter 3, JDBC Resources, in Sun GlassFish Enterprise Server 2.1 Administration Guide.

To Set Up the BPEL Database

Before You Begin

If you are using an Oracle database, copy the driver file (ojdbc14.jar) from your Oracle installation to GlassFish_Home/glassfish/lib, and then stop and restart the GlassFish server.

Configure the user and database as described in Configuring the User and Database for Persistence in Using the BPEL Designer and Service Engine.

Create one XA connection pool and JDBC resource and one non-XA connection pool and JDBC resource.

This is described in Creating an XA Connection Pool and a JDBC Resource in Using the BPEL Designer and Service Engine and Creating a Non-XA Connection Pool and JDBC Resource in Using the BPEL Designer and Service Engine.

For each JDBC resource you created, return to the JDBC Resources page on the GlassFish Admin Console and do the following:
1. Select the JDBC resource from the list, and then click the Target tab.
2. Click Manage Targets.
3. Under Available Targets, select the cluster and click Add.
4. Click OK.
5. In the Targets table, select the cluster and then click Enable.

To automatically create the database tables, do the following:
1. In the NetBeans Services window, expand Servers > GlassFish V2 > JBI > Service Engines.
2. Right-click sun-bpel-engine, and then select Start.
3. On the Properties window, enable persistence and update the names of the XA and non-XA data source fields to match the JDBC resources you created above.
4. Stop and start sun-bpel-engine.
5. Shutdown sun-bpel-engine.

Adding the BPEL Service Engine to the Cluster

Before you can add the BPEL SE to a cluster, you need to add a shared library. When you add the BPEL SE to a cluster, you need to configure certain properties. The SE must be configured for persistence and pointing to the correct data sources. All instances of the BPEL SE should point to a single persistence database (which you created earlier under To Set Up the BPEL Database).

To Add the BPEL Service Engine to the Cluster

Add the following shared library to the cluster as described in To Add a Shared Library to a Cluster:
- sun-wsdl-ext-library

Add the BPEL SE (sun-bpel-engine) to the cluster as described in To Add a Java CAPS JBI Component to a Cluster. Configure the following properties on the Manage Targets page before you click OK:
1. Under General – Configure Component, specify a value for the Lease Renewal Interval.
  
  Note –
  The Lease Renewal Interval is the time period in seconds that BPEL engines wait before renewing their lease to let the cluster know it is still running (also known as the heartbeat). If an engine does not update within the specified time period, it is considered to be unavailable.
2. Under Persistence – Manage Persistence/Recovery, set Persistence Enabled to true.
3. In the Non XA Data Source Name property, enter the JNDI name of the non-XA JDBC resource that you created earlier.
4. In the XA Data Source Name property, enter the JNDI name of the XA JDBC resource that you created earlier.
  
  This is the database that persists state data for business process instances for recovery.
5. Configure the remaining runtime properties as you typically would for the BPEL SE.
  
  For more information, see Configuring the BPEL Service Engine Runtime Properties in Using the BPEL Designer and Service Engine.

Verify that the engines table in the persistence database contains a row for each instance in the cluster.

Tip –
If the rows do not appear, check the following:
- Both JDBC Resources are enabled on the target cluster.
- The engine is enabled on the target cluster.
If both of the above are enabled, you might need to stop and restart the BPEL SE in order for the rows to appear.

You can also verify that the engines are renewing the lease within the specified interval by querying the engines table again after the interval has passed and verifying that the LASTUPDATETIME column is updated accordingly.

Debugging a Business Process Deployed in a Cluster

When configuring debugging for a business process in a clustered environment, you need to configure each instance in the cluster for debugging and you need to set the breakpoints and attach the port number using a separate NetBeans IDE instance for each cluster instance.

To Debug a Business Process Deployed in a Cluster

Launch the GlassFish Admin Console.

In the navigation bar on the left, expand JBI, expand Components, and then select sun-bpel-engine.

In the View/Update Instance field, select an instance you want to monitor.

Set the Debug Enabled property to true.

Set the Debug Port property to a unique valid port number.

Click Save.

Repeat the above steps for each instance you want to monitor.

If you set breakpoints in the business process and attach a port number, you need to launch a new NetBeans IDE instance, set a break point, and then attach the port numbers for each instance in the cluster.