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

com.ibm.conversation
Interface ConversationManager

All Known Implementing Classes:
AbleConversationManager

public interface ConversationManager

The ConversationManager interface represents an object that creates, initializes, and destroys Conversation objects.

Each agent will have one ConversationManager, which is initialized with several things to pass into each new Conversation it creates: a MessageTransformFactory, a ConversationPolicyHandlerFactory, and defaults for the Conversation's MessageSystemAdapter, DecisionLogicAdapter, root conversation policy, and root policy role.

Conversations are created by a call to newConversation(), either on the initiative of the agent owning this ConversationManager, or as a result of an inbound message requesting a conversation. In both cases, the ConversationManager creates and initializes a new Conversation, then hands over control of the new Conversation to this ConversationManager's own DecisionLogicAdapter.

Because of this, the DecisionLogicAdapter assigned to this ConversationManager should be capable of executing the setup phase of the conversation, for case where this agent initiates it as well as when the other agent does so. Similarly, this ConversationManager's initial policy (and its initiator and responder role) should be the conversation policy used during the setup phase.

See Also:
Conversation

Method Summary
 void closeConversation(java.lang.String convId)
          Ends the conversation with the given ID.
 ConversationContext getContext(java.lang.String convId)
          Returns the ConversationContext for a given conversation.
 Conversation getConversation(java.lang.String convId)
          Returns the Conversation with the given conversation ID.
 java.util.Set getConversationIds()
          Returns the set of all active conversation IDs.
 ConversationPolicyHandlerFactory getConversationPolicyHandlerFactory()
          Returns this ConversationManager's ConversationPolicyHandlerFactory.
 java.lang.String getInitialPolicyName()
          Returns the name of the policy assigned to newly created conversations.
 java.lang.String getInitiatorRole()
          Returns the role this agent should use in a new conversation, when this agent initiates it.
 MessageTransformFactory getMessageTransformFactory()
          Returns this ConversationManager's MessageTransformFactory.
 ConversationMetaData getMetaData(java.lang.String convId)
          Returns the conversation meta-data associated with a given conversation
 int getNumConversations()
          Returns the number of conversations currently going on.
 java.lang.String getResponderRole()
          Returns the role this agent should use in a new conversation, when another agent has initiated it.
 Conversation newConversation(ConversationMetaData metaData, boolean isInitiator)
          Creates and initializes a new Conversation.
 void setDecisionLogicAdapter(DecisionLogicAdapter dla)
          Sets the DecisionLogicAdapter used by this ConversationManager.
 void setInitialPolicy(java.lang.String policyName, java.lang.String initiatorRole, java.lang.String responderRole)
          Sets the conversation policy to assign to a newly created Conversation, and the roles to use if this agent, or another agent, is the initiator of it.
 void setMessageSystemAdapter(MessageSystemAdapter msa)
          Sets the MessageSystemAdapter used by this ConversationManager.
 

Method Detail

getNumConversations

public int getNumConversations()
Returns the number of conversations currently going on.

Returns:
The number of conversations currently going on.

getConversationIds

public java.util.Set getConversationIds()
Returns the set of all active conversation IDs.

The conversation IDs returned are the IDs assigned by this ConversationManager to the conversations currently in progress.

Returns:
The set of all active conversation IDs.

getMetaData

public ConversationMetaData getMetaData(java.lang.String convId)
Returns the conversation meta-data associated with a given conversation

The conversation is specified by the conversation ID assigned by this ConversationManager to the conversation.

Parameters:
convId - The conversation ID in question.
Returns:
The ConversationMetaData for the conversation with the given ID, or null if not found.

getContext

public ConversationContext getContext(java.lang.String convId)
Returns the ConversationContext for a given conversation.

Parameters:
convId - The conversation ID of the conversation in question.
Returns:
The ConversationContext for the given conversation, or null if not found.

getConversation

public Conversation getConversation(java.lang.String convId)
Returns the Conversation with the given conversation ID.

Parameters:
convId - The conversation ID of the conversation in question.
Returns:
The Conversation with the given conversation ID, or null if not found.

setMessageSystemAdapter

public void setMessageSystemAdapter(MessageSystemAdapter msa)
Sets the MessageSystemAdapter used by this ConversationManager.

The MessageSystemAdapter is assigned to newly created Conversations, during the initial stage of conversation setup. It must be able to deliver the initial conversation-setup message in the case where this agent initiates the conversation.

Parameters:
msa - The new MessageSystemAdapter.

setDecisionLogicAdapter

public void setDecisionLogicAdapter(DecisionLogicAdapter dla)
Sets the DecisionLogicAdapter used by this ConversationManager.

The DecisionLogicAdapter is assigned to each newly created Conversation, regarless of whether this agent or another agent initiated it. Accordingly it must be able to support both the initiator and responder roles of this ConversationManager's initial policy.

Parameters:
dla - The new DecisionLogicAdapter.

getMessageTransformFactory

public MessageTransformFactory getMessageTransformFactory()
Returns this ConversationManager's MessageTransformFactory.

This MessageTransformFactory is assigned to all new Conversations when they are created.

Returns:
The MessageTransformFactory.

getConversationPolicyHandlerFactory

public ConversationPolicyHandlerFactory getConversationPolicyHandlerFactory()
Returns this ConversationManager's ConversationPolicyHandlerFactory.

This ConversationPolicyHandlerFactory is assigned to all new Conversations when they are created.

Returns:
The ConversationPolicyHandlerFactory.

setInitialPolicy

public void setInitialPolicy(java.lang.String policyName,
                             java.lang.String initiatorRole,
                             java.lang.String responderRole)
Sets the conversation policy to assign to a newly created Conversation, and the roles to use if this agent, or another agent, is the initiator of it.

The policy should be a conversation-setup policy. The roles should be the roles defined in that policy.

Parameters:
policyName - the name of the policy
initiatorRole - the role to use if this agent is the initiator.
initiatorRole - the role to use if another agent is the initiator.

getInitialPolicyName

public java.lang.String getInitialPolicyName()
Returns the name of the policy assigned to newly created conversations.

Returns:
The policy name.

getInitiatorRole

public java.lang.String getInitiatorRole()
Returns the role this agent should use in a new conversation, when this agent initiates it.

Returns:
The role.

getResponderRole

public java.lang.String getResponderRole()
Returns the role this agent should use in a new conversation, when another agent has initiated it.

Returns:
The role.

newConversation

public Conversation newConversation(ConversationMetaData metaData,
                                    boolean isInitiator)
Creates and initializes a new Conversation.

This creates a new Conversation object and gives it a unique conversation ID; assigns it the given ConversationMetaData (and copies the conversation ID into the meta-data); assigns its MessageSystemAdapter, DecisionLogicAdapter, MessageTransformFactory, and ConversationPolicyHandlerFactory; and sets the initial policy and role. If isInitiator is true, the role assigned to the new conversation is the one returned by getInitiatorRole(). Otherwise, the role is the one returned by getResponderRole().

This does not call Conversation.start() on the new Conversation, so the user must do so. This is to allow replacement of the defaults (the MessageSystemAdapter, the DecisionLogicAdapter, and the initial policy and role) before anything happens.

Parameters:
metaData - The meta-data object to assign to the new Conversation.
isInitiator - Flag specifying whether this agent is initiating the conversation.
Returns:
The newly created Conversation

closeConversation

public void closeConversation(java.lang.String convId)
Ends the conversation with the given ID.

Discards the Conversation with the given ID, which has presumably just ended. Called after the last message has been sent or received.

Parameters:
convId - The conversation ID of the Conversation to close.

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

(C) Copyright IBM Corporation 1999, 2003