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

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 addPendingDecisionEvent(com.ibm.able.conversation.AbleConversation.DecisionLogicEvent newOutput)
          Adds the given decision data to the queue of pending decision data outputs.
protected  void addPendingMessage(MessageHandle newMh)
          Adds the given message to the queue of pending messages.
 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 deliverDecisionData()
          Flushes the queue of pending decision data outputs by giving them, one by one, to this Conversation's DecisionLogicAdapter.
 void deliverMessages()
          Flushes the queue of pending outbound messages by giving them, one by one, to this Conversation's MessageSystemAdapter.
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.
 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.

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.
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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.Conversation
Parameters:
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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.Conversation
Parameters:
fac - 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
Following copied from interface: com.ibm.conversation.Conversation
Parameters:
fac - 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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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
Following copied from interface: com.ibm.conversation.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.

processMessage

public void processMessage(MessageHandle mh)
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 via deliverMessages(),

Specified by:
processMessage in interface Conversation
Parameters:
mh - The message.
See Also:
deliverMessages()

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

Specified by:
processDecision in interface Conversation
Parameters:
ddh - The decision data.
See Also:
deliverDecisionData()

deliverMessages

public void deliverMessages()
Flushes the queue of pending outbound messages by giving them, one by one, to this Conversation's MessageSystemAdapter.

A message is given to the MessageSystemAdapter via a call to MessageSystemAdapter.sendMessage().


deliverDecisionData

public void deliverDecisionData()
Flushes the queue of pending decision data outputs by giving them, one by one, to this Conversation's DecisionLogicAdapter.

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.


addPendingDecisionEvent

protected final void addPendingDecisionEvent(com.ibm.able.conversation.AbleConversation.DecisionLogicEvent newOutput)
Adds the given decision data to the queue of pending decision data outputs.

Parameters:
newOutput - The decision-data to add.

addPendingMessage

protected final void addPendingMessage(MessageHandle newMh)
Adds the given message to the queue of pending messages.

Parameters:
newMh - The message 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.

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

(C) Copyright IBM Corporation 1999, 2003