Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.conversation
Interface ConversationPolicyHandler

All Known Subinterfaces:
  CpStateMachineHandler

All Known Implementing Classes:
  AbleCpStateMachineHandler

public interface ConversationPolicyHandler

The ConversationPolicyHandler interface represents an object that executes a conversation policy.

A ConversationPolicyHandler must be assigned a ConversationPolicyListener when it is initialized. Then, when the ConversationPolicyHandler processes a valid input, it will generate outputs by calling ConversationPolicyListener methods.

A Conversation creates and uses one or more ConversationPolicyHandlers, one per conversation policy. A ConversationPolicyHandler takes input messages (received from the other agent) and decisions (made by this agent) and attempts to match each one to a "legal" transition defined by the conversation policy. Depending on whether such a match is found, and on its nature if found, the ConversationPolicyHandler generates outputs by invoking appropriate method(s) on its ConversationPolicyListener. Depending on the input and of the conversational context, a single input may give rise to zero, one, or more than one output.

The possible inputs to a ConversationPolicyHandler are given by the following methods:

- `processMessage()`: for message inputs. Called by the the messaging system when a message has arrived from the other agent.
- `processDecision()`: for decision inputs. Called by this agent's decision logic.
- `timerExpired()`: for state-timeout inputs. Called by the Conversation when a state-timer has expired.
- `childReturn()`: for child-return inputs. Called by the Conversation when a child policy has finished execution.

Possible outputs are defined by the `ConversationPolicyListener` interface. The mapping from inputs to outputs is described in the detailed descriptions of the input methods.

A ConversationPolicyHandler has a current state, which changes as inputs are processed. This is a string that uniquely identifies a particular set of constraints on legal inputs. For ConversationPolicyHandler to be in a given state means that, regardless of the past inputs it has already processed, there is a given set of allowed sequences of possible future inputs. If the conversation policy is represented by a `CpStateMachine`, then the current state is identical to the `stateName` property of the current `CpState`. If the conversation policy is represented by something else (e.g., a rule set) the some other string must be used.

For a given role, a state either is or is not a decision state. A decision state is a state in which the agent playing the given role is allowed, by the conversation policy, to make a decision--i.e., to invoke `processDecision()` on this ConversationPolicyHandler.

Method Summary
`boolean` | `childReturn(java.lang.String returnString)` Causes this ConversationPolicyHandler to take a child-return transition with the child-return string, if found.
`java.lang.String` | `getCurrentStateName()` Returns the name of the current state of the conversation policy being executed.
`java.util.Collection` | `getDecisionLogicCallbackNames(java.lang.String role)` Returns a Collection containing the names of all states that are decision-logic callback points for the given role.
`MessageTransformFactory` | `getMessageTransformFactory()` Returns the MessageTransformFactory that is used in getting MessageTransforms.
`ConversationPolicyListener` | `getOutputListener()` Returns the output listener used by this ConversationPolicyHandler.
`java.lang.String` | `getPolicyName()` Returns the name of the conversation policy being executed.
`java.util.Collection` | `getRoles()` Returns a Collection containing the roles supported by the policy.
`java.lang.String` | `getSelfRole()` Returns the role this ConversationPolicyHandler is playing in the conversation policy.
`boolean` | `isDecisionState()` Indicates whether the current state is a decision state.
`boolean` | `processDecision(java.lang.String name, java.lang.Object[] args)` Causes this ConversationPolicyHandler to take the transition matching the given decision name & args, if found.
`boolean` | `processMessage(java.lang.Object message)` Causes this ConversationPolicyHandler to take the transition matching the given message, if one is found.
`void` | `setMessageTransformFactory(MessageTransformFactory fac)` Sets the MessageTransformFactory that is used in getting MessageTransforms.
`void` | `setOutputListener(ConversationPolicyListener listener)` Sets the output listener used by this ConversationPolicyHandler.
`void` | `start()` Puts the conversation policy into its start state.
`boolean` | `timerExpired(java.lang.String stateName)` Causes this ConversationPolicyHandler to take a timeout transition, if the current state name matches the given state name.

Method Detail

### getPolicyName

    public java.lang.String getPolicyName()

  Returns the name of the conversation policy being executed.

  Returns:
    The name of the convesation policy being executed, or null if there is none.

### getRoles

    public java.util.Collection getRoles()

  Returns a Collection containing the roles supported by the policy.

  Each entry in the Collection is a String.

  Returns:
    The roles defined by the policy.

### getSelfRole

    public java.lang.String getSelfRole()

  Returns the role this ConversationPolicyHandler is playing in the conversation policy.

  Returns:
    The role.

### getDecisionLogicCallbackNames

    public java.util.Collection getDecisionLogicCallbackNames(java.lang.String role)

  Returns a Collection containing the names of all states that are decision-logic callback points for the given role. This will be a subset of the state names defined in the policy.

  Each entry in the Collection is a String.

  Parameters:
    `role` - The role
  Returns:
    The callback names for the given role.

### getCurrentStateName

    public java.lang.String getCurrentStateName()

  Returns the name of the current state of the conversation policy being executed.

  The name of the current state is any string that uniquely identifies a "state" of the conversation policy being executed. If the conversation policy is represented by a `CpStateMachine`, then the current state is identical to the `stateName` property of the current `CpState`. If the conversation policy is represented by something else (e.g., a rule set) the some other string must be returned.

  Returns:
    The name of the current state.

### isDecisionState

    public boolean isDecisionState()

  Indicates whether the current state is a decision state.

  A decision state is one in which input from this agent's decision logic is allowed, given current state of the conversaiton policy and the role this agent is playing.

  Returns:
    true if the current state is a decision state, false if not.

### getMessageTransformFactory

    public MessageTransformFactory getMessageTransformFactory()

  Returns the MessageTransformFactory that is used in getting MessageTransforms.

  Each transition is associated with a MessageTransform, which is used to classify whether an input message or decision matches that transition, and to translate from a message to decision data and vice-versa.

  Returns:
    The MessageTransformFactory.

### setMessageTransformFactory

    public void setMessageTransformFactory(MessageTransformFactory fac)

  Sets the MessageTransformFactory that is used in getting MessageTransforms.

  Each transition is associated with a MessageTransform, which is used to classify whether an input message or decision matches that transition, and to translate from a message to decision data and vice-versa.

  Parameters:
    `fac` - The MessageTransformFactory.

### getOutputListener

    public ConversationPolicyListener getOutputListener()

  Returns the output listener used by this ConversationPolicyHandler.

  When this ConversationPolicyHandler changes its state (e.g., as the result of a valid input), it will invoke the appropriate method(s) on the output listener. E.g., if the state-change is one in which this agent is supposed to send a message, then this ConversationPolicyHandler invokes the output listener's `outboundMessage()` method.

  Returns:
    The output listener.

### setOutputListener

    public void setOutputListener(ConversationPolicyListener listener)

  Sets the output listener used by this ConversationPolicyHandler.

  When this ConversationPolicyHandler changes its state (e.g., as the result of a valid input), it will invoke the appropriate method(s) on the output listener. E.g., if the state-change is one in which this agent is supposed to send a message, then this ConversationPolicyHandler invokes the output listener's `outboundMessage()` method.

  Parameters:
    `listener` - The new output listener.

### start

    public void start()

  Puts the conversation policy into its start state.

  The policy, role and output listener should all be set before this is called.

  If the start state is a decision state for the assigned role (i.e., the agent owning this ConversationPolicyHandler is permitted to send the first message), then calling this method will cause this ConversationPolicyHandler to issue a decision request by invoking `decisionPoint()` on its output listener.

### processMessage

    public boolean processMessage(java.lang.Object message)

  Causes this ConversationPolicyHandler to take the transition matching the given message, if one is found.

  This is called by the Conversation when the messaging system gives it a message (i.e., from within `Conversation.processMessage()`).

  If the transition is found, this ConversationPolicyHandler uses its MessageTransformFactory to obtain a MessageTransform appropriate to that transition. The MessageTransform converts the message into decision data, which is given to the output listener, either via a call to `decisionPoint()` if the transition's destination state is a decision state, or via `inboundData()` if not.

  It may also generate other outputs as follows. If the destination state is a load-child state, then this ConversationPolicyHandler invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, this ConversationPolicyHandler invokes `unexpectedMessage()` on its output listener. This is the only case in which the failure to find a transition causes the invocation of a method on the output listener.

  Parameters:
    `message` - The message object to be processed.
  Returns:
    true if the transition found & taken; false otherwise.

### processDecision

    public boolean processDecision(java.lang.String name,
                                   java.lang.Object[] args)

  Causes this ConversationPolicyHandler to take the transition matching the given decision name & args, if found.

  This is called by the Conversation when the decision logic gives it a decision (i.e., from within `Conversation.processDecision()`).

  If the transition is found, this ConversationPolicyHandler uses its MessageTransformFactory to obtain a MessageTransform appropriate to that transition. The MessageTransform converts the decision data into a message, which is given to the output listener via `ConversationPolicyListener.outboundMessage()`.

  It may also generate other outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Parameters:
    `name` - The name of the decision
    `args` - The decision data. If `null`, there is no data associated with the named decision.
  Returns:
    true if the transition found & taken; false otherwise.

### childReturn

    public boolean childReturn(java.lang.String returnString)

  Causes this ConversationPolicyHandler to take a child-return transition with the child-return string, if found.

  This is called by the Conversation when a child policy of this ConversationPolicyHandler terminates. This ConversationPolicyHandler searches for a matching transition (i.e., one that is corresponds to a child-return with the given string). If found, it takes the transition.

  If the transition is found and taken, this ConversationPolicyHandler may generate outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Parameters:
    `returnString` - The child-return string.
  Returns:
    true if the transition found & taken; false otherwise.

### timerExpired

    public boolean timerExpired(java.lang.String stateName)

  Causes this ConversationPolicyHandler to take a timeout transition, if the current state name matches the given state name.

  This is called by the Conversation when a previously-set state-timer expires. This ConversationPolicyHandler checks whether the current state is equal to the given string, and whether there is a timeout transition from the current state. If both conditions are true, it takes the timeout transition.

  If the transition is found and taken, this ConversationPolicyHandler may generate outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Parameters:
    `stateName` - The name of the state for which the timer was set.
  Returns:
    true if the transition found & taken; false otherwise.

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005