Skip to main content

Using the Messaging APIs

InterSystems IRIS provides messaging APIs that can be used to communicate directly with a variety of messaging platforms: JMS, Kafka, RabbitMQ, Amazon Simple Notification Service (SNS), and Amazon Simple Queue Service (SQS). These API classes are available in the %External.Messaging package.

Most of the code flow is the same regardless of the platform. This page discusses this common flow and the common classes and methods. Other articles provide details for specific messaging platforms; see the links above.

(In addition to the APIs described in this page, InterSystems provides specialized classes for use in interoperability productions. These classes enable productions to communicate directly with the same messaging platforms; follow the links above for details.)

Connecting to a Messaging Platform

Before you can send or receive messages, your code needs to:

  1. Create a settings object, which contains information about connecting to the platform. This object is an instance of one of the settings classes. InterSystems provides a set of platform-specific settings classes, which are all subclasses of %External.Messaging.SettingsOpens in a new tab. Create an instance of the applicable class and set its properties as needed.

    For example (Kafka):

     Set settings = ##class(%External.Messaging.KafkaSettings).%New()
     Set settings.username = "amandasmith"
     Set settings.password = "234sdsge"
     Set settings.servers = "100.0.70.179:9092, 100.0.70.089:7070"
     Set settings.clientId = "BazcoApp"
     // If Consumer, specify a consumer group
     Set settings.groupId = "G1"
    
  2. Create the messaging client object, which is also specific to the platform. This object is an instance of one of the client classes, which are all subclasses of %External.Messaging.ClientOpens in a new tab.

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

     Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC)
     // if tSC is an error, handle error scenario 

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

    CreateClient() returns an instance of the appropriate client class. For example, if the settings variable is an instance of %External.Messaging.KafkaSettingsOpens in a new tab, the returned object is an instance of %External.Messaging.KafkaClientOpens in a new tab.

    Similarly, if settings is an instance of %External.Messaging.SNSSettingsOpens in a new tab, the returned object is an instance of %External.Messaging.SNSClientOpens in a new tab.

Creating Topics/Queues

Before you can send messages, you may need a topic or queue depending on which is relevant to your specific messaging platform.

Platform-specific settings for a topic/queue are passed into the common method as a string, but these settings are defined using an object, so the object’s ToJSON() method must be called when passing in the settings. The following code creates a new Kafka topic using the common method:

 Set topic = "quick-start-events"
 Set queueSettings = ##class(%External.Messaging.KafkaTopicSettings).%New()
 Set queueSettings.numberOfPartitions = 1, queueSettings.replicationFactor = 1
 Set tSC = client.CreateQueueOrTopic(topic, queueSettings.ToJSON())

Be aware that some messaging platforms have their own method for creating a topic/queue that may include advanced capabilities.

Sending Messages

Once you have a messaging client object and any relevant topic/queue object, call the methods of the client object to send messages, as follows:

  1. Create a message object, which is an instance of a message class. InterSystems provides a set of platform-specific message classes, which are all subclasses of %External.Messaging.MessageOpens in a new tab.

    For example (Kafka):

     Set msg = ##class(%External.Messaging.Messaging).%New()
     Set msg.topic = "quick-start-events"
     Set msg.value = "body of the message"
     Set msg.key = "somekey"
  2. Call the SendMessage() method of the client object, passing the message object as the argument. For example:

     Set tSC = client.SendMessage(msg)
     // if tSC is an error, handle error scenario 

    The method returns a status code, which your code should check before proceeding.

  3. When your application no longer needs a topic/queue, your code can safely delete it using the DeleteTopicOrQueue() method of the client object.

     Do client.DeleteQueueOrTopic(topic)
    

    Be aware that some messaging platforms have their own method for deleting a topic/queue that may include advanced capabilities.

Receiving Messages

For messaging platforms that can receive messages, use the ReceiveMessage() method of the client object to receive messages. The first argument for this method is the name of the topic/queue. The second argument is an instance of %ListOfObjectsOpens in a new tab. The method returns messages by reference using this second argument.

ReceiveMessage() also accepts a JSON-formatted string of settings as an optional third argument. Available settings vary by platform, and are defined as properties of the ReceiveSettings class for each platform. To define these settings, create a new instance of the ReceiveSettings class and set properties as desired. Then, use the ToJSON() method inherited by the ReceiveSettings object to provide these settings to the ReceiveMessage() method.

The ReceiveMessage() method returns a status code, which your program should check before it continues.

In the following example, a JMS client (client) receives messages from a JMS queue (queue), with the timeout for message retrieval set to 200 milliseconds:

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

 #dim messages As %ListOfObjects
 Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
 // if tSC is an error, handle error scenario

The %ListOfObjectsOpens in a new tab instance messages contains the messages obtained from the topic/queue.

Deleting Topics/Queues

When your application no longer needs a topic/queue, your code can safely delete it using the DeleteTopicOrQueue() method of the client object.

 Do client.DeleteQueueOrTopic(topic)

Be aware that some messaging platforms have their own method for deleting a topic/queue that may include advanced capabilities.

Disconnecting from a Messaging Platform

When your code is done communicating with the messaging platform, call the Close() method of the client object. For example:

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