Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
    `data` - 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)
                        throws ConversationException

  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.
  Throws:
    `ConversationException` - If there is no currently active policy.

### 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 there is no currently active policy, or if the decision is illegal, as determined by the conversational context.

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005