Distributed Events Plugin

The Distributed Events Plugin adds a major enhancement to multi-node XNAT systems, where multiple Tomcat servers are connected to a single XNAT database to distribute user load. One major flaw in this setup has been the real-time updating of events that affect user permissions across all login nodes. This plugin addresses that flaw by using ActiveMQ's Publish/Subscribe messaging to make critical system events that occur on a single node available to other nodes in a distributed configuration.

Feature Description

A distributed or load-balanced XNAT configuration includes two or more XNAT instances (aka nodes) that work together to distribute resource-intensive tasks across multiple workers. The tasks to be shared are placed by the originating node onto a queue maintained by an external MQ instance. Each task is then picked up by any of the other nodes when they have threads available to perform the task. 

However, each instance has its own set of internal caches, which are updated on the instance in response to changes in the system, e.g. creation or deletion of projects, subjects, experiments, etc. This works well in a stand-alone XNAT deployment, but in a distributed configuration leads to the various caches being out of sync. For example, when a project is added on node A an event is triggered, with one of the event handlers updating cache items that will change based on that, like overall project count, cached permissions, etc., but only on node A: node B’s cache will reflect the system state prior to the project creation.

The distributed events framework will leverage MQ topics, which differ from queues in that queued items are removed from the queue as they’re consumed, meaning that only a single node consumes the queued item, while items in topics persist until all nodes have consumed them. This means that events that were previously only visible locally on a single node can be published and shared across a distributed or load-balanced system.

Affected Events

The following events are now immediately available to all nodes:

Use Cases

Affected XNAT ticket: https://radiologics.atlassian.net/browse/XNAT-6889

In practice, this means that on an XNAT system with nodes A, B, and C, you could see the following (as examples):

• When Alice on node A creates a public project, Bennie who is already logged into node B would be able to see that project in the Browse > Data menu on their next page load.

• When Alice on node A creates a subject and uploads an image session to their project, Bennie on node B would see those updates to that project on their next page load.

• If Bennie adds Charlie to their private project, and Charlie is logged into node C, Charlie would be able to see that project in their project listings on their next page load.

• If Charlie shares Alice’s subject into Bennie’s private project, Bennie would see that shared subject and experiment data on their next page load.

• Additionally, counts (such as the listings of projects, subjects, and experiments on the XNAT home page) are updated for all users following each of these events

Previously, each of these events would be invisible to users on other nodes until they had logged out and back in again.

Resources for Installation

The plugin jar is available here: https://bitbucket.org/xnatx/dist-events/downloads/. Installation follows the standard process for Deploying Plugins in XNAT. This plugin “leaves no trace”, meaning it can be easily installed or uninstalled without leaving any artifact on your system.

XNAT Version Compatibility Matrix

Version 1.0 has been tested against the latest versions of XNAT. We believe it should be backwards compatible through XNAT 1.8.4 and later.