RabbitMQ-Ensemble-adapter

Ensemble adapter for RabbitMQ

Installation

1. Install java 1.8.

2. Get the JAR: build RabbitMQ-Ensemble-javaapi or download latest jar.

3. Create (or use any existing one) Java gateway. To create one go to SMP > System Administration > Configuration > Connectivity > Object Gateways. Remember the Port value.

4. Start Java Gateway.

5. In a terminal in a target namespace execute:

   Set class = "isc.rabbitmq.API"
   Set classPath = ##class(%ListOfDataTypes).%New()
   Do classPath.Insert(PATH-TO-JAR)
   Set gateway = ##class(%Net.Remote.Gateway).%New() 
   Set sc = gateway.%Connect("localhost", PORT, $Namespace, 2, classPath)
   Set sc = gateway.%Import(class)
   Write ##class(%Dictionary.CompiledClass).%ExistsId(class)
   

6. In the namespace isc.rabbitmq.API class should be present and compiled.

7. Import this project and compile.

8. For samples refer to the test production isc.rabbitMQ.Production.

Development

Development is done on Cache-Tort-Git UDL fork

Interoperability adapter

isc.rabbitmq package provides all traditional Interoperability components: Inbound and Outbound Adapters and Operation/Service.

For RabbitMQ to function Java Gateway is required. It can be run in three different ways:

• As Interoperability Service
• As Object Gateway from SMP
• From OS bash

For Interoperability production we recommend running Java Gateway as Interoperability Service. To do that add new EnsLib.JavaGateway.Service service to your production. In RabbitMQ production elements select Java Gateway Service name as a value for JGService setting.

ClassPath for all these elements must contain the paths to amqp jar and RabbitMQ-Ensemble-javaapi jar.

Usage

Check isc.rabbitmq.Utils for sample code. The main class is isc.rabbitmq.API. It has the following methods.

Methods

Arguments

Initialization

Java Gateway

First you need a Java Gateway object (hereinafter: gateway). For example you can get it using this method:

/// Get JGW object
ClassMethod Connect(gatewayName As %String, path As %String, Output sc As %Status) As %Net.Remote.Gateway
{
	Set gateway = ""
	Set sc = ##class(%Net.Remote.Service).OpenGateway(gatewayName, .gatewayConfig)
	Quit:$$$ISERR(sc) gateway
	Set sc = ##class(%Net.Remote.Service).ConnectGateway(gatewayConfig, .gateway, path, $$$YES)
	Quit gateway
}

Where:

• gatewayName - is name of Java Gateway (it would be started automatically)
• path - path to JAR

RabbitMQ

Now that Java Gateway connection is established we can connect to RabbitMQ:

ClassMethod GetAPI(gateway As %Net.Remote.Gateway) As isc.rabbitmq.API
{
	Set host = "localhost"
	Set port = -1
	Set user = "guest"
	Set pass = "guest"
	Set virtualHost = "/"
	Set queue = "Test"
	Set durable = $$$YES
Set api = ##class(isc.rabbitmq.API).%New(gateway, host, port, user, pass, virtualHost, queue, durable)
Quit api

}

All parameters are described in the table above. Note that durable argument is used only if you’re creating a new queue. If the queue alreay exists you should still provide it (0 or 1) but it won’t be used.

Sending messages

Assuming you already have api object, sending messages can be done by one of two ways:

• sending messages to default queue
• sending messages to specified queue

Sending messages to default queue

Default queue is a queue specified during creation of the api object. To send a message just call sendMessage or sendMessageId:

#Dim api As isc.rabbitmq.API
#Dim msg As %GlobalBinaryStream
Do api.sendMessage(msg)
Do api.sendMessageId(msg, "correlationId", "messageId " _ $zdt($zts,3,1,3))

Where stream is a message body. You can either provide both messageId and correlationId or non of them.

Sending messages to specified queue

Everything is the same as above, except you call sendMessageToQueue \ sendMessageToQueueId method and the first argument is the name of the queue.

Reading messages

Messages are always read from the default queue (specified at creation of the api object). Message body can be received as text or as a stream.

Reading message as a stream

First you need to prepare props to pass by reference into Java and then call readMessageStream:

#Dim api As isc.rabbitmq.API
#Dim msg As %GlobalBinaryStream
#Dim props As %ListOfDataTypes
Set props = ##class(%ListOfDataTypes).%New()
For i=1:1:15 Do props.Insert("")
Set msg = api.readMessageStream(.props)

props would be filled with message metainformation, and msg is a stream containig message body.

Reading message as a string

#Dim api As isc.rabbitmq.API
#Dim props As %ListOfDataTypes
Set props = api.readMessageString()

props would be filled with message metainformation and message body, note that you don’t need to initialize it on the InterSystems side before calling RabbitMQ.

Props

Elements appearing in props. All of them besides first and second are optional. Conversion from list into RabbitMQ.Message is available in the ListToMessage method of RabbitMQ.InboundAdapter class.