ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.conversation
Interface ConversationPolicyHandler

All Known Subinterfaces:
CpStateMachineHandler

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:

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.
 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.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.

getSelfRole

public java.lang.String getSelfRole()
Returns the role this ConversationPolicyHandler is playing in the conversation policy.

Returns:
The 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.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003