com.ibm.able.conversation
Class AbleCpStateMachineHandler

java.lang.Object
  com.ibm.able.conversation.AbleOwned
      com.ibm.able.conversation.AbleCpStateMachineHandler

All Implemented Interfaces:

ConversationPolicyHandler, CpStateMachineHandler, java.io.Serializable

public class AbleCpStateMachineHandler

extends AbleOwned

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(AbleBean owner)
Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.

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

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.
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.
CpStateMachine	getStateMachine() Returns the CpStateMachine for the conversation policy being executed.
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.
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.
protected void	validateConfiguration() Checks whether the instance variables are set to valid values.

Methods inherited from class com.ibm.able.conversation.AbleOwned

getAbleOwner, logException, logMessage, setAbleOwner

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

See Also:

Constant Field Values

CURRENT_STATE_PROPERTY

public static final java.lang.String CURRENT_STATE_PROPERTY

Property name of the PropertyChangeEvent fired when the state changes.

See Also:

Constant Field Values

Constructor Detail

AbleCpStateMachineHandler

public AbleCpStateMachineHandler()

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

AbleCpStateMachineHandler

public AbleCpStateMachineHandler(AbleBean owner)

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

Parameters:

owner - The AbleBean that "owns" this object.

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

If newRole is null, does not set the role, but does set the state machine and current state.

Parameters:

newMachine - The state machine for the conversation policy to execute.

newRole - The role to play in the conversation policy.

AbleCpStateMachineHandler

public AbleCpStateMachineHandler(AbleBean owner,
                                 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().

If newRole is null, does not set the role, but does set the state machine and current state.

Parameters:

owner - The AbleBean that "owns" this object.

newMachine - The state machine for the conversation policy to execute.

newRole - The role to play in the conversation policy.

Method Detail

init

public 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().

If newRole is null, does not set the role, but does set the state machine and current state.

Parameters:

newMachine - The state machine for the conversation policy to execute.

newRole - The role to play in the conversation policy. May be null.

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

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

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

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

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

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

Returns:

The role.

getDecisionLogicCallbackNames

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

Description copied from interface: ConversationPolicyHandler

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.

Specified by:

getDecisionLogicCallbackNames in interface ConversationPolicyHandler

Parameters:

role - The role

Returns:

The callback names for the given role.

getRoles

public java.util.Collection getRoles()

Description copied from interface: ConversationPolicyHandler

Returns a Collection containing the roles supported by the policy.

Each entry in the Collection is a String.

Specified by:

getRoles in interface ConversationPolicyHandler

Returns:

The roles defined by the policy.

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

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

Parameters:

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

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

Parameters:

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

Parameters:

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

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

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

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. Assumed non-null.

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.

validateConfiguration

protected void validateConfiguration()

Checks whether the instance variables are set to valid values. I.e., they're non-null, and the role is one of the policy's roles, the current state is one of the policy's states, etc.

Throws:

java.lang.IllegalStateException - if any instance variables is invalid.

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.