Creating and Deploying to WebLogic Server Clusters

Tutorial 3: Setting Up Cluster Resources for MedRec

This tutorial describes how to set up the WebLogic Server resources required to deploy and run the MedRec applications. These resources include:

Java Database Connectivity (JDBC) connection pools and data sources for the PointBase database management system
Java Message Service (JMS) persistent store, JMS server, queue, and connection factory
JavaMail mail sessions

The tutorial includes the following sections:

Prerequisites

Before starting this tutorial:

Create the MedRecClusterDomain as described in Tutorial 1: Creating a WebLogic Server Cluster.
Start the PointBase Database, Administration Server, and Cluster using the instructions in Tutorial 2: Starting the Cluster.
Make sure you have the Administration Console opened in a browser window and that all servers in the cluster are running. See Tutorial 2: Starting the Cluster for information on starting the Administration Console.

Procedure

Follow these steps to configure WebLogic Server resources for the MedRec Server:

Step 1: Create a JDBC connection pool.

This JDBC connection pool uses a JDBC driver that does not support distributed transactions (non-XA).

In the left pane of the Administration Console, open Services-> JDBC.
Right-click Connection Pools and choose Configure a new JDBCConnectionPool.
Choose Pointbase for the Database Type.
Choose Pointbase's Driver (Type 4) Versions:4.X for the Database Driver.
Click Continue.
Enter:
Click Continue.
Ensure that the information to test the connection to the Pointbase database is correct, then click Test Driver Configuration.
Note: Be sure you have started PointBase, or the test of its driver configuration will fail.
After verifying that the connection succeeded, the Administration Console display the Create and Deploy page. To deploy to the new cluster:
- Select medreccluster in the list of clusters.
- Select All servers in the cluster is selected.
Click Create and Deploy to deploy the new pool.
Verify that the pool deployed by examining its entry in the JDBC Connection Pools table. pb/MedRecPool should appear in the table, and its Deployed status should be "True."

Step 2: Create a JDBC DataSource.

Client and server-side JDBC applications obtain a DBMS connection through a DataSource. A DataSource is an interface between an application and the JDBC connection pool.

In the left pane of the Administration Console, open Services-> JDBC.
Right-click Data Sources and choose Configure a new JDBCTXDataSource.
Enter pb/MedRecTxDataSource in the Name field and MedRecTxDataSource in the JNDI Name field.
Ensure that Honor Global Transactions is checked.
Click Continue.
Choose pb/MedRecPool in the Pool Name list box.
Click Continue.
Ensure that medreccluster is checked as the cluster on which you want to deploy this data source. Also ensure that the All servers in the cluster option is selected.
Click Create.
To verify that the DataSource was deployed:

Step 3: Create a JMS Connection Factory.

In the left pane of the Administration Console, open Services-> JMS.
Right-click Connection Factories and choose Configure a new JMSConnectionFactory.
Enter jms/MedRecQueueConnectionFactory in the Name field and jms/MedRecQueueConnectionFactory in the JNDI Name field.
Click the Create button.
Select medreccluster in the Targets list.
Ensure that the All servers in the cluster option is selected.
Click Apply to target the connection factory to the cluster.
Select the Configuration tab.
Select the Transactions tab.
Select the XA Connection Factory Enabled check box.
Click Apply.
To verify that the factory was deployed:

Step 4: Create a JMS JDBC store.

A JMS JDBC store consists of a JDBC database that can be used for persistent messaging.

In the left pane of the Administration Console, open Services-> JMS.
Slect Stores in the left pane.
In the right pane, choose Configure a new JMS JDBC Store.
Enter MedRecJMSJDBCStore in the Name field.
Choose pb/MedRecPool in the Connection Pool list box.
Enter MedRec in the Prefix Name field.
Click Create.

Step 5: Create a JMS server.

A JMS server manages connections and message requests on behalf of JMS clients.

In the left pane of the Administration Console, open Services-> JMS.
Right-click Servers and choose Configure a new JMSServer.
Enter MedRecJMSServer in the Name field.
Choose MedRecJMSJDBCStore in the Store list box.
Click Create.
Choose one of the available servers in the cluster—MedRec1, MedRec2, or MedRec3—from the target list. Do not select the migratable servers listed. That is, do not select MedRec1 (migratable), MedRec2 (migratable), or MedRec3 (migratable).
Click Apply.
To verify that the server was targeted:

Step 6: Create the JMS queues.

JMS queues are based on the point-to-point (PTP) messaging model, which enables the delivery of a message to exactly one recipient. A queue sender (producer) sends a message to a specific queue. A queue receiver (consumer) receives messages from a specific queue.

The following procedure describes how to create the three JMS queues used by message-driven beans for registering new users of the MedRec application, handling email, and uploading XML files.

In the left pane of the Administration Console, select Services-> JMS->Servers->MedRecJMSSserver.
Right-click Destinations and choose Configure a new JMSQueue.
In the right pane, enter jms/REGISTRATION_MDB_QUEUE in the Name field.
Enter jms/REGISTRATION_MDB_QUEUE in the JNDI Name field.
Click Create.
In the left pane, right-click Destinations and choose Configure a new JMSQueue.
In the right pane, enter jms/MAIL_MDB_QUEUE in the Name field.
Enter jms/MAIL_MDB_QUEUE in the JNDI Name field.
Click Create.
In the left pane, right-click Destinations and choose Configure a new JMSQueue.
In the right pane, enter jms/XML_UPLOAD_MDB_QUEUE in the Name field.
Enter jms/XML_UPLOAD_MDB_QUEUE in the JNDI Name field.
Click Create.
To verify that the queues were created:
- Click the Destinations node in the left pane.
- Verify that all three queues appear in the right-hand table.

Step 7: Add email capabilities to the MedRec application.

WebLogic Server includes the JavaMail API version 1.1.3 reference implementation from Sun Microsystems. Using the JavaMail API, you can add email capabilities to your WebLogic Server applications. To configure JavaMail for use in WebLogic Server, you create a Mail Session in the WebLogic Server Administration Console. A mail session allows server-side components and applications to access JavaMail services with JNDI, using Session properties you preconfigure for them.

In the left pane of the Administration Console, open Services.
Right-click the Mail node and choose Configure a new MailSession.
Enter:
Click Create.
Select medreccluster in the Targets box.
Ensure that the All servers in the cluster option is selected.
Click Apply.
To verify that the factory was deployed:

Step 8: Configure the MedRec Sample Authenticator.

The MedRec Sample Authenticator retrieves login credentials from the configured PointBase RDBMS for a given username. Within the provider, passwords are validated, and if correct, the user's group associations are retrieved.

In the left pane of the Administration Console, expand the Security—>Realms—>myrealm—>Providers node.
Select the Authentication node under the Providers node.
In the right pane, select Configure a New MedRec Sample Authenticator.
In the General tab in the right pane:
The SUFFICIENT control flag indicates that the LoginModule does not need to succeed. If it does succeed, control is returned to the application. However, if it does not succeed, the server tries other configured authentication providers.
In the left pane of the Administration Console, expand the Security—>Realms—>myrealm—>Providers—>Authentication node.
Select the DefaultAuthenticator in the left pane of the Administration Console.
In the General tab in the right pane, select SUFFICIENT from the Control Flag menu.
Click Apply.
Because WebLogic Server cycles through available Authentication providers, reorder the provider list so that the PointBase database is not queried each time a login is attempted (for example, each time you log into the Administration Console in subsequent tutorials.

Select the Security—>Realms—>myrealm—>Providers—>Authentication node in the left pane of the Administration Console.
In the right pane of the Console, select Re-Order the Configured Authentication Providers.
Use the arrows in the Configured Providers list to define the following order of authentication providers:
Click Apply.

Best Practices

Only the JMS Server is pinned to a single server in the cluster. Target all other services to all servers in the cluster.
When you create a JDBC DataSource, be sure you enable global transaction support (by checking the Honor Global Transactions box) so that your application can support transaction services.

The MedRec application uses a DataSource with transactions enabled (a TxDataSource object) when persisting application data to the database using entity beans.
Consider using a persistent JMS store to ensure that your JMS messages are not lost if a problem occurs before the message-driven beans process the messages on the JMS queue.
You cannot, however, configure a transaction (XA) JDBC connection pool to be used with a JMS JDBC store. JMS must use a JDBC connection pool that uses a non-XA resource driver. JMS does the XA support in the layer above the JDBC driver.

This is because WebLogic JMS is its own resource manager. That is, JMS itself implements the XAResource and handles the transactions without depending on the database (even when the messages are stored in the database). This means that whenever you are using JMS and a database (even if it is the same database where the JMS messages are stored), then it is two-phase commit transaction.
When configuring the persistent JMS store, you can persist JMS messages to a directory on the file system (called JMS file store) or to a database using JDBC (called JMS JDBC database store). If you want better performance and do not need the reliability of a database, BEA recommends you persist JMS messages to the file system.

The Big Picture

The MedRec application uses JMS to create a new patient record. The asynchronous nature of JMS allows the task to be queued and completed later while the user continues with another task.

After the user clicks Create on the Web page to register a new patient, a JMS message is created and put on the REGISTRATION_MDB_QUEUE JMS queue. The RegistrationEJB message-driven bean takes the message off the queue and persists the new patient data to the database using an instance of the PatientEJB entity bean. The PatientEJB entity bean uses the JDBC DataSource to connect to the Pointbase database.

The MedRec application uses other entity beans to persist additional data to the database.

The MedRec application uses persistent JMS messaging, which means that the new patient JMS messages that are put on the queue are also stored in a Pointbase database so that the messages can be retrieved in case a problem occurs (such as a server crash) before the message-driven bean is able to process them. The application uses the JMS JDBC store to connect to and update the JMS tables in the Pointbase database.