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

com.ibm.able.conversation
Class AbleCpStateMachineHandler

java.lang.Object
  |
  +--com.ibm.able.conversation.AbleCpStateMachineHandler
All Implemented Interfaces:
ConversationPolicyHandler, CpStateMachineHandler, java.io.Serializable

public class AbleCpStateMachineHandler
extends java.lang.Object
implements CpStateMachineHandler, java.io.Serializable

The AbleCpStateMachineHandler class is an ABLE-specific implementation of the CpStateMachineHandler interface.

The ABLE-specific features consist of exception messages.

See Also:
Serialized Form

Field Summary
static java.lang.String CURRENT_STATE_PROPERTY
          Property name of the PropertyChangeEvent fired when the state changes.
protected static long serialVersionUID
          Serialized version identifier in form YYYYMMDDVerRelModxx
 
Constructor Summary
AbleCpStateMachineHandler()
          Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.
AbleCpStateMachineHandler(CpStateMachine newMachine, java.lang.String newRole)
          Constructs an AbleCpStateMachineHandler object with the given properties.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener newListener)
          Adds the given PropertyChangeListener to this object's internal property-change support.
 void addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener newListener)
          Adds the given PropertyChangeListener to this object's internal property-change support.
protected  void changeState(CpState newState)
          Changes the current state.
 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 contextString()
          Returns a one-line string giving role and current state.
protected  void firePropertyChange(java.beans.PropertyChangeEvent event)
          Fires the given PropertyChangeEvent using this object's internal property-change support.
 CpState getCurrentState()
          Returns the current state of the conversation policy being executed.
 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.
 CpStateMachine getStateMachine()
          Returns the CpStateMachine for the conversation policy being executed.
protected  void init(CpStateMachine newMachine, java.lang.String newRole)
          Sets the state machine and role, then sets the current state to the state machine's initial state.
 boolean isDecisionState()
          Indicates whether the current state is a decision state.
protected  boolean isDecisionState(CpState testState)
          Determines whether a given state is a decision state for the role this agent is playing.
 void printDebug(java.lang.String msg)
          Returns a debugging string identifying this class type and instance, followed by the given message.
 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 msg)
          Causes this ConversationPolicyHandler to take the transition matching the given message, if one is found.
 void removePropertyChangeListener(java.beans.PropertyChangeListener oldListener)
          Removes the given PropertyChangeListener from this object's internal property-change support.
 void removePropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener oldListener)
          Removes the given PropertyChangeListener from this object's internal property-change support.
 void setMessageTransformFactory(MessageTransformFactory tfac)
          Sets the MessageTransformFactory that is used in getting MessageTransforms.
 void setOutputListener(ConversationPolicyListener newListener)
          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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

protected static final long serialVersionUID
Serialized version identifier in form YYYYMMDDVerRelModxx

CURRENT_STATE_PROPERTY

public static final java.lang.String CURRENT_STATE_PROPERTY
Property name of the PropertyChangeEvent fired when the state changes.
Constructor Detail

AbleCpStateMachineHandler

public AbleCpStateMachineHandler()
Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.

AbleCpStateMachineHandler

public AbleCpStateMachineHandler(CpStateMachine newMachine,
                                 java.lang.String newRole)
Constructs an AbleCpStateMachineHandler object with the given properties.

Sets the state machine, role, and current state via a call to init().

Parameters:
newMachine - The state machine for the conversation policy to execute.
newRole - The role to play in the conversation policy.
Method Detail

init

protected void init(CpStateMachine newMachine,
                    java.lang.String newRole)
Sets the state machine and role, then sets the current state to the state machine's initial state.

Does not start the conversation. That must be done by start().

Parameters:
newMachine - The state machine for the conversation policy to execute.
newRole - The role to play in the conversation policy.

getStateMachine

public CpStateMachine getStateMachine()
Description copied from interface: CpStateMachineHandler
Returns the CpStateMachine for the conversation policy being executed.

This returns the actual CpStateMachine in use, not a copy of it. Users should not make any changes to the CpStateMachine returned by this method.

Specified by:
getStateMachine in interface CpStateMachineHandler
Following copied from interface: com.ibm.conversation.CpStateMachineHandler
Returns:
The CpStateMachine for the conversation policy being executed.

getCurrentState

public CpState getCurrentState()
Description copied from interface: CpStateMachineHandler
Returns the current state of the conversation policy being executed.

This returns the actual current CpState, not a copy of it. Users should not make any changes to the CpState returned by this method.

Specified by:
getCurrentState in interface CpStateMachineHandler
Following copied from interface: com.ibm.conversation.CpStateMachineHandler
Returns:
The CpState for the current state.
See Also:
ConversationPolicyHandler.getCurrentStateName()

getCurrentStateName

public java.lang.String getCurrentStateName()
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
getCurrentStateName in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
The name of the current state.

isDecisionState

public boolean isDecisionState()
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
isDecisionState in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
true if the current state is a decision state, false if not.

getPolicyName

public java.lang.String getPolicyName()
Description copied from interface: ConversationPolicyHandler
Returns the name of the conversation policy being executed.

Specified by:
getPolicyName in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
The name of the convesation policy being executed, or null if there is none.

getSelfRole

public java.lang.String getSelfRole()
Description copied from interface: ConversationPolicyHandler
Returns the role this ConversationPolicyHandler is playing in the conversation policy.

Specified by:
getSelfRole in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
The role.

getMessageTransformFactory

public MessageTransformFactory getMessageTransformFactory()
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
getMessageTransformFactory in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
The MessageTransformFactory.

setMessageTransformFactory

public void setMessageTransformFactory(MessageTransformFactory tfac)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
setMessageTransformFactory in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Parameters:
fac - The MessageTransformFactory.

getOutputListener

public ConversationPolicyListener getOutputListener()
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
getOutputListener in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Returns:
The output listener.

setOutputListener

public void setOutputListener(ConversationPolicyListener newListener)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
setOutputListener in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Parameters:
listener - The new output listener.

start

public void start()
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
start in interface ConversationPolicyHandler

processMessage

public boolean processMessage(java.lang.Object msg)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
processMessage in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
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)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
processDecision in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
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)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
childReturn in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Parameters:
returnString - The child-return string.
Returns:
true if the transition found & taken; false otherwise.

timerExpired

public boolean timerExpired(java.lang.String stateName)
Description copied from interface: ConversationPolicyHandler
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.

Specified by:
timerExpired in interface ConversationPolicyHandler
Following copied from interface: com.ibm.conversation.ConversationPolicyHandler
Parameters:
stateName - The name of the state for which the timer was set.
Returns:
true if the transition found & taken; false otherwise.

isDecisionState

protected boolean isDecisionState(CpState testState)
Determines whether a given state is a decision state for the role this agent is playing.

Parameters:
testState - The state to be tested.
Returns:
true if testState is a decision state; false if not.

changeState

protected void changeState(CpState newState)
Changes the current state.

After changing the state, takes any appropriate actions for the new state (e.g., setting timer, loading a child conversation poliy). Does not take any actions associated with the transition (i.e., forwarding an outbound message or inbound decision data).

Parameters:
newState - The state to change to. Must be in the current state machine.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener newListener)
Adds the given PropertyChangeListener to this object's internal property-change support.

Parameters:
newListener - The PropertyChangeListener to add.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String property,
                                      java.beans.PropertyChangeListener newListener)
Adds the given PropertyChangeListener to this object's internal property-change support.

Parameters:
property - The property name under which to add the listener.
newListener - The PropertyChangeListener to add.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener oldListener)
Removes the given PropertyChangeListener from this object's internal property-change support.

Parameters:
oldListener - The PropertyChangeListener to remove.

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String property,
                                         java.beans.PropertyChangeListener oldListener)
Removes the given PropertyChangeListener from this object's internal property-change support.

Parameters:
property - The property name for which the listener is to be removed.
oldListener - The PropertyChangeListener to remove.

firePropertyChange

protected void firePropertyChange(java.beans.PropertyChangeEvent event)
Fires the given PropertyChangeEvent using this object's internal property-change support.

Parameters:
event - The PropertyChangeEvent to fire.

contextString

public java.lang.String contextString()
Returns a one-line string giving role and current state. For debugging only.

Returns:
The string giving role and current state.

printDebug

public void printDebug(java.lang.String msg)
Returns a debugging string identifying this class type and instance, followed by the given message. For debugging only.

Parameters:
msg - The message.
Returns:
The debugging string.

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

(C) Copyright IBM Corporation 1999, 2003