WebSphere Distributed Transaction Support for a Generic JMS Provider Table of contents Overview.......................................................................................................................................... 2

Sample application...................................................................................................................... 2 WebSphere Application Server V5.................................................................................................. 3

Software requirements ................................................................................................................ 3 Configure DB2 database to support two-phase commit transaction........................................... 3 Prepare a generic JMS provider -- SonicMQ .............................................................................. 3 Configure the WebSphere JDBC provider and data source ....................................................... 7 Configure the WebSphere generic JMS providers.................................................................... 12 Create a generic JMS provider ................................................................................................. 12 Configure a JMS Connection Factory ....................................................................................... 13 Configure a JMS Destination .................................................................................................... 14 Configure a Listener Port of a Message Driven Bean............................................................... 15 Deploy and test the sample application .................................................................................... 18

WebSphere Application Server Version 4 ..................................................................................... 24 Software requirements .............................................................................................................. 24 Configure a DB2 database to support two-phase commit transaction...................................... 24 Prepare a generic JMS Provider – SonicMQ ............................................................................ 24 Install the required WebSphere Fix Pack and e-fixes ............................................................... 25 WebSphere Application Server transactions support for Generic Java Message Service providers.................................................................................................................................... 25 Configure WebSphere JDBC provider and Data Source .......................................................... 25 Configure WebSphere generic JMS providers.......................................................................... 27 Bind and register the external JMS provider information into WebSphere............................... 27 Create WebSphere XA generic JMS provider .......................................................................... 27 Create the JMS Connection Factory ......................................................................................... 28 Create JMS destinations ........................................................................................................... 29 Deploy and test the sample application .................................................................................... 31

Conclusion ..................................................................................................................................... 37

Overview IBM® WebSphere® Application Server is a leading Java™ transaction server that lets the customer run transactional business logic. As a transaction manager, WebSphere Application Server supports the coordination of resource managers like Relational Database and JMS provider through their XAResource interface and participates in distributed global transactions using the two-phase commit protocol. IBM WebSphere MQ is the leading messaging product in the e-business world, and the integration with WebSphere Application Server is well documented and used by many customers. To accommodate customers using different JMS providers other than WebSphere MQ, this article demonstrates the configuration and basic behavior of WebSphere distributed global transaction support for generic JMS provider. This tutorial configures WebSphere Application Server Version 4 and 5 with SonicMQ Evaluation Edition Version 5, a generic JMS provider. It highlights the generic JMS provider and two-phase commit transaction support available under WebSphere Application Server Version 4 and 5. The same concepts and descriptions are applicable to any XA enabled JMS providers. The sample application code included in this tutorial demonstrates various usages of messaging in this environment. Special emphasis is placed on configuring this environment to support two-phase commit/XA transactions using IBM DB2 UDB and SonicMQ, with WebSphere acting as the transaction coordinator. Sample application This tutorial uses two J2EE enterprise applications to demonstrate the two-phase commit feature under WebSphere Application Server Version 4 and 5. These applications follow J2EE specification 1.2 and 1.3 respectively, and the sample application for WebSphere Application Server V5 contains an extra component called Message Driven Bean (MDB). The demo application is very simple. A stateless session EJB will insert a DB2 database record into EMPLOYEE table of DB2 SAMPLE database and then publish a message to the generic JMS provider under a global transaction context. All the business logic is wrapped by a container managed transactional method whose transaction attribute is set as “Required”. We also presented a Web application as the test driver that will input business data and invoke the session EJB to process a transaction. You can download the sample Enterprise applications that contain all the source code. The development tool for those sample applications is WebSphere Studio Application Developer Version 5. Now, let’s begin our tour of the WebSphere two-phase commit transaction demo. Two sections of this documentation demonstrate the configuration for WebSphere Application Server V5 and V4 separately.

WebSphere Application Server V5 Software requirements

• Windows® 2000 Pro Service Pack 3 • WebSphere Studio Application Developer Version 5.0 • WebSphere Application Server Version 5.0.1 (base) • IBM DB2 UDB 7.2 with fixpack 7 for Windows • SonicMQ Evaluation Edition Version 5.0

Configure DB2 database to support two-phase commit transaction Let’s begin by using the DB2® “SAMPLE” database in this lab, and making sure that DB2 has started by checking the Windows Services. You need to configure the DB2 instance to use JTS as the transaction processing monitor (TP). This is required by the WebSphere transaction manager for two-phase commit transaction protocol.

1. Select Start Programs IBM DB2 Control Center to bring up the DB2 control center GUI. 2. Right-click the DB2 instance that contains the SAMPLE database that is to be enabled for JTA

access. 3. Select Multisite Update Configure to start the Smart guide utility. 4. Click the Use the TP monitor named below radio button. Select JTS as the TP monitor, and click

Finish. 5. Bind the necessary packages to the database. From the DB2 Command Line Processor window,

select Start programs IBM DB2 DB2 Command Line Processor; issue the following commands:

db2=> connect to sample

db2=> bind db2home\bnd\@db2cli.lst db2=> bind db2home\bnd\@db2ubind.lst db2=> disconnect sample

Important: db2home is the installation root for IBM DB2 UDB, “C:\SQLLIB” in our case. This is a onetime configuration for DB2 that lets WebSphere get XA enabled database connections from DB2. Prepare a generic JMS provider -- SonicMQ In this lab, we will use the default SonicMQ configuration provided by the product installation program. The most important configuration for integrating with WebSphere Application Server is creating JMS Administered Objects – Connection Factory and Destinations. SonicMQ provides JMS Administered Objects Tool, a utility that can accomplish this task.

1. Start SonicMQ Broker and Container. From Windows, select Start Programs Sonic Software SonicMQ SonicMQ Container1. SonicMQ starts the container and broker.

2. Open the Sonic Management Console. From Windows, select Start Programs Sonic Software SonicMQ Management Console.

3. In the “Management Console”, select Tools JMS Administered Objects. The JMS Administered Objects tool opens.

4. Select JNDI Naming Service Sonic Storage. 5. If the domain name is not the default Domain1, specify the domain name in Domain. The

classname for the Context Factory is automatically selected. 6. Specify the URL of the management broker as the Provider URL. ( tcp://localhost:2506 ) 7. Select Connect to connect to the internal store. The new connection is listed under Object Stores,

as shown in following figure:

Figure 1. Connect to SonicMQ JNDI Naming Service internal store.

8. Click Connect. 9. Under Object Stores in the left panel, select the connection and then select the Connection

Factories tab in the right panel. Select New. 10. In the Administration section in the General tab of the Connection Factory Maintenance panel,

specify:

Lookup Name — Enter a name of your choice for the connection factory object. (XAJmsTopicConnectionFactory) Factory Type — Select the connection factory type from the Factory Type list:

XATopicConnectionFactory

11. In the Basic Connection Parameters section, specify the Connection URL tcp://hostname:port ( tcp://localhost:2506 ).

12. Leave the rest configuration parameters as the default value, Select Update. The top panel displays the new connection factory.

Figure 3. Create JMS Administered Objects – XAConnectionFactory.

13. To provide the support for WebSphere Message Driven Bean, we need to create another JMS Connection Factory object in SonicMQ. Specify the lookup name as “ListenerTopicConnectionFactory”.

Important: The Factory type for this object will be -- TopicConnectionFactory

Figure 4. Create Non-XA TopicConnectionFactory.

14. From Object Stores in the left panel, select the connection. The right panel has two tabs:

Destinations and Connection Factories. Select New. 15. Enter a Lookup Name for the Topic or Queue – DemoTopic. 16. Select the Destination Type: Queue or Topic. 17. Enter the Destination Name (TopicA in our case), the name of the queue or topic, then click

Enter.

Figure 5. Create JMS Administered Objects – Destinations.

Exit the Sonic Management Console. Configure the WebSphere JDBC provider and data source In this part, you will create an XA enabled DB2 JDBC driver that lets WebSphere Application Server connect to DB2 database using two-phase commit transaction protocol, and prepare a data source under this JDBC driver.

1. Start the WebSphere Application Server. From Windows command line, type:

C:\WebSphere\AppServer\bin\> StartServer.bat server1 Important: This article assumes that WebSphere Application Server V5 has been installed under: C:\WebSphere\AppServer

2. Open a browser and start WebSphere Web based admin client window by pointing to following address: http://localhost:9090/admin 3. From the left panel Navigation Tree of your admin console, expand the Resources and click on JDBC Providers: 4. Select the proper scope for your JDBC provider; it is “Node” in our case. 5. Click New. From the General Properties page, select DB2 Legacy CLI-based Type 2 JDBC Driver (XA) from the drop down list, and then click OK.

Figure 6. Create a new JDBC provider.

You should get a page like Figure 7 below.

Figure 7. Create DB2 XA JDBC provider.

Important: WebSphere Application Server V5 uses “WebSphere Variables” to manage some path anclasspath settings. So, in the “classpath” property for your JDBC Driver, it uses the ${DB2_JDBC_DRIVER_PATH} to present the directory where the JDBC driver is located. Please make sure that you have already defined this variable in your WebSphere Environment.

classpath settings. So, in the “classpath” property for your JDBC Driver, it uses the ${DB2_JDBC_DRIVER_PATH} to present the directory where the JDBC driver is located. Please make sure that you have already defined this variable in your WebSphere Environment.

d d

To define this variable: Expand Environment and click Manage WebSphere Variables. Then, click “DB2_JDBC_DRIVER_PATH” from the right panel. Specify the directory where contains your DB2 JDBC driver in the variable definition page: (c:/SQLLIB/java in our case)

To define this variable: Expand Environment and click Manage WebSphere Variables. Then, click “DB2_JDBC_DRIVER_PATH” from the right panel. Specify the directory where contains your DB2 JDBC driver in the variable definition page: (c:/SQLLIB/java in our case) Figure 8. Manage WebSphere variables. Figure 8. Manage WebSphere variables.

Let’s keep going and create the data source for our sample application.

6. Locate the DB2 Legacy CLI-based Type 2 JDBC Driver (XA) you just created. Click it to get into the JDBC Providers page. At the bottom of your workspace, locate the Additional Properties and click Data Sources to get into the data source creation page.

7. Click New to create a new data source. In the data source creation workspace, type in the Name of the Data Source, JNDI name for the data source (jdbc/SampleDBXA for our sample Application ), and keep the Datasource Helper Classname as the default value.

com.ibm.websphere.rsadapter.DB2DataStoreHelper. You can leave the rest of properties as the default value.

8. Click OK to finish the data source creation process. Now, we need to configure the Authentication for the data source we created.

9. Click the data source you just created. Locate and click the J2C Authentication Data Entries 10. At the bottom of the current workspace, click New. 11. In the configuration page for the new Authentication alias, type in the Alias name, user Id

and password, which has permission to access DB2 database. Figure 9. Create new Authentication alias for the data source

12. Click OK. 13. Get back to the Configuration page for the data source, locate the property Container-managed

Authentication Alias and select the Alias we just created from the drop down list. Click OK to finish the data source configuration.

Now, let’s save all our new configurations. From the Task Bar on top of your admin console, click Save and follow the instructions to save the configuration change. In the normal step, we should specify the real DB2 database in the Data Source “Custom Properties” configuration page. However, WebSphere uses the “SAMPLE” for all the Data Source database default value, so we can take advantage of this default.

Configure the WebSphere generic JMS providers WebSphere Application Server Version 5 supports the use of generic JMS Providers, and provides the service for two-phase commit transaction with Generic JMS Server as the resource manager. WebSphere Generic JMS Provider provides JNDI mapping for the real JMS connection factory and JMS destination objects configured into the external name space, hiding the use of an external provider and its resources from the custom applications. In this part, we will register the JMS destinations and JMS connection factories into the WebSphere JNDI name space using Admin Console. Create a generic JMS provider

1. Start WebSphere Application Server and open an Admin Console. 2. In the navigation tree, expand Resources, and click Generic JMS Providers. 3. Select the right scope for this resource (Node for our case), and click New to start creating a new

JMS provider. Here is the configuration page for creating a new Generic JMS provider: Figure 10. Create a new Generic JMS provider.

In the Classpath property, you need to specify the Generic JMS provider’s client side libraries.

For the External Initial Context Factory and External Provider URL, you should type in the Generic JMS Server’s JNDI implementation, the Java class name (com.sonicsw.jndi.mfcontext.MFContextFactory) for Initial Context Factory and URL for the JNDI naming server respectively.

Configure a JMS Connection Factory

1. In the navigation tree, expand the Resources Generic JMS Providers. 2. In the workspace, click the JMS provider we just created (Sonic JMS Provider). 3. At the bottom of this configuration page, locate the Additional Properties and click the JMS

Connection Factories. Then click New to create a new Connection Factory. Figure 11. Create a new JMS ConnectionFactory.

Here are the configuration properties: Name Used by WebSphere for administration purposes. Type Specify this connection factory. It is used for point-to-point or the pub/sub model. JNDI Name Used to bind the connection factory to the application server’s name space.

External JNDI Name

The Generic JMS Server managed JMS administered object for Connection Factory JNDI name.

The authentication configuration is depending on the vendor implementation of the Generic JMS Server. We leave it blank in our case. Click OK to finish and save the configuration. WebSphere V5 provides the service of JMS connection and session pooling. Configure a JMS Destination

1. In the navigation tree, expand the “Resources” Generic JMS Providers, 2. In the workspace, click the JMS provider we just created (Sonic JMS Provider). 3. At the bottom of this configuration page, locate the Additional Properties and click the JMS

Destinations. Then click New to create a new JMS Destination. Figure 12. Create a new JMS Destination.

Here are the configuration properties for the JMS destination: Name Used by WebSphere for administration purposes. Type Specify this connection factory is used for point-to-point or pub/sub model. JNDI name Binds the destination into the application server’s name space. External JNDI Name The Generic JMS Server managed JMS administered object.

Configure a Listener Port of a Message Driven Bean WebSphere Version 5 support for Message Driven Bean (MDB) is based on JMS message listener and the message listener service. The main component of WebSphere’s MDB support is the Listener Port that will bind the JMS Connection Factory and JMS Destinations. In this section, we will demonstrate the usage of a MDB with the Generic JMS Server as JMS provider.

1. Create another Connection Factory under Sonic JMS Provider.

Figure 13. Create a WebSphere JMS ConnectionFactory for MDB Listener.

2. In the navigation frame, expand Server and click on Application Servers. 3. Click the Server1 from the workspace. 4. In the configuration page, under Additional Properties, select Message Listener Service.

Figure 14. WebSphere Message Listener Service.

5. From the “Message listener Service” page, select Listener Ports and click New. 6. In the configuration page, specify “DemoListener” as the Listener port name. Set the Initial State to

start. Fill in the JNDI names for the Connection Factory and Destinations we created in last two steps into the “Connection Factory JNDI name” (jms/sonic/ListenerTCF) and “Destination JNDI name” (jms/sonic/DemoTopic).

Figure 15. Create Listener Port.

7. Click OK to complete the Listener Port creation. Save the changes. 8. Restart WebSphere Application Server.

Deploy and test the sample application Now, it is the time to deploy and test our sample application. We will use WebSphere Studio Application Developer V5 as the build and deployment tool in this article. The sample application has been created for you. Important: You can skip the WebSphere Application Developer part of this excercise, and download the sample application ear file from the link XADdemo_V5.ear.

1. Start WebSphere Application Developer Start Programs IBM WebSphere Studio Application Developer 5.0; accept the default workspace directory.

2. In the J2EE perspective, locate the “XADemo_V5EJB” project and expand this folder. Double click the EJB Deployment Descriptor. In the deployment descriptor view, click the References tab, you can find out all the resource reference definition and bindings been configured for you.

Figure 16. Define the Resource References using WebSphere Studio Application Developer.

3. Click the Assembly Descriptor tab, locate the “Container transactions” setting. Make sure the Required transactional feature has been set for XADummy:TestXA method

4. Locate the “XADemo_V5” Enterprise Application project, right-click and select Export. Choose “EAR file” and Next. Specify the directory where you want to export this ear file to:

Figure 17. Export Enterprise application ear file.

Close WebSphere Studio Application Developer.

5. After properly configuring the JDBC and JMS provider, we can begin to install and test our sample application. Start the Generic JMS Server first. Then start the WebSphere V5 Application server, and open the Admin Console.

6. From the navigation frame, expand the Applications and click Install New Application. 7. From the Preparing for the application installation page, specify the location for the

sample: application ear file: \WebSphere\AppServer\installableApps\XADemo_V5.ear and click Next.

8. Select the “Generate Default Bindings:” check box and leave everything else as default value. Click Next.

9. Now you are in “Step 1: Provide options to perform the installation”. Select Deploy EJBs and click Next.

10. In step 2 of Enterprise application installation wizard, choose DB2UDB_V72 for the Deploy EJBs Option – Database type. Click Next.

11. Specify the Listener Port for the Message Driven bean in the sample application. We will use the DemoListener we created in last section.

12. Keep the default values in step 4 of the installation wizard, and click Next to step 5. 13. “Step 5: Map resource references to resources”, here you need to bind the Application

resource reference to the run time JDBC and JMS providers. Click Next.

Figure 18. Bind the resource references

14. Leave all the default settings in Step 6, 7, 8, and review your configuration in “Step 9: Summary.” 15. Click to finish and to install the sample application. When the installation process is

complete, you should see Application XADemo_V5 installed successfully. Save the current configuration before starting the demo application.

16. Now, you can start the Application and run the demo. In the Admin Console, expand the Applications and click Enterprise Applications. Select the check box besides the XADemo_5 and click Start from the menu bar. (You may need to restart the Application Server before launching the sample application).

Figure 19. Start the Demo Enterprise Application.

With the Enterprise Application started successfully, you can launch a browser and test our demo application: http://localhost:9080/XADemo

Figure 20. Access the demo Web page and input test information.

SonicMQ provides a sample application MessageMonitor that listens for any message topic activity—by subscribing to all topics in the topic hierarchy—and then displays each message in its window. In the Sonic Command Prompt, browse to MessageMonitor directory: C:\SonicMQ\samples\TopicPubSub\MessageMonitor Then, type the command: ..\..\SonicMQ MessageMonitor . It will open a GUI window. After submitting an employee record from the Demo web page, you can check the Topic and browse the message sent by Demo Application: Click the link to submit the request: If the two-phase commit transaction completes successfully, you should see this screen:

Figure 21. Demo result page.

And you can use the DB2 control center or command line to check whether the database record is successfully inserted into the Employee table. Check the SonicMQ MessageMonitor window, you will find the message that published through the sample application. Figure 22. SonicMQ Topic monitor.

Remember, we have a message driven bean deployed into the server, and will monitor the messages been published. In our demo, the MDB will catch the message and write it out to the Application Server standard output. So, let’s check the file:

C:/WebSphere/AppServer/logs/server1/SystemOut.log: Here is what we get from a single transaction: [3/25/03 14:23:32:625 EST] 3710bd8a SystemOut O INFO: Message has been successfully published to Generic JMS Server ( Stateless EJB publish message ) [3/25/03 14:23:33:356 EST] 6485bdb4 SystemOut O Pub/Sub sample message bean onMessage() method called ( MDB’s onMessage() called ) [3/25/03 14:23:33:356 EST] 6485bdb4 SystemOut O onMessage() text received: INFO: Message received from user: Gang Chen ( display the message received ) In order to test the basic behavior of WebSphere distributed global transaction, we can do a very simple test. Just go back to the input page of the sample Web application. Fill in the employee information with a duplicate Employee No (We have changed the SAMPLE database employee table definition to enable the EmployNo as primary key). Obviously, the database insert will fail. Consequently, you can’t see any message related to this global transaction been published to JMS topic by using the SonicMQ MessageMonitor.

WebSphere Application Server Version 4

Software requirements

• Windows 2000 Service Pack 3 • WebSphere Studio Application Developer V5.0 • WebSphere Application Server Advanced Edition Version 4.0.5 • IBM DB2 UDB 7.2 with fixpack 7 for Windows • SonicMQ Evaluation Edition Version 5.0

Configure a DB2 database to support two-phase commit transaction Please reference section 1 for instructions. Prepare a generic JMS Provider – SonicMQ Please reference section 1 for instructions. You don’t need to setup the ConnectionFactory for Message Driven Bean in this session.

Install the required WebSphere Fix Pack and e-fixes To use a generic JMS server as the JMS provider under WebSphere Version 4, you have to install at least WebSphere Fix Pack 4. Besides the Fix Pack, there are several e-fixes that need to be applied as well to support the full feature of WebSphere Generic JMS Server integration. Please check the following table to set up your environment:

Table 1. Required WebSphere e-fixes

WAS 4.0.4 WAS 4.0.5 WAS 4.0.6 PQ67210 WebSphere Application Server transactions support for Generic Java Message Service providers

Apply PQ67210 Part of fixpack 5

PQ69610 Transaction Manager unneccessarily spawns retry thread when a XAER_RMFAIL (-7) return is given from xa_end.

Apply PQ69610 Apply PQ69610 Will be part of fixpack 6

PQ70608 Memory Leak

Apply PQ70608 Apply PQ70608 Will be part of fixpack 6

PQ73742 Generic JMS provider connection and session close

Apply PQ73742 Apply PQ73742 Will be part of fixpack 6

You can download WebSphere fixpack and e-fixes from IBM WebSphere’s support Web site; here is the link: http://www-3.ibm.com/software/webservers/appserv/support/ Follow the exact order when applying e-fixes. For instance, apply PQ67210 first, then PQ69610 and PQ70608. Besides those efixes, you need to copy one of the WebSphere MQ ma88 library file to WebSphere’s lib directory. It is com.ibm.mq.jar and you can download this file from the IBM WebSphere MQ Support Web site. Configure WebSphere JDBC provider and Data Source You need to start your WebSphere administration Server first before configuring any resources.

1. Start the Admin Console, and select WebSphere Administration Domain Resources JDBC Providers.

2. Highlight the JDBC Providers, right-click, and select New to bring up the JDBC Provider properties dialog where you can create your JDBC provider for XA access to DB2.

3. In the General page, give it a name, and make sure you choose “COM.ibm.db2.jdbc.DB2XADataSource” as the Implementation class.

4. Click the “Node” tab to specify the library for DB2 JDBC Driver.

Figure 1. Create a new JDBC provider.

5. Click OK to close the dialog window. 6. From the Admin Console Resources list, you can see the JDBC driver you just created. Click the

“+” to expand this item, right click the DataSources folder and choose New. 7. In the Data Source Properties window, specify the Data Source you want to use:

Figure 2. Create a new Data Source.

There is no specific Data Source configuration to enable database global transaction. Configure WebSphere generic JMS providers Bind and register the external JMS provider information into WebSphere As defined by J2EE JMS specification, the JMS provider should provide two types of JMS administered objects – Connection Factory and Destinations by using a JNDI store. Since WebSphere is the transaction coordinator, it needs to know the information of those JMS administered objects. We need to bind or register the JNDI information for those JMS administered objects into WebSphere’s JNDI namespace. WebSphere Application Server provides a utility to accomplish this task. com.ibm.ejs.jms.generic.GenericJMSBinder We have provided a script that will execute this utility from a command line. You can download this script JMSBinder.bat. Important: Make sure that the WebSphere Admin Server and Generic JMS server are running before executing this script to bind the JMS administered objects. Create WebSphere XA generic JMS provider To provide the support for Generic JMS provider in a two-phase commit environment, we have to use the WebSphere JMS provider component. It adds an extra support level on top of the JMS provider client library to enable WebSphere transaction management for generic JMS resources.

1. Start the WebSphere Admin Console.

2. Under the Resources, locate the JMS Providers. Right-click and choose New, you should type in the name for this provider, and JNDI lookup Information:

Figure 3. Create WebSphere generic JMS provider.

Please make sure that you use “com.ibm.websphere.naming.WsnInitialContextFactory” as the Context factory class name, and WebSphere naming provider URL as the Provider URL.

3. Switch to the Nodes tab where you should specify the classpath for the required Generic JMS provider client side libraries.

For SonicMQ, you should specify following library jar files in the Nodes classpath:

%SonicMQ_HOME%/lib/sonic_Client.jar

%SonicMQ_HOME%/lib/sonic_XA.jar %SonicMQ_HOME%/lib/mfcontext.jar %SonicMQ_HOME% is the installation root directory for SonicMQ. In our case, it is c:\SonicMQ

4. Click OK when you finish the setting. Create the JMS Connection Factory

1. Expand the JMS provider you just created, right click the “JMS Connection Factories” and select New.

Figure 4. Create JMS Connection Factory.

2. In the External JNDI path, you should type in the JNDI name (WASNameSpaceURL) you used in the JMS binder script. (It is an indirect JNDI lookup you can see from this step).

Create JMS destinations This part is a little bit tricky, we need to create another Generic JMS provider, and use the external JMS server as the JNDI naming Server instead of the WebSphere implementation. It is totally different than configuring the JMS Connection Factory object, because it has to be wrapped by WebSphere to provide XA support. However, there is no XA requirement for a JMS destination like Queues or Topics, so we can directly binds them into external JMS server’s JNDI name space.

1. Following the same steps described in previous section “setup WebSphere XA JMS provider”, create another Generic JMS Provider named “Non-XA Generic JMS Provdier”, and replace the WebSphere JNDI parameters with external JMS provider’s JNDI service.

Figure 5. Create a Non-XA Generic JMS provider.

Important: Don’t forget to install the JMS client side libraries into Nodes.

2. Right click the JMS Destinations and select New to expand this newly created Generic JMS Server. Type in the JNDI name for the JMS Queues or Topics.

The JNDI name for JMS Destination will be the JNDI name for the JMS administered object directly from the JMS provider JNDI namespace.

Figure 6. Create JMS destinations.

So far, we have finished all required configurations for all the resources. Deploy and test the sample application Now, it’s the time to deploy and test our sample application. We will use WebSphere Studio Application Developer V5 as the build and deployment tool in this lab -- the sample application has been created for you. Important: You can skip the WebSphere Studio Application Developer part of this section, and get the sample application ear file from the Web link, XADdemo_V4.ear

1. Start WebSphere Studio Application Developer by selecting Start Programs IBM WebSphere Studio Application Developer 5.0, and accept the default workspace directory.

2. In the J2EE perspective, locate the “XADemo_V4EJB” project and expand this folder. Double-click the EJB Deployment Descriptor. In the deployment descriptor view, click the References tab; you can see all the resource reference definition and bindings that have been configured for you.

Figure 7. Define the resource references using Websphere Studio Application Developer.

3. Locate the “XADemo_V4” Enterprise Application project, right click and select Export. Choose “EAR file” and Next. Specify the directory to where you want to export this ear file:

Figure 8. Export Enterprise application ear file.

Close WebSphere Studio Application Developer.

4. In the Admin Console, locate the “Enterprise Applications” and right click to select Install Enterprise Application.

5. Provide the source directory for the sample enterprise application ear file in the Install Enterprise Application Wizard. Click Next.

Figure 9: Install new Enterprise Application.

6. Click Next for the next 4 pages. Accept the default setting. 7. In the “Mapping Resource References to Resources” page, select the corresponded resource

providers for the resource references. Figure 10. Bind the application resource references to WebSphere runtime resource providers.

8. Install this enterprise application into the Default Server. Go through the rest of the InstallatioWizard, and click Finish.

n

9. After the Enterprise Application successfully deployed, start the “Default Server” Application Server JVM from Admin console. Now, we are ready to test our application.

10. Launch a browser and test our demo application using the following URL: http://localhost:9080/XADemo Figure 11. Access the demo Web page and input the test information.

Tip: SonicMQ provides a sample application MessageMonitor that listens for any message topic activity—by subscribing to all topics in the topic hierarchy—and then displays each message in its window. In the Sonic Command Prompt, browse into MessageMonitor directory: C:\SonicMQ\samples\TopicPubSub\MessageMonitor Then, type the command: \..\SonicMQ MessageMonitor. It will open a GUI window. After submitting an employee record from the Demo web page, you can check the Topic and browse the message sent by Demo Application: Click the link to submit the request: If the two-phase commit transaction completes successfully, you should see this screen:

Figure 12. Demo result page.

And you can use the DB2 control center or command line to check whether the database record is successfully inserted into the Employee table. Check the SonicMQ MessageMonitor window; you will find the message that published through the sample application. Figure 13. SonicMQ Topic monitor.

In order to test the basic behavior of WebSphere distributed global transaction, we can do a very simple test. Just go back to the input page of the sample Web application. Fill in the employee information with a duplicate Employee No (we have changed the SAMPLE database employee table definition to enable the EmployNo as primary key ). Obviously, the database insert will fail. Consequently, you can’t see any message related to this global transaction been published to JMS topic by using the SonicMQ MessageMonitor.

Conclusion Using a JMS asynchronous programming model in a transaction business environment is quite a challenging task for a J2EE application server. In this tutorial, we demonstrated how IBM WebSphere Application Server accomplishes this exciting task by implementing the JMS and X/Open specification. With a focus on WebSphere's distributed global transaction support for a generic JMS provider using two-phase commit protocol, this tutorial gives you a reference on integrating different resources like Relational Database and a JMS provider in a global transaction environment. By following the configuration steps provided by this article, you can easily implement your transactional business logic using IBM WebSphere Application Server. IBM and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Microsoft and Windows are registered trademark of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. IBM copyright and trademark information