Getting started with JMS

This article explains how to work with the Java Message Service (JMS) in Semarchy xDI. JMS is an standard API for sending data messages between systems using a service bus.

Create a JMS metadata

Define a JMS metadata

A JMS metadata holds information about a JMS server, as well as the Queues and Topics configured in that server. Such a metadata can be used in processes via JMS actions, using Semarchy xDI metadata features such as referencing, configuration, etc, to send and receive messages.

To create a JMS metadata:

  1. Right-click a folder in your project and then select New > Metadata.

  2. In the New Metadata wizard, select Generic Message Queuing and then click Next.

    getting started create metadata

  3. Name the metadata and click Next.

  4. Select the module and the third-party libraries required for the component and click Finish.
    The metadata is created.

  5. In the newly created metadata, select the server node and complete the connection configuration. This configuration depends on your message bus. The configuration for common message buses are listed below.

Table 1. Configuration for Active MQ
Property Value

Initial Context Factory Class

org.apache.activemq.jndi.ActiveMQInitialContextFactory

Connection Factory Name

ConnectionFactory

URL

tcp://<server>:<port>
Table 2. Configuration for Open JMS
Property Value

Initial Context Factory Class

org.exolab.jms.jndi.InitialContextFactory

Connection Factory Name

ConnectionFactory

URL

tcp://<server>:<port>
Table 3. Configuration for Open MQ
Property Value

Initial Context Factory Class

com.sun.jndi.fscontext.RefFSContextFactory

Connection Factory Name

ConnectionFactory

URL

file:///<file_location>

<file_location> is the directory where the .bindings file is stored. It is necessary to copy this file from the Open MQ server to a location accessible to the runtime. This file contains information about the queues and topics and is found on the Open MQ Server.
Table 4. FFMQ
Property Value

Initial Context Factory Class

net.timewalker.ffmq3.jndi.FFMQInitialContextFactory

Connection Factory Name

factory/ConnectionFactory

URL

tcp://<server>:<port>

Define Queues

You can define the queues after configuring the connection. In JMS, queues contain messages delivered to subscribers.

To define a queue:

  1. Right-click the server node and select New > Queue.

    getting started create queue topic

  2. Enter a Name and a Physical Name for the queue.

    For FFMQ, the physical name must be specified in the queue/<queue_name> format. For example, queue/Purchase_Queue

  3. If using Active MQ:

    1. Right-click the server node and select New > Property.

    2. In the new properties, set the Name queue.<queue_name> and the Value to <queue_name>.

    3. Repeat the above steps for each queue node in such a way that the property node immediately follows the queue node.

The Physical Name must match the name of the queue in the JMS server. Depending on their configuration, some JMS servers can create queues on the fly. If this is not the case with your JMS server, make sure that a queue that you define in the metadata exists in the server.

Define Topics

Topics deliver messages using a publish and subscribe model. Multiple subscribers can subscribe to one topic.

To create a topic:

  1. Right-click the server node and select New > Topic.

    getting started create queue topic

  2. Enter a Name and a Physical Name for the topic.

    For FFMQ, the physical name must be specified as topic/<topic_name>. For example, topic/Transactions.

  3. If using Active MQ:

    1. Right-click the server node and select New > Property.

    2. In the new properties, set the Name topic.<topic_name> and the Value to <topic_name>.

    3. Repeat the above steps for each topic node in such a way that the property node immediately follows the topic node.

  4. If you are using Active MQ, Open MQ, or FFMQ, make sure that that the JMS Client ID property is set on the server node. You can also set this property in JMS actions. Multiple processes cannot run at the same time with the same JMS Client Id, and JMS uses this string property to distinguish different client applications.

The Physical Name must match the name of the topic in the JMS server. Depending on their configuration, some JMS servers can create topics on the fly. If this is not the case with your JMS server, make sure that a topic that you define in the metadata exists in the server.

Define subscribers

JMS subscribers consume message from a topic.

To create a subscriber:

  1. Right-click the topic node and select New > Subscriber.

    getting started subscriber

  2. Enter the Name and the Physical Name of the subscriber.

Subscribers are automatically created in JMS Servers when they first try to read from a topic, and do not need to pre-exist in the JMS server.

Use JMS in processes

In Semarchy xDI Designer, the palette contains the following actions in the Internet & Networking category to interact with JMS servers:

getting started tools

The following sections explain how to use these actions in processes.

Send messages to a queue

In the following example, the Send JMS File Message From File action sends a JMS message from files.

getting started jms operation

In this example:

  • The File Wait action directly binds the parameters of the files to the JMS action. A JMS message is sent for each file found by the File Wait action.

  • JMS Send Message From File action. The corresponding queue node of the JMS metadata is dragged and dropped on this action to automatically set properties of the action (JMS_CONNECTION, JMS_DESTINATION, etc.) from the metadata. In addition:

    • IN_FILE_MASK is the file name mask for the files to send as messages. It is set to :{FILE_NAME}:, which corresponds the file name returned by the File Wait action via the bind link.

    • JMS_MESSAGE_TYPE is set to ByteMessage.

    • IN_FILE_DIR is the directory containing the files, and matches the directory specified in the File Wait action.

    • JMS_ACKNOWLEDGE_MODE is set to AUTO_ACKNOWLEDGE. The acknowledge mode determines how the consumer informs the provider that it has successfully received a message.

    • JMS_USER_DEFINED_PROPERTIES is used to set custom properties. It is set to <setProperty name="fileName" type="String">:{FILE_NAME}:</setProperty>.
      With this configuration, the fileName property is set to the name of the file. This property may be reused by the message consumer to write it to a file with the same name.

Consume messages from a queue

In the following example, the Receive JMS File Message to File action is used to retrieve the message sent using the Send JMS File Message From File action in the previous section.

getting started receive message

The corresponding queue node in the JMS metadata is dragged and dropped on Receive JMS File Message to File to set the connection properties.

The OUT_FILE_PATTERN parameter is set to [fileName], which corresponds to a JMS property. It is the same custom JMS property that was set in the JMS_USER_DEFINED_PROPERTIES parameter of the Send JMS File Message From File action. You can also set the OUT_FILE_PATTERN parameter to a property using the same mechanism.

Send messages to a topic

In the following example, the corresponding topic node in the JMS metadata is dragged and dropped on the JMS Send Message From File action.

getting started send message topic

Consume messages from a topic

In the following example, the corresponding topic node in the JMS metadata is dragged and dropped on the JMS Receive Message to File action.

getting started receive message topic