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.

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:

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:

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:

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

• WebSphere Application Server resources
  • Work management and transaction inflow
    See David Currie's excellent developerWorks article for more information on how work is scheduled.
  • WebSphere Application Server information center
    A single Web portal to all WebSphere Application Server documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere Application Server.
  • WebSphere Application Server developer resources page
    Technical resources to help you use WebSphere Application Server.
  • WebSphere Application Server product page
    Product descriptions, product news, training information, support information, and more.
  • WebSphere Application Server information roadmaps
    Roadmap of articles and resources to help you with installation, migration, administration, development, troubleshooting, and understanding the underlying technology.
  • WebSphere Application Server documentation library
    WebSphere Application Server product manuals.
  • WebSphere Application Server support
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • Download a free trial version of WebSphere Application Server V7
    WebSphere Application Server V7 is a Java EE 5 certified, EJB 3.0 supported application platform that drives business agility with an innovative, performance based foundation for your SOA environment on the broadest range of platforms in the industry.
  
  
• WebSphere MQ resources
  • WebSphere MQ V7 information center
    A single Web portal to all WebSphere MQ V7 documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere MQ V7.
  • WebSphere MQ developer resources page
    Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  • WebSphere MQ product page
    Product descriptions, product news, training information, support information, trial download, and more.
  • WebSphere MQ product family
    A description of the ten or so different editions of WebSphere MQ.
  • WebSphere MQ documentation library
    WebSphere MQ product manuals.
  • IBM Redbook: WebSphere MQ V7 features and enhancements
    Describes the fundamental concepts and benefits of message queuing technology, describes the new features in V7, and provides a business scenario that shows those features in action.
  • Download a free trial version of WebSphere MQ V7
    A 90-day, full featured, no-charge trial of WebSphere MQ V7
  • WebSphere MQ support page
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • WebSphere MQ public newsgroup
    A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users.
  • WebSphere MQ SupportPacs
    Downloadable code, documentation, and performance reports for the WebSphere MQ family of products.
  
  
• WebSphere resources
  • developerWorks WebSphere developer resources
    Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
  • developerWorks WebSphere application integration developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application integration and business integration solutions.
  • developerWorks WebSphere business process management developer resources
    WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
  • developerWorks WebSphere SOA and Web services developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
  • Most popular WebSphere trial downloads
    No-charge trial downloads for key WebSphere products.
  • WebSphere forums
    Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  • WebSphere on-demand demos
    Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
  • developerWorks WebSphere weekly newsletter
    The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
  • WebSphere-related books from IBM Press
    Convenient online ordering through Barnes & Noble.
  • WebSphere-related events
    Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  
  
• developerWorks resources
  • Trial downloads for IBM software products
    No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  • developerWorks blogs
    Join a conversation with developerWorks users and authors, and IBM editors and developers.
  • developerWorks tech briefings
    Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
  • developerWorks podcasts
    Listen to interesting and offbeat interviews and discussions with software innovators.
  • developerWorks on Twitter
    Check out recent Twitter messages and URLs.
  • IBM Education Assistant
    A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
  
  

About the author

Paul 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Activation specifications
• Detecting messages
• Processing messages
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers