Skip to content

Overview

Development

Overview

IDEs

API Explorer

JMS Listener Endpoint

The JMS listener endpoint enables developers to write integrations that react to messages received via Java Message Service (JMS) - a specification for implementing reliable, asynchronous, loosely-coupled communications. Apache ActiveMQ is TORO Integrate's default message broker, but since v3.1, there's been added support for ActiveMQ Artemis and RabbitMQ.

Properties

Properties Default Description
Destination (required) The JMS destination this endpoint should listen to.
Service (required) The service to execute when the endpoint is triggered.
Transacted false Flag determining whether the service invocation should be wrapped in a transaction.
Acknowledgement Mode 1 (auto) For non-transacted JMS session, this property determines how JMS messages are acknowledged.
Durable false Durable subscription ensures that this endpoint receives messages across restarts.
Run As 'Anonymous' The user to run the service in behalf of. This is logged to Tracker.
Log To Tracker false Flag determining whether executions should be logged to Tracker.
Document Type 'JMS' The document type to be registered to Tracker when this endpoint is triggered.

Service

When the endpoint is triggered, the following variables are exposed to the configured service:

Name Type Description
parameters java.util.Map Contains all the variables below.
esbPackage ESBPackage The Integrate package that contains this endpoint.
properties java.util.Map Contains all the properties associated with the endpoint.
message javax.jms.Message The message that triggered this endpoint.
destination javax.jms.Destination The destination of the message.
destinationName java.lang.String The destination of the message, in String.
replyTo javax.jms.Destination The reply destination, or null.
correlationId java.lang.String The message correlation ID, or null.
internalId java.lang.String Tracker internal ID. If the endpoint was configured to not track, this value will be null.

Depending on the type of message received by the endpoint, TORO Integrate exposes additional variables:

Example

Gloop as a Service

Consider this integration using Gloop. This is invoked when the JMS destination configured for the endpoint receives a Message.

JMS-replying service

(4) This line sends back the received message as the reply.

Want more examples?

The distribution ships with an Integrate package called examples, which contains services (including the above example) demonstrating more use cases.

Groovy Script as a Service

Consider this Groovy script that simply prints the available variables in the context:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[
    'parameters',
    'esbPackage',
    'properties',
    'destination',
    'destinationName',
    'message',
    'replyTo',
    'correlationId',
    'internalId',

    'content'].each {

    println "$it\t : " + this[it]
}

When the endpoint is triggered - in this case, a JMS message sent to the configured destination - the console prints accordingly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
parameters   : [ <omitted> ]
esbPackage   : ESBPackage [name=examples]
properties   : [ <omitted> ]
destination  : topic://toroIntegrate.universe-questions
destinationName  : toroIntegrate.universe-questions
message  : ActiveMQTextMessage {commandId = 1260, responseRequired = false, messageId = ID:TORO-MBP06-53671-1523846101995-2:1:7:4:2, originalDestination = null, originalTransactionId = null, producerId = ID:TORO-MBP06-53671-1523846101995-2:1:7:4, destination = topic://toroIntegrate.universe-questions, transactionId = null, expiration = 0, timestamp = 1523851868500, arrival = 0, brokerInTime = 1523851868500, brokerOutTime = 1523851868502, correlationId = null, replyTo = null, persistent = true, type = null, priority = 4, groupID = null, groupSequence = 0, targetConsumerId = null, compressed = false, userID = null, content = null, marshalledProperties = null, dataStructure = null, redeliveryCounter = 0, size = 1036, properties = null, readOnlyProperties = true, readOnlyBody = true, droppable = false, jmsXGroupFirstForConsumer = false, text = "What's the answer to life?"}
replyTo  : null
correlationId    : null
internalId   : null
content  : "What's the answer to life?"

Ad hoc message publishing

In Coder Studio, JMS messages can be sent by right-clicking on an instance in the Coder Navigator view, and choosing Send JMS Message. This prompts a dialog where you can choose a destination and the content you would like to send.

Send JMS Message dialog

Groovy Method as a Service

We can configure the endpoint to use Groovy methods as services as well. Consider the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
class DeepThought {

  void respond(def message) {
    if (message.getReplyTo() == null) {
      "I can't answer without introducing yourself.".info()
      return
    }
    message.replyWith( "42" )
  }
}

Assuming the service DeepThought#respond is configured in the endpoint, we can trigger it by sending a message to the destination topic://toroIntegrate.universe-questions. By invoking the following publisher:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class Hitchhiker {

  final def destination = "topic://universe-questions"

  void ask() {
      def question = "What's the answer to the ultimate question of life, the universe and everything?"
      question.publishTo(destination) { reply ->
          "Uhm..'${reply.text}'?".info()
      }
  }
}

Like the info() method, replyWith() and publishTo() are extension methods for JMS operations. The ask() method publishes a JMS message, and waits for a reply - which DeepThought complies with "42".

Destination prefixes

TORO Integrate uses the configured application property jms.prefix as the prefix (or "toroIntegrate", if none provided) for its JMS destinations. While publishing, the prefix should be omitted - like in this case: topic://universe-questions.