|
ABLE 2.0.0 07/02/2003 10:25:01 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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).
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 |
public java.lang.String getConversationId()
The conversation ID is assigned by the ConversationManager at the time
this Conversation is created. Its value is equal to that of
getMetaData().getSelfConversationId()
;
public ConversationMetaData getMetaData()
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.
public void setMetaData(ConversationMetaData data)
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.
The
- new meta-data object.public ConversationContext getContext()
public java.lang.String getRootPolicyName()
The root policy name must be set (via setRootPolicy()
) before
the conversation is started, and should not be changed thereafter.
public java.lang.String getRootPolicyRole()
The root policy role must be set (via setRootPolicy()
) before
the conversation is started, and should not be changed thereafter.
public void setRootPolicy(java.lang.String newName, java.lang.String newRole)
The root policy name and role must be set before the conversation is started, and should not be changed thereafter.
newName
- The new root policy's name.newRole
- The role to play in the new root policy.public java.lang.String getActivePolicyName()
null
if there is none.public java.lang.String getActivePolicyRole()
null
if there is none.public ConversationPolicyHandler getConversationPolicyHandlerAt(int level)
level
- The level of the desired policy handler.public ConversationPolicyHandler getActivePolicyHandler()
public void setMessageTransformFactory(MessageTransformFactory fac)
The ConverstionManager assigns a default MessageTransformFactory at the time the Conversation is created. It can safely be replaced anytime.
fac
- The new MessageTransformFactory to use.public void setConversationPolicyHandlerFactory(ConversationPolicyHandlerFactory fac)
The ConverstionManager assigns a default ConversationPolicyHandlerFactory at the time the Conversation is created. It can safely be replaced anytime.
fac
- The new ConversationPolicyHandlerFactory to use.public DecisionLogicAdapter getDecisionLogicAdapter()
The ConversationManager assigns a default DecisionLogicAdapter at the time the Conversation is created. It can safely be replaced anytime.
public void setDecisionLogicAdapter(DecisionLogicAdapter newDLA)
The ConversationManager assigns a default DecisionLogicAdapter at the time the Conversation is created. It can safely be replaced anytime.
newDLA
- The new DecisionLogicAdapter to use.public MessageSystemAdapter getMessageSystemAdapter()
The ConversationManager assigns a default MessageSystemAdapter at the time the Conversation is created. It can safely be replaced anytime.
public void setMessageSystemAdapter(MessageSystemAdapter newMSA)
The ConversationManager assigns a default MessageSystemAdapter at the time the Conversation is created. It can safely be replaced anytime.
newMSA
- The new MessageSystemAdapter to use.public void start()
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.
public void processMessage(MessageHandle mh)
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.
mh
- The MessageHandle containing the message to be processed.public void processDecision(DecisionDataHandle ddh) throws ConversationException
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.
ConversationException
- If the decision is illegal, as determined by the
conversational context.
|
ABLE 2.0.0 07/02/2003 10:25:01 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |