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:
Call the
PipelineManager
’s methodcreateChain()
. ThecreateChain()
method constructs the appropriatePipelineChain
object and sets the proper return type into it. It implicitly locks and disables the chain and then adds it to the Pipeline Manager.Edit the chain by making calls to the
createLink()
,setHeadLink()
, andaddTransition()
methods of thePipelineManager
.createLink()
is called to create all thePipelineLink
objects that will be used in this chain and to link them together.setHeadLink()
is called to set the first link object into the chain.addTransition()
is called to create any additional transitions between links.
Call
enableChain()
to allow execution andunlockChain()
to allow other threads to edit the chain. These last two calls must be made in this order. Otherwise, an exception will be thrown becauseenableChain()
requires the caller to have a lock on the chain.
Editing an Existing Processor Chain
Follow these steps to edit an existing processor chain.
Call
lockChain()
. This call will block until there are no threads executing the chain and a lock can be obtained.Call
setHeadLink()
,createLink()
,addTransition()
, andremoveTransition()
to edit the chain, as described in the preceding Creating a New Processor Chain from Scratch section.Call
unlockChain()
to release the lock and allow execution of the chain to resume.
Replacing an Existing Processor Chain
Follow these steps to remove a chain and replace it with a new version of the same chain.
Create a copy of the chain you want to replace by calling
duplicateChain()
and passing thechainId
, which will be replaced as the argument. This call will return a duplicate disabled copy of that chain.Edit the new chain, using the
setHeadLink()
,createLink()
,addTransition()
, andremoveTransition()
methods, as described in the Editing an Existing Processor Chain section.Call
lockChain()
on the chain that is to be replaced.Call
replaceChain()
with the new chain as the argument. This will replace the chain that has the same name as the new chain.Call
enableChain()
andunlockChain()
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
.
Call
copyChain(oldChainName, newChainName)
. This returns a copy of the chain with a new name. The new chain is locked and disabled.Edit the new chain if required, as described in the Editing an Existing Processor Chain section.
Call
enableChain()
to allow execution on it andunlockChain()
to allow other threads to edit the chain. These last two calls must be made in this order or an exception will be thrown, becauseenableChain()
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.
Call
lockChain()
in thePipelineManager
with thechainId
. This insures that no thread executes in the chain and no other thread edits this chain.Remove the two transitions from Pipeline Link 1 by doing the following:
Get references to Pipeline Link 2 and Pipeline Link 3.
Call
removeTransition()
twice to remove the two transitions that come from Pipeline Link 1.
Call
createLink()
in thePipelineChain
to create Pipeline Link 1a. The arguments tocreateLink()
will be as follows: Pipeline Link 1a, aPipelineProcessor
object, a reference to the link whose ID is Pipeline Link 1, and 1. This creates the transition from Pipeline Link 1 to Pipeline Link 1a.Call
addTransition()
twice to add the two transitions to Pipeline Link 2 and Pipeline Link 3.Call
removeTransition()
with arguments Pipeline Link 3 and 1. This removes the transition from Pipeline Link 3 to Pipeline Link 4.Call
unlockChain()
on the chain.