ActiveMQ

ActiveMQ is a high performance Apache 2.0 licensed Message Broker and JMS 1.1 implementation.

It provides a high performance and scalable implementation of an effective and popular message queue that lets you decouple your front end applications (and the Cloud CMS UI Server) from back end API notifications.

You can use ActiveMQ to transmit any volume of data, at any level of throughput, without losing messages or requiring other services to be always available.

Cloud CMS Application Server

The Cloud CMS Application Server is a middle-tier cluster that sits between your mobile/web application and the Cloud CMS API. It provides a wide range of request-time services for your front-end application for fast performance, object caching and more.

It features integration with ActiveMQ as a means of listening to events that occur within the Cloud CMS API. When content is created, updated or deleted within the Cloud API, notifications are received and placed onto an ActiveMQ queue.

The Cloud CMS Application Server cluster hears these messages and responds by invalidating cache and doing the necessary bookkeeping to keep the middle-tier consistent with changes from your editorial team.

How it works

You will need to run ActiveMQ on your own (either as a standalone service or a standalone container). ActiveMQ needs to be accessible to the API and the UI via a host and port.

  1. When the editorial team makes changes to content inside of Cloud CMS, the Cloud CMS API pushes notifications to an ActiveMQ Topic.
  2. The ActiveMQ Topic must be configured to send those notifications to an ActiveMQ message queue.
  3. The Cloud CMS Application Server listens for messages on the ActiveMQ message queue using the STOMP protocol.
  4. When messages are received, the Cloud CMS Application server automatically invalidates cache state for your client facing applications.

The STOMP Protocol

The Cloud CMS Application Server provides support for the http://stomp.github.io/ (Streaming Text Oriented Messaging Protocol) protocol.

As such, the Cloud CMS Application Server is compatible with a variety of message queues, including ActiveMQ and RabbitMQ. For an informed list, see https://stomp.github.io/implementations.html.

The Cloud CMS Application Server uses its support for the STOMP protocol to connect to an ActiveMQ message queue. This requires that you run a standalone or separate ActiveMQ installation.

Configure ActiveMQ

Within Apache ActiveMQ, you must define a Topic and a Message Queue. The Cloud CMS API posts notifications to the topic. You must configure the topic to push these notifications into the queue.

Define an ActiveMQ Queue

Adjust your activemq.xml file to define a new queue. You can give it any name you like. Here's an example where we define a queue named myQueue:

<destinations>
    <queue physicalName="myQueue" />
</destinations>

Define an ActiveMQ Topic

Adjust your activemq.xml file to define a new topic. There are many ways to do this. Here's one such way where we define a new topic named myTopic and connect it to the queue we defined before.

Any notifications that are received will be routed to the myQueue queue.

<destinationInterceptors>
    <virtualDestinationInterceptor>
        <virtualDestinations>
            <compositeTopic name="myTopic">
                <forwardTo>
                    <queue physicalName="myQueue" />
                </forwardTo>
            </compositeTopic>
        </virtualDestinations>
    </virtualDestinationInterceptor>
</destinationInterceptors>

Configure the Cloud CMS API

To configure the Cloud CMS API to use the activemq notification provider, you can adjust your docker.properties file to have something like this:

gitana.default.application.deployer.uiserver.notifications.enabled=true
gitana.default.application.deployer.uiserver.notifications.providerType=activemq
gitana.default.application.deployer.uiserver.notifications.topic=myTopic
gitana.default.application.deployer.uiserver.notifications.configuration.username=
gitana.default.application.deployer.uiserver.notifications.configuration.password=
gitana.default.application.deployer.uiserver.notifications.configuration.host=activemq.myserver.com
gitana.default.application.deployer.uiserver.notifications.configuration.port=61616

Where the host is assumed to be activemq.myserver.com and the port 61616. Change these as you require. Note that this sends notifications to the myTopic topic.

Configure the Cloud CMS Application Server

To configure the Cloud CMS Application Server, you can add the following to your environment upon startup:

CLOUDCMS_NOTIFICATIONS_ENABLED=true
CLOUDCMS_NOTIFICATIONS_STOMP_HOST=activemq.myserver.com
CLOUDCMS_NOTIFICATIONS_STOMP_PORT=61613
CLOUDCMS_NOTIFICATIONS_STOMP_USERNAME=
CLOUDCMS_NOTIFICATIONS_STOMP_PASSWORD=
CLOUDCMS_NOTIFICATIONS_STOMP_QUEUE_URL=/queue/myQueue

Where the host is assumed to be activemq.myserver.com and the STOMP port is 61613. Change these as you require. Note that this read messages off the queue named /queue/myQueue.

Alternatively, you can specify this via the server configuration, like this:

"notifications": {
    "enabled": true,
    "type": "activemq",
    "configuration": {
        "host": "<host>",
        "port": "<port>",
        "username": "<username>",
        "password": "<password>",
        "queueUrl": "<queue url>"
    }
}

And then restart your Node app. When your Node app comes online, you should see a message indicating that the connection to ActiveMQ via the STOMP protocol was established and is good to go.