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: Kafka, SNS, SMS, and JMS. These API classes are available in the %External.Messaging package.

Most of the code flow is the same regardless of the platform. This article 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 article, InterSystems provides specialized classes for use in 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.Settings. 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.Client.

    To create the messaging client object, call the CreateClient() method of %External.Messaging.Client, 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.

    CreateClient() returns an instance of the appropriate client class. For example, if the settings variable is an instance of %External.Messaging.KafkaSettings, the returned object is an instance of %External.Messaging.KafkaClient.

    Similarly, if settings is an instance of %External.Messaging.SNSSettings, the returned object is an instance of %External.Messaging.SNSClient.

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 = "quickstart-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.Message.

    For example (Kafka):

     Set msg = ##class(%External.Messaging.Messaging).%New()
     Set msg.topic = "quickstart-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 $$$ISERR(tSC) { //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 %ListOfObjects, which is returned by reference. The method returns a status code, which your code should check before proceeding:

 #Dim messages As %ListOfObjects
 Set tSC = client.ReceiveMessage(topic, .messages)
 If $$$ISERR(tSC) { //handle error scenario }

The %ListOfObjects instance 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()
Feedback