Skip to main content

Using the JMS Messaging API

InterSystems provides an API you can use to produce and consume messages using a Java Messaging Service (JMS). Your code acts as a producer or consumer by creating a client, then calling the client’s methods to perform actions like sending and receiving messages. InterSystems IRIS also provides methods to create and delete JMS queues and topics.

The JMS API is based on the common messaging classes that are shared by other messaging platforms. This page describes platform-specific variations in the work flow which these common classes establish.

In addition to the API described here, InterSystems provides specialized classes that you can use to send messages to a JMS and retrieve messages from a JMS as part of an interoperability production.

Connecting to JMS

To create a connection to a JMS application:

  1. Create a settings object. To do this, create an instance of %External.Messaging.JMSSettingsOpens in a new tab and set its properties as needed:

     Set settings = ##class(%External.Messaging.JMSSettings).%New()
     Set settings.url = "messaging.bazco.com"
     Set settings.connectionFactoryName = "connectionFactory"
     Set settings.initialContextFactoryName = "eventContextFactory"
     Set settings.username = "briannawaller"
     Set settings.password = "824yvpi"
    

    For a full list of the properties available, see the JMSSettings class reference page.

  2. Create the messaging client object. To do this, call the CreateClient() method of the generic %External.Messaging.ClientOpens in a new tab class, passing the settings object as the first argument. For example:

     Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC)
     If $$$ISERR(tSC) {
           //handle error scenario
     }

    The method returns a status code by reference as the second argument. Your code should check the status before proceeding.

    Because the settings object is an instance of %External.Messaging.JMSSettingsOpens in a new tab, the returned object (client) is an instance of %External.Messaging.JMSClientOpens in a new tab.

JMS Producers

InterSystems IRIS can act as a producer within a JMS application by calling API methods to create messages and then send them. If you need to create the queues or topics which will route your messages, see Working with Queues and Topics. The following flow uses the client object to interact with a JMS application as a producer:

Set Message Properties (Optional)

The JMS specification allows you to attach a variety of metadata to a message, using both specified message headers and custom message properties. To create and set properties for a JMS message, you must create a %ListOfObjectsOpens in a new tab collection of JMS message property objects. A JMS message object (described in the next section) accepts this list as an optional property. For each message property you want to define:

  1. Create a new instance of the %External.Messaging.JMSMessagePropertyOpens in a new tab object.

  2. Set the properties of the message property object:

    • key, the message property key

    • type, the data type of the message property value

    • value, a string representation of the message property value

  3. Add the message property object to your list of message property objects.

Refer to the JMS documentationOpens in a new tab for more information about message properties. The following example prepares a custom time stamp property:

 Set propList = ##class(%ListOfObjects).%New()

 Set key = "odbcUtcTimestamp"
 Set type = "String"
 Set value = $zdatetime($horolog, 3, 8)

 Set msgProp1 = ##class(%External.Messaging.JMSMessageProperty).%New()
 Set msgProp1.key = key
 Set msgProp1.type = type
 Set msg.value = value

 Set tSC = propList.Insert(msgProp1)
Create Message

To prepare a message to be sent, create a new instance of the %External.Messaging.JMSMessageOpens in a new tab object. Then, define properties for that message object. You must specify the name of the destination and the type ("Text" or "Bytes") of the message. Depending on the message type, use the textBody property or the bytesBody property to set the message body. If you have created a list of message property objects as described in the previous section, provide that list as the properties property.

 Set destination = "quick-start-events-queue"
 Set type = "Text"
 Set textBody = "MyMessage"

 Set msg = ##class(%External.Messaging.JMSMessage).%New()
 Set msg.destination = destination
 Set msg.type = type
 Set msg.textBody = textBody
 Set msg.properties = propList
Send Message

After creating a message, you can send it to the destination queue or topic by executing the SendMessage() method for the JMS client object. For example:

 set tSC = client.SendMessage(msg)
 if $$$ISERR(tSC) { 
       //handle error scenario
 }

JMS Consumers

InterSystems IRIS can act as an a consumer within a JMS application by calling an API method to retrieve messages for a topic. The following flow uses the client to interact with a JMS application as a consumer:

Configure Settings for Message Retrieval (Optional)

The JMS client object can use the ReceiveMessage() method to act as a consumer of JMS messages. This method allows you to specify settings for the message retrieval operation by providing a JSON-formatted string as an optional argument. To do so, create a new instance of the %External.Messaging.JMSReceiveSettingsOpens in a new tab class and set properties as desired. The following properties are available:

  • receiveTimeout, an integer specifying the duration of time (in milliseconds) before the retrieval operation times out. If not set, the default value is 100.

  • subscriber (optional), a string containing a subscriber name to identify the client

For example:

 Set rset = ##class(%External.Messaging.JMSReceiveSettings).%New()
 Set rset.receiveTimeout = 200
Retrieve Messages

To retrieve messages, invoke the ReceiveMessage() method inherited by the JMS client object. This method takes the name of a queue or a topic as an argument and returns messages as a %ListOfObjectsOpens in a new tab by reference. If you have specified message retrieval settings as described in the preceding section, provide these settings as a third argument using the ToJSON() method for the settings object.

 #dim messages As %ListOfObjects
 Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())

Working with Queues and Topics

InterSystems IRIS provides an API to manage destinations for JMS messages. For point-to-point messaging, you can create or delete a queue. For publisher-to-subscriber messaging, you can create or delete a topic.

Create or Delete an Queue

Create an Queue

A JMS client object includes a CreateQueue() method for creating a queue. CreateQueue() accepts the queue name as an argument:

 Set queueName = "quick-start-events"

 Set tSC = client.CreateQueue(queueName)

As an alterative, you can create the queue with a method that is common to all messaging platforms. See %External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab for details.

Delete an Queue

You can delete a JMS queue with a method that is common to client objects for all messaging platforms supported by the API. See %External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab for details.

 Set tSC = client.DeleteQueueOrTopic(queueName)

Create or Delete a Topic

Create a Topic

A JMS client object includes a CreateTopic() method for creating a topic. CreateTopic() accepts the topic name as an argument:

 Set topicName = "alerts_urgent"

 Set tSC = client.CreateTopic(topicName)

As an alterative, you can create the topic with a method that is common to all messaging platforms. See %External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab for details.

Delete a Topic

You can delete a JMS topic with a method that is common to client objects for all messaging platforms supported by the API. See %External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab for details.

 Set tSC = client.DeleteQueueOrTopic(topicName)

Close Client

An InterSystems IRIS application that is done communicating with a JMS application should close the client with the Close() method for the client object. For example:

 Do:client'="" client.Close()
FeedbackOpens in a new tab