Avitek Medical Records Development Tutorials
Configuring Domains and Servers
Tutorial 3: Configuring WebLogic Server Resources with the Administration Console
This tutorial describes how to configure the WebLogic Server resources required to deploy and run the MedRec application on the MedRec server. These resources include:
- Java Database Connectivity (JDBC) global data sources for the PointBase database management system.
- Java Message Service (JMS) persistent stores, JMS servers, and queues.
- Store and Forward (SAF) agents to be used by Web Services reliable messaging
- JavaMail mail sessions
- Custom DBMS Authenticators
The tutorial includes the following sections:
Prerequisites
Before starting this tutorial:
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.
You use the Administration Console to create the WebLogic Server resources used by the MedRec application suite.
- Open the Administration Console by navigating in a browser to:
http://
host
:7101/console
where host
refers to the computer on which MedRecServer
is running. If your browser is on the same computer as MedRecServer, then you can use the URL http://localhost:7101/console
.
- Specify
weblogic
for both the username and password and click Log In.
Step 2: Create the stand-alone JDBC data sources.
In WebLogic Server, you configure database connectivity by adding JDBC data sources to your WebLogic domain. A data source is a J2EE standard method of configuring connectivity to a database. A data source can be deployed by itself as a stand-alone module, or deployed as part of an Enterprise application as a packaged module.
Each WebLogic data source contains a pool of database connections. Applications look up the data source in the JNDI tree or in the local application context and then reserve a database connection with the getConnection
method. Data sources and their connection pools provide connection management processes that help keep your system running and performing well.
This procedure describes how to create two stand-alone JDBC data sources: the first uses an XA JDBC driver and the second one does not. Typically you always use an XA JDBC driver when creating a data source. However, because JMS JDBC stores do not support XA resource drivers (WebLogic JMS implements its own XA resource), a second non-XA data source is needed. A later procedure shows how to associate the non-XA data source to a JMS JDBC store.
- Click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services—>JDBC.
- In the right pane, click New.
- On the JDBC Data Source Properties page:
- In the Name field, enter
MedRecGlobalDataSource
.
- In the JNDI Name text box, enter
jdbc/MedRecGlobalDataSource
.
- Select
PointBase
as the Database Type.
- Select
PointBase's Driver (Type 4) Versions:4.X 5.X
as the Database Driver.
- On the Transaction Options page, un-check Supports Global Transactions. Leave One-Phase Commit checked.
This JDBC data source will be used to create a JDBC store, which requires that the data source not support global transactions.
- On the Connection Properties page:
- In the Database Name field, enter
demo
.
- In the Host Name field, enter
localhost
(default value).
- In the Port field, enter
9092
(default value).
- In the Database User Name field, enter
medrec
.
- In the Password and Confirm Password fields, enter
medrec
.
- In the Test Database Connection page, ensure that the information to test the connection to the PointBase database is correct.
Text field values are based on information you have already provided as well as default PointBase values (such as the Pointbase driver class name of com.pointbase.jdbc.jdbcUniversalDriver
).
Click Test Configuration to test the connection; the message Connection test succeeded
appears in the Messages pane if you have configured the data source correctly.
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.
- Select the MedRecServer target.
The new data source is listed in the Data Sources table.
- In the Summary of JDBC Data Sources page, click New.
- On the JDBC Data Source Properties page:
- In the Name field, enter
MedRecGlobalDataSourceXA
.
- In the JNDI Name text box, enter
jdbc/MedRecGlobalDataSourceXA
.
- Select
PointBase
as the Database Type.
- Select
PointBase's Driver (Type 4XA) Versions:4.X 5.X
as the Database Driver.
- On the Transaction Options page, click Next.
- On the Connection Properties page:
- In the Database Name field, enter
demo
.
- In the Host Name field, enter
localhost
(default value).
- In the Port field, enter
9092
(default value).
- In the Database User Name field, enter
medrec
.
- In the Password and Confirm Password fields, enter
medrec
.
- In the Test Database Connection page, ensure that the information to test the connection to the PointBase database is correct.
The values of the text fields are based on information you have already provided as well as default Pointbase values (such as the Pointbase XA driver class name of com.pointbase.xa.xaDataSource
).
Click Test Configuration to test the connection; the message Connection test succeeded
appears in the Messages pane if you have configured the data source correctly.
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.
- Select the MedRecServer target.
The new data source is listed in the Data Sources table.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 3: Create the file stores used by Web Services reliable messaging.
The Web Services reliable messaging feature uses a persistent store to store its messages. The MedRec tutorials describe how to use a file store to store the messages; you can also use a JDBC store although this procedure is not documented in the tutorials.
Note: WebLogic Web Services reliable messaging is a service-to-service feature, which means that one client Web Service invokes another Web Service reliably. Typically each Web Service is deployed to two different WebLogic Server instances; each server instance in turn has its own store-and-forward (SAF) agent and persistent store. However, because these tutorials assume a single-server domain for ease of development, both Web Services are deployed to the same server, and thus use the same SAF agent and persistent store.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services.
- In the right pane, click New and choose the Create FileStore option.
- In the Name field, enter
MedRecWseeFileStore
.
- In the Target drop-down list, select
MedRecServer
.
- In the Directory field, enter
medrecWseeFileStore
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 4: Create a JMS JDBC store.
Persistent stores are used to store persistent messages. This JMS JDBC store uses the non-XA data source you created in Step 2: Create the stand-alone JDBC data sources.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services.
- In the right pane, click New and choose the Create JDBCStore option.
- In the Name field, enter
MedRecJMSJDBCStore
.
- In the Target drop-down list, select
MedRecServer
.
- In the Data Source drop-down list, select
MedRecGlobalDataSource
.
- In the Prefix Name field, enter
MedRec
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 5: Create JMS servers.
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.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services—>Messaging.
- In the right pane, click New.
- In the Name field, enter
MedRecJMSServer
.
- In the Persistent Store drop-down list, select
MedRecJMSJDBCStore
.
- In the Target drop-down list, select
MedRecServer
.
- In the Summary of JMS Servers page, click New.
- In the Name field, enter
MedRecWseeJMSServer
.
- In the Persistent Store drop-down list, select
MedRecWseeFileStore
.
- In the Target drop-down list, select
MedRecServer
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 6: Create the stand-alone JMS module and queue.
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.
You configure JMS queues by first creating a stand-alone JMS module and then configuring it with a JMS queue, as described in the following procedure.
In addition to the queue that is part of the stand-alone JMS module, the medrecEar
application uses the following JMS queues configured as part of a packaged JMS module,
REGISTRATION_MDB_QUEUE
MAIL_MDB_QUEUE
XML_UPLOAD_MDB_QUEUE
These application-scoped JMS queues are first registered in the weblogic-application.xml
deployment descriptor of the medrecEar
application, and then described in XML files.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services—>Messaging.
- In the right pane, click New.
- On the Create JMS System Module page:
- In the Name field, enter
MedRec-jms
.
- In the Descriptor File Name field, enter
MedRec-jms.xml
.
- Leave the Location in Domain field blank.
- In the Targets box, check
MedRecServer
.
- Check the Would You Like to Add Resources to This JMS System Module? checkbox.
- At the bottom of the Configuration tab, above or below the Summary of Resources table, click New.
- In the JMS Destination Properties page:
- In the Name field, enter
weblogic.wsee.reliability.wseeMedRecDestinationQueue
.
- In the JNDI Name field, enter
weblogic.wsee.DefaultQueue
.
- Leave the Template drop-down list to
None
.
- Click Advanced Targeting.
- To the right of the SubDeployments drop-down list, click Create a New Subdeployment.
- In the SubDeployment Name field, enter
MedRecWseeJMSServer
.
- In the Targets box, check
MedRecWseeJMSServer
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 7: Create the Store and Forward (SAF) agent.
The Store-and-Forward (SAF) service enables WebLogic Server to deliver messages reliably between applications that are distributed across WebLogic Server instances. In the MedRec application, the SAF service is used internally by the Web Services that have been configured with reliable messaging.
Note: WebLogic Web Services reliable messaging is a service-to-service feature, which means that one client Web Service invokes another Web Service reliably. Typically each Web Service is deployed to two different WebLogic Server instances; each server instance in turn has its own SAF agent and persistent store. However, because these tutorials assume a single-server domain for ease of development, both Web Services are deployed to the same server, and thus use the same SAF agent.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services—>Messaging.
- Click Store-and-Forward Agents.
- In the right pane, click New.
- On the Store-and-Forward Agent Properties page:
- In the Name field, enter
MedRecSAFAgent
.
- In the Persistent Store drop-down list, select
MedRecWseeFileStore
.
- In the Agent Type drop-down list, select
Both
.
- In the Servers box, check
MedRecServer
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 8: Add email capabilities to the MedRec application.
WebLogic Server includes the JavaMail API version 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 pre-configure.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, expand MedRecDomain—>Services.
- In the right pane, click New.
- In the Name field, enter
mail/MedRecMailSession
.
- In the table of Mail Sessions, click on
mail/MedRecMailSession
.
- Select the Configuration tab and:
- In the JNDI Name field, enter
mail/MedRecMailSession
.
- In the JavaMail Properties text box, enter values for the
mail.user
and mail.host
properties.
For example, if you want 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
- In the Servers box, check
MedRecServer
.
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Step 9: Configure the MedRec Custom DBMS Authenticator.
The MedRec Custom DBMS 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.
- If you have not already done so, click Lock & Edit, located in the upper left Change Center window of the Administration Console.
- In the left Domain Structure window, click MedRecDomain—>Security Realms.
- In the right pane, click the
myrealm
entry of the Realms table.
- Select the Providers—>Authentication tab.
- On the Create a New Authentication Provider page:
- In the Name field, enter
MedRecSampleAuthenticator
.
- In the Type drop-down list, select
CustomDBMSAuthenticator
.
- In the Authentication Providers table, click
MedRecSampleAuthenticator
.
- Select the Configuration—>Common tab.
- In the Control Flag drop-down list, select SUFFICIENT.
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.
- Select the Configuration—>Provider Specific tab.
- In the Data Source Name field, enter
MedRecGlobalDataSourceXA
.
- In the Plug-in Class Name field, enter
com.bea.medrec.security.MedRecDBMSPlugin
.
This plug-in class is physically located in the MedRecDBMSPlugin.jar
file that you added to WebLogic Server's CLASSPATH
in Tutorial 1: Creating a WebLogic Domain and Server Instance for Development.
- In the left Domain Structure window, click MedRecDomain—>Security Realms.
- In the right pane, click the
myrealm
entry of the Realms table.
- Select the Providers—>Authentication tab.
- In the Authentication Providers table, click
DefaultAuthenticator
.
- In the Control Flag drop-down list, select SUFFICIENT.
- In the left Domain Structure window, click MedRecDomain—>Security Realms.
- In the right pane, click the
myrealm
entry of the Realms table.
- Select the Providers—>Authentication tab.
Because WebLogic Server cycles through available Authentication providers, this step reorders 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).
- Use the arrows in the Authentication Providers list to define the following order of authentication providers:
MedRecSamplesAuthenticator
- In the Change Center, click Activate Changes to update the MedRec server configuration.
Best Practices
- You typically should use an XA JDBC driver to create a JDBC data source.
- JMS JDBC stores do not support XA resource drivers because WebLogic JMS implements its own XA resource. Therefore, do not associate a JDBC data source 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 that uses 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 that 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
application-scoped 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 data source 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.
The medrecEar
application has two flavors of Web Services that the physicianEar
application invokes: reliable and non-reliable. The reliable Web Service uses the store-and-forward agent and filestore internally to ensure that the messages are delivered reliably.
The WebLogic Server security framework cycles through the three configured providers (DefaultAuthenticator
, MedRecSamplesAuthenticator
, and DefaultIdentityAsserter
) during patient authentication.
Related Reading