Message Driven Bean - IBM · 2019-06-19 · Overview of Sample Enterprise Applications ... In the navigation pane of the Admin Console application, expand Resources → JMS and click

WebSphere Application Server for z/OS Version 7

Message Driven BeanImplementation with Activation Specification

This document can be found on the web at:www.ibm.com/support/techdocs

Search for document number WP101792 under the category of "White Papers"

Version Date: November 18, 2010See "Document Change History" on page 19 for a description of the changes in this version of the document

John CowelIBM Certified IT Specialist

[email protected]

IBM IOT East andIBM Advanced Technical Skills

WP101792 – Message Driven Bean Implementation with Activation Specification

Many thanks to the following people for their assistance and contributions to this effort:Matthew Leming - WebSphere Messaging Development (Hursley)

Ron Lotter - WebSphere Enablement

Carolyn Elkins - Washington Systems Center

Le-Win Tai - Washington Systems Center

Don Bagwell - Washington Systems Center

Mike Cox - Washington Systems Center

© 2010, IBM CorporationIBM Americas Advanced Technical Skills - 2 - ibm.com/support/techdocs

Version Date: Thursday, November 18, 2010


Table of ContentsOverview....................................................................................................................................4

Software Environment.......................................................................................................................4WebSphere Configuration.......................................................................................................5

WebSphere PROC Updates..............................................................................................................5WebSphere MQ Messaging Provider Settings..................................................................................5Define Queue Connection Factory....................................................................................................7Define Queues..................................................................................................................................8Define Activation Specification..........................................................................................................8

Deploy Sample Enterprise Applications..............................................................................10Deploy MDBDriver.ear....................................................................................................................10Deploy MDListener.ear....................................................................................................................11

Overview of Sample Enterprise Applications......................................................................13MDBDriver.ear.................................................................................................................................13MDBListener.ear.............................................................................................................................14

Execute Sample Enterprise Applications............................................................................15MDBDriver.......................................................................................................................................15MDBListener...................................................................................................................................16

Application Trace Information..............................................................................................18Document Change History....................................................................................................19




OverviewThis White Paper is intended to facilitate initial testing of a simple Message Driven Bean (MDB) enterprise application in WebSphere Application Server for z/OS V7 with WebSphere MQ V7. The enterprise applications associated with this document make use of the JMS feature of WebSphere MQ to support both JMS and MDB components deployed in the WebSphere z/OS run-time environment.

The setup instructions for the enterprise applications outlined in this document do NOT make use of the Internal JMS Provider (IJP) that is an element of WebSphere V7. Although the IJP could be used for this purpose, the intent is to configure and test an External MQ JMS Provider. Additionally, since BINDINGS mode is used to connect to WebSphere MQ, it is assumed you already have WebSphere MQ installed in the same LPAR as WebSphere Application Server and are able to define the necessary queues to be used by the enterprise applications. Two queues need to be defined to WebSphere MQ. You may name the queues whatever you wish. They should be defined as PERSISTENT, with GET and PUT ENABLED and also should be marked SHARE. The instructions for defining these queues to WebSphere MQ are not included in this document. Given the instructions in this document, a WebSphere Systems Programmer or Application Developer may simply take the EAR files included and use them to test the run-time infrastructure. A Project Interchange zip file is also included that may be imported in to Rational Application Developer (RAD). This is available so you may browse the applications to ensure they do nothing malicious, or use them as a starting point for future development of MDB applications. These applications were made to be very simple so the focus would be on the customization and configuration of JMS and MDB infrastructures in WebSphere.Software Environment

Application Development EnvironmentIBM Rational® Application Developer™ for WebSphere® SoftwareVersion: 7.5.5.1Build ID: 20100324_0059

z/OS Environment

Product Version Service Levelz/OS V1.11 PUT1004

WebSphere application Server V7.0 7.0.0.11

WebSphere MQ V7.0 7.0.1.2




WebSphere ConfigurationWebSphere PROC Updates

The Application Server where you deploy the EAR files will need to have access to MQ load libraries. If these libraries are not loaded into LPA or in the LINKLIST, you will need to add these libraries to the STEPLIB concatenation in the PROCs. This is true for both the Servant and Adjunct PROCs.// DD DISP=SHR,DSN=hlq.SCSQANLE// DD DISP=SHR,DSN=hlq.SCSQAUTH

WebSphere MQ Messaging Provider Settings

To connect to a WebSphere MQ queue manager or queue-sharing group in bindings mode, the WebSphere MQ messaging provider needs to know where to load native libraries from. This information is known as native path information. Procedure for setting native path information:1. In the navigation pane of the Admin Console application, expand Resources → JMS and

click JMS providers.2. Select the WebSphere MQ messaging provider that is at the correct Scope for the

connection factory or activation specification that will create the bindings mode connection. Note that native path information at Server scope is used in preference to native path information at higher scopes, and native path information at Node scope is used in preference to native path information at Cell scope. For this example the native path information is set at the Server scope.Note: When using WebSphere MQ messaging provider connection factories or activation specifications that create bindings mode connections to a WebSphere MQ for z/OS® queue manager, ensure that the IDBACK parameter is large enough. Otherwise, MQExceptions with a completion code of 2, and a reason code of 2025 (MQRC_MAX_CONNS_LIMIT_REACHED) can occur.

3. Under General Properties, in the Native library path property, enter the full name of the directory that contains the WebSphere MQ native libraries. For example, on the system where this sample was developed the value is /shared/mqm/V7R0M1/java/lib. Enter only one directory name.




While you are on this screen, check the box - “Enable JCA based inbound message delivery”. Otherwise, the Activation Specification will not work.If you do not check this box, after deployment of the MDBListener application and upon start-up of that application, you may see the following message in SYSPRINT of the servant address space:Trace: 2010/07/29 13:02:53.318 01 t=8CA030 c=UNK key=P8 (13007002) ThreadId: 0000001f FunctionName: com.ibm.ws.sib.utils.ras.SibMessage SourceId: com.ibm.ws.sib.utils.ras.SibMessage Category: WARNING ExtendedMessage: BBOO0221W: Ý:¨ CWWMQ0093W: An attempt has been made to use a WebSphere MQ messaging provider activation specification. However the control region adjunct process has not been configured to start, so the activation specification will not function correctly.Click OK, then Save and Synchronize the changes.Upon first start of server after the Native library path is set on the provider you will see the following SEVERE error in SYSPRINT of the server:Trace: 2010/07/29 12:28:42.936 01 t=8E2A78 c=UNK key=P8 (13007002) ThreadId: 00000000 FunctionName: com.ibm.ejs.jms.JMSRegistration SourceId: com.ibm.ejs.jms.JMSRegistration Category: SEVERE ExtendedMessage: BBOO0220E: WMSG1623E: The WebSphere MQ messaging provider installedConnectors/wmq.jmsra.rar has been updated and an application server restart is required to pick up this update. The WebSphere MQ messaging provider has been disabled.Stop and restart the server and everything will be fine.




Define Queue Connection FactoryOne Queue Connection Factory is used for this sample.

Procedure for defining the Queue Connection Factory:1. In the navigation pane of the Admin Console application, expand Resources → JMS

and click JMS providers.2. Click the WebSphere MQ messaging provider on which you set the Native library

path.3. Under Additional Properties, click Queue connection factories.4. Click New.5. Complete the fields as follows:

Name: MQ_MDBQCFJNDI name: jms/MQ_MDBQCFDescription: WebSphere MQ Queue Connection Factory for Message Driven

Bean samples

6. Click Next.7. Select radio button Enter all the required information into this wizard

and click Next.8. Enter your Queue manager or queue sharing group name and click Next.9. Change Transport to Bindings and click Next.10. In a Network Deployment configuration, Test connection will likely fail, so just click

Next.11. Click Finish.

Save and synchronize your configuration changes.




Define QueuesTwo WebSphere MQ queues are required for these samples. The names of the queues may be anything you wish.

Procedure for defining the Queues:1. In the navigation pane of the Admin Console application, expand Resources → JMS

and click Queues.2. On the right, in the Queues panel, click the drop-down menu and set the scope to either

the appropriate Node or Server.3. Click New.4. Select WebSphere MQ messaging provider and click OK.5. Fill in the fields as follows:

Name: MQ_MDBDriverQJNDI name: jms/MQ_MDBDriverQDescription: WebSphere MQ Queue for Message Driven Bean samplesQueue name: JRCOWEL.TEST1.QUEUE (your queue name)Queue manager: QML4 (your QMGR name)

6. Click OK.

Repeat the above steps for the second queue:

Name: MQ_MDBListenerQJNDI name: jms/MQ_MDBListenerQDescription: WebSphere MQ Queue for Message Driven Bean samplesQueue name: JRCOWEL.TEST2.QUEUE (your queue name)Queue manager: QML4 (your QMGR name)

Save and synchronize your configuration changes.Define Activation Specification

Procedure for defining Activation Specification:1. In the navigation pane of the Admin Console application, expand Resources → JMS

and click JMS providers.2. Click the WebSphere MQ messaging provider on which you set the Native library

path.3. Under Additional Properties, click Activation specifications.




4. Click New.5. Complete the fields as follows:

Name: MQ_MDBActSpecJNDI name: jms/MQ_MDBActSpecDescription: WebSphere MQ Activation Specification for

Message Driven Bean samples

6. Click Next.7. Fill in the MDB destination data as follows:

Destination JNDI name jms/MQ_MDBDriverQ

8. Click Next.9. Select radio button Enter all the required information into this wizard

and click Next.10. Enter your Queue manager or queue sharing group name and click Next.11. Change Transport to Bindings and click Next.12. In a Network Deployment configuration, Test connection will likely fail, so just click

Next.13. Click Finish.

Save and synchronize your configuration changes.




Deploy Sample Enterprise ApplicationsDeploy MDBDriver.ear

1. In the navigation pane of the Admin Console application, expand Applications and click New Application.

2. On the right, in the New Application panel, click New Enterprise Application.

3. Browse to the location of MDBDriver.ear, select the file, and click Next.

4. Accept the default of Fast Path and click Next.5. Accept the defaults at Step 1: Select Installation options and click Next.6. At Step 2: Map modules to servers, select the appropriate server and click Next.7. At Step 3: Map resource references to resources:

• Click Browse to the right of jms/MDBDriverQ, select MQ_MDBDriverQ and click Apply.

• Click Browse to the right of jms/MDBQCF, select MQ_MDBQCF and clickApply.

8. Click Next.9. Click Finish.

10. Click Review, select check box Synchronize changes with Nodes, then click Save.




Deploy MDListener.ear1. In the navigation pane of the Admin Console application, expand Applications and click

New Application.

2. On the right, in the New Application panel, click New Enterprise Application.

3. Browse to the location of MDBListener.ear, select the file, and click Next.

4. Accept the default of Fast Path and click Next.5. Accept the defaults at Step 1: Select Installation options and click Next.6. At Step 2: Map modules to servers, select the appropriate server and click Next.7. At Step 3 Bind listeners for message-driven beans:

• Click the box to the left of MDBListenerEJB.• Select the Activation Specification radio button.• Expand Apply Multiple Mappings.• Under Target Resource JNDI Name, select jms/MDBActSpec and click Apply.

8. Click Next.9. At Step 4: Map resource references to resources:

• Check the box next to MDBListenerEJB and MDBListenerWeb in the javax.jms.Queue box.

• Click the down arrow next to Set Multiple JNDI Names and select jms/MDBListenerQ.

• Check the box next to MDBListenerWeb and MDBListenerEJB in the javax.jms.QueueConnectionFactory box.




• Click the down arrow next to Set Multiple JNDI Names and selectjms/MQ_MDBQCF.

10. Click Next.11. Click Finish.

12. Click Review, select check box Synchronize changes with Nodes, then click Save.




Overview of Sample Enterprise ApplicationsThe drawing below shows a high level overview of the interaction between the two enterprise applications:

MDBDriver.earA very simple application that consists of a web component that puts one or more messages to an MQ queue. If application MDBListener is not deployed, this application may also be used to retrieve the message(s) put to the MQ queue. This application deployed alone could be used to verify all the plumbing is in place to communicate with WebSphere MQ. Without an MDB it would not exercise the activation specification.

Application artifacts:

displayResults.jps Display message(s) retrieved from MQ queuegetMsgs.jsp Get message(s) from MQ queueindex.jsp Default page of applicationputMsgs.jsp Put message(s) on MQ queueMDBDriverServlet.java Java servlet to put/get message(s) on MQ queue using JMS API.

Accepts input from jsp's and forwards results to jsp's.The message put on the queue is based on the text passed from the jsp. The servlet name is added to the beginning of the message before it is put on the queue.




MDBListener.earThis application consists of both a web component and an EJB component. The artifacts of this application are:

EJB ComponentMDBListenerEJBBean.java This Message Driven Bean makes use of an Activation Specification

to retrieve messages from an MQ queue as opposed to a Listener Port. The Activation Specification is notified when a message shows up on the Destination the Activation Specification is listening to - the output queue of the MDBDriver application - and presents the message to the onMessage method of the MDB. The MDB extracts the text of the message, adds the EJB name to the beginning of the message, then writes the message to an output queue (another MQ queue) using JMS API.This MDB is written at spec level 2.1, not EJB 3.0, so it should work with WebSphere V6.1 or V7.

Web ComponentdisplayResults.jsp Display message(s) retrieved from MDBlistenerEJBBean output

queuegetMsgs.jsp Get message(s) from MDBlistenerEJBBean output queueindex.jsp Default page of applicationMDBListenerServlet.java Java servlet to get message(s) from MQ queue using JMS API.

These message(s) were put on the queue by the Message Driven Bean.




Execute Sample Enterprise ApplicationsMDBDriver

To execute the MDBDriver application, open a browser and enter the following url:http://your.host.com:port/MDBDriverWeb

You will see a screen that looks like:

Click Put Messages on MDBDriver Queue

On this screen you may change the text of the message and/or specify the number of messages you want to be put on the queue. Once you have filled in the fields, press Put Messages. This will put the message(s) on the MQ_MDBDriverQ queue with MDBDriverServlet pretended to the message(s).




You will notice a link to Get Messages from MDBDriver Queue. If you click on this link, the MDBDriver application will attempt to retrieve any messages from queue MQ_MDBDriverQ. This link will work, but if you have deployed the MDBListener application there will be no messages on this queue because they will have been delivered to the Message Driven Bean in the MDBListener application via the Activation Specification that has been defined in the environment.

MDBListenerTo execute the MDBListener application, open a browser and enter the following url:

http://your.host.com:port/MDBListenerWebYou will see a screen that looks like:

Click Get Messages from MDBListenerEJB Output Queue.

On the resulting screen you may choose the number of messages to get from the queue – All (the default) or some number from 1 to n:




Once you have chosen how many messages to get, click GET Message(s). You will see a screen similar to the following:




Application Trace InformationThe sample applications included with this document include trace information imbedded in the code. Normally in WebSphere most, if not all, traces are turned off so you will not see any additional information in the job log during execution of the applications. If you wish to see these trace messages from the applications you need to enter the following modify command against the application server where the applications are deployed:

F {server_name},TRACEJAVA='com.ibm.wsc.*=all'

NOTE: This command is issued against the controller address space job name.

As a result of issuing the command above you will see information similar to the following in SYSPRINT (STDOUT) of the application server:

>>>>>>>>MDBDriverServlet: Method=doPost>>>>>>>>MDBDriverServlet: Method=doPost: create queueConnection>>>>MDBDriverServlet: Method=doPost: create queueSession>>>>MDBDriverServlet: Method=doPost: create queueSender>>>>MDBDriverServlet: Method=doPost: start queueConnection>>>>MDBDriverServlet: Method=doPost: paramHowMany=4>>>>MDBDriverServlet: Method=doPost: Number of messages to put on queue (msgNum): 4>>>>MDBDriverServlet: Method=doPost: Put message 0 on queue.>>>>MDBDriverServlet: Method=doPost: Message: JMSMessage class: jms_text JMSType: null JMSDeliveryMode: 2 JMSExpiration: 0 JMSPriority: 4 JMSMessageID: null JMSTimestamp: 0 JMSCorrelationID: null JMSDestination: null JMSReplyTo: null JMSRedelivered: falseDBDriverServlet: Message 0 - Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesqu …

You will see similar messages from the MDBListener enterprise application.To turn off this application trace information, you can do one of two things:

1. Recycle the application server.2. Issue one of the following modify commands against the application server:

F {server_name},TRACENONEF {server_name},TRACEINIT




Document Change HistoryCheck the date in the footer of the document for the version of the document.

11/16/10 Original document.

End of WP101792



Documents

Message Driven Bean - IBM · 2019-06-19 · Overview of Sample Enterprise Applications ... In the navigation pane of the Admin Console application, expand Resources → JMS and click