Setting Up WebLogic Server Resources for the MedRec Server

This tutorial describes how to set up the WebLogic Server resources required to deploy and run the MedRec application. The tutorial sets up resources for the MedRec server. These resources include:

• Java Database Connectivity connection pools and data sources for the PointBase database management system

• Java Message Service persistent store, JMS server, queue, and connection factory

• JavaMail mail sessions

The tutorial includes the following sections:

• Prerequisites

• Procedure

• Best Practices

• The Big Picture

• Related Reading

Prerequisites

Before starting this tutorial:

• Create the MedRec domain and MedRec server, and start the MedRec server. See Tutorial 1: Creating a WebLogic Domain and Server Instance for Development.

• Start the PointBase database management system. See Tutorial 2: Starting the PointBase Development Database.

Procedure

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

• Step 1: Invoke the Administration Console for the MedRec server in your browser.

• Step 2: Create the JDBC connection pools.

• Step 3: Create a JDBC DataSource.

• Step 4: Create a JMS JDBC store.

• Step 5: Create a JMS server.

• Step 6: Create the JMS queues.

• Step 7: Create a JMS connection factory.

• Step 8: Add email capabilities to the MedRec application.

• Step 9: Configure the MedRec Sample Authenticator.

Step 1: Invoke the Administration Console for the MedRec server in your browser.

Use the Administration Console to create the WebLogic Server resources used by the MedRec application suite.

1. Enter the following URL in your browser:

   http://127.0.0.1:7101/console
   
   

2. Enter weblogic as the username and password, then click Sign In.

Step 2: Create the JDBC connection pools.

A JDBC connection pool describes how to physically connect to a database, in this case a PointBase database. This procedure describes how to create two JDBC connection pools: the first uses an XA JDBC driver and the second one does not.

Typically you always use an XA JDBC driver when creating a connection pool. However, because JMS JDBC stores do not support XA resource drivers (WebLogic JMS implements its own XA resource), a second non-XA connection pool is needed. Later procedures show how to associate the XA connection pool to a JDBC DataSource and the non-XA connection pool to a JMS JDBC store.

1. In the left pane of the Administration Console, expand Services - >JDBC.

2. Click Connection Pools.

3. In the right pane, click Configure a new JDBC Connection Pool.

4. Select PointBase as the Database Type.

5. Select PointBase's Driver (Type 4XA) Versions:4.X as the Database Driver.

6. Click Continue.

7. In the Name field, enter MedRecPool-PointBase-XA.

8. In the Database Name field, enter demo.

9. Accept localhost as the Host Name of the computer that is hosting PointBase.

10. In the Port field, enter 9092.

11. In the Database User Name field, enter medrec.

12. In the Password and Confirm Password fields, enter medrec.

13. Click Continue.

14. 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. For details, see Tutorial 2: Starting the PointBase Development Database.

15. After verifying that the connection succeeded, click Create and Deploy.

16. Click Configure a new JDBC Connection Pool.

17. Select PointBase as the Database Type.

18. Select PointBase's Driver (Type 4) Versions:4.X as the Database Driver.

19. Click Continue.

20. In the Name field, enter MedRecPool-PointBase.

21. In the Database Name field, enter demo.

22. Accept localhost as the Host Name of the computer that is hosting PointBase.

23. In the Port field, enter 9092.

24. In the Database User Name field, enter medrec.

25. In the Password and Confirm Password fields, enter medrec.

26. Click Continue.

27. Ensure that the information to test the connection to the PointBase database is correct, then click Test Driver Configuration.

28. After verifying that the connection succeeded, click Create and Deploy.

Step 3: 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. This DataSources uses the XA connection pool you created in Step 2: Create the JDBC connection pools.

1. In the left pane of the Administration Console, expand Services - > JDBC.

2. Click Data Sources.

3. In the right pane, click Configure a new JDBC Data Source.

4. In the Name field, enter MedRecTxDataSource.

5. In the JNDI Name field, enter MedRecTxDataSource.

6. Select the Honor Global Transactions checkbox.

7. Click Continue.

8. In the Pool Name list box, select MedRecPool-PointBase-XA.

9. Click Continue.

10. Ensure that MedRecServer is selected as the server on which you want to deploy this data source.

11. Click Create.

Step 4: Create a JMS JDBC store.

JMS stores are used to store persistent messages. This JMS JDBC store uses the non-XA connection pool you created Step 2: Create the JDBC connection pools.

1. In the left pane of the Administration Console, expand Services - > JMS.

2. Click Stores.

3. In the right pane, click Configure a new JMS JDBC Store.

4. In the Name field, enter MedRecJMSJDBCStore.

5. In the Connection Pool list box, select MedRecPool-PointBase.

6. In the Prefix Name field, enter MedRec.

7. Click Create.

Step 5: Create a JMS server.

JMS servers host the queue and topic destinations used by JMS clients. To persistently store messages in destinations, the JMS server must be configured with a JMS store.

1. In the left pane of the Administration Console, expand Services - > JMS.

2. Click Servers.

3. In the right pane, click Configure a new JMS Server.

4. In the Name field, enter MedRecJMSServer.

5. In the Persistent Store list box, select MedRecJMSJDBCStore.

6. Click Create.

7. In the Target list box, select MedRecServer.

8. Click Apply.

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 three JMS queues, which are used by message-driven beans for registering new users of the MedRec application, handling email, and uploading XML files.

1. In the left pane of the Administration Console, expand Services - > JMS - >Servers - >MedRecJMSSserver.

2. Create the queue for the registration message-driven bean:

   1. In the left pane, click Destinations.

   2. In the right pane, click Configure a new JMS Queue.

   3. In the Name field, enter jms/REGISTRATION_MDB_QUEUE.

   4. In the JNDI Name field, enter jms/REGISTRATION_MDB_QUEUE.

   5. Click Create.

3. Create the queue for the email message-driven bean:

   1. In the left pane, click Destinations.

   2. In the right pane, click Configure a new JMS Queue.

   3. In the Name field, enter jms/MAIL_MDB_QUEUE.

   4. In the JNDI Name field, enter jms/MAIL_MDB_QUEUE.

   5. Click Create.

4. Create the queue for the XML upload message-driven bean:

   1. In the left pane, click Destinations.

   2. In the right pane, click Configure a new JMS Queue.

   3. In the Name field, enter jms/XML_UPLOAD_MDB_QUEUE.

   4. In the JNDI Name field, enter jms/XML_UPLOAD_MDB_QUEUE.

   5. Click Create.

Step 7: Create a JMS connection factory.

JMS clients use JMS connection factories to create a connection to a WebLogic Server instance. JMS client messaging requests to a particular destination are routed through their connection's host WebLogic Server to the WebLogic Server hosting the JMS server destination. JMS connection factories are also used to configure the defaults for the JMS clients that use them.

1. In the left pane of the Administration Console, expand Services - > JMS.

2. Click Connection Factories.

3. In the right pane, click Configure a new JMS Connection Factory.

4. In the Name field, enter jms/MedRecQueueConnectionFactory.

5. In the JNDI Name field, enter jms/MedRecQueueConnectionFactory.

6. Click Create.

7. In the Targets box, select MedRecServer.

8. Click Apply.

9. Select the Configuration - >Transactions tab.

10. Select the XA Connection Factory Enabled check box.

11. Click Apply.

Step 8: 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 that you preconfigure.

1. In the left pane of the Administration Console, expand Services - >Mail.

2. In the right pane, click Configure a new Mail Session.

3. In the Name field, enter mail/MedRecMailSession.

4. In the JNDIName field, enter mail/MedRecMailSession.

5. In the Properties text box, enter values for the mail.user and mail.host properties.

   For example, if you want any email generated by the MedRec application to be sent to you, and your email address is joe@mail.mycompany.com, enter:

    mail.user=joe;mail.host=mail.mycompany.com
   
   

6. Click Create.

7. In the Targets box, select MedRecServer.

8. Click Apply.

Step 9: 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.

1. In the left pane of the Administration Console, expand the Security - >Realms - >myrealm - >Providers node.

2. Select the Authentication node under the Providers node.

3. In the right pane, select Configure a New MedRec Sample Authenticator.

4. On the General tab in the right pane:

   • In the Name field, enter MedRecSampleAuthenticator.

   • From the Control Flag menu, select SUFFICIENT.

   • Click Create to create the new authenticator.

   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.

5. In the left pane of the Administration Console, expand Security - >Realms - >myrealm - >Providers - >Authentication.

6. In the left pane of the Administration Console, click DefaultAuthenticator.

7. In the General tab in the right pane, select SUFFICIENT from the Control Flag menu.

8. Click Apply.

9. 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).

   In the left pane of the Administration Console, select Security - >Realms - >myrealm - >Providers - >Authentication.

10. In the right pane of the Console, click Re-Order the Configured Authentication Providers.

11. Use the arrows in the Configured Providers list to define the following order of authentication providers:

    1. DefaultAuthenticator

    2. MedRec Samples Authenticator

    3. DefaultIdentityAsserter

12. Click Apply.

Best Practices

• When you create a JDBC DataSource, be sure you enable global transaction support (by selecting 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.

• You typically want to use an XA JDBC driver when creating a JDBC connection pool.

• JMS JDBC stores do not support XA resource drivers as WebLogic JMS implements its own XA resource. Therefore, do not associate a connection pool that uses an XA JDBC driver with a JMS JDBC store.

• In most cases, to avoid unnecessary JMS request routing, the JMS connection factory should be targeted to the same WebLogic Server instance as the JMS server.

• 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 simpler configuration, BEA recommends you persist JMS messages to the file system. If you want to store your persistent messages in a remote database rather than on the JMS server's host machine, BEA recommends you use a JDBC JMS store.

• Always configure quotas for WebLogic JMS servers. JMS quotas prevent too many messages from overflowing server memory. In addition, consider configuring message paging, as persistent and non-persistent messages consume server memory unless paging is enabled.

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; for details, see Patient, Physician, and Administrator Data.

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 to update the JMS tables in the PointBase database.

Related Reading

• Introduction to WebLogic JDBC

• JDBC Connection PoolsJMS Topic Page

• WebLogic JMS Fundamentals

• Configuring JMSUsing JavaMail with WebLogic Server Applications