Configuring the IEP Service Engine for Clustering

You can configure the IEP SE to run in a GlassFish cluster on the same or different servers, You can also configure the SE for high availability and failover on a standalone GlassFish server. This topic describes configuring the IEP SE on a GlassFish cluster. For information on standalone configuration for high availability and failover, see Configuring Components for Standalone High Availability and Failover). The IEP SE can be implemented in a cluster on the same or different servers.

The IEP SE uses a database to maintain instance information in a cluster. In a clustered environment, an event processor belongs to any one of the live cluster instances at a given time. All instances can receive the incoming messages, and once a message is received it is inserted into the IEP database for further processing. The instance that owns the event processor picks up the event to complete processing. The output is only written by the instance that owns the event processor. If an instance fails, any in-process transactions are taken over by one of the remaining instances and the process is completed. When the failed engine recovers, it continues to process new requests.

The IEP SE is not dependent on any shared libraries.

Setting Up the IEP Database

Default connection pools and JDBC resources are automatically created for an IEP Derby database, as are the Derby database and persistence tables once you enable the engine on the cluster. The tables are automatically created for an Oracle database, but you need to manually create the connection pools and JDBC resources for Oracle.

For Derby, you can customize the default connection pools and JDBC resources if necessary, or create new ones for the cluster. IEP uses both XA and non-XA transactions so two connection pools and JDBC resources are required, one for each type.

For more information about creating connection pools and JDBC resources, see Chapter 3, “JDBC Resources”, in Sun GlassFish Enterprise Server v2.1.1 High Availability Administration Guide.

To Set Up the IEP Database

1. If you are using Oracle, do the following. These steps are not necessary for other database platforms.
   1. Copy the Oracle driver (ojdbc14.jar) from your Oracle installation to GlassFish_Home/lib. Restart the GlassFish server.
   2. Create an Oracle database instance using the administrative tools provided by Oracle.
   3. Customize and run the following script to create the IEP user (or use the information in the script as a guide).

      http://wiki.open-esb.java.net/attach/HowToRunIEPOnOracle/create_iepse_user.sql

2. Launch the GlassFish Admin Console.
3. Create and configure two connection pools for the database, one for XA transactions and one for non-XA transactions. Point both connection pools to the same database using the same user name and password.

   ---

   Note - For Derby, you can use the connection pools that are automatically created when IEP is installed.

   ---

   • Select Allow Non Component Callers.
   • For a Derby database, enter the following properties:

     • Host (can be localhost)

     • PortNumber (1527 is the default Derby port)

     • DatabaseName

     • User

     • Password

     • connectionAttributes (set this to ;create=true to automatically create the Derby database)

   • For an Oracle database, enter the following properties:

     • URL (the format for the URL is jdbc:oracle:thin:@hostName:portNumber:databaseName)

     • user

     • password

4. Create and configure two JDBC resources for the database, one for XA transactions and one for non-XA transactions. After you enter the name and connection pool, do the following:
   1. Under Available Targets, select the cluster and click Add.
   2. Click OK.

      This adds the resource to the cluster and enables the resource on the cluster.

5. To create the database tables, complete the steps under Adding the IEP Service Engine to the Cluster.

Adding the IEP Service Engine to the Cluster

The IEP SE is not dependent on any shared libraries; you only need to add the service engine to the cluster.

To Add the IEP Service Engine to the Cluster

1. Add the IEP SE (sun-bpel-engine) to the cluster as described in To Add a Java CAPS JBI Component to a Cluster.
2. Before you click OK on the Manage Targets page, do the following:
   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. In the Non XA Data Source Name property, enter the JNDI name of the non-XA JDBC resource that you created earlier.
   3. 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.

   4. Update the value of the Database Schema Name property if you created the database using a username other than iepseDB.
   5. Configure the remaining runtime properties as you typically would for the IEP SE.

      For more information, see Oracle Java CAPS Intelligent Event Processor (IEP) User’s Guide.

3. Verify that the EMS_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 IEP SE in order for the rows to appear.

   ---