Using the JMS Messaging API

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)

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

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
 }

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

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())