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:
-
Right-click a folder in your project and then select New > Metadata.
-
In the New Metadata wizard, select Generic Message Queuing and then click Next.
-
Name the metadata and click Next.
-
Select the module and the third-party libraries required for the component and click Finish.
The metadata is created. -
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.
Property | Value |
---|---|
Initial Context Factory Class |
|
Connection Factory Name |
|
URL |
|
Property | Value |
---|---|
Initial Context Factory Class |
|
Connection Factory Name |
|
URL |
|
Property | Value | ||
---|---|---|---|
Initial Context Factory Class |
|
||
Connection Factory Name |
|
||
URL |
|
Property | Value |
---|---|
Initial Context Factory Class |
|
Connection Factory Name |
|
URL |
|
Define Queues
You can define the queues after configuring the connection. In JMS, queues contain messages delivered to subscribers.
To define a queue:
-
Right-click the server node and select New > Queue.
-
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
-
If using Active MQ:
-
Right-click the server node and select New > Property.
-
In the new properties, set the Name
queue.<queue_name>
and the Value to<queue_name>
. -
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:
-
Right-click the server node and select New > Topic.
-
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
. -
If using Active MQ:
-
Right-click the server node and select New > Property.
-
In the new properties, set the Name
topic.<topic_name>
and the Value to<topic_name>
. -
Repeat the above steps for each topic node in such a way that the property node immediately follows the topic node.
-
-
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:
-
Right-click the topic node and select New > Subscriber.
-
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:
-
JMS Operation send a JMS Operation to a remote JMS Server. For example, a commit/rollback.
-
JMS Receive Message to File receives messages from a JMS Server.
-
JMS Send Message From File sends a message to a JMS server.
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.
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, thefileName
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.
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.
|