package com.sourceforge.jpatterns.patterns.bhv.chain;

 import java.io.Serializable;

 /**

  * This interface is going to be used as the DTO between different actors of "chain of responsibility" patterns implemented here. It

  * could be used at both "hierarchical" and "chainable" implementations of this patterns. todo: check this statement

  * <br/>

  * It identifies all the necessary methods for working with the chain of responsibility.

  * <ul>

  * <li>identifying the type of message</li>

  * <li>allow to pass the input objects</li>

  * <li>allows to check the output of chain</li>

  * </ul>

  * <p/>

  * Also the important feature is it allows to identify the handlers/hierarchy items which added/extended/initialized the inputs

  * and outputs. todo: check this statement

  * <p/>

  * todo: what about rmi/ejb/jta/jms communication? COuld this message used here??

  * todo: why we need it cloneable???

  * todo: which other interfaces it should extend

  *

  * todo: think over forwards/includes at the chain handlers etc.

  * 

  * $Author:: zmicer             $<br/>

  */

 public interface IChainMessage extends Serializable, Cloneable

 {

     /**

      * @return the type of message. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).

      */

     String getType();

     /**

      * @return returns the constant allowing us to determine the status of message (if it is under construction or was proceed by the

      *         certain handlers/items etc ) todo: check this statement, introduce constants + introduce configuration os the system

      *         to do it

      */

     String getStatus();

     /**

      * The type of message. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).

      * <br/>

      * The method allowing us to setup the item of the message (in simply words to modify the state of object is intended just to be

      * used at the initialization of the message). At the base class of this interface the status would be analyzed using the

      * {@link IChainMessage#getStatus()} method to understand if we could change the status.

      * <br/>

      * So it would be allowed only if the message is mutatable (configuration of the system allows us to do it - e.g. some handler

      * changing the type of the message during sending it to the another handler/item. todo: check this statement) or

      * it is under construction (was not send and was not processed yet).

      *

      * @throws IllegalStateException in the case the message is not at the appropriate state to be set with the typ

      */

     void setType(String type) throws IllegalStateException;

     /**

      * Get unout param by its name.

      * todo: method allowing to determine inouts param by the id/items/handler could(shoul????) be added

      * todo: should we allow to remove the input params?? system configuration???

      * todo: where input params could be changed - at the handlers/items/inner runners etc??

      * todo: permissions for reading/writing here???

      * <p/>

      * Note: the configuration system of implementation may restrict the usage of this method (it is unpermissed)

      *

      * @param name name of the input param. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).

      *

      * @return Object, some informatino which was put as input param

      *

      * @throws UnsupportedOperationException in the case the message could not return the input params

      *

      * @java5 consider java5 here

      */

     Object getInputParam(String name) throws UnsupportedOperationException;

     /**

      * Get the info which was put to that <code>IChainMessage</code> object.

      * todo: all the todos of above mentioned method have power here.

      * <p/>

      * <p/>

      * Note: the configuration system of implementation may restrict the usage of this method (it is unpermissed)

      *

      * @param param the name of param using which the object should be obtained. Can not be null (otherwise

      *              <code>IllegalArgumentException</code> would appear).

      *

      * @return the Object, output result.

      *

      * @throws UnsupportedOperationException in the case the message could not return the input params

      *

      * @java5 consider java5 here

      */

     Object getOutputInfo(String param) throws UnsupportedOperationException;

 }