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 AbleCpStateMachineHandler

    java.lang.Object
      com.ibm.able.conversation.AbleOwned
          com.ibm.able.conversation.AbleCpStateMachineHandler

All Implemented Interfaces:
  ConversationPolicyHandler, CpStateMachineHandler, java.io.Serializable

public class AbleCpStateMachineHandler
extends AbleOwned
implements CpStateMachineHandler, java.io.Serializable

The AbleCpStateMachineHandler class is an ABLE-specific implementation of the CpStateMachineHandler interface.

The ABLE-specific features consist of exception messages.

See Also:
  Serialized Form

Field Summary
`static java.lang.String` | `CURRENT_STATE_PROPERTY` Property name of the PropertyChangeEvent fired when the state changes.
`protected static long` | `serialVersionUID` Serialized version identifier in form YYYYMMDDVerRelModxx

Constructor Summary
`AbleCpStateMachineHandler()` Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.
`AbleCpStateMachineHandler(AbleBean owner)` Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.
`AbleCpStateMachineHandler(AbleBean owner, CpStateMachine newMachine, java.lang.String newRole)` Constructs an AbleCpStateMachineHandler object with the given properties.
`AbleCpStateMachineHandler(CpStateMachine newMachine, java.lang.String newRole)` Constructs an AbleCpStateMachineHandler object with the given properties.

Method Summary
`void` | `addPropertyChangeListener(java.beans.PropertyChangeListener newListener)` Adds the given PropertyChangeListener to this object's internal property-change support.
`void` | `addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener newListener)` Adds the given PropertyChangeListener to this object's internal property-change support.
`protected void` | `changeState(CpState newState)` Changes the current state.
`boolean` | `childReturn(java.lang.String returnString)` Causes this ConversationPolicyHandler to take a child-return transition with the child-return string, if found.
`java.lang.String` | `contextString()` Returns a one-line string giving role and current state.
`protected void` | `firePropertyChange(java.beans.PropertyChangeEvent event)` Fires the given PropertyChangeEvent using this object's internal property-change support.
`CpState` | `getCurrentState()` Returns the current state of the conversation policy being executed.
`java.lang.String` | `getCurrentStateName()` Returns the name of the current state of the conversation policy being executed.
`java.util.Collection` | `getDecisionLogicCallbackNames(java.lang.String role)` Returns a Collection containing the names of all states that are decision-logic callback points for the given role.
`MessageTransformFactory` | `getMessageTransformFactory()` Returns the MessageTransformFactory that is used in getting MessageTransforms.
`ConversationPolicyListener` | `getOutputListener()` Returns the output listener used by this ConversationPolicyHandler.
`java.lang.String` | `getPolicyName()` Returns the name of the conversation policy being executed.
`java.util.Collection` | `getRoles()` Returns a Collection containing the roles supported by the policy.
`java.lang.String` | `getSelfRole()` Returns the role this ConversationPolicyHandler is playing in the conversation policy.
`CpStateMachine` | `getStateMachine()` Returns the CpStateMachine for the conversation policy being executed.
`void` | `init(CpStateMachine newMachine, java.lang.String newRole)` Sets the state machine and role, then sets the current state to the state machine's initial state.
`boolean` | `isDecisionState()` Indicates whether the current state is a decision state.
`protected boolean` | `isDecisionState(CpState testState)` Determines whether a given state is a decision state for the role this agent is playing.
`boolean` | `processDecision(java.lang.String name, java.lang.Object[] args)` Causes this ConversationPolicyHandler to take the transition matching the given decision name & args, if found.
`boolean` | `processMessage(java.lang.Object msg)` Causes this ConversationPolicyHandler to take the transition matching the given message, if one is found.
`void` | `removePropertyChangeListener(java.beans.PropertyChangeListener oldListener)` Removes the given PropertyChangeListener from this object's internal property-change support.
`void` | `removePropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener oldListener)` Removes the given PropertyChangeListener from this object's internal property-change support.
`void` | `setMessageTransformFactory(MessageTransformFactory tfac)` Sets the MessageTransformFactory that is used in getting MessageTransforms.
`void` | `setOutputListener(ConversationPolicyListener newListener)` Sets the output listener used by this ConversationPolicyHandler.
`void` | `start()` Puts the conversation policy into its start state.
`boolean` | `timerExpired(java.lang.String stateName)` Causes this ConversationPolicyHandler to take a timeout transition, if the current state name matches the given state name.
`protected void` | `validateConfiguration()` Checks whether the instance variables are set to valid values.

Methods inherited from class com.ibm.able.conversation.AbleOwned
`getAbleOwner, logException, logMessage, setAbleOwner`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### serialVersionUID

    protected static final long serialVersionUID

  Serialized version identifier in form YYYYMMDDVerRelModxx

  See Also:
    Constant Field Values

### CURRENT_STATE_PROPERTY

    public static final java.lang.String CURRENT_STATE_PROPERTY

  Property name of the PropertyChangeEvent fired when the state changes.

  See Also:
    Constant Field Values

Constructor Detail

### AbleCpStateMachineHandler

    public AbleCpStateMachineHandler()

  Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.

### AbleCpStateMachineHandler

    public AbleCpStateMachineHandler(AbleBean owner)

  Constructs an AbleCpStateMachineHandler object, but leaves state machine and role unset.

Parameters:
  `owner` - The AbleBean that "owns" this object.

### AbleCpStateMachineHandler

    public AbleCpStateMachineHandler(CpStateMachine newMachine,
                                     java.lang.String newRole)

  Constructs an AbleCpStateMachineHandler object with the given properties.

  Sets the state machine, role, and current state via a call to `init()`.

  If newRole is null, does not set the role, but does set the state machine and current state.

Parameters:
  `newMachine` - The state machine for the conversation policy to execute.
  `newRole` - The role to play in the conversation policy.

### AbleCpStateMachineHandler

    public AbleCpStateMachineHandler(AbleBean owner,
                                     CpStateMachine newMachine,
                                     java.lang.String newRole)

  Constructs an AbleCpStateMachineHandler object with the given properties.

  Sets the state machine, role, and current state via a call to `init()`.

  If newRole is null, does not set the role, but does set the state machine and current state.

Parameters:
  `owner` - The AbleBean that "owns" this object.
  `newMachine` - The state machine for the conversation policy to execute.
  `newRole` - The role to play in the conversation policy.

Method Detail

### init

    public void init(CpStateMachine newMachine,
                     java.lang.String newRole)

  Sets the state machine and role, then sets the current state to the state machine's initial state.

  Does not start the conversation. That must be done by `start()`.

  If newRole is null, does not set the role, but does set the state machine and current state.

  Parameters:
    `newMachine` - The state machine for the conversation policy to execute.
    `newRole` - The role to play in the conversation policy. May be null.

### getStateMachine

    public CpStateMachine getStateMachine()

  Description copied from interface: `CpStateMachineHandler`
  Returns the CpStateMachine for the conversation policy being executed.

  This returns the actual CpStateMachine in use, not a copy of it. Users should not make any changes to the CpStateMachine returned by this method.

  Specified by:
    `getStateMachine` in interface `CpStateMachineHandler`
  Returns:
    The CpStateMachine for the conversation policy being executed.

### getCurrentState

    public CpState getCurrentState()

  Description copied from interface: `CpStateMachineHandler`
  Returns the current state of the conversation policy being executed.

  This returns the actual current CpState, not a copy of it. Users should not make any changes to the CpState returned by this method.

  Specified by:
    `getCurrentState` in interface `CpStateMachineHandler`
  Returns:
    The CpState for the current state.
  See Also:
    `ConversationPolicyHandler.getCurrentStateName()`

### getCurrentStateName

    public java.lang.String getCurrentStateName()

  Description copied from interface: `ConversationPolicyHandler`
  Returns the name of the current state of the conversation policy being executed.

  The name of the current state is any string that uniquely identifies a "state" of the conversation policy being executed. If the conversation policy is represented by a `CpStateMachine`, then the current state is identical to the `stateName` property of the current `CpState`. If the conversation policy is represented by something else (e.g., a rule set) the some other string must be returned.

  Specified by:
    `getCurrentStateName` in interface `ConversationPolicyHandler`
  Returns:
    The name of the current state.

### isDecisionState

    public boolean isDecisionState()

  Description copied from interface: `ConversationPolicyHandler`
  Indicates whether the current state is a decision state.

  A decision state is one in which input from this agent's decision logic is allowed, given current state of the conversaiton policy and the role this agent is playing.

  Specified by:
    `isDecisionState` in interface `ConversationPolicyHandler`
  Returns:
    true if the current state is a decision state, false if not.

### getPolicyName

    public java.lang.String getPolicyName()

  Description copied from interface: `ConversationPolicyHandler`
  Returns the name of the conversation policy being executed.

  Specified by:
    `getPolicyName` in interface `ConversationPolicyHandler`
  Returns:
    The name of the convesation policy being executed, or null if there is none.

### getSelfRole

    public java.lang.String getSelfRole()

  Description copied from interface: `ConversationPolicyHandler`
  Returns the role this ConversationPolicyHandler is playing in the conversation policy.

  Specified by:
    `getSelfRole` in interface `ConversationPolicyHandler`
  Returns:
    The role.

### getDecisionLogicCallbackNames

    public java.util.Collection getDecisionLogicCallbackNames(java.lang.String role)

  Description copied from interface: `ConversationPolicyHandler`
  Returns a Collection containing the names of all states that are decision-logic callback points for the given role. This will be a subset of the state names defined in the policy.

  Each entry in the Collection is a String.

  Specified by:
    `getDecisionLogicCallbackNames` in interface `ConversationPolicyHandler`
  Parameters:
    `role` - The role
  Returns:
    The callback names for the given role.

### getRoles

    public java.util.Collection getRoles()

  Description copied from interface: `ConversationPolicyHandler`
  Returns a Collection containing the roles supported by the policy.

  Each entry in the Collection is a String.

  Specified by:
    `getRoles` in interface `ConversationPolicyHandler`
  Returns:
    The roles defined by the policy.

### getMessageTransformFactory

    public MessageTransformFactory getMessageTransformFactory()

  Description copied from interface: `ConversationPolicyHandler`
  Returns the MessageTransformFactory that is used in getting MessageTransforms.

  Each transition is associated with a MessageTransform, which is used to classify whether an input message or decision matches that transition, and to translate from a message to decision data and vice-versa.

  Specified by:
    `getMessageTransformFactory` in interface `ConversationPolicyHandler`
  Returns:
    The MessageTransformFactory.

### setMessageTransformFactory

    public void setMessageTransformFactory(MessageTransformFactory tfac)

  Description copied from interface: `ConversationPolicyHandler`
  Sets the MessageTransformFactory that is used in getting MessageTransforms.

  Each transition is associated with a MessageTransform, which is used to classify whether an input message or decision matches that transition, and to translate from a message to decision data and vice-versa.

  Specified by:
    `setMessageTransformFactory` in interface `ConversationPolicyHandler`
  Parameters:
    `tfac` - The MessageTransformFactory.

### getOutputListener

    public ConversationPolicyListener getOutputListener()

  Description copied from interface: `ConversationPolicyHandler`
  Returns the output listener used by this ConversationPolicyHandler.

  When this ConversationPolicyHandler changes its state (e.g., as the result of a valid input), it will invoke the appropriate method(s) on the output listener. E.g., if the state-change is one in which this agent is supposed to send a message, then this ConversationPolicyHandler invokes the output listener's `outboundMessage()` method.

  Specified by:
    `getOutputListener` in interface `ConversationPolicyHandler`
  Returns:
    The output listener.

### setOutputListener

    public void setOutputListener(ConversationPolicyListener newListener)

  Description copied from interface: `ConversationPolicyHandler`
  Sets the output listener used by this ConversationPolicyHandler.

  When this ConversationPolicyHandler changes its state (e.g., as the result of a valid input), it will invoke the appropriate method(s) on the output listener. E.g., if the state-change is one in which this agent is supposed to send a message, then this ConversationPolicyHandler invokes the output listener's `outboundMessage()` method.

  Specified by:
    `setOutputListener` in interface `ConversationPolicyHandler`
  Parameters:
    `newListener` - The new output listener.

### start

    public void start()

  Description copied from interface: `ConversationPolicyHandler`
  Puts the conversation policy into its start state.

  The policy, role and output listener should all be set before this is called.

  If the start state is a decision state for the assigned role (i.e., the agent owning this ConversationPolicyHandler is permitted to send the first message), then calling this method will cause this ConversationPolicyHandler to issue a decision request by invoking `decisionPoint()` on its output listener.

  Specified by:
    `start` in interface `ConversationPolicyHandler`

### processMessage

    public boolean processMessage(java.lang.Object msg)

  Description copied from interface: `ConversationPolicyHandler`
  Causes this ConversationPolicyHandler to take the transition matching the given message, if one is found.

  This is called by the Conversation when the messaging system gives it a message (i.e., from within `Conversation.processMessage()`).

  If the transition is found, this ConversationPolicyHandler uses its MessageTransformFactory to obtain a MessageTransform appropriate to that transition. The MessageTransform converts the message into decision data, which is given to the output listener, either via a call to `decisionPoint()` if the transition's destination state is a decision state, or via `inboundData()` if not.

  It may also generate other outputs as follows. If the destination state is a load-child state, then this ConversationPolicyHandler invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, this ConversationPolicyHandler invokes `unexpectedMessage()` on its output listener. This is the only case in which the failure to find a transition causes the invocation of a method on the output listener.

  Specified by:
    `processMessage` in interface `ConversationPolicyHandler`
  Parameters:
    `msg` - The message object to be processed.
  Returns:
    true if the transition found & taken; false otherwise.

### processDecision

    public boolean processDecision(java.lang.String name,
                                   java.lang.Object[] args)

  Description copied from interface: `ConversationPolicyHandler`
  Causes this ConversationPolicyHandler to take the transition matching the given decision name & args, if found.

  This is called by the Conversation when the decision logic gives it a decision (i.e., from within `Conversation.processDecision()`).

  If the transition is found, this ConversationPolicyHandler uses its MessageTransformFactory to obtain a MessageTransform appropriate to that transition. The MessageTransform converts the decision data into a message, which is given to the output listener via `ConversationPolicyListener.outboundMessage()`.

  It may also generate other outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Specified by:
    `processDecision` in interface `ConversationPolicyHandler`
  Parameters:
    `name` - The name of the decision
    `args` - The decision data. If `null`, there is no data associated with the named decision.
  Returns:
    true if the transition found & taken; false otherwise.

### childReturn

    public boolean childReturn(java.lang.String returnString)

  Description copied from interface: `ConversationPolicyHandler`
  Causes this ConversationPolicyHandler to take a child-return transition with the child-return string, if found.

  This is called by the Conversation when a child policy of this ConversationPolicyHandler terminates. This ConversationPolicyHandler searches for a matching transition (i.e., one that is corresponds to a child-return with the given string). If found, it takes the transition.

  If the transition is found and taken, this ConversationPolicyHandler may generate outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Specified by:
    `childReturn` in interface `ConversationPolicyHandler`
  Parameters:
    `returnString` - The child-return string.
  Returns:
    true if the transition found & taken; false otherwise.

### timerExpired

    public boolean timerExpired(java.lang.String stateName)

  Description copied from interface: `ConversationPolicyHandler`
  Causes this ConversationPolicyHandler to take a timeout transition, if the current state name matches the given state name.

  This is called by the Conversation when a previously-set state-timer expires. This ConversationPolicyHandler checks whether the current state is equal to the given string, and whether there is a timeout transition from the current state. If both conditions are true, it takes the timeout transition.

  If the transition is found and taken, this ConversationPolicyHandler may generate outputs as follows. If the destination state is a decision state, then this ConversationPolicyHandler invokes `decisionPoint()`. If the destination state is a load-child state, then it invokes `cpLoad()`. If the destination state is a terminal state, it invokes `cpDone()`. If the destination state has a timeout, it invokes `setTimer()`.

  If no matching transition is found, `false` is returned, but no other action is taken.

  Specified by:
    `timerExpired` in interface `ConversationPolicyHandler`
  Parameters:
    `stateName` - The name of the state for which the timer was set.
  Returns:
    true if the transition found & taken; false otherwise.

### isDecisionState

    protected boolean isDecisionState(CpState testState)

  Determines whether a given state is a decision state for the role this agent is playing.

  Parameters:
    `testState` - The state to be tested. Assumed non-null.
  Returns:
    true if testState is a decision state; false if not.

### changeState

    protected void changeState(CpState newState)

  Changes the current state.

  After changing the state, takes any appropriate actions for the new state (e.g., setting timer, loading a child conversation poliy). Does not take any actions associated with the transition (i.e., forwarding an outbound message or inbound decision data).

  Parameters:
    `newState` - The state to change to. Must be in the current state machine.

### validateConfiguration

    protected void validateConfiguration()

  Checks whether the instance variables are set to valid values. I.e., they're non-null, and the role is one of the policy's roles, the current state is one of the policy's states, etc.

  Throws:
    `java.lang.IllegalStateException` - if any instance variables is invalid.

### addPropertyChangeListener

    public void addPropertyChangeListener(java.beans.PropertyChangeListener newListener)

  Adds the given PropertyChangeListener to this object's internal property-change support.

  Parameters:
    `newListener` - The PropertyChangeListener to add.

### addPropertyChangeListener

    public void addPropertyChangeListener(java.lang.String property,
                                          java.beans.PropertyChangeListener newListener)

  Adds the given PropertyChangeListener to this object's internal property-change support.

  Parameters:
    `property` - The property name under which to add the listener.
    `newListener` - The PropertyChangeListener to add.

### removePropertyChangeListener

    public void removePropertyChangeListener(java.beans.PropertyChangeListener oldListener)

  Removes the given PropertyChangeListener from this object's internal 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 internal property-change support.

  Parameters:
    `property` - The property name for which the listener is to be removed.
    `oldListener` - The PropertyChangeListener to remove.

### firePropertyChange

    protected void firePropertyChange(java.beans.PropertyChangeEvent event)

  Fires the given PropertyChangeEvent using this object's internal property-change support.

  Parameters:
    `event` - The PropertyChangeEvent to fire.

### contextString

    public java.lang.String contextString()

  Returns a one-line string giving role and current state. For debugging only.

  Returns:
    The string giving role and current state.

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