Adapter properties and commands

Edit online

This section lists the properties supported by the adapter and Java Message Service(JMS) headers.

This section lists the properties supported by the adapter.

URL

Specifies the URL or the broker URL that allows to run a configured broker using a single URL for all the configuration (Example of default broker URL: tcp://localhost:61616). This is a mandatory property. It is required at the time of setting the connection.

The corresponding adapter command is-URL.

Login Username

Specifies the username to use for authentication when connecting to the message broker. The corresponding adapter command is -U username (or -USERNAME username).

Login Password

Specifies the password value to use for authentication when connecting to the message broker. The corresponding adapter command is -P password (or -PASSWORD password).

Truststore File

Specifies the path to the truststore in PKCS#12 or JKS format that the adapter uses to validate the broker certificate when SSL/TLS is enabled. The truststore must contain the chain of certificates up to the CA certificate that is used to sign the broker certificate. The corresponding adapter command is -TSL path (or -TRUSTSTORELOCATION path).

Truststore Password

Specifies the password for the adapter to use to access the specified truststore when SSL/TLS is enabled. The corresponding adapter command is -TSP password (or -TRUSTSTOREPASSWORD password).

Truststore Type

Specifies the type of truststore (PKCS#12 or JKS). The corresponding adapter command is -TST type (or -TRUSTSTORETYPE type).

Keystore File

Specifies the path to the keystore in PKCS#12 or JKS format that the adapter uses to retrieve the private key and certificate with the public key. Which is required, if the broker is configured to request clients to provide a certificate for SSL/TLS connections. The corresponding adapter command is -KSL path (or -KEYSTORELOCATION path).

Keystore Password

Specifies the password for the adapter to access the specified keystore when SSL/TLS is enabled. The corresponding adapter command is -KSP password (or –KEYSTOREPASSWORD password).

Key Password

Specifies the password for the adapter to access the private key in the specified keystore when SSL/ TLS is enabled. The password is required, if the private key is secured with a password different from the keystore password. The corresponding adapter command is -KP password (or -KEYPASSWORD password).

Keystore Type

Specifies the type of Keystore (PKCS#12, JKS, or JVM). The corresponding adapter command is -KST type (or -KEYSTORETYPE type).

Read Mode

Specifies whether to keep or delete the messages in ActiveMQ queue after a successful read operation. The corresponding adapter command is -RM keep|delete (or -READMODE keep|delete).

Note: The default is keep, so it is not necessary to specify -READMODE keep.

Queue Name

Specifies the queue name to and from which messages are to be sent and received. This is mandatory parameter. Queue name property can be passed to adapter input or output cards using -Q (or -QUEUE) command.

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. The corresponding adapter command is -CQ (or -CREATEQUEUE).

Validate Queue

Specifies whether to validate queue before reading or sending message. The corresponding adapter command is -V (or -VALIDATE).

Message Type

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 -MT (or -MSGTYPE ) command.

Delay Time

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 -DT (or -DELAYTIME) command.

Logging

Specifies the level of logging to use for the log (trace) file produced by the adapter. The default is Off. The value Information means log informational, the value Errors Only means log error messages only, and the value Verbose means log debug and trace level messages along with the informational and error messages.

The corresponding adapter command is:

-T [E|V] [+] [file_path]

-T -> Log adapter informational messages.

-TE -> Log only adapter errors.

-TV -> Use verbose (debug) logging. The log file records all activity that occurs while the adapter is producing or consuming messages.

+ -> Appends the trace information to the existing log file. Omit this argument to create a new log file.

file_path -> The full path to the adapter trace log. If you omit this keyword, the adapter creates the m4activeMQ.trc log file in the map directory

Append Log

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

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.

Java Message Service(JMS) headers

Enables users to include standard Java Message Service(JMS) headers and user-defined properties in the messages produced to the ActiveMQ broker and retrieve them from messages consumed from the broker.

Messages in link, which include header information, are always represented as JSON documents.

The version of the header is stored in the version JSON element, while the actual payload of the ActiveMQ messages are stored in the payload JSON element. Binary payloads are stored using hex digit pairs or base64 encoding.

The JMS headers are represented by JSON elements with elements that match the JMS headers, except they are in lowercase and use an underscore as a word separator.

The JMS properties are represented by JSON elements that start with an underscore ("_") character.

JSON Template

The following JSON template captures the version element, and all supported JMS headers, two user-defined message properties (title and size), and the payload element. This element can be used as the starting point to create JSON schemas for use in ActiveMQ adapter cards and nodes.

{
    "version": 1,
    "destination": "",
    "reply_to": "",
    "type": "",
    "delivery_mode": 0,
    "priority": 0,
    "message_id": "",
    "timestamp": 0,
    "correlation_id": "",
    "expiration": 0,
    "redelivered": false,
    "_title": "",
    "_size": 0,
    "payload": ""
}
Table 1. JMS header properties and command
Adapter property Command Source Target
Message Header -HDR version ✓ ✓
Message Header Elements -MHE list ✓  
Message Payload Encoding -MPE encoding ✓ ✓
Destination -DES name   ✓
Reply To -RTO name   ✓
Type -TYP type   ✓
Delivery Mode -DM mode   ✓
Priority -PRI priority   ✓
Message Id -MID id   ✓
Timestamp -TMS time   ✓
Correlation Id -CID id   ✓
Expiration -EXP duration   ✓
Redelivered -RED   ✓

Message Header

Specifies the version of the JSON document used to represent ActiveMQ messages. The default value None means that the entire data passed to and from the adapter represents the message payload. No header information is present, and the message is not represented as a JSON header document. The value Version 1 indicates the JSON document version 1 is used. The corresponding adapter command is -HDR version (or -HEADER version).

Message Header Elements

Specifies a comma-separated list of elements to include in the JSON document representation of the consumed messages. Any whitespace characters in the list are NOT ignored and are considered part of the element names. The order of elements in the provided list will match the order of elements in the generated JSON document. Note that the version and payload elements must be explicitly included in the list for the message payload to be included in the JSON document. The corresponding adapter command is -MHE list (or -MESSAGEHEADERELEMENTS list)

Message Payload Encoding

Specifies the encoding of the payload element value in the JSON message representation. The corresponding adapter command is -MPE encoding (or -MESSAGEPAYLOADENCODING encoding).

The supported values are:

Text: The value is a string representation of the message payload. It assumes that the actual message payload is already in text format, encoded in the current system locale character set. The corresponding adapter command value is text.

JSON: The value is in JSON format. This can be an atomic JSON value, a JSON object, or a JSON array. It assumes that the actual message payload is already in JSON format, encoded in the current system locale character set. The corresponding adapter command value is json.

Hex Pairs: The value is a string consisting of consecutive hex-digit pairs, where each pair corresponds to a single byte from the message payload. The corresponding adapter command value is hex_pairs.

Base64: The value is a string that represents base64 encoded message payload's binary content. The corresponding adapter command value is base64.

Destination

Specifies the name of the destination queue to set for the messages produced. It corresponds to the JMSDestination standard JMS header. The value can also be set on a per-message basis using the destination element in the JSON message document. The corresponding adapter command is -DES name (or –DESTINATION name).

Reply To

Specifies the name of the response queue to set for the produced messages. It corresponds to the JMSReplyTo standard JMS header. The value can also be set on a per-message basis using the reply_to element in the JSON message document. The corresponding adapter command is -RTO name (or –REPLYTO name).

Type

Specifies the user-defined message type to set for the produced messages. It corresponds to the JMSType standard JMS header. The value can also be set on a per-message basis using the type element in the JSON message document. The corresponding adapter command is -TYP type (or –TYPE type).

Delivery Mode

Specifies the mode of delivery to set for the produced messages. It corresponds to the JMSDeliveryMode standard JMS header. The value can also be set on a per-message basis using the delivery_mode element in the JSON message document. The following values are supported:

Non Persistent: For instructing the broker that it is not required to store messages in transit to stable storage. The corresponding adapter command value is 1.

Persistent: For instructing the broker to store messages in transit in to stable storage. It is the default value, and the corresponding adapter command value is 2.

The corresponding adapter command is -DM mode (or –DELIVERYMODE mode).

Priority

Specifies the priority value to set for the produced messages. It corresponds to the JMSPriority standard JMS header. The value can also be set on a per-message basis using the priority element in the JSON message document. The corresponding adapter command is -PRI priority (or –PRIORITY priority).

Message Id

This property specifies the message identifier value to set for the messages that are produced. It corresponds to the JMSMessageID standard JMS header. The value can also be set on a per-message basis using the message_id element in the JSON message document. The corresponding adapter command is -MID id (or –MESSAGEID id).

Timestamp

This property specifies the timestamp value to set for the messages that are produced. It corresponds to the JMSTimestamp standard JMS header. The value can also be set on a per-message basis using the timestamp element in the JSON message document. The corresponding adapter command is -TMS time (or –TIMESTAMP time).

Correlation Id

This property specifies the correlation identifier value to set for the messages produced. It corresponds to the JMSCorrelationID standard JMS header. The value can also be set on a per-message basis using the correlation_id element in the JSON message document. The corresponding adapter command is -CID id (or –CORRELATIONID id).

Expiration

This property specifies the message expiration duration in milliseconds to set for the messages produced. It corresponds to the JMSExpiration standard JMS header. The value can also be set on a per-message basis using the expiration element in the JSON message document. The corresponding adapter command is -EXP duration (or –EXPIRATION duration).

Redelivered

Specifies that the message is being resent. It corresponds to the JMSRedelivered standard JMS header. The value can also be set on a per-message basis using the delivery_mode element in the JSON message document. The corresponding adapter command is -RED (or -REDELIVERED).