The following section describes various ways to construct or edit a processor chain using the API.

Locking and Synchronization for Editing Processor Chains

When you edit a processor chain, you must first obtain a lock on the chain, using the lockChain() method of the PipelineManager.When you lock a chain, the PipelineManager gets a reference to the calling thread and stores it within the requested chain. If the lock reference of the chain is null, then the lock is granted. If the lock reference is the same as the requesting thread, then the chain is already locked by the caller and execution falls through. For all other cases an exception is thrown, which means that the chain is already locked by another thread.

Portions of the lockChain() and unlockChain() methods need to be synchronized, particularly those with sections that check the lock reference and set it.

The lock cannot be granted if there are threads executing in the requested chain. The chain keeps a reference count for all the threads executing within it. If this count is greater than 0, then the call to lockChain() blocks until the reference count is 0. When the reference count reaches 0, then the blocked call is notified and the lockChain() method continues. To prevent starvation of the lockChain() call, once that method is called, other threads attempting to call runProcess() will sleep until unlockChain() is called. Once this happens, all the threads sleeping on the runProcess() call will be notified.

Creating a New Processor Chain from Scratch

To create a new processor chain using the API:

Editing an Existing Processor Chain

Follow these steps to edit an existing processor chain.

Replacing an Existing Processor Chain

Follow these steps to remove a chain and replace it with a new version of the same chain.

  1. Create a copy of the chain you want to replace by calling duplicateChain() and passing the chainId, which will be replaced as the argument. This call will return a duplicate disabled copy of that chain.

  2. Edit the new chain, using the setHeadLink(), createLink(), addTransition(), and removeTransition() methods, as described in the Editing an Existing Processor Chain section.

  3. Call lockChain() on the chain that is to be replaced.

  4. Call replaceChain() with the new chain as the argument. This will replace the chain that has the same name as the new chain.

  5. Call enableChain() and unlockChain() on the new chain, in that order.

Creating a New Processor Chain from an Existing Chain

Follow these steps to create a chain based on an existing chain in the PipelineManager.

  1. Call copyChain(oldChainName, newChainName). This returns a copy of the chain with a new name. The new chain is locked and disabled.

  2. Edit the new chain if required, as described in the Editing an Existing Processor Chain section.

  3. Call enableChain() to allow execution on it and unlockChain() to allow other threads to edit the chain. These last two calls must be made in this order or an exception will be thrown, because enableChain() requires the caller to have a lock.

Adding and Removing Transitions to and from a Processor Chain

Adding and removing transitions to and from a processor chain requires the use of the addTransition() and removeTransition() methods.

The following before and after diagram demonstrates adding and removing transitions. Pipeline Link 1 is the head of the chain. Pipeline Link 1a is inserted after Pipeline Link 1 and before Pipeline Link 2 and Pipeline Link 3. The transition from Pipeline Link 3 to Pipeline Link 4 is removed.

loading table of contents...