Apache ActiveMQ Adapter

With the ActiveMQ Adapter, users can access any of the queues of the Active MQ Adapter to send and receive messages. Users can also create a new queue altogether for sending and receiving messages.

This document provides an overview of the Apache ActiveMQ message-broker service and the Apache ActiveMQ adapter.

Apache ActiveMQ picks up messages from a message queue—breaks-up a message in a way that the message does not give away much information of the sender-application to the application that picks up the message. After breaking up, it places the message to the queue to be picked up by any application. The Apache ActiveMQ can then collect the response from the recipient-application, break down the response in a way that reveals the least information about the recipient-application—and, then place the transformed response to the message queue. In doing so, it effectively implements decoupling of the two communicating applications by minimizing the mutual awareness that these two applications should have of one another to be able to exchange messages. A message is deleted from the queue upon viewing. Apache ActiveMQ is an open source message broker and an asynchronous messaging system, written in Java with Java Message Service (JMS) client.

The ActiveMQ adapter establishes a connection to the ActiveMQ server from an application, through which users of the application can access any of the queues of the ActiveMQ server to send and receive messages. With this adapter, users can send the following three types of messages to a queue: Text, Byte, and Blob. Messages are received one at a time in the order of their insertion.

Adapter properties and commands

This section provides the details of the adapter properties to be set to define connections and actions, and import schemas. The following table lists their properties, scope, whether they are required or not, and the adapter commands they map to for use in the compiled maps and map executions. DI scope means the property is dynamically enumerated - the adapter is invoked during action configuration to provide the set of allowed values for that property. A detailed description of the properties is provided after the table.

Table 1. Apache ActiveMQ Adapter properties and commands
Adapter property	Scope CO: Connection DI: Discovery IC: Input card OC: Output card G: GET function P: Put function	Required	Corresponding adapter command must be used directly in GET and PUT functions
URL= URL	CO	Yes	-URL, the URL to connect to the queue.
createQueue= create_queue	OC/P	No	-CQ, Boolean flag to decide if the queue needs to be created.
queueName= queue_name	DI/IC/OC/G/P	Yes	-Q, queue name to send and receive messages.
msgType= message_type	OC/P	No	-MT The type of message being sent (Supported types are: Text/ Byte/ Blob).
delayTime= delay_time	IC/G	No	-DT Receives the next message that arrives within the specified delay-time duration.
logging=info\|errors\|verbose\|off	IC/OC/G/P	No	-T[E\|V]?[+]? `[file_name]`
append_log=true\|false	IC/OC/G/P	No	-T[E\|V]?[+]? [`file_name`]
log_file_name=file_name	IC/OC/G/P	No	-T[E\|V]?[+]? [`file_name`]

URL= URL

URL or the Broker URI allows to run a configured broker using a single URI for all the configuration (example of default broker URL: tcp://localhost:61616). This required parameter is needed at the time of setting the connection. This is mandatory parameter. The URL can be used with -URL command.

createQueue= create_queue

This is a boolean flag. It is used at the time of sending a message to the ActiveMQ. If this flag is set to true and the particular queue is not present, it will create the queue. If this flag is set to false and the queue is not present, user will get invalid queue name exception. If the value is not mentioned for this flag, then by default the value is false. Create queue parameter can be passed to the adapter using -CREATEQUEUE or -CQ command.

queueName= queue_name

This required property states the queue name to and from which messages are to be sent and received. Queue name property can be passed to adapter input or output cards using -QUEUE or -Q command.

msgType= message_type

This property specifies the type of message being sent to the ActiveMQ adapter. The currently supported message types are: Text, Blob, Byte. Examples of Blob file are a large image file, and a PDF file among others. An 'invalid message type' exception will occur, if a user tries to set a message type other than the supported ones. Though this is an optional parameter, it is recommended to set a message type at the time of creating an output card. Message type property can be passed to adapter output cards using -MSGTYPE or -MT command.

delayTime= delay_time

This property specifies the time duration after the lapse of which, the adapter will look out for the next message. A timeout of zero never expires, and the call blocks indefinitely. The timeout value is specified in milliseconds. This property is optional but recommended to set when receiving message from ActiveMQ (used in input card) with a minimum value (1) to avoid getting stuck in case no message is present in the queue. The Delay-time property can be passed to adapter input using -DELAYTIME or -DT command.

logging=info|errors|verbose|off

This property specifies the level of logging to be used for the log (trace) file produced by the adapter. The default is off. The value info means log informational and error messages, the value error means log error messages only, and the value verbose means log debug and trace level messages along with the informational and error messages.

append_log=true|false

This property specifies the flag that indicates the action to be taken when the specified log file already exists. When set to true, the log messages are appended to the file. When set to false: the file is truncated, and the messages are written to the empty file. The default value is true.

log_file_name=file_name

This is the name of the log file, where the log messages are written. If not specified, the default log file name m4activeMQ.trc is used, and the file is stored to the directory in which the executed compiled map resides.

Examples_{Examples of GET map function}

In the following example, assume that the adapter being used in a GET function is defined as follows:

This will pick the first message in the queue and transform according to the adapter mentioned in the output card.

GET("ACTIVEMQ", "-URL tcp://localhost:61616 -Q TEST_QUEUE -DT 5 -TV C:\temp\m4activemq.log")

Now, assume the GET map function was defined as follows (the specified queue name is not present):

GET("ACTIVEMQ", -URL tcp://localhost:61616 -Q MISSING_QUEUE -DT 5 -TV C:\temp\m4activemq.log)

In this case, the adapter throws error: Queue MISSING_QUEUE doesn't exist, as it cannot find the queue name specified.

_{Examples of PUT map function}

In the following example, assume that the adapter being used in a PUT function is defined as follows:

If the queue is not present, it will create the queue and put the message; if the queue is present, it will simply put the message into the queue TEST_QUEUE. Here, the message type is byte.

PUT("ACTIVEMQ", "-URL tcp://localhost:61616 -Q TEST_QUEUE -CQ -MT byte -TV C:\temp\m4activemq.log", in_data_type)

Now, assume that the message type is not mentioned.PUT("ACTIVEMQ", "-URL tcp://localhost:61616 -Q TEST_QUEUE -CQ -TV C:\temp\m4activemq.log", in_data_type)

In this case, it will throw the following error: Message type must be blob/byte/Text.

Now, assume that the adapter is used in a PUT function, but the queue name mentioned is not present.

PUT("ACTIVEMQ", "-URL tcp://localhost:61616 -Q TEST_QUEUE -MT byte -TV C:\temp\m4activemq.log", in_data_type)). It will throw the following error message: Queue TEST_QUEUE does not exist. By default, the create queue flag is false. It needs to be set to true explicitly, if the queue is not present and the user wants to create the queue.