ActiveMQ Connector Guide

The ActiveMQ connector provides a quick and simple way to achieve seamless integration between your ActiveMQ message broker and other applications and endpoints in your ecosystem.

For example, an organization uses ActiveMQ to deliver messages to different applications. Now, the organization is adding a service to enable customers to create an account from their mobile app. For this purpose, a REST API "open account" request is sent from the mobile device to the organization URL.

The OpenLegacy service, based on the ActiveMQ connector, serializes the "open account" data from the request into an ActiveMQ message format and publishes the message to an ActiveMQ queue so that other applications in the organization ecosystem can fulfill the request.

In this guide you will learn how to implement scenarios, similar to the scenario above, using the OpenLegacy ActiveMQ solution.

The guide outline

To configure the OpenLegacy solution to work with your ActiveMQ implementation, perform the following steps:

Use the CLI to generate an asset containing a model of the ActiveMQ message input parameters; see Steps 1 - 4 below.
Upload the asset to an OpenLegacy Hub project; see Step 5 below.
Generate a microservice on top of the uploaded asset in the OL Hub and deploy it in your destination platform; see Step 6 below.

Prerequisites

Download and install OpenLegacy CLI.
Sign in to the OpenLegacy Hub and obtain your login credentials.
After you are logged in to OL Hub, generate an API key to be able to log in to the hub from the CLI.
Prepare an XSD file describing the field metadata of the messages to be published in your ActiveMQ queue.

Create ActiveMQ module and assets

To create an ActiveMQ asset, perform the following steps in the OpenLegacy CLI:

Create an ActiveMQ module using the ActiveMQ connector.
Test the connection to your ActiveMQ message broker implementation.
Create an ActiveMQ asset.
Test the created asset by sending a test message to the ActiveMQ topic.

Step 1. Create an ActiveMQ module

First, open the CLI and create the ActiveMQ module. For example:

> ol create module activemq-module --connector activemq

$ ol create module activemq-module --connector activemq

Step 2. Test the connection to the ActiveMQ message broker

Run the ol test connection command to verify that your ActiveMQ message broker implementation is accessible and that the connection properties at your disposal are correct. The command sends a connection request to the broker and returns a success message when the broker is accessible and an error message when it's not.

Navigate to the module folder you just created. For example:
```
[module-name]> cd activemq-module
```
```
[module-name]$ cd activemq-module
```
From under the module directory, display the help menu of the ol test connection command to review the ActiveMQ connector connection properties. Refer to Options for the description of each option.
```
> ol test connection --help
```
```
$ ol test connection --help
```

For a full definition of each option, see ol test connection options.

Run ol test connection with the selected connection properties. For example:

> ol test connection --user admin --password admin --input-queue target.queue

$ ol test connection --user admin --password admin --input-queue target.queue

❗️
You can save your connection properties in a connection profile and reuse them in different command invocations by using the --profile option.

Step 3. Add an asset to the ActiveMQ module

After verifying the connection parameters, you can create an ActiveMQ asset by executing the ol add command. To create the asset, provide to the ol add command an XSD file containing a description of the ActiveMQ message fields metadata. The connector parses the XSD file and produces an asset file containing the input and output metadata model of the asset.

Review the ol add command options:

[module-name]> ol add --help

[module-name]$ ol add --help

For a full definition of each option, see ol add options.

Provide to the ol add command a file path to the XSD file. For example:

> ol add --file-path open_acc.xsd --operation-name open_account

$ ol add --file-path open_acc.xsd --operation-name open_account

Step 4. Test the ActiveMQ asset

After adding the ActiveMQ asset, you can test the asset by executing the ol test asset command to verify that you can push messages to the ActiveMQ queue and get the expected response.

For example, in the scenario where the open_account asset is tested, you want to verify that the request to open a specified account was published successfully to ActiveMQ.

From your module folder root go to assets/open_account/test_data/case1/:

> cd assets/open_account/test_data/case1/

$ cd assets/open_account/test_data/case1/

Open in.json:

case-1> notepad in.json

case-1$ notepad in.json

in.json contains the asset input fields required for performing the test.

For example in the scenario where the open_account asset is tested, in.json contains the asset input fields required for creating an account.

{
 "account":{
  "name":"",
  "type":"",
  "currency":"",
  "number":"",
  "bank":"",
  "customerId":"",
  "balance":""
 }
}

Fill in the values of the input fields in in.json.

In the open_account asset example, fill the details on the new account.

{
 "account":{
  "name":"John and Jannet Smith",
  "type":"CHK",
  "currency":"USD",
  "number":"0023564487",
  "bank":"12",
  "custome
      rId":"48857",
  "balance":"1564"
 }
}

Now you are ready to run ol test asset:

> ol test asset open_account

$ ol test asset open_account

The response from the test is displayed:

Test asset for test case-1 succeeded. response:

{
 "account": {
  "name": "John and Jannet Smith",
  "type": "CHK",
  "currency": "USD",
  "number": "0023564487",
  "bank": "12",
  "customerId": "48857",
  "balance": "1564"
 }
}

Search the relevant queue in ActiveMQ and confirm that the message you sent as part of the test appears in the message list.

Step 5. Push the module to the OL Hub

Now that you are sure that the connecting properties are accurate and that a message can be published in an ActiveMQ queue, you can push the finalized module to the hub.

❗️
Make sure you are logged in to the OL Hub before executing the ol push module command.

Run the ol push module command from the module folder root:
```
[module-name]> ol push module
```
```
[module-name]$ ol push module
```
The CLI displays the command success status:

Module activemq-module pushed successfully to the HUB

Step 6. Continue in OL Hub

Your ActiveMQ module is now on the OL Hub and can be included in projects.

Next generate a microservice on top of your uploaded asset in the OL Hub.

Connector Options

ol add options

--file-path

The location of the asset XSD source file. The XSD code is parsed by the connector to create the metadata model used for modeling the ActiveMQ input queue message.

--file-path ./open_acc.xsd

--out-file-path

The location of the asset XSD source file. The XSD code is parsed by the connector to create the metadata model used for modeling the ActiveMQ output queue message.

--out-file-path ./open_acc.out.xsd

--operation-name

The name of the created asset. If not provided, the name of the XSD source file will be used as the asset name.

--operation-name open_account

--file-type

The asset source file type. Currently, only the XSD type is supported.

--file-type xsd

--raw

Include the --raw flag to add the raw-data-transformer asset to the ActiveMQ module. The asset contains a single field called `content` used for storing the entire message contents in a byte array format. The single-field asset is used when the input message does not require pre-processing and can be passed in its original content and format to the ActiveMQ queue.

ol test connection options

❗️
The ol test connection options can also be used with the ol add command.

--input-queue

The ActiveMQ input queue name

--input-queue target.queue

--output-queue

The ActiveMQ output queue name

--output-queue origin.queue

--output-queue-strategy

The mode by which output messages are selected by the client:

CORRELATION_ID: The client selects an output message with the same ID as the input message (default).
BROWSE: The client searches for messages containing specified text at a specified location in the message. The text and location can be specified by an ol set property command.
NEW_SESSION
BASE64: The CORRELATION_ID value is encoded in BASE64

--output-queue-strategy base64

--connector-type

The ActiveMQ asset can support the following work mode configurations:

PRODUCE: When the client publishes messages to the input queue.
CONSUME: When the client subscribes to messages from the output queue.
PRODUCE_CONSUME: When the client publishes messages to the input queue and subscribes to response messages from the output queue (default).

--connector-type produce

--output-header-length

The number of bytes at the beginning of a message dedicated to the message header. The parser does not read the data stores in those bytes.

--output-header-length 200

--hostname

The hostname or IP of the remote ActiveMQ message broker (default: localhost)

--hostname https://192.86.32.238

--port

The ActiveMQ message broker port number (default: 61616)

--port 65895

--user

The host user login credential

--user demo-user

--password

The host user password credential

--password P@ssw0rd

--code-page (required)

The host code page (default: UTF-8)

--code-page 037

--timeout

The maximum time in milliseconds to wait for connection to the ActiveMQ message broker before aborting (default: 30000).

--timeout 40000

--expiry

The expiration period for a message in the queue in milliseconds (default: -1)

--expiry 100000

--thread-pool-size

The thread pool size (default: 1)

--thread-pool-size 5

--connection-creation-timeout

After a message is published to the input queue, the maximum time in milliseconds to wait for a response in the output queue before aborting (default: 5000).

--connection-creation-timeout 50000

--pool.max-size

The maximum number of threads allowed in the thread pool (default: 10)

--pool.max-size 20

--delivery-mode

Specify messages delivery mode [NON_PERSISTENT, PERSISTENT] (default: NON_PERSISTENT)

--delivery-mode non_persistent

--jms-messages-mode

The JMS queue message format [TEXT_MESSAGE, BYTES_MESSAGE, OBJECT_MESSAGE, STREAM_MESSAGE, MAP_MESSAGE] (default: TEXT_MESSAGE)

--jms-messages-mode bytes_message

--ssl.enabled

Enabled-true when the connection is SSL (default: false)

--ssl.enabled true

--ssl.key-store

The key store path/file name

--ssl.key-store [path/file_name]

--ssl.key-store-password

The key store password

--ssl.key-store-password P@ssw0rd

--ssl.trust-store

The trust store path/file name

--ssl.trust-store [path/file_name]

--ssl.trust-store-password

The trust store password

--ssl.trust-store-password P@ssw0rd

--ssl.ssl-protocol

The SSL protocol (default: TLS)

--ssl.ssl-protocol ssl

--profile

The selected connection property set to be added to the ol add or ol test connection commands (see: Connection Profiles).

--profile dev

ActiveMQ Connector Guide

The guide outline

Prerequisites

Create ActiveMQ module and assets

Step 1. Create an ActiveMQ module

Step 2. Test the connection to the ActiveMQ message broker

❗️
You can save your connection properties in a connection profile and reuse them in different command invocations by using the --profile option.

Step 3. Add an asset to the ActiveMQ module

Step 4. Test the ActiveMQ asset

Step 5. Push the module to the OL Hub

❗️
Make sure you are logged in to the OL Hub before executing the ol push module command.

Step 6. Continue in OL Hub

Connector Options

ol add options

ol test connection options

❗️
The ol test connection options can also be used with the ol add command.

The guide outline

Prerequisites

Create ActiveMQ module and assets

Step 1. Create an ActiveMQ module

Step 2. Test the connection to the ActiveMQ message broker

❗️You can save your connection properties in a connection profile and reuse them in different command invocations by using the --profile option.

Step 3. Add an asset to the ActiveMQ module

Step 4. Test the ActiveMQ asset

Step 5. Push the module to the OL Hub

❗️Make sure you are logged in to the OL Hub before executing the ol push module command.

Step 6. Continue in OL Hub

Connector Options

ol add options

ol test connection options

❗️The ol test connection options can also be used with the ol add command.

❗️
You can save your connection properties in a connection profile and reuse them in different command invocations by using the --profile option.

❗️
Make sure you are logged in to the OL Hub before executing the ol push module command.

❗️
The ol test connection options can also be used with the ol add command.