Asynchronous Messaging Using JMS

 

+
+

 

Contents

  1. Overview
  2. JMS providers
  3. Install WebSphere MQ as the JMS provider
  4. WebSphere MQ Provider Settings
  5. WebSphere MQ JMS connection pooling
  6. Moving from embedded WebSphere JMS provider to WebSphere MQ
  7. JMS servers on Application Servers
  8. Queue Connection factories
  9. Configure a topic connection factory
  10. Configure a queue destination
  11. Configure a topic destination
  12. JMS server settings
  13. Configure a new JMS connection using wsadmin.sh
  14. Configure a new JMS destination using wsadmin
  15. Configure a new JMS provider using wsadmin
  16. Troubleshooting

 

Overview

WAS supports JMS-based messaging, which enables Java programs to exchange asynchronous messages using a combination of queue connection factories, queue destinations, and listener ports.

One common usage of JMS is to read in XML files for batch processing. Records can be put into queues, pulled from queues using MDBs on listener ports, and then processed by EJBs.

There are several flavors of JMS providers, with the two most common in a WebSphere context being embedded JMS and MQ JMS. The former comes bundled with WAS, and should be treated as a "lite" version. The latter users WebSphere MQ, which is a standalone product, separate from WAS.

When installing V5.1.x with the WebSphere MQ product as the JMS Provider, manually set the MQ_INSTALL_ROOT variable in the console...

Environment | Manage WebSphere Variables | MQ_INSTALL_ROOT

With automatic asynchronous messaging are automatically retrieved from JMS destinations, optionally within a transaction, then sent to the message-driven bean in a J2EE application.

The Enterprise edition uses the WBI Server Foundation to provide extended messaging.

WAS also supports bean-managed messaging, which gives an enterprise bean complete control over the messaging infrastructure; for example, for connection and session pool management. The appserver has no role in bean-managed messaging.

For troubleshooting, IBM hosts a useful JMS only search engine.

 

JMS providers

JMS provider options include the Embedded Messaging Server option of WAS, WebSphere MQ, or a generic JMS provider.

WAS provides default JMS support with its Embedded Messaging Server component, which is installed with WAS, administered through the console and managed as part of the WAS runtime. This function is only accessible from WAS Web, EJB and client containers, and is not interoperable with WebSphere MQ.

For more information...

  1. Selecting the most appropriate JMS provider for your applications
  2. JMS Topologies and Configurations

 

Install WebSphere MQ as the JMS provider

To install and configure WebSphere MQ (MQSeries) for use as a JMS provider to IBM WAS...

  1. Create and mount a journalized file system called /var/mqm for messaging working data. If a large amount of messaging work builds up in /var/mqm, other system activity will not be affected.

    You can also create separate file systems for your log data (var/mqm/log) and error files (var/mqm/errors).

    You should store log files on a different physical volume from the messaging queues (var/mqm). This ensures data integrity in the case of a hardware failure. If you are creating separate file systems, allow a minimum of 30 MB of storage for /var/mqm, 20 MB of storage for /var/mqm/log, and 4 MB of storage for /var/mqm/errors.

    The /var file system is used to store all the security logging information for the system, and is used to store the temporary files for email and printing. Therefore, it is critical that you maintain free space in /var for these operations.

  2. Do not install WebSphere Studio Application Developer and WAS on the same machine when using WebSphere MQ.

  3. Verify prerequisites are satisfied

  4. Install WebSphere MQ 5.3, with the required MQ features.

    You cannot install WebSphere MQ on top of WAS embedded messaging. Remove WAS first, install MQ, and then re-install WAS.

  5. Install any CSD* updates.

  6. If you want to use WebSphere MQ - Publish/Subscribe support, you need to provide a Publish/Subscribe broker.

    For example, you can do this by using either WebSphere MQ Event Broker or WebSphere MQ Integrator.

  7. Although it is to recommended for performance reasons, you can Install WAS on the same host as WebSphere MQ. Do not install the WAS embedded JMS provider.

  8. Set...

    MQJMS_LIB_ROOT=$WAS_HOME/Java/lib
    export MQJMS_LIB_ROOT

  9. Define WebSphere MQ resources.

  10. Secure messaging directories and log files

    1. For the /var/mqm/errors directory 

      chmod 3777 /var/mqm/errors
chown mqm:mqm /var/mqm/errors

touch /var/mqm/errors/AMQERR01.LOG 
chown mqm:mqm /var/mqm/errors/AMQERR01.LOG
chmod 666 /var/mqm/errors/AMQERR01.LOG

touch /var/mqm/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/errors/AMQERR02.LOG
chmod 666 /var/mqm/errors/AMQERR02.LOG

touch /var/mqm/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/errors/AMQERR03.LOG 
chmod 666 /var/mqm/errors/AMQERR03.LOG

    2. For the /var/mqm/qmgrs/@SYSTEM/errors directory 

      chmod 3777 /var/mqm/qmgrs/@SYSTEM/errors
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG 
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR01.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR02.LOG

touch /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG
chown mqm:mqm /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG 
chmod 666 /var/mqm/qmgrs/@SYSTEM/errors/AMQERR03.LOG

 

WebSphere MQ Provider Settings

These properties apply only if you have installed WebSphere MQ as the JMS provider over the internal JMS provider installed with WAS. You cannot change these properties.

To view, go to...

Resources | WebSphere MQ JMS Provider

Name

The name by which the WebSphere MQ JMS provider is known for administrative purposes.

Data type String
Default WebSphereMQJMSProvider

Description

A description of the JMS provider, for administrative purposes within IBM WAS.

Data type String
Default WebSphere MQ JMS provider

Classpath

The Java classpath for the JMS provider. The list of paths or JAR file names that together form the location for the JMS provider classes.

Data type String
Default $MQJMS_LIB_ROOT

Native Library Path

The native library path for the JMS provider. An optional path to any native libraries needed by the JMS provider.

Data type String
Default $MQJMS_LIB_ROOT

The Native Library Path property is set to the directory where the WebSphere MQ Java feature is installed.

 

WebSphere MQ JMS connection pooling

To improve the overall performance of JMS within the system, the message listener service enables the connection pooling facility provided by the WebSphere MQ JMS implementation. This support does not affect the performance of a message listener, because it retains its connections while listening on a destination, but does affect the overall JMS system performance. When a connection is no longer required, WebSphere MQ can pool the connection then reuse it later instead of destroying it.

Connection pooling is only available if WebSphere MQ is configured as the JMS provider.

An application can explicitly poll for messages on a destination. WAS also provides a message listener service that applications can use to automatically retrieve messages from JMS destinations for processing by message-driven beans, without the application having to explicitly poll JMS destinations.

Tools for working with messaging include the WebSphere Studio for developing and packaging J2EE applications that use JMS, message-driven beans, or extended messaging; the Application Assembly Tool, as described in Assembling applications with the Assembly Toolkit; and the product systems administration tools, as described in System Administration.

To configure WebSphere MQ JMS connection pooling go to...

Servers | Application Servers | appserver | Message Listener Service properties | Custom Properties

...and tweak the following parameters...

mqjms.pooling.threshold

Maximum number of unused connections in the pool.

mqjms.pooling.timeout Timeout in milliseconds for unused connections in the pool.

 

Moving from embedded WebSphere JMS provider to WebSphere MQ

The procedure below will work only if you already have an MQ client installed. If you do not, then the procedure below will fail. Your only migration path is to completely remove WAS and ND, and then reinstall. Install MQ first. Then install WAS and ND. When reinstalling, do not specify the embedded messaging client.

I strongly recommend verifying your proposed JMS topology and migration scenario with IBM before proceeding.

  1. For WebSphere MQ point-to-point messaging, install the base WebSphere MQ product.

    When installing WebSphere MQ, perform the following actions...

    1. When asked if you want to remove or modify the version of WebSphere MQ currently installed, choose to remove the Server. (The WebSphere MQ install program recognizes the installed WebSphere embedded messaging as an installed version of WebSphere MQ.)

    2. Select the option to keep existing queue managers.

    3. Proceed with the installation of the full WebSphere MQ Server by running the install program again, after the old WebSphere MQ server (the Embedded Messaging Server) has been removed.

  2. Configure WebSphere MQ queue resources to WAS.

  3. For WebSphere MQ publish/subscribe messaging, install a Publish/Subscribe broker, such as WebSphere MQ Event Broker.

  4. Configure WebSphere MQ topic resources to WAS.

    For publish/subscribe messaging, WebSphere applications can continue to use WebSphere topic resources (through the embedded messaging JMS provider) or WebSphere MQ topics.

 

JMS servers on Application Servers

Appservers that are not part of an ND cell have internal JMS servers that you can configure to access JMS resources...

Servers | Application Servers | server | Server components | JMS Server

If you want the JMS server to be started automatically when the appserver is next started, set the Initial state property to started.

If you want to add a new queue to be hosted by the JMS server, add the administrative name of the queue to the Queue Names field. The name must match the name of a WebSphere Queue administrative object and is case-sensitive.

 

Queue Connection factories

An application component uses a connection factory to access a connection instance, which the component then uses to connect to the underlying enterprise information system.

Examples of connections include database connections, JMS connections, and SAP R/3 connections.

Connection factories are used to create connections with the JMS provider for a specific JMS queue or topic destination. Each connection factory encapsulates the configuration parameters needed to create a connection to a JMS destination.

To specify properties for connection factories with WebSphere MQ JMS Provider, go to...

Resources | WebSphere MQ JMS Provider | Additional Properties | WebSphere MQ Queue Connection Factories

Specify any of the following WebSphere MQ SSL properties that you need, as Custom properties of the connection factory...

SSLPEERNAME
SSLCRL
SSLCIPHERSUITE

 

Configure a topic connection factory

To specify properties for topic connection factories with WebSphere MQ JMS provider, go to...

Resources | WebSphere MQ JMS Provider | Additional Properties | WebSphere MQ Topic Connection Factories

Specify any of the following WebSphere MQ properties that you need, as Custom properties of the connection factory...

SSLPEERNAME
SSLCRL
SSLCIPHERSUITE
MSGSELECTION
SUBSTORE

 

Configure a queue destination

To configure properties for queue destinations with a WebSphere MQ Provider, go to...

Resources | WebSphere MQ JMS Provider | WebSphere MQ Queue Destinations

You need to create corresponding queues in WebSphere MQ using runmqsc or MQ Explorer.

The WebSphere MQ Queue Manager on which the queue resides (or will reside) must be configured for remote administration and be running.

 

Configure a topic destination

To specify properties for topic destination, for a WebSphere MQ JMS provider, go to...

Resources | WebSphere MQ JMS Provider | WebSphere MQ Topic Destinations

 

JMS server settings

The JMS functions on a node within the WAS administration domain are served by the JMS server on that node. Use this panel to view or change the configuration properties of the selected JMS server.

Use this panel to configure a general set of JMS server properties, which add to the default values of properties configured automatically for the embedded WebSphere JMS provider.

In general, the default values of WebSphere MQ properties are adequate for WebSphere internal JMS servers. However, if you are running high messaging loads, you may need to change some WebSphere MQ properties; for example, properties for log file locations, file pages, and buffer pages.

Name The name by which the JMS server is known for administrative purposes within IBM WAS.

This name should not be changed.

Data type String
Units Not applicable
Default WebSphere Internal JMS Server
Range Not applicable

Description A description of the JMS server, for administrative purposes within IBM WAS.

This string should not be changed.

Data type String
Default WebSphere Internal JMS Server

Number of threads   The number of concurrent threads to be used by the publish/subscribe matching engine

The number of concurrent threads should only be set to a small number.

Data type Integer
Units Threads
Default 1
Range Greater than or equal to 1.

Queue Names The names of the queues hosted by this JMS server. Each queue name must be added on a separate line.

Each queue listed in this field must have a separate queue administrative object with the same administrative name. To make a queue available to applications, define a WebSphere queue and add its name to this field on the JMS Server panel for the host on which you want the queue to be hosted.

Data type ASCII
Units Queue name
Default Not applicable
Range Each entry in this field is a queue name of up to 45 characters, which must match exactly (including use of upper- and lowercase characters) the WebSphere queue administrative object defined for the queue.

Initial state The state that you want the JMS server to have when it is next cycled.

Data type Enum
Units Not applicable
Default Started
Range

Started

The JMS server is started automatically.

Stopped

The JMS server is not started automatically. If any deployed enterprise applications are to use JMS server functions provided by the JMS server, the system administrator must start the JMS server manually or select the Started value of this property then restart the JMS server.

To restart the JMS server for an appserver, stop then restart that application server.

 

Configure a new JMS connection using wsadmin.sh

 

Using Jacl

###
### Identify the parent ID...
###

set JMSParent [$AdminConfig getid /Cell:cell/Node:node/JMSProvider:JMSProvider]

###
### Get required attributes...
###

$AdminConfig required GenericJMSConnectionFactory

###
### Set up required attributes...
###

set name [list name JMSCF1]
set jndi [list jndiName jms/JMSConnFact1]
set extJndi [list externalJNDIName jms/extJMSCF1]
set jmscfAttrs [list $name $jndi $extJndi]

###
### Create generic JMS connection factory...
###

$AdminConfig create GenericJMSConnectionFactory $JMSParent $jmscfAttrs


###
### Save the changes...
###

$AdminConfig save

 

Using Jython

JMSParent = AdminConfig.getid('/Cell:cell/Node:node/JMSProvider:JMSProvider')
print JMSParent

print AdminConfig.required('GenericJMSConnectionFactory')

name = ['name', 'JMSCF1']
jndi = ['jndiName', 'jms/JMSConnFact1']
extJndi = ['externalJNDIName', 'jms/extJMSCF1']
jmscfAttrs = [name, jndi, extJndi]
print jmscfAttrs

print AdminConfig.create('GenericJMSConnectionFactory', JMSParent, jmscfAttrs)

AdminConfig.save()

 

Configure a new JMS destination using wsadmin

 

Using Jacl:

set JMSParent [$AdminConfig getid /Cell:cell/Node:node/JMSProvider:JMSP1]


### Get required attributes...

$AdminConfig required GenericJMSDestination


### Set up required attributes...

set name [list name JMSD1]
set jndi [list jndiName jms/JMSDestination1]
set extJndi [list externalJNDIName jms/extJMSD1]
set jmsdAttrs [list $name $jndi $extJndi]


### Create generic JMS destination...

$AdminConfig create GenericJMSDestination $JMSParent  $jmsdAttrs

$AdminConfig save

Using Jython

JMSParent = AdminConfig.getid('/Cell:cell/Node:node/JMSProvider:JMSP1')
print JMSParent

print AdminConfig.required('GenericJMSDestination')

name = ['name', 'JMSD1']
jndi = ['jndiName', 'jms/JMSDestination1']
extJndi = ['externalJNDIName', 'jms/extJMSD1']
jmsdAttrs = [name, jndi, extJndi]
print jmsdAttrs

print AdminConfig.create('GenericJMSDestination', JMSParent,  jmsdAttrs)

AdminConfig.save()

 

Configure a new JMS provider using wsadmin

### Identify the parent ID...
set node [$AdminConfig getid /Cell:cell/Node:node/]

### Get required attributes...

$AdminConfig required JMSProvider

### Set up required attributes...

set name [list name JMSP1]
set extICF [list externalInitialContextFactory  "Put the external initial context factory here"] 
set extPURL [list externalProviderURL "Put the external provider URL here"] 
set jmspAttrs [list $name $extICF $extPURL]


### Create the JMS provider...

set JMSParent [$AdminConfig create JMSProvider $node $jmspAttrs]

### Save the changes...

$AdminConfig save

 

Using Jython

node = AdminConfig.getid('/Cell:cell/Node:node/')
print node

print AdminConfig.required('JMSProvider')

name = ['name', 'JMSP1']
extICF = ['externalInitialContextFactory',  "Put the external initial context factory here"] 
extPURL = ['externalProviderURL', "Put the external provider URL here"] 
jmspAttrs = [name, extICF, extPURL]
print jmspAttrs

JMSParent = AdminConfig.create('JMSProvider', node, jmspAttrs)
print JMSParent

AdminConfig.save()

 

Troubleshoot WebSphere Messaging

  1. Check that the JMS server has been started

  2. Check that you have successfully installed the WebSphere Messaging function.

  3. Check the Release Notes for specific problems and workarounds

  4. Check for WebSphere Messaging messages in

    $WAS_HOME/logs/server/SystemOut.log

    For messages related to WebSphere Messaging, look for the prefixes: MSGS and WMSG.

  5. Check that queue destinations and their connection factories have corresponding JNDI names

  6. Check that JNDI names match those configured for messaging applications

  7. Check that connection factories are configured onto nodes that can provide the JMS resources.

  8. Enable the debug trace for the "Messaging" group.