Package org.apache.commons.chain

Interface Chain<C extends Context>

Type Parameters:
C - Type of the context associated with this chain
All Superinterfaces:
Command<C>
All Known Implementing Classes:
ChainBase
public interface Chain<C extends Context> extends Command<C>
A Chain represents a configured list of Commands 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 Commands 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 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 Commands 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.

Version:
$Revision$ $Date$
Author:
Craig R. McClanahan

  • Field Summary

    Fields inherited from interface org.apache.commons.chain.Command

    CONTINUE_PROCESSING, PROCESSING_COMPLETE

  • Method Summary

    Modifier and Type
    Method
    Description
    <CMD extends Command<C>>
    void
    addCommand(CMD command)
    Add a Command to the list of Commands that will be called in turn when this Chain's execute() method is called.
    boolean
    execute(C context)
    Execute the processing represented by this Chain according to the following algorithm.

  • Method Details

    • addCommand

      <CMD extends Command<C>> void addCommand(CMD command)
      Add a Command to the list of Commands 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 Commands; instead, an exception will be thrown.
      Type Parameters:
      CMD - the Command type to be added in the Chain
      Parameters:
      command - The Command to be added
      Throws:
      IllegalArgumentException - if command is null
      IllegalStateException - if this Chain has already been executed at least once, so no further configuration is allowed

    • execute

      boolean execute(C context) throws Exception
      Execute the processing represented by this Chain according to the following algorithm.
      • If there are no configured Commands 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 Commands is encountered, or until one of the executed Commands returns true or throws an exception.
      • Walk backwards through the Commands 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 Commands returned true.
      Specified by:
      execute in interface Command<C extends Context>
      Parameters:
      context - The Context to be processed by this Chain
      Returns:
      true if the processing of this Context has been completed, or false if the processing of this Context should be delegated to a subsequent Command in an enclosing Chain
      Throws:
      Exception - if thrown by one of the Commands in this Chain but not handled by a postprocess() method of a Filter
      IllegalArgumentException - if context is null