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

com.ibm.conversation
Interface Conversation

All Known Implementing Classes:
AbleConversation

public interface Conversation

The Conversation interface represents an object that executes one side of a conversation.

Each participant in a conversation will have its own Conversation object, which it uses to classify and parse incoming messages and to generate outgoing messages. A single Conversation object is used for a complete conversational session, which may involve any number of conversation policies (CPs). Each CP is executed by a single ConversationPolicyHandler (CPH), which is created when the CP starts execution and discared when the CP is done. When the conversational session has ended, the Conversation object is discarded.

Information about both participants (i.e., the agent that owns this Conversation object, as well as the agent it is conversing with) is stored in a ConversationMetaData object, which is initialized as part of the conversation setup process and should not be changed thereafter.

The Conversation interface also defines methods for enquiring about the conversational context, which is given by the stack of CPs, the role each agent is playing in each, and the current state of each.

Conversations are created by a ConversationManager, which installs in each one a MessageTransformFactory and a ConversationPolicyHandlerFactory (neither of which may be replaced), default values for the root policy name and role (both of which may be replaced any time before the conversation is started) and default values for the MessageSystemAdapter and DecisionLogicAdapter (both of which may be replaced anytime).

See Also:
ConversationManager, ConversationPolicyHandler

Method Summary
 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.
 void processDecision(DecisionDataHandle ddh)
          Passes the given decision data to the currently active conversation policy handler for processing.
 void processMessage(MessageHandle mh)
          Passes the given message to the currently active ConversationPolicyHandler for processing.
 void setConversationPolicyHandlerFactory(ConversationPolicyHandlerFactory fac)
          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 fac)
          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.
 

Method Detail

getConversationId

public java.lang.String getConversationId()
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();

Returns:
The conversation ID.

getMetaData

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

Returns:
The ConversationMetaData object for this conversation.

setMetaData

public void setMetaData(ConversationMetaData data)
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.

Parameters:
The - new meta-data object.

getContext

public ConversationContext getContext()
Returns the current conversational context for this conversation.

Returns:
A ConversationContext object describing the conversational context.

getRootPolicyName

public java.lang.String getRootPolicyName()
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.

Returns:
The name of the root policy.

getRootPolicyRole

public java.lang.String getRootPolicyRole()
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.

Returns:
The root policy role.

setRootPolicy

public void setRootPolicy(java.lang.String newName,
                          java.lang.String newRole)
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.

Parameters:
newName - The new root policy's name.
newRole - The role to play in the new root policy.

getActivePolicyName

public java.lang.String getActivePolicyName()
Returns the name of the conversation policy currently active in this conversation.

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

getActivePolicyRole

public java.lang.String getActivePolicyRole()
Returns the role this agent is playing in the currently active conversation policy.

Returns:
The role, or null if there is none.

getConversationPolicyHandlerAt

public ConversationPolicyHandler getConversationPolicyHandlerAt(int level)
Returns the conversation policy handler at the given level of the stack.

Parameters:
level - The level of the desired policy handler.
Returns:
The ConversationPolicyHandler, or null if there is none.

getActivePolicyHandler

public ConversationPolicyHandler getActivePolicyHandler()
Returns the currently active conversation policy handler.

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

setMessageTransformFactory

public void setMessageTransformFactory(MessageTransformFactory fac)
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.

Parameters:
fac - The new MessageTransformFactory to use.

setConversationPolicyHandlerFactory

public void setConversationPolicyHandlerFactory(ConversationPolicyHandlerFactory fac)
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.

Parameters:
fac - The new ConversationPolicyHandlerFactory to use.

getDecisionLogicAdapter

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

Returns:
The DecisionLogicAdapter for this Conversation.

setDecisionLogicAdapter

public void setDecisionLogicAdapter(DecisionLogicAdapter newDLA)
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.

Parameters:
newDLA - The new DecisionLogicAdapter to use.

getMessageSystemAdapter

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

Returns:
The MessageSystemAdapter for this Conversation.

setMessageSystemAdapter

public void setMessageSystemAdapter(MessageSystemAdapter newMSA)
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.

Parameters:
newMSA - The new MessageSystemAdapter to use.

start

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


processMessage

public void processMessage(MessageHandle mh)
Passes the given message to the currently active ConversationPolicyHandler for processing.

This method is invoked by the messaging system upon receipt of a message, from the other agent, that belongs to this Conversation.

Note that it is not safe to assume that the given message is in fact legal--i.e., that it conforms to the conversation policy being executed. The contents of the message is outside the control of this agent, so receipt of an illegal message is not a program error. Hence, no exception is thrown. Instead, the ConversationPolicyHandler invokes DecisionLogicAdapter.unexpectedMessage() on the decision logic adapter.

Parameters:
mh - The MessageHandle containing the message to be processed.

processDecision

public void processDecision(DecisionDataHandle ddh)
                     throws ConversationException
Passes the given decision data to the currently active conversation policy handler for processing.

This method is called by the decision logic, in order to trigger the sending of a message containing the (suitably transformed) decision data.

Since the decision is being made by the same agent that owns this Conversation object, it is a program error if the decision doesn't match a legal transition in the currently active converstion policy. Therefore, an exception is thrown when an illegal decision is passed in.

Throws:
ConversationException - If the decision is illegal, as determined by the conversational context.

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

(C) Copyright IBM Corporation 1999, 2003