Update queue - JMS

The Genesis platform enables you to use a Jakarta Messaging (former JMS) compliant message broker as its real-time update-queue back-end via ArtemisMQ.

Using a centralised external broker is highly recommended for complex, large or dynamically scaled clusters, as it reduces the complexity and overhead of peer-to-peer connectivity at the cost of maintaining or (re-using) a message broker.

Prerequisites

To use Genesis Jakarta Messaging on the platform, you must install ArtemisMQ in the host (or hosts in case of High Availability). This is described in the ArtemisMQ documentation.

info

Genesis does not ship Artemis MQ server, just its client library.

JMS configuration options

Basic configuration

To use Jakarta Messaging in your Genesis application, set the MqLayer in your application's system definition file.

genesis-system-definition.kts

systemDefinition {
    global {
        ...
        item(name = "MqLayer", value = "JMS")
        ...
    }
}

The Config variables are listed below.

Config Item	Description	Default
JmsHost (required)	The host name, can hold multiple values separated by comma; this enables you to use HA failover	http://localhost:61616
JmsUsername	Username to connect
JmsPassword	Password to connect (can be encrypted using GenesisKey)
JmsTopicSubscriptionMode	Enum value (TRANSIENT, PERSISTENT)	TRANSIENT
JmsMaxConnectionRetryOnStartup	The number of connections the process will attempt to make to the broker before declaring the process DOWN	20
JmsReconnectDelayMs	The amount of time in milliseconds (exponentially) for a connection reattempt to be made, in case of connectivity problems or other faults	1000
JmsRetryToSendDelayMs	The amount of time in milliseconds for retrying to send a message in case of failure.	1000

Durable consumers

You can configure specific processes to receive messages that were sent when the process was offline. This offers a useful method for processes to recover from missing messages without the need to replay an entire data stream.

For example, assume you have an application named alpha and you are going to set up ALPHA_CONSOLIDATOR to be a durable consumer of the update queue.

1. Create a configuration file for the ALPHA_CONSOLIDATOR process with the contents:

alpha-consolidator-process-config.kts

process {
    systemDefinition {
        item(name = "JmsTopicSubscriptionMode", value = "PERSISTENT")
    }
}

2. Add the details of the newly created configuration to your application's processes.xml file:

procesess.xml

<process name="ALPHA_CONSOLIDATOR">
    <groupId>ALPHA</groupId>
    <start>true</start>
    <options>-Xmx256m -DRedirectStreamsToLog=true -DXSD_VALIDATE=false -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5106</options>
    <module>genesis-pal-consolidator</module>
    <package>global.genesis.pal.consolidator</package>
    <script>alpha-consolidator.kts</script>
    <config>alpha-consolidator-process-config.kts</config>
    <language>pal</language>
    <primaryOnly>true</primaryOnly>
</process>

3. Perform genesisInstall to apply the configuration and start the processes normally.

danger

Do not define JmsTopicSubscriptionMode at Global level, as this will cause all messages to be stored and delivered once the process is back online.

High availability

Prerequisites

The quickest way to set up High Availability with ArtemisMQ is:

• Use a shared store.
• Use discovery via static connectors.

This method is tested and supported by Genesis. There are many other ways of implementing High Availability, but if you implement a different solution, it is vital that you test it thoroughly.

How it works

The diagram below represents using a two-node cluster to show how the Genesis processes behave in this scenario.

1. All processes connect to the primary broker:

2. If there is a failure on the primary broker, the back-up turn primary and all clients automatically re-establish a connection to it:

info

During the failover period, the processes will be reported as DOWN.

Troubleshooting

Process reports DOWN

Scenario: The mon command displays the following message for one or more Genesis processes: UpdateQueue: Update queue is not connected.

There are two possible causes for this:

• The process could not connect in the first place.
• The connection to the message broker has been lost.

caution

At initialisation, processes are terminated automatically after the retry attempts are exhausted. However, if the connection is lost after the initialisation occurs, the processes are not shut down automatically; manual intervention is required from application support.

Resolution: Ensure that the message broker is online and accepting connections. Make sure that the configuration in the genesis-system-definition.kts has the correct values.

Process no longer exists but there are obsolete queues in the message broker

Scenario: You have set up a durable consumer, but this process no longer exists in your application; you can see Artemis Console queues with messages that are never going to be consumed.

Resolution: Remove the queue from the Artemis MQ management console or CLI.