com.ibm.able.conversation
Class AbleConversation

java.lang.Object
  com.ibm.able.conversation.AbleConversation

All Implemented Interfaces:

Conversation

public class AbleConversation

extends java.lang.Object

implements Conversation

The AbleConversation class executes one side of a single conversation, managing all ConversationPolicyHandlers, etc., as needed. It's owned by, and has a reference to, an AbleConversationManager.

An AbleConversation immediately processes any message or decision-data given to it as input, and stores any outputs generated by the currently active ConversationPolicyHandler in two queues: one for output messages to be given to the MessageSystemAdapter, and the other for decision-data to be given to the DecisionLogicAdapter. To do this, it uses an internal, private ConversationPolicyListener that it attaches to all ConversationPolicyHandlers. The output queues are flushed periodically by the AbleConversationManager that owns this Conversation.

This is not an AbleBean, but it may become one in the future. For this reason, some of the methods are copied from the AbleBean interface. It will only be used as a transient object in ABLE, so it does not implement the Serializable interface.

Field Summary

static java.lang.String	CHILD_CP_DONE_PROPERTY Property name of the PropertyChangeEvent fired when a child conversation policy has just terminated.
static java.lang.String	CHILD_CP_LOADED_PROPERTY Property name of the PropertyChangeEvent fired when a child conversation policy has just been loaded.

Constructor Summary

AbleConversation(AbleConversationManager mgr, java.lang.String newConvId)
Constructs an AbleConversation object.

Method Summary

protected void	addPendingOutputEvent(com.ibm.able.conversation.AbleConversation.OutputEvent newOutput) Adds the given output event to the queue of pending output events.
void	addPropertyChangeListener(java.beans.PropertyChangeListener newListener) Adds the given PropertyChangeListener to this object's property-change support.
void	addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener newListener) Adds the given PropertyChangeListener to this object's property-change support, under the given property name.
void	dispatchOutputs() Flushes the queue of pending ConversationPolicyHandler outputs one by one.
protected void	firePropertyChange(java.beans.PropertyChangeEvent event) Fires the given PropertyChangeEvent to registered PropertyChangeListeners.
ConversationPolicyHandler	getActivePolicyHandler() Returns the currently active conversation policy handler.
java.lang.String	getActivePolicyName() Returns the name of the conversation policy currently active in this conversation.
java.lang.String	getActivePolicyRole() Returns the role this agent is playing in the currently active conversation policy.
ConversationContext	getContext() Returns the current conversational context for this conversation.
java.lang.String	getConversationId() Returns the conversation ID for this conversation.
ConversationPolicyHandler	getConversationPolicyHandlerAt(int level) Returns the conversation policy handler at the given level of the stack.
DecisionLogicAdapter	getDecisionLogicAdapter() Returns the DecisionLogicAdapter currently in use for this Conversation.
MessageSystemAdapter	getMessageSystemAdapter() Returns the MessageSystemAdapter currently in use for this Conversation.
ConversationMetaData	getMetaData() Returns the conversation meta-data for this conversation.
java.lang.String	getRootPolicyName() Returns the name of the root conversation policy for this conversation.
java.lang.String	getRootPolicyRole() Returns the role this agent plays when it executes the root conversation policy.
protected void	loadPolicy(java.lang.String name, java.lang.String role) Creates, initializes, and installs a new ConversationPolicyHandler with the given policy and role.
protected void	popPolicy(java.lang.String returnCode) Pops the currently active ConversationPolicyHandler from the stack and sends the return code to its parent.
void	processDecision(DecisionDataHandle ddh) Processes the given decision.
void	processMessage(MessageHandle mh) Processes the given message.
void	removePropertyChangeListener(java.beans.PropertyChangeListener oldListener) Removes the given PropertyChangeListener from this object's property-change support.
void	removePropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener oldListener) Removes the given PropertyChangeListener from this object's property-change support for the given property name.
void	setConversationPolicyHandlerFactory(ConversationPolicyHandlerFactory newFactory) Sets the ConversationPolicyHandlerFactory to use in creating ConversationPolicyHandlers for this conversation.
void	setDecisionLogicAdapter(DecisionLogicAdapter newDLA) Sets the DecisionLogicAdapter to use for this Conversation.
void	setMessageSystemAdapter(MessageSystemAdapter newMSA) Sets the MessageSystemAdapter to use for this Conversation.
void	setMessageTransformFactory(MessageTransformFactory newFactory) Sets the MessageTransformFactory to use in creating MessageTransforms for translating messages into decision data, and vice-versa.
void	setMetaData(ConversationMetaData data) Sets the conversation meta-data for this conversation.
void	setRootPolicy(java.lang.String newName, java.lang.String newRole) Sets the name and role of the root conversation policy.
void	start() Begins execution of the conversation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CHILD_CP_DONE_PROPERTY

public static final java.lang.String CHILD_CP_DONE_PROPERTY

Property name of the PropertyChangeEvent fired when a child conversation policy has just terminated.

See Also:

Constant Field Values

CHILD_CP_LOADED_PROPERTY

public static final java.lang.String CHILD_CP_LOADED_PROPERTY

Property name of the PropertyChangeEvent fired when a child conversation policy has just been loaded.

See Also:

Constant Field Values

Constructor Detail

AbleConversation

public AbleConversation(AbleConversationManager mgr,
                        java.lang.String newConvId)

Constructs an AbleConversation object.

Parameters:

mgr - The ConverstionManager that owns this Converstion.

newConvId - The conversation ID of this Conversation.

Method Detail

getConversationId

public java.lang.String getConversationId()

Description copied from interface: Conversation

Returns the conversation ID for this conversation.

The conversation ID is assigned by the ConversationManager at the time this Conversation is created. Its value is equal to that of getMetaData().getSelfConversationId();

Specified by:

getConversationId in interface Conversation

Returns:

The conversation ID.

setMetaData

public void setMetaData(ConversationMetaData data)

Description copied from interface: Conversation

Sets the conversation meta-data for this conversation.

Does not copy the new meta-data's contents; just replaces the old meta-data object with the new one. This should not be called once the conversation has been set up.

Specified by:

setMetaData in interface Conversation

Parameters:

data - The new meta-data object.

getMetaData

public ConversationMetaData getMetaData()

Description copied from interface: Conversation

Returns the conversation meta-data for this conversation.

Does not return a copy, but the actual meta-data object in use. After the conversation has been set up, the properties of this meta-data object should not be changed.

Specified by:

getMetaData in interface Conversation

Returns:

The ConversationMetaData object for this conversation.

getContext

public ConversationContext getContext()

Description copied from interface: Conversation

Returns the current conversational context for this conversation.

Specified by:

getContext in interface Conversation

Returns:

A ConversationContext object describing the conversational context.

setRootPolicy

public void setRootPolicy(java.lang.String newName,
                          java.lang.String newRole)

Description copied from interface: Conversation

Sets the name and role of the root conversation policy.

The root policy name and role must be set before the conversation is started, and should not be changed thereafter.

Specified by:

setRootPolicy in interface Conversation

Parameters:

newName - The new root policy's name.

newRole - The role to play in the new root policy.

getRootPolicyName

public java.lang.String getRootPolicyName()

Description copied from interface: Conversation

Returns the name of the root conversation policy for this conversation.

The root policy name must be set (via setRootPolicy()) before the conversation is started, and should not be changed thereafter.

Specified by:

getRootPolicyName in interface Conversation

Returns:

The name of the root policy.

getRootPolicyRole

public java.lang.String getRootPolicyRole()

Description copied from interface: Conversation

Returns the role this agent plays when it executes the root conversation policy.

The root policy role must be set (via setRootPolicy()) before the conversation is started, and should not be changed thereafter.

Specified by:

getRootPolicyRole in interface Conversation

Returns:

The root policy role.

getActivePolicyName

public java.lang.String getActivePolicyName()

Description copied from interface: Conversation

Returns the name of the conversation policy currently active in this conversation.

Specified by:

getActivePolicyName in interface Conversation

Returns:

The name of the active policy, or null if there is none.

getActivePolicyRole

public java.lang.String getActivePolicyRole()

Description copied from interface: Conversation

Returns the role this agent is playing in the currently active conversation policy.

Specified by:

getActivePolicyRole in interface Conversation

Returns:

The role, or null if there is none.

getConversationPolicyHandlerAt

public ConversationPolicyHandler getConversationPolicyHandlerAt(int level)

Description copied from interface: Conversation

Returns the conversation policy handler at the given level of the stack.

Specified by:

getConversationPolicyHandlerAt in interface Conversation

Parameters:

level - The level of the desired policy handler.

Returns:

The ConversationPolicyHandler, or null if there is none.

getActivePolicyHandler

public ConversationPolicyHandler getActivePolicyHandler()

Description copied from interface: Conversation

Returns the currently active conversation policy handler.

Specified by:

getActivePolicyHandler in interface Conversation

Returns:

The currently active ConversationPolicyHandler, or null if there is none.

setMessageTransformFactory

public void setMessageTransformFactory(MessageTransformFactory newFactory)

Description copied from interface: Conversation

Sets the MessageTransformFactory to use in creating MessageTransforms for translating messages into decision data, and vice-versa.

The ConverstionManager assigns a default MessageTransformFactory at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

setMessageTransformFactory in interface Conversation

Parameters:

newFactory - The new MessageTransformFactory to use.

setConversationPolicyHandlerFactory

public void setConversationPolicyHandlerFactory(ConversationPolicyHandlerFactory newFactory)

Description copied from interface: Conversation

Sets the ConversationPolicyHandlerFactory to use in creating ConversationPolicyHandlers for this conversation.

The ConverstionManager assigns a default ConversationPolicyHandlerFactory at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

setConversationPolicyHandlerFactory in interface Conversation

Parameters:

newFactory - The new ConversationPolicyHandlerFactory to use.

getDecisionLogicAdapter

public DecisionLogicAdapter getDecisionLogicAdapter()

Description copied from interface: Conversation

Returns the DecisionLogicAdapter currently in use for this Conversation.

The ConversationManager assigns a default DecisionLogicAdapter at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

getDecisionLogicAdapter in interface Conversation

Returns:

The DecisionLogicAdapter for this Conversation.

setDecisionLogicAdapter

public void setDecisionLogicAdapter(DecisionLogicAdapter newDLA)

Description copied from interface: Conversation

Sets the DecisionLogicAdapter to use for this Conversation.

The ConversationManager assigns a default DecisionLogicAdapter at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

setDecisionLogicAdapter in interface Conversation

Parameters:

newDLA - The new DecisionLogicAdapter to use.

getMessageSystemAdapter

public MessageSystemAdapter getMessageSystemAdapter()

Description copied from interface: Conversation

Returns the MessageSystemAdapter currently in use for this Conversation.

The ConversationManager assigns a default MessageSystemAdapter at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

getMessageSystemAdapter in interface Conversation

Returns:

The MessageSystemAdapter for this Conversation.

setMessageSystemAdapter

public void setMessageSystemAdapter(MessageSystemAdapter newMSA)

Description copied from interface: Conversation

Sets the MessageSystemAdapter to use for this Conversation.

The ConversationManager assigns a default MessageSystemAdapter at the time the Conversation is created. It can safely be replaced anytime.

Specified by:

setMessageSystemAdapter in interface Conversation

Parameters:

newMSA - The new MessageSystemAdapter to use.

start

public void start()

Description copied from interface: Conversation

Begins execution of the conversation.

This should be called only once. It clears the policy-handler stack, then creates a new policy-handler running the root policy in the root policy role and adds the new policy-handler to the stack.

If the start state is a decision state for this agent, calling start() will cause DecisionLogicAdapter.decisionPoint() to be called on the decision logic adapter. This is the signal to the decision logic that it is supposed to start the conversation in earnest, by making its first decision.

Specified by:

start in interface Conversation

loadPolicy

protected void loadPolicy(java.lang.String name,
                          java.lang.String role)

Creates, initializes, and installs a new ConversationPolicyHandler with the given policy and role.

Parameters:

name - The policy name.

role - The role.

popPolicy

protected void popPolicy(java.lang.String returnCode)

Pops the currently active ConversationPolicyHandler from the stack and sends the return code to its parent. If there it no parent (i.e., currently active CPH is the root), closes the conversation.

Parameters:

returnCode - The return code to send to the parent.

processMessage

public void processMessage(MessageHandle mh)
                    throws ConversationException

Processes the given message.

This gives the message to the active policy handler for processing, then stores the policy handler's outputs until they are dispatched. Dispatching is done asynchronously via dispatchOutputs(),

Specified by:

processMessage in interface Conversation

Parameters:

mh - The message.

Throws:

ConversationException - If there is no currently active policy.

See Also:

dispatchOutputs()

processDecision

public void processDecision(DecisionDataHandle ddh)
                     throws ConversationException

Processes the given decision.

This gives the decision data to the active policy handler for processing, then stores the policy handler's outputs until they are dispathed. Dispatching is done asynchronously via dispatchOutputs().

Specified by:

processDecision in interface Conversation

Parameters:

ddh - The decision data.

Throws:

ConversationException - If there is no currently active policy, or if the decision is illegal, as determined by the conversational context.

See Also:

dispatchOutputs()

dispatchOutputs

public void dispatchOutputs()

Flushes the queue of pending ConversationPolicyHandler outputs one by one.

Messages are given to the MessageSystemAdapter. Conversation-management outputs (e.g., load child policy & child policy done) are processed by this AbleConversation object. Decision data is given to the DecisionLogicAdapter via a call to the appropriate method: e.g., DecisionLogicAdapter.decisionPoint() if the conversation is at a decision point for this agent.

addPendingOutputEvent

protected final void addPendingOutputEvent(com.ibm.able.conversation.AbleConversation.OutputEvent newOutput)

Adds the given output event to the queue of pending output events.

Parameters:

newOutput - The decision-data to add.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener newListener)

Adds the given PropertyChangeListener to this object's property-change support.

Parameters:

newListener - The new PropertyChangeListener.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String property,
                                      java.beans.PropertyChangeListener newListener)

Adds the given PropertyChangeListener to this object's property-change support, under the given property name.

Parameters:

property - The property name.

newListener - The new PropertyChangeListener.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener oldListener)

Removes the given PropertyChangeListener from this object's 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 property-change support for the given property name.

Parameters:

property - The property name.

oldListener - The PropertyChangeListener to remove.

firePropertyChange

protected void firePropertyChange(java.beans.PropertyChangeEvent event)

Fires the given PropertyChangeEvent to registered PropertyChangeListeners.

Parameters:

event - The PropertyChangeEvent.