JMS Message Listeners
JMS Message Listeners allow you to listen for incoming JMS messages. You specify the source of the messages (JMS Topic or JMS Queue) and a task that will be executed for each incoming message.
JMS messaging requires a JMS API (jms.jar) and specific third-party libraries. Every one of these libraries must be available on a classpath of an application server. Some application servers contain these libraries by default; however, some do not. In such a case, libraries must be added explicitly before starting the CloverDX Server.
|JMS Message Listeners on Worker|
JMS Message Listener always runs on Server Core, but you can use it to execute jobs on Worker.
In such a case, make sure that the required
JMS implementation is dependent on the application server that the CloverDX Server is running in.
In Cluster, you can either explicitly specify which node will listen to JMS or not. If unspecified, all nodes will register as listeners. In the case of JMS Topic, all nodes will get the message and trigger the task (multiple instances) or, in the case of JMS Queue, a random node will consume the message and run the task (just one instance).
JMS Message Listener Modes
JMS Message Listener supports two modes which influence its life cycle.
You can choose between these modes by enabling/disabling the
Trigger new task for every message option:
Table 33.2. JMS Message Listener Modes
The listener connects to the JMS source (queue/topic) and responds to each incoming message by triggering the selected task (e.g. graph or jobflow). The connection to the source is not interrupted during the process.
The listener connects to the JMS source (queue/topic) and waits for a message. Once the message is received, it stays in the queue, the listener disconnects from the source and responds to the message by triggering the selected task (e.g. graph or jobflow). Once the task is finished, the listener reconnects to the source and waits for another message. This way, the triggered task can use JMSReader to connect to the same source as the listener which, in some use cases, increases performance.
The listener is disconnected from the source for the duration of the triggered task, but for the maximum of the task.jms.callback.timeout value.
Attributes of JMS Message Listener
Below is the list of attributes which can be set up for JMS Message Listeners:
Table 33.3. Attributes of JMS Message Listener
This attribute is useful only in a Cluster environment. It is a node ID where the listener should be initialized. If it is not set, the listener is initialized on all nodes in the Cluster.
In the Cluster environment, each JMS event listener has a Node IDs attribute which may be used to specify the Cluster node which will consume messages from the queue/topic. There are the following possibilities:
In a standalone environment, the Node IDs attribute is ignored.
|Initial context||Default or custom|
|Initial context factory class|
A full class name of the
The specified class must be on the web-app classpath or application-server classpath. It is usually included in one library with a JMS API implementation for each specific JMS broker provider.
|Broker URL||A URL of a JMS message broker|
|Connection factory||A JNDI name of a connection factory. It depends on a JMS provider.|
|Username||A username for a connection to a JMS message broker|
|Password||A password for a connection to JMS message broker|
|Queue/Topic||A JNDI name of a message queue/topic on the Server|
If false, the message consumer is connected to the broker as 'non-durable', so it receives only messages which are sent while the connection is active. Other messages are lost.
If the attribute is true, the consumer is subscribed as 'durable' so it receives even messages which are sent while the connection is inactive. The broker stores such messages until they can be delivered or until the expiration is reached.
This switch is useful only for Topics destinations, because Queue destinations always store messages until they can be delivered or the expiration is reached.
Please note that consumer is inactive e.g. during server restart and during short moment when the user updates the "JMS message listener" and it must be re-initialized. So during these intervals, the message in the Topic may get lost if the consumer does not have the durable subscription.
If the subscription is durable, client must have ClientId specified.
This attribute can be set in different ways in dependence on JMS provider.
E.g. for ActiveMQ, it is set as a URL parameter
Available only when Durable subscriber is
This query string can be used as a specification of conditions for filtering incoming messages. Syntax is well described on Java EE API web site. It has different behavior depending on the type of consumer (queue/topic):
Queue: Messages that are filtered out remain in the queue.
Topic: Messages filtered out by a Topic subscriber's message selector will never be delivered to the subscriber. From the subscriber's perspective, they do not exist.
|Number of consumers||E.g. 1|
A Groovy code may be used for additional message processing and/or for refusing a message. Both features are described below.
Optional Groovy code
Groovy code may be used for additional message processing or for refusing a message.
Additional message processing Groovy code may modify/add/remove values stored in the containers "properties" and "data".
Refuse/acknowledge the message If the Groovy code returns
Boolean.FALSE, the message is refused. Otherwise, the message is acknowledged. A refused message may be redelivered, however the JMS broker should configure a limit for redelivering messages. If the Groovy code throws an exception, it’s considered a coding error and the JMS message is NOT refused because of it. So, if the message refusal is to be directed by some exception, it must be handled in Groovy.
Table 33.4. Variables accessible in Groovy code
|javax.jms.Message||msg||instance of a JMS message|
See below for details. It contains values (String or converted to String) read from a message and it is passed to the task which may then use them. For example, the execute graph task passes these parameters to the executed graph.
See below for details. Contains values (Object, Stream, etc.) read or proxied from the message instance and it is passed to the task which may then use them. For example, the execute graph task passes it to the executed graph as dictionary entries.
|javax.servlet.ServletContext||servletContext||An instance of ServletContext.|
|com.cloveretl.server.api.ServerFacade||serverFacade||An instance of serverFacade usable for calling CloverDX Server core features.|
|java.lang.String||sessionToken||SessionToken needed for calling serverFacade methods|
Message data available for further processing
A JMS message is processed and the data it contains is stored into two data structures: Properties and Data.
Table 33.5. Properties Elements
For each message property, one entry is created where "key"
is made of the
|JMS_MAP_[map entry key]|
If the message is an instance of MapMessage, for each map entry,
one entry is created where "key" is made of the
|JMS_TEXT||If the message is an instance of TextMessage, this property contains content of the message.|
|JMS_MSG_CLASS||A class name of a message implementation.|
|JMS_MSG_CORRELATIONID||Correlation ID is either a provider-specific message ID or an application-specific String value.|
|JMS_MSG_DESTINATION||The JMSDestination header field contains the destination to which the message is being sent.|
JMSMessageID is a String value that should function as a unique key for identifying messages in a historical repository. The exact scope of uniqueness is provider-defined. It should at least cover all messages for a specific installation of a provider, where an installation is some connected set of message routers.
|JMS_MSG_REPLYTO||A destination to which a reply to this message should be sent.|
|JMS_MSG_TYPE||A message type identifier supplied by the client when the message was sent.|
|JMS_MSG_DELIVERYMODE||The DeliveryMode value specified for this message.|
The time the message expires, which is the sum of the time-to-live value specified by the client and the GMT at the time of the send.
The JMS API defines ten levels of priority value (0 = lowest, 9 = highest). In addition, clients should consider priorities 0-4 as gradations of normal priority and priorities 5-9 as gradations of expedited priority.
The time a message was handed off to a provider to be sent. It is not the time the message was actually transmitted, because the actual send may occur later due to transactions or other client-side queueing of messages.
Note that all values in the “Properties” structure are stored as a String type – however they are numbers or text.
For backwards compatibility, all listed properties can also be accessed using lower-case keys; however, it is a deprecated approach.
Table 33.6. "Data" elements
|JMS_DATA_MSG||An instance of javax.jms.Message.|
An instance of java.io.InputStream. Accessible only for TextMessage, BytesMessage, StreamMessage, ObjectMessage (only if a payload object is an instance of String). Strings are encoded in UTF-8.
An instance of String. Only for TextMessage and ObjectMessage, where a payload object is an instance of String.
|JMS_DATA_OBJECT||An instance of java.lang.Object - message payload. Only for ObjectMessage.|
The Data container is passed to a task that can use it, depending on its implementation. For example, the task execute graph passes it to the executed graph as dictionary entries.
In a Cluster environment, you can explicitly specify node IDs, which can execute the task. However, if the data payload is not serializable and the receiving and executing node differ, an error will be thrown as the Cluster cannot pass the data to the executing node.
Inside a graph or a jobflow, data passed as dictionary entries can be used in some component attributes.
For example, the File URL attribute would look like:
"dict:JMS_DATA_STREAM:discrete" for reading the data directly from the incoming
JMS message using a proxy stream.
If the graph is executed on Worker, the dictionary entries must be serialized; otherwise, they cannot be passed to the graph.
For backwards compatibility, all listed dictionary entries can also be accessed using lower-case keys; however, it is a deprecated approach.
JMS is a complex topic that goes beyond the scope of this document. For more detailed information about JMS, refer to the Oracle website: https://docs.oracle.com/javaee/7/tutorial/jms-concepts.htm#BNCDQ