JMS Channel Example Introduction

This project shows an example of a simple server application that uses JMS to retrieve text messages from a message queue. The primary goal of this project is to show how a JMS channel can easily integrate with the ActiveSpaces Transactions Channel framework.

Please see the enclosed source, javadoc, and example class descriptions.

Usage

JMS Provider

This example may be used with either a Apache ActiveMQ or a TIBCO Enterprise Message Service (EMS) JMS provider.

See the Command Line Arguments section for details on how to specify which JMS provider to use.

ActiveMQ

The ActiveSpaces Transactions installation includes the ActiveMQ software needed to run this example. The example's pom.xml includes ActiveMQ as a dependency.

The JMS channel example starts an embedded ActiveMQ message broker. This allows the example to be used without dependencies on external servers or software.

TIBCO EMS

TIBCO EMS is not included in the ActiveSpaces Transactions installation.

To use this example with EMS, you must have access to a running EMS server. Unlike with ActiveMQ, this example does not start an embedded EMS server.

The JMS channel example connects to the JMS provider using an empty username and password. If your EMS server will not allow this then you will need to update the method JmsProvider.startJmsProvider().

The JMS channel example expects the requests message queue to exist. If your EMS server does not allow message queues to be created dynamically then you will need to create the requests queue on your EMS server prior to running the example.

Please see Using the JMS Channel Example with TIBCO EMS for additional information.

Command Line Arguments

The JMS channel example supports two command-line arguments.

Use the jmsprovider command-line argument to specify which JMS provider to use. The possible values are activemq and ems. The default value is activemq.

Use the providerurl command-line argument to specify the URL at which the JMS provider listens for connection requests. The URL should be of the form tcp://host:port. The default value is tcp://localhost:61616.

When using Apache ActiveMQ, the providerurl argument specifies the URL for the embedded JMS provider. If you are running the example on the ActiveSpaces Transactions Development Appliance then the host part of the URL should be localhost or the IP address of the ActiveSpaces Transactions Development Appliance. Use the IP address in the URL if the JMS clients used with the example are not run from the ActiveSpaces Transactions Development Applicance.

Command-line arguments must be specified as name/value pairs. For example:

  java ... com.kabira.examples.jmschannel.Main jmsprovider=activemq providerurl=tcp://localhost:12345

If you use the TIBCO ActiveSpaces Transactions Deployment Maven plugin to run the example then you change the command-line arguments by editing the arguments configuration within the deploy-maven-plugin section of the example's pom.xml file:

            <plugin>
                <groupId>com.tibco.ast</groupId>
                <artifactId>deploy-maven-plugin</artifactId>
                <configuration>
                    <mainClass>com.kabira.examples.jmschannel.Main</mainClass>
                     ...
                    <arguments>
                        <argument>jmsprovider=activemq</argument>
                        <argument>providerurl=tcp://localhost:61616</argument>
                    </arguments>
                </configuration>
                ...
            </plugin>

Message Queues

The server reads the inbound messages from the requests message queue.

Your JMS client program may optionally use the reply-to message header to specify the message queue to which the server should send its response. The server does not send a response if the reply-to header is not set in the inbound message.

Starting the example

To start the example on the ActiveSpaces Transactions Development Appliance:

NOTE: kabira-server.local only works on OS X. Other platforms may use a different name, or have to specify an IP address.

mvn -Dcom.kabira.fluency.administrationPort=2000 \
      -Dcom.kabira.fluency.hostName=kabira-server.local \
      compile deploy:exec

When using Apache ActiveMQ as the JMS provider the example will display:

Starting ActiveMQ JMS provider at tcp://localhost:61616 ...
==============================================
JMS channel service started.
To stop this application, stop the "jms" service.
==============================================

When using TIBCO EMS as the JMS provider the example will display:

Using the Tibco EMS JMS provider at tcp://localhost:61616 ...
==============================================
JMS channel service started.
To stop this application, stop the "jms" service.
==============================================

Using the example

At this point, you can connect to your JMS provider with a JMS client, and send text messages to the requests queue. The JMS provider delivers the messages to the JMS channel server since the server creates an Endpoint that listens for messages on the requests queue.

If you want the JMS channel server to send back a response message then your client must set the reply-to header in its message.

When the JMS channel server receives a message it prints the contents to standard output. If the client has set the reply-to header the server sends a response message to the queue specified in the reply-to header. The contents of the response message is simply the contents of the request message.

Here is the server output after a client sends a "hello" message to the requests queue:

Starting the JMS provider at tcp://192.168.131.129:60606 ...
Starting ActiveMQ JMS provider at tcp://localhost:61616 ...
==============================================
JMS channel service started.
To stop this application, stop the "jms" service.
==============================================
Received message from requests: [hello]

See com.kabira.examples.jmschannel.test.JmsClient for an example of a simple ActiveMQ JMS client.

See Apache ActiveMQBrowser for an open source GUI administration tool that can be used to send messages to an ActiveMQ JMS provider.

Administration

Integrating our JMS channel with the ActiveSpaces Transactions Channel framework allows the JMS channel to be managed using ActiveSpaces Transactions administration tools.

In the following Kabira Manager view, the "jms" Service is selected. The Endpoint for the inbound "requests" queue is attached to the "jms" Service.

View of the "jms" Service in Kabira Manager.

To shut down the application, stop the "jms" service via the Kabira Manager, using the "stop" button in the upper right corner of the Service jms window.

Each Endpoint is created with a Session instance to manage session-level statistics:

View of the "requests" Endpoint in Kabira Manager.

Select the named Session instance will show the details for that instance:

View of the "requests:consumer" Endpoint in Kabira Manager.

Dependencies

See the Dependencies page for information on the channel's dependencies.

For each dependency listed in the Project Dependencies section of the Dependencies page, the channel's POM (or parent POM) defines a property specifying the version of the dependency used by the channel. These properties can be overridden if there is a need to change the dependency versions used by the channel. The names of these properties are of the form com.tibco.groupId.artifactId.version where groupId and artifactId are the group id and artifact id of the dependency. For example, the property named com.tibco.com.tibco.ast.version specifies the version of the dependency with the group id of com.tibco and the artifact id of ast.