The Java Message Service (JMS) provides a framework for enterprise messaging systems. The JMS defines a set of specifications for enterprise messaging systems that allow messages to be sent across application components. A number of providers are available for use, including Apache ActiveMQ, Progress SonicMQ, and IBM WebSphere MQ.

JMS is supported for third-party providers only. NexJ supports internal message queues using ObjectQueue channels. Two resource adapters are available for use with JMS: the NexJ resource adapter and the native resource adapter.

The general process for setting up JMS integration is:

Add the MessageQueue channels that will use the JMS provider in the connections or environment file.
Configure each channel with the properties required for the specific JMS provider.
Configure settings for the JMS provider.
If using the native resource adapter, configure settings for the application server.

Info

The WebSphere JMS engine can initiate very long running transactions. When the JMS engine is configured to use a database with the SNAPSHOT_ISOLATION setting turned on (which is the case with the DefaultRelationalDatabase on Microsoft SQL Server), all changes to the database will cause the version store to grow until the transaction is completed. This is exacerbated by enabling persistent statistics as this configuration increases the number of database changes made on an idle cluster. To alleviate this issue, NexJ recommends that you either configure the WebSphere JMS engine to use a file store or alternatively use a separate database for the WebSphere JMS store with the SNAPSHOT_ISOLATION setting turned off for that database.

Adding factory and destination properties

JMS providers require different properties to be set on the MessageQueue channel. Add factory and destination properties to the connections or environment file based on the JMS provider.

Before you can add factory and destination properties, you must add the MessageQueue channels that will use the JMS provider to the connections or environment file. See Creating channel connections for more information.

To add factory and destination properties:

In the environment or connection editor window, select the Channel Connections tab. In the Channel Connections area, select a channel to edit.
In the General subtab, for every MessageQueue channel, enter the connection factory name in the Factory field.
In the Destination field, for every MessageQueue channel, enter the destination name.
In the Properties subtab, click the Add button in the Factory Properties and Destination Properties sections to add properties.
Double-click inside the Name and Value columns to edit each property. Enter the new name and value.
Add the required properties to each channel until completed.

Each JMS provider requires its own set of properties to configure. See the respective section for each JMS provider.

Setting properties for ActiveMQ

Set these properties within the connections or environment file when using ActiveMQ.

MessageQueue channel properties for ActiveMQ

Factory properties

Name	Value	Value example
`brokerURL`	<broker-url>	vm://localhost

Destination properties

Name	Value	Value example
`physicalName`	<destination-physical-name>	queue.SYSTEM_QUEUE

Configuring settings for the NexJ resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.engine.activemq.ActiveMQAdapter

Set each channel to use this destination:
class:org.apache.activemq.command.ActiveMQ[Queue|Topic]

Configuring settings for the native resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.platform.activemq.ActiveMQPlatformAdapter

Set each channel to use this destination:
class:org.apache.activemq.command.ActiveMQ[Queue|Topic]

Configuring ActiveMQ broker URLs

See the following for more information on configuring ActiveMQ broker URLs:

Setting properties for SonicMQ

Set these properties within the connections or environment file when using SonicMQ.

MessageQueue channel properties for SonicMQ

Factory properties

Name	Value	Value example
`brokerURL`	<broker-url>	tcp://localhost:2506
`connectionURLs`	<connection-url>	tcp://localhost:2506
`destination`	<destination-physical-name>	queue.NEXJ_QUEUE

Destination properties

Name	Value	Value example
`[queue\|topic]Name`	<destination-physical-name>	queue.NEXJ_QUEUE\| topic.SYSTEM_TOPIC

Info

The physical destination name must match the physical name defined in the actual queue.

brokerURL values and connectionURL values must match, and must be specified in the following format:
tcp://<host>:<port>

Configuring settings for the NexJ resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.platform.sonicmq.SonicMQPlatformAdapter

Set each channel to use this destination:
class:progress.message.jclient.[Queue|Topic]

Configuring settings for the native resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.platform.sonicmq.SonicMQPlatformAdapter

Set each channel to use this destination:
class:progress.message.jclient.[Queue|Topic]

Setting properties for WebSphere MQ

Set these properties within the connections or environment file when using WebSphere MQ.

MessageQueue channel properties for WebSphere MQ

Factory properties

Name	Value	Value example
`hostName`	<wmq-host>	localhost
`queueManager`	<queue-manager-name>	QM
`transportType`	1	only "1" supported

Destination properties for queues

Name	Value	Value example
`baseQueueName`	<queue-physical-name>	queue.NEXJ_QUEUE
`baseQueueManagerName`	<queue-manager-name>	QM

Destination properties for topics

Name	Value	Value example
`baseTopicName`	<topic-physical-name>	topic.SYSTEM_TOPIC

Info

The physical destination names for queues and topics must match the physical name defined in the actual destinations.

Configuring settings for the NexJ resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.engine.webspheremq.WebSphereMQAdapter

Set each channel to use this destination:

class:com.ibm.mq.jms.MQ[Queue|Topic]

Configuring settings for the native resource adapter

Configure these settings for each MessageQueue channel.

Set each channel to use this factory:
class:nexj.core.rpc.jms.ra.platform.webspheremq.WebSphereMQPlatformAdapter

Set each channel to use this destination:
class:com.ibm.mq.jms.MQ[Queue|Topic]

Configuring JMS providers

Each JMS provider requires their own settings to configure. Refer to the JMS provider's documentation for more information.

Configuring ActiveMQ

In order to alter the resource adapter settings, extract activemq-rar.rar using the Java jar command. After changes are made, recreate the activemq-rar.rar to be used on your application server.

If you are using the NexJ resource adapter, you only need to copy activemq-core.jar and kahadb.jar into your application server's lib directory. If you are using the native resource adapter, follow the directions below.

To configure ActiveMQ to use the native resource adapter:

Locate your activemq-ra.rar resource adapter file. Create a temporary directory and move the resource adapter file to it.
Open a command line console. Navigate to the temporary directory you created.
In the command line, extract the resource adapter file with the following command:
jar xvf activemq-rar.rar
Using a text editor of your choice, make the following changes to META-INF/ra.xml:
1. Change the value of the ServerUrl element from:
  <config-property-value>tcp://localhost:61616</config-property-value>
  to
  <config-property-value>vm://localhost</config-property-value>
2. Change the value of the BrokerXmlConfig element from:
  <config-property-value></config-property-value>
  to
  <config-property-value>xbean:broker-config.xml</config-property-value>
In the command line, recreate the resource adapter file with the following command, where <tempdir> is your temporary directory:
jar cvf activemq-rar.rar ./META-INF/manifest.mf -C <tempdir>

Info

See the following for more information on configuring broker-config.xml:

• http://activemq.apache.org/xml-reference.html

If you are using the native resource adapter, you should now configure the application server. For specific instructions on WebSphere servers, see WebSphere configuration for JMS providers.

Configuring SonicMQ

Follow these instructions to configure the SonicMQ JMS provider.

If you are using the NexJ resource adapter, copy broker.jar, sonic_Client.jar, and sonic_XA.jar into the application server's lib directory.

These are the general steps to configuring SonicMQ. Documentation for using the SonicMQ Management Console can be found here: http://documentation.progress.com/output/Sonic/Docs.htm .

To configure SonicMQ:

Make sure SonicMQ is running. If it is not running, start it.
If credential authentication is being used, then add the necessary user credentials to the SonicMQ Administrators group using the Sonic Management Console.
Define all the SonicMQ destinations and queues. It is not necessary to create topics as they will be created automatically.

If you are using the native resource adapter, you should now configure the application server. For specific instructions
on WebSphere servers, see WebSphere configuration for JMS providers.

Configuring WebSphere MQ

Use WebSphere MQ commands to configure WebSphere MQ. Refer to the IBM WebSphere MQ documentation for information on using the WebSphere MQ commands.

If you are using the NexJ resource adapter, copy the files com.ibm.mq.jmqi.jar, com.ibm.mqetclient.jar, com.ibm.mqjms.jar, and dhbcore.jar into the application server's lib directory.

These are the general steps to configuring WebSphere MQ. Documentation for setting up WebSphere can be found here: http://www-01.ibm.com/software/integration/wmq/library/ .

To configure WebSphere MQ:

If credential authentication is being used, add the necessary user credentials to the "mqm" group.
Create the WebSphere MQ queue manager using the crtmqm command.
Define all destinations for the queue manager, including all queues and topics.
Start the queue manager with the strmqm command.
Start the message queue listener with the runmqlsr command.

If you are using the native resource adapter, you should now configure the application server. For specific instructions on WebSphere servers, see WebSphere configuration for JMS providers.

Configuring application servers using the native resource adapter

Configure the application server in order to use JMS when using the native resource adapter. Each JMS provider has its own settings to configure, and you configure the settings for each application server using different methods.

Required server properties for JMS providers using the native resource adapter

When using native resource adapters, each JMS provider requires their own settings to configure. Configure all the required properties on the application server.

These settings are for use with the native resource adapters only, to be configured on the application server side in addition to the settings in the connection or environment file. If you are using the NexJ resource adapter, you only need to configure the settings in the connection or environment file. See Adding factory and destination properties for the NexJ resource adapter settings.

Required server properties for ActiveMQ using the native resource adapter

When configuring ActiveMQ on the application server, the following configuration properties must be defined for use with the native resource adapter:

Factory properties

Name	Value	Value example
`Jndi-name`	<factory-JNDI-name>	nexj/jms/cf/SystemQueue
`ServerUrl`	<broker-url>	vm://localhost
`physicalName`	<destination-physical-name>	queue.SYSTEM_QUEUE

Info

The ServerUrl must correspond to the brokerURL as defined in the MessageQueue channels. The physical destination name must match the physical name as defined in the MessageQueue channels.

Required server properties for SonicMQ using the native resource adapter

When configuring SonicMQ on the application server, the following configuration properties must be defined for use with the native resource adapter:

Factory properties

Name	Value	Value example
`BrokerUrl`	<broker-url>	tcp://localhost:2506

Destination properties

Name	Value	Value example
`[queue\|topic]Name`	<destination-physical-name>	queue.NEXJ_QUEUE\|topic.SYSTEM_TOPIC

Info

The physical destination name must match the physical name defined in the MessageQueue channels.

Required server properties for WebSphere MQ using the native resource adapter

When configuring WebSphere MQ on the application server, the following configuration properties must be defined for use with the native resource adapter:

Factory properties

Name	Value	Value example
`Jndi-name`	<factory-JNDI-name>	nexj/jms/cf/SystemQueue
`hostName`	<wmq-host>	localhost
`queueManager`	<queue-manager-name>	QM
`transportType`	CLIENT	only CLIENT supported

Destination properties for queues

Name	Value	Value example
`baseQueueName`	<queue-physical-name>	queue.NEXJ_QUEUE
`baseQueueManagerName`	<queue-manager-name>	QM

Destination properties for topics

Name	Value	Value example
`baseTopicName`	<topic-physical-name>	topic.NEXJ_TOPIC

Info

The physical destination names for queues and topics must match the physical name as defined in the MessageQueue channels.

WebSphere configuration for JMS providers

The WebSphere application server is managed through the WebSphere Integrated Solutions console. Refer to the IBM WebSphere documentation for information on using the console.

The general steps to setting up a WebSphere server are as follows:

Use the WebSphere Integrated Solutions console to install the required .RAR resource adapter file.
Define the connection factories for the resource adapter with the required configuration properties.
Define the administered objects for the resource adapter with the required configuration properties.

The configuration on the server must match the settings defined in the connections or environment file.

Info

Documentation for using SonicMQ with WebSphere can be found here: http://documentation.progress.com/output/Sonic/Docs.htm.

JMS engine integration

Adding factory and destination properties

Setting properties for ActiveMQ

MessageQueue channel properties for ActiveMQ

Configuring settings for the NexJ resource adapter

Configuring settings for the native resource adapter

Configuring ActiveMQ broker URLs

Related links

Setting properties for SonicMQ

MessageQueue channel properties for SonicMQ

Configuring settings for the NexJ resource adapter

Configuring settings for the native resource adapter

Related links

Setting properties for WebSphere MQ

MessageQueue channel properties for WebSphere MQ

Configuring settings for the NexJ resource adapter

Configuring settings for the native resource adapter

Related links

Configuring JMS providers

Configuring ActiveMQ

Configuring SonicMQ

Configuring WebSphere MQ

Configuring application servers using the native resource adapter

Required server properties for JMS providers using the native resource adapter

Required server properties for ActiveMQ using the native resource adapter

Required server properties for SonicMQ using the native resource adapter

Required server properties for WebSphere MQ using the native resource adapter

WebSphere configuration for JMS providers