In this article
Java Message Service (JMS) is an API for sending data messages between systems. This article shows how to implement JMS features in Stambia.
Prerequesites
The JMS features require Stambia Designer and Stambia Runtime in version 17.2.8, or higher.
For this article, you need to install a JMS Server. We use OpenJMS as an example, and we also give information for ActiveMQ, OpenMQ and FFMQ.
Stambia can work with other JMS products, but we cannot cover all of them in this article. Please contact the support team if you have troubles setting up another JMS product.
Installing the JMS libraries
First download the libraries (jar files) from the JMS vendor, and copy them into the stambiaRuntime installation directory. Please consult the JMS product's documentation to know which files are required.
We recommend to store your libraries in a "addons" subdirectory in the Runtime lib directory.
Then restart the Runtime.
Creating the JMS metadata
Defining Metadata
The JMS Metadata will hold information on the JMS server, the queues and the topics.
This metadata information can be used in processes through the JMS Actions, with the usual Stambia Metadata features (Referencing, Configuration, etc.).
Create a new Generic Message Queueing Server metadata.
And set the properties as follows with your own settings
Please consult your JMS product documentation to know which are the correct values for the Factory properties. Here is an indication :
Active MQ :
Initial Context Factory Class : org.apache.activemq.jndi.ActiveMQInitialContextFactory
Connection Factory Name : ConnectionFactory
URL : tcp://<server>:<port>
Open JMS :
Initial Context Factory Class : org.exolab.jms.jndi.InitialContextFactory
Connection Factory Name : ConnectionFactory
URL : tcp://<server>:<port>
OpenMQ :
Initial Context Factory Class : com.sun.jndi.fscontext.RefFSContextFactory
Connection Factory Name : ConnectionFactory
URL : file:///<file location>
This location is the directory where the ".bindings" file is stored. It is necessary to copy this file from the Open MQ server,to a place the runtime can access.
This file contains information about the queues and topics and can be found on the Open MQ Server
FFMQ :
Initial Context Factory Class : net.timewalker.ffmq3.jndi.FFMQInitialContextFactory
Connection Factory Name : factory/ConnectionFactory
URL : tcp://<server>:<port>
Defining Queues
Right click on the Server node and choose New > Queue.
Note that the Physical Name must match the Queue name as declared on the JMS server.
Depending on their configuration, some JMS Servers create the queues on the fly, but if it is not the case, the queue defined in Physical Name must exist.
Active MQ specificity
Active MQ requires a property node for each queue under the Server node.
Right click on the Server node, choose New > Property.
Set Name = "queue.<nameOfQueue>", and Value = "<nameOfQueue>".
FFMQ specificity
For FFMQ, Physical Name must be queue/<nameOfQueue>
Defining Topics
Right click on the Server node and choose New > Topic.
Like the queues, the Physical Name must match the Topic name as declared on the JMS server.
Depending on their configuration, some JMS Servers create the topics on the fly too, but if it is not the case, the topic defined in Physical Name must exist.
Active MQ specificity
1) Active MQ requires a property node for each topic under the Server node.
Right click on the Server node, choose New > Property.
Set Name = "topic.<nameOfTopic>", and Value = "<nameOfTopic>".
2) Active MQ requires that a JMS CLIENT ID is set.
Open MQ specificity
Open MQ requires that a JMS CLIENT ID is set.
FFMQ specificity
1) For FFMQ, Physical Name must be topic/<nameOfTopic>
2) FFMQ requires that a JMS CLIENT ID is set
Note about JMS CLIENT ID
You can set this property on the server node or individually in each JMS Actions in the process.
It is a string property which is used by JMS to separate the different client's applications. (Ex: You cannot have multiple processes running at the same time with the same clientId).
Defining Subscribers
Right click on the Server node and choose New > Subscriber.
Most of the time subscribers are created on the fly, so they don't have to exist on the JMS Server.
Using JMS In processes
Overview of the Stambia JMS Actions
The Designer's Palette contains three Actions in the "Internet & Network" category:
- JMSSendMessage
- Sends a message to a JMS Server.
- JMSReceiveMessage
- Receives messages from a JMS Server. This Action can be used as a source of a Bind Link.
- JMSOperation
- Performs the specified operation. For example committing / rollbacking.
You can use these Actions in your Processes. We will see all these Actions in detail below.
Queues
Sending a message to a queue
We are going to use the Send JMS File Messages Action, which send JMS message(s) from file(s). The message(s) are contained in the file(s).
Process overview
The File Wait
We use here a file wait action to bind the parameters of the files (File name for exemple) directly to the JMS Action.
With that, a JMS Message will be sent for each files found by the File Wait.
Our files here are juste simple text files which contains an 'Hello World'
The JMS Action
We dragged and dropped the queue node of the metadata on the action, which permits to fill the associated properties in it (JMS_CONNECTION,JMS_DESTINATION,...)
IN_FILE_MASK is the mask for the files used to send the message. we set it to :{FILE_NAME}:, which is the name of the file taken from the bind.
JMS MESSAGE TYPE is set to ByteMessage
IN_FILE_DIR is the directory in which the files are.
JMS_ACKNOWLEDGE_MODE is set to AUTO_ACKNOWLEDGE. The acknowledge mode is the way the consumer is going to inform the provider it has successfully received a message
JMS_USER_DEFINED_PROPERTIES is used to set custom properties. We set it to <setProperty name="fileName" type="String">:{FILE_NAME}:</setProperty>. here we set a property in which we put the name of the file. We will be able to retrieve and use this property when we will receive the message (shown in the next part).
Receiving a message from a queue
We are now going to use the Receive JMS File Messages Action, to retrieve the message we just sent before.
Process overview :
Like the Send Action we dragged and dropped the queue from the metadata.
Note that we are using [fileName] in the OUT_FILE_PATTERN parameter. It is the custom jms property we set in the Send Action in the JMS_USER_DEFINED_PROPERTIES parameter. You can use it with [propertyName].
Topics
Sending a message to a topic
To send a message to a topic, the operation is the same as the one for a queue.
You can drag and drop (or fill the properties associated) the topic from the metadata on the receive action and set the other properties, like we saw for the queue.
Receiving a message from a topic
To receive a message from a topic, drag and drop the topic subscriber from the metadata on the receive action and set the properties like for the queues.
