All Implemented Interfaces:
    Command

All Known Implementing Classes:
    TestChain, ChainBase

A Chain represents a configured list of Command s that will be executed in order to perform processing on a specified Context . Each included Command will be executed in turn, until either one of them returns true, one of the executed Command s throws an exception, or the end of the chain has been reached. The Chain itself will return the return value of the last Command that was executed (if no exception was thrown), or rethrow the thrown exception.

Note that Chain extends Command , so that the two can be used interchangeably when a Command is expected. This makes it easy to assemble workflows in a hierarchical manner by combining subchains into an overall processing chain.

To protect applications from evolution of this interface, specialized implementations of Chain should generally be created by extending the provided base class org.apache.commons.chain.impl.ChainBase ) rather than directly implementing this interface.

Chain implementations should be designed in a thread-safe manner, suitable for execution on multiple threads simultaneously. In general, this implies that the state information identifying which Command is currently being executed should be maintained in a local variable inside the execute() method, rather than in an instance variable. The Command s in a Chain may be configured (via calls to addCommand()) at any time before the execute() method of the Chain is first called. After that, the configuration of the Chain is frozen.

author: Craig - R. McClanahan

version: $ - Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $

 public  void addCommand(Command command)
Add a Command  to the list of Command s that will
be called in turn when this Chain 's execute()
method is called. Once execute() has been called
at least once, it is no longer possible to add additional
Command s; instead, an exception will be thrown.

 public boolean execute(Context context) throws Exception
Execute the processing represented by this Chain  according
to the following algorithm.

If there are no configured Command s in the Chain ,
return false.
Call the execute() method of each Command 
configured on this chain, in the order they were added via calls
to the addCommand() method, until the end of the
configured Command s is encountered, or until one of
the executed Command s returns true
or throws an exception.
Walk backwards through the Command s whose
execute() methods, starting with the last one that
was executed. If this Command  instance is also a
Filter , call its postprocess() method,
discarding any exception that is thrown.
If the last Command  whose execute() method
was called threw an exception, rethrow that exception.
Otherwise, return the value returned by the execute()
method of the last Command  that was executed. This will be
true if the last Command  indicated that
processing of this Context  has been completed, or
false if none of the called Command s
returned true.