Processing messages with the WebSphere Application Server V7 and V8 WebSphere MQ messaging provider activation specifications

This article describes the WebSphere MQ messaging provider activation specifications in WebSphere Application Server and the mechanisms they use to connect to WebSphere MQ queue managers and monitor destinations for messages, and then shows how the application server delivers suitable messages to message-driven beans for processing. The article is for WebSphere Application Server administrators and developers who need to tune their systems, as well as for WebSphere MQ administrators who want to understand how the application server interacts with WebSphere MQ.

Share:

Paul Titheridge, Service Specialist, WebSphere MQ Level 3 Support team, IBM

Photo of Paul TitheridgePaul Titheridge has been working on the WebSphere MQ Level 3 Support team at the IBM Hursley Lab in the United Kingdom since 2003, and he specialises in resolving issues related to interactions between WebSphere MQ and WebSphere Application Server. You can contact Paul pault@uk.ibm.com.



05 October 2011

Also available in Chinese Japanese

Introduction

IBM® WebSphere® Application Server V7 and V8 provide support for asynchronous messaging based on the Java Message Service (JMS) specification. Using the WebSphere MQ messaging provider, you can write message-driven beans that listen on a WebSphere MQ destination (either a message queue or a topic). When a message arrives on the destination, the message-driven bean's onMessage() method is invoked to process the message.

In WebSphere Application Server V7 and V8, the WebSphere MQ messaging provider supports the use of activation specifications to monitor destinations hosted by WebSphere MQ queue managers. This article shows how activation specifications connect to WebSphere MQ on distributed platforms, describes the mechanism used to monitor the destinations looking for messages, and then shows how message-driven beans are invoked after a suitable message has been detected. The article assumes a basic knowledge of JMS and WebSphere MQ.

Activation specifications

In general terms, J2C activation specifications are administered objects that contain information about how to connect to a JMS provider, along with details of the destination on that JMS provider that will be monitored for messages. When deploying an application that contains a message-driven bean, you need to specify the activation specification that the message-driven beans will use. When the activation specification starts up, it connects to a JMS provider, opens the JMS destination, and then monitors it looking for messages.

Figures 1 and 2 below show a sample WebSphere MQ activation specification that has been defined using the activation specification panel in the WebSphere Application Server Integrated Solutions Console. When this activation specification starts up, it makes a BINDINGS mode connection to a local WebSphere MQ queue manager called pault, opens the destination jms/TestQueue, and then starts monitoring this destination for messages.

Figure 1. Specifying the queue manager name and transport type
Specifying the queue manager name and transport type
Figure 2. Specifying the JMS destination that an activation specification will monitor
Specifying the JMS destination that an activation specification will monitor

Activation specifications can be configured to use message selectors, which enables them to only pass messages that meet the selection criteria to message-driven beans. In Figure 2 above, no message selector has been specified, and therefore all messages that arrive on the destination are suitable for processing by this activation specification.

Once an activation specification finds a suitable message, it schedules a piece of work within the application server to process it. Each message requires a JMS server session in order to run, and multiple messages can be processed at the same time.

Each activation specification has an associated server session pool, and its size controls the number of messages that can be processed concurrently by an activation specification. The default size of the server session pool is 10, which means that up to 10 messages can be processed at the same time by a single activation specification. To change the server session pool size, modify the activation specification advanced property Maximum server sessions, as shown in Figure 3:

Figure 3. Specifying how many messages can be processed concurrently
Specifying how many messages can be processed concurrently

Detecting messages

The mechanism that an activation specification uses to detect messages on JMS destinations hosted on a WebSphere MQ queue manager varies depending on the WebSphere MQ messaging provider mode that is being used, as described below.

WebSphere MQ messaging provider normal mode

Activation specifications use the WebSphere MQ messaging provider normal mode if they are connecting to a WebSphere MQ V7 queue manager and they have the Provider versionproperty set to either unspecified (the default value) or 7. In this mode of operation, the activation specification takes advantage of a number of the features of WebSphere MQ V7 when connecting to a queue manager and getting messages. When it starts up, the activation specification:

  1. Creates a connection to the WebSphere MQ queue manager it has been set up to use.
  2. If the activation specification is configured to use a Queue Destination, it opens the queue using the WebSphere MQ API call MQOPEN.
  3. If the activation specification has been configured to use a Topic Destination, it issues a WebSphere MQ API MQSUB call to subscribe to the appropriate topic.
  4. After the queue has been opened or the topic subscribed to, the activation specification uses the WebSphere MQ API call MQCB to register a callback. The callback is set up with the following WebSphere MQ GetMessageOptions:
    • MQGMO_BROWSE_FIRST
    • MQGMO_UNMARKED_BROWSE_MSG
    • MQGMO_MARK_BROWSE_CO_OP
  5. After the callback has been registered, the activation specification issues a WebSphere MQ MQCTL API call, which tells the queue manager that the activation specification is ready to start receiving messages.

Now, when a suitable message arrives on the queue that the activation specification is monitoring, or is published on the topic that the activation specification has subscribed to, the queue manager marks the message to prevent any other activation specifications from seeing it, and then passes details of the message to the activation specification via the callback that was set up earlier.

WebSphere MQ messaging provider migration mode

The other way that activation specifications can connect to a WebSphere MQ queue manager is by using the WebSphere MQ messaging provider migration mode. This mode is used if one of the following conditions is true:

  • The activation specification is configured to connect to a WebSphere MQ V6 queue manager.
  • The activation specification is configured to connect to a WebSphere MQ V7 queue manager, and has the Provider Versionproperty set to 6.
  • The activation specification has been configured to connect to a WebSphere MQ V7 queue manager using the CLIENT transport, and is using a WebSphere MQ channel that has the Sharing Conversations (SHARECNV) property set to 0.

When the activation specification starts up in migration mode, it:

  1. Creates a connection to the WebSphere MQ queue manager it has been set up to use.
  2. If the activation specification has been configured to monitor a Queue Destination, it issues an MQOPEN API call to open the queue.
  3. If the activation specification has been configured to use a Topic Destination, it:
    • Opens a subscription for the topic.
    • Checks the values of the activation specification Broker Properties Broker connection consumer subscription queue and Broker durable subscriber connection consumer queue to see which WebSphere MQ queue the Broker will publish messages for this activation specification to.
    • Calls the WebSphere MQ API MQOPEN to open the appropriate subscription queue.
  4. Once the queue has been opened on the queue manager, the activation specification browses the queue looking for messages by issuing a number of MQGET API calls. The activation specification uses a combination of the WebSphere MQ GetMessageOptions MQGMO_BROWSE_FIRST and MQGMO_BROWSE_NEXT to scan the queue from top to bottom.

Processing messages

When an activation specification has detected a message on a destination (either because a WebSphere MQ V7 queue manager has passed back information about a message via a callback, or because the activation specification has browsed a suitable message), it:

  1. Constructs a message reference that represents the message.
  2. Gets a server session from the activation specification server session pool.
  3. Loads up the server session with the message reference.
  4. Schedules a piece of work with the application server Work Manager.

The activation specification then goes back to looking for more messages.

Getting server sessions

As mentioned earlier, activation specifications will process up to 10 messages concurrently by default. What happens if an activation specification tries to process a message and all 10 server sessions are already busy processing messages? In this situation, the activation specification will block until a server session becomes free. As soon as a server session is available, the activation specification loads it up with the message reference, and then schedules a new piece of work so the server session can run again.

Scheduling work

Once the activation specification loads a server session with a message reference, it schedules some work so that the message can be processed. What happens to the work? The Work Manager:

  1. Gets a thread from the WebSphere Application Server WebSphere MQ messaging provider Resource Adapter thread pool. The name of this thread pool is WMQJCAResourceAdapter.
  2. Runs the piece of work on this thread.

After the work has been scheduled, the application server Work Manager will run this piece of work at some point in the future. The work, when started:

  1. Starts either a local or global (XA) transaction, depending on whether the message-driven bean requires XA transactions or not (specified in the message-driven bean's deployment descriptor).
  2. If this is the first time the server session has been used, it:
    • Creates a new connection to WebSphere MQ.
    • Issues an MQOPEN API call to open the queue where the message resides.
  3. Gets the message from WebSphere MQ by issuing a destructive MQGET API call.
  4. Runs the message-driven bean's onMessage() method.
  5. Once onMessage() has completed, the server session completes the local or global transaction before exiting.

To improve performance, the connection to the queue manager that the server session uses is left open after the message has been processed and the work completed. Then, the next time the server session is used to process a message, it need not reconnect to WebSphere MQ and reopen the queue containing the message. By default, unused server sessions associated with activation specifications are left open for 30 minutes before being closed off. You can later this timeout period by modifying the value of the activation specification advanced property Server session pool timeout, as shown in Figure 4 below

On a lightly loaded system, the time between the piece of work being scheduled and the Work Manager starting the work can be just a few milliseconds. On busy systems, there may be a lengthy delay before the work is actually started. There are two possible reasons for a delay:

  • There were no free threads in the WMQJCAResourceAdapter thread pool to run the work.
  • The Work Manager was able to get a thread from the thread pool, and but then could not start the work because the application server was too busy.

The Work Manager records when a piece of work was scheduled, and when it starts the work, it checks how much time has elapsed since the activation specification scheduled the work. By default, the activation specification expects the work to be started within 10 seconds of it being scheduled. If more than 10 seconds elapse before the Work Manager starts the work, then a WorkRejected exception is returned back to the activation specification, causing exceptions similar to the one below to appear in the application server SystemErr.log:

Exception in thread "WMQJCAResourceAdapter : 1" java.lang.RuntimeException:
javax.resource.spi.work.WorkRejectedException: Work timed out (id=4), error code: 1
:   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :   :  
Caused by: javax.resource.spi.work.WorkRejectedException: Work timed out
(id=4), error code: 1

When an exception like this one occurs, the message in the Message Reference will have been "unmarked" by the queue manager, so that it can be reprocessed. You can change this 10-second time limit on the activation specification Advanced properties panel using Start timeout, as shown in Figure 4:

Figure 4. Modifying the server session timeout and the amount of time to wait for work to start
Modifying the server session timeout and the amount of time to wait for work to start

Earlier, it was mentioned that a piece of work might get delayed if there are not enough threads in the WMQJCAResourceAdapter thread pool, which leads to the obvious question, "What should the size of this thread pool be?". One thread pool per application server is used by activation specifications to run server sessions. Each activation specification has an advanced property called Maximum server sessions, which defines the maximum number of concurrent server sessions that can be running at the same time. Since each server session is used to process messages, this property essentially says how many messages can be processed concurrently by message-driven beans using this activation specification. So in order to determine what the size of the WMQJCAResourceAdapter thread pool should be, you need to add up the values of the Maximum server sessions properties for each WebSphere MQ messaging provider activation specification on the application server. For example, suppose you have 25 activation specifications defined, each with the Maximum server sessions property set to 3. In this situation, there can be up to 75 server sessions running concurrently, each of them using a thread from the WMQJCAResourceAdapter thread pool. Therefore you should set the maximum size of this thread pool to 75. Figure 5 shows the WMQJCAResourceAdapter thread pool panel in the WebSphere Integrated Solutions Console, where you can change the size of this thread pool:

Figure 5. Changing max number of threads available to all activation specifications defined in the application server.
Changing max number of threads available to all activation specifications defined in the application server.

If you start seeing WorkRejected errors appearing in the application server SystemOut.log file, the first thing to check is that the WMQJCAResourceAdapter thread pool is large enough to handle all of the server sessions needed by your activation specifications. If the thread pool is the right size, then the errors are caused by the Work Manager being unable to start the work request within the specified time period. In this situation, you should either increase the value of the activation specification advanced property Start Timeout, or investigate reducing the load on your application server system.

Using WebSphere MQ messaging provider normal mode

As described above, there are three situations in which there might be a delay in between a message being detected and that message being processed by a message-driven bean:

  • If all server sessions associated with an activation specification are being used.
  • If all threads in the WMQJCAResourceAdapter thread pool are being used to process messages.
  • If there is a delay between work being scheduled and the Work Manager actually starting the work.

If the activation specification is running in WebSphere MQ messaging provider normal mode, the queue manager marks messages before passing their details back to the activation specification. Marking the message means that no other activation specification (or WebSphere Application Server Listener Port), either running in the same application server or on a different application server, can see the message, which prevents another message-driven bean from getting the message before a server session has had time to process it.

By default, messages are marked for 5 seconds. To change this time period, modify the WebSphere MQ queue manager property Message mark browse interval (MARKINT).

After WebSphere MQ has passed details of a message to process to an activation specification, the 5 second timer starts. During these five seconds:

  1. The activation specification must get a server session from the server session pool.
  2. The server session must be loaded up with details of the message to process.
  3. The work must be scheduled.
  4. The Work Manager must start the work request.

If there is a delay in getting a server session or a thread from the WMQJCAResourceAdapter thread pool, or if the system is busy and it takes a long time for the Work Manager to schedule the work, then the time between WebSphere MQ passing details of the message and it actually being consumed might be longer than 5 seconds. What happens in this situation?

Well, if the message has been on the queue for longer than 5 seconds, the queue manager will unmark it, and another activation specification or listener port is then free to come along and get the message. If this happens, then when the server session that has previously been given details of this message tries to get it, it will find that the message is no longer on the destination, and write the following message to the application server SystemOut.log:

CWSJY0003W: JMSCC0108: WebSphere classes for JMS attempted to get 
a message for delivery to an message listener that had previously been 
marked using browse-with-mark, but the message was not there.

Should you see this message, you have three options:

  • Increase the value of the WebSphere MQ queue manager property Message mark browse interval (MARKINT), to give the activation specification more time to get the message. If you have multiple applications monitoring the same destination and want the messages to be processed quickly, you should think hard about adopting this approach, as increasing the amount of time the message is marked for will prevent any other applications from getting it.
  • Tune the application server so that it does not block either waiting for a server session or waiting for a thread from the WMQJCAResourceAdapter thread pool. To do this, increase the size of both the server session pool and the thread pool. This change will mean that messages can be processed within the default message browse mark interval, although more resources will be used within the application server as it will be able to process more messages concurrently.
  • Do nothing. Not recommended, because it means that the activation specification will waste time and resources trying to get messages that have already been picked up and processed by another application!

Conclusion

This article described the mechanisms that activation specifications use to get messages from WebSphere MQ queue managers, including how activation specifications create a connection to a queue manager and the mechanisms they use to monitor JMS destinations looking for suitable messages to process. The article also described how the application server schedules the processing of messages, once a suitable message has been found.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=763738
ArticleTitle=Processing messages with the WebSphere Application Server V7 and V8 WebSphere MQ messaging provider activation specifications
publish-date=10052011