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.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` | `addPendingOutputEvent(com.ibm.able.conversation.AbleConversation.OutputEvent newOutput)` Adds the given output event to the queue of pending output events.
`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` | `dispatchOutputs()` Flushes the queue of pending ConversationPolicyHandler outputs one by one.
`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.
`protected void` | `popPolicy(java.lang.String returnCode)` Pops the currently active ConversationPolicyHandler from the stack and sends the return code to its parent.
`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.

  See Also:
    Constant Field Values

### 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.

  See Also:
    Constant Field Values

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`
  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`
  Parameters:
    `data` - 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`
  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`
  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`
  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`
  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`
  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`
  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`
  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`
  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`
  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`
  Parameters:
    `newFactory` - 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`
  Parameters:
    `newFactory` - 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`
  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`
  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`
  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`
  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.

### popPolicy

    protected void popPolicy(java.lang.String returnCode)

  Pops the currently active ConversationPolicyHandler from the stack and sends the return code to its parent. If there it no parent (i.e., currently active CPH is the root), closes the conversation.

  Parameters:
    `returnCode` - The return code to send to the parent.

### processMessage

    public void processMessage(MessageHandle mh)
                        throws ConversationException

  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 asynchronously via `dispatchOutputs()`,

  Specified by:
    `processMessage` in interface `Conversation`
  Parameters:
    `mh` - The message.
  Throws:
    `ConversationException` - If there is no currently active policy.
  See Also:
    `dispatchOutputs()`

### 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 asynchronously via `dispatchOutputs()`.

  Specified by:
    `processDecision` in interface `Conversation`
  Parameters:
    `ddh` - The decision data.
  Throws:
    `ConversationException` - If there is no currently active policy, or if the decision is illegal, as determined by the conversational context.
  See Also:
    `dispatchOutputs()`

### dispatchOutputs

    public void dispatchOutputs()

  Flushes the queue of pending ConversationPolicyHandler outputs one by one.

  Messages are given to the MessageSystemAdapter. Conversation-management outputs (e.g., load child policy & child policy done) are processed by this AbleConversation object. 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.

### addPendingOutputEvent

    protected final void addPendingOutputEvent(com.ibm.able.conversation.AbleConversation.OutputEvent newOutput)

  Adds the given output event to the queue of pending output events.

  Parameters:
    `newOutput` - The decision-data 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.

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