If you are developing functionality that might be used an a multi-node environment, it is important to consider whether your code might have issues operating in a multi-node XNAT installation environment. Setup and configuration of a multi-node XNAT environment is described here.
Most code in XNAT and most code you're likely to develop will work fine as-is in a multi-node environment. Users will trigger the code by issuing URLs to a specific web application instance either via the XNAT UI or via script or command line. That instance will then execute the code and carry out its task. Other code, however, may run as a listener, waiting for things to happen in the system and responding or as a scheduled task that triggers at specific intervals. It is important to consider whether, in a multi-node setup, multiple instances will try to carry out these requests simultaneously and whether that could cause problems.
In an out-of-the box XNAT installation an example of this type of task is the session xml rebuilder, which builds new imaging sessions from recently arrived images in the prearchive. The Node/Task Framework is included in XNAT 1.7 to simplify coding such tasks and assist in making a decision whether or not a given node should perform the task.
Coding Your Task
It should be relatively simple to code your task in a way so that it is configurable and executes safely in a multi-node environment. We'll use the code for the Session XML Rebuilder as the code sample. You can find the full source code here. The relevant lines of code are included below:
Key implementation details:
- Specify @XnatTask annotation
- This allows XNAT to discover your task so that administrators can configure where your task executes in their environment.
- Administrators will be able to configure which nodes should run your task under the "XNAT Task Settings" administration page. Your task will automatically show up as one of the XNAT tasks to be configured.
- Extend AbstractXnatTask
- This provides implementation for the shouldRunTask() method that will use the configured execution resolver and the configuration supplied by the local site to determine whether the current node should run the task.
- If you are unable to extend AbstractXnatTask, you can instead implement the XnatTaskI interface that the AbstractXnatTask class implements and supply implementation for the required methods.
- Call shouldRunTask() method to determine whether to continue performing task or return without performing the task.
Execution resolvers do the work of deciding whether the current node should execute a task. In an out-of-the-box XNAT installation, there currently are two execution resolvers;
- SingleNodeExecutionResolver - Administrators specify, via XNAT Task Settings configuration, a single node that should run the task.
- SingleNodeExecutionResolverWithFailover - Administrators specify a list of nodes that can handle the task. If one is not reachable and has not executed the task within a configured span of time, the next node will run the task.
If these execution resolvers are not sufficient for your needs, you can write your own. We'll use the SingleNodeExecutionResolver as a code example. You can find the full source code here. The key lines of code are below:
Key Implementation Details:
- Specify @XnatTaskExecutionResolver annotation.
- This allows XNAT to discover your execution resolver.
- It will automatically be one of the execution resolvers administrators can select from to configure their tasks to run.
- Implement XnatTaskExecutionResolverI interface.
- You'll need to supply implementation for the shouldRunTask() and getConfigurationElementsYaml() methods.
- The shouldRunTask() method is the main method where a determination is made as to whether or not the current node should process the task.
- In the getConfigurationElementsYaml() method, you'll return the configuration UI elements required to configure your resolver. Presumably, the preference values users will set here will be referenced in the shouldRunTask() method to determine whether or not the current node should process the task.