org.perfectjpattern.core.api.behavioral.chainofresponsibility
Interface IHandler<R>

Type Parameters:

R - Request parameter type

All Known Subinterfaces:

IParameterlessHandler

All Known Implementing Classes:

AbstractHandler, AbstractParameterlessHandler, NullHandler

public interface IHandler<R>

Chain of Responsibility Design Pattern: Avoid coupling the sender of a request to its receiver by giving more than one object a chance to handle the request. Chain the receiving objects and pass the request along the chain until an object handles it. (Gamma et al, Design Patterns)

Responsibility: Abstract definition of the "Handler".

• Defines an interface for handling requests.
• Implements the Successor link.

Example usage:

    //
    // Create chain elements 
    //  
    IHandler myFirst = new ConcreteHandler();
    IHandler mySecond = new ConcreteHandler();
    IHandler myThird = new ConcreteHandler();
    
    //
    // Associate Handler elements 
    //
    myFirst.setSuccessor(mySecond);
    mySecond.setSuccessor(myThird);
    
    //
    // Execute the first Handler that triggers the execution of the 
    // complete chain.
    //
    myFirst.start(NullRequest.getInstance());
 

Version:

$Revision: 1.0 $ $Date: Jun 23, 2007 1:27:25 PM $

Author:

Giovanni Azua

Method Summary

boolean	canHandle(R aRequest) Returns true if this IHandler can handle the given request, false otherwise.
IHandler<R>	getSuccessor() Returns the Successor handler.
void	handle(R aRequest) Handle the given request.
void	setChainStrategy(IChainStrategy aStrategy) Set the IChainStrategy to this IHandler.
void	setSuccessor(IHandler<R> aSuccessor) Sets the Successor element.
void	start(R aRequest) Triggers execution of the Chain if the target Handler is the first reference, otherwise implements the decision-making regarding forwarding the request to its successor IHandler instance.

Method Detail

canHandle

boolean canHandle(R aRequest)
                  throws IllegalArgumentException

Returns true if this IHandler can handle the given request, false otherwise.

Parameters:

aRequest - Context-specific request to handle.

Returns:

true if this IHandler can handle the given request, false otherwise.

Throws:

IllegalArgumentException - 'aRequest' must not be null.

start

void start(R aRequest)
           throws IllegalArgumentException

Triggers execution of the Chain if the target Handler is the first reference, otherwise implements the decision-making regarding forwarding the request to its successor IHandler instance.

Parameters:

aRequest - Context-specific request to handle.

Throws:

IllegalArgumentException - 'aRequest' must not be null.

handle

void handle(R aRequest)
            throws IllegalArgumentException

Handle the given request. Implements the actual handling logic and must not contain any decision-making regarding e.g. forwarding the request.

Parameters:

aRequest - Context-specific request to handle.

Throws:

IllegalArgumentException - 'aRequest' must not be null.

IllegalArgumentException - 'aRequest' can not be handled.

getSuccessor

IHandler<R> getSuccessor()

Returns the Successor handler.

Returns:

Successor handler.

setSuccessor

void setSuccessor(IHandler<R> aSuccessor)
                  throws IllegalArgumentException

Sets the Successor element.

Parameters:

aSuccessor - Successor handler

Throws:

IllegalArgumentException - 'aSuccessor' must not be null.

setChainStrategy

void setChainStrategy(IChainStrategy aStrategy)
                      throws IllegalArgumentException

Set the IChainStrategy to this IHandler. IChainStrategy allows to easily modify how the Chain should behave. Possible implementations are e.g.

• Halt as soon as the first Handler processes the request
• Let all handlers process the request
• Let the first N handlers process the request

Parameters:

aStrategy - Continuation strategy defines how the chain should behave

Throws:

IllegalArgumentException - 'aStrategy' must not be null.