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

com.ibm.conversation
Interface CpState

All Known Implementing Classes:
BasicCpState

public interface CpState

The CpState interface represents a state in a CpStateMachine.

There are three types of state:

Connectivity constraints: There are constraints on the way in which states and transitions are connected togehter. See CpStateTransition for details.

This a fat interface for all state types. It was done this way, rather than as a base interface and three sub-interfaces, because of the relative simplicity of the state's API.


Field Summary
static int IN_CHILD
          The state type for in-child states.
static int NO_TYPE
          The state type for states whose type has not been set.
static int NORMAL
          The state type for normal states.
static int TERMINAL
          The state type for terminal states.
static java.lang.String[] TYPE_STRINGS
          Strings for each of the state types.
 
Method Summary
 boolean addTransition(CpStateTransition newTrans)
          Attempts to add the given transition to this state's transitions.
 java.lang.String getChildPolicyName()
          Returns the name of the child policy to be loaded when this state is entered.
 java.lang.String getChildPolicyRole(java.lang.String parentRole)
          Returns the role of the child conversation policy which will be played by the agent that is playing the given role in the current conversation policy (i.e., the conversation policy of which this CpState is a state).
 java.lang.String getName()
          Returns the state's name.
 int getNumTransitions()
          Returns the number of transitions from this state (i.e., its out-degree).
 java.lang.String getReturnCode()
          Returns the state's return code.
 long getTimeoutInMillis()
          Returns the state's timeout value.
 CpStateTransition getTransition(java.lang.String transId)
          Returns the transition with the given name.
 java.util.Collection getTransitions()
          Returns a Collection containing this state's transitions.
 java.util.Collection getTransitionsWithSender(java.lang.String role)
          Returns a Collection containing all of the transitions for which the given role is the sender of a message.
 int getType()
          Returns the states's type.
 int getTypeFromString(java.lang.String str)
          Returns the state type matching the given string.
 java.lang.String getTypeString()
          Returns a string corresponding to the state's type.
 boolean hasTransitionWithSender(java.lang.String role)
          Indicates whether this state has a transition in which the given role sends a message.
 boolean setChildPolicyName(java.lang.String newName)
          Attempts to set the name of the child policy to be loaded when this state is entered.
 boolean setChildPolicyRole(java.lang.String parentRole, java.lang.String childRole)
          Sets the role that will be played, in the child policy, by the agent that plays the given role in the current policy.
 void setName(java.lang.String newName)
          Sets the state's name.
 boolean setReturnCode(java.lang.String rc)
          Sets the state's return code.
 void setTimeoutInMillis(long millis)
          Sets the state's timeout value.
 

Field Detail

NO_TYPE

public static final int NO_TYPE
The state type for states whose type has not been set.

NORMAL

public static final int NORMAL
The state type for normal states.

IN_CHILD

public static final int IN_CHILD
The state type for in-child states.

TERMINAL

public static final int TERMINAL
The state type for terminal states.

TYPE_STRINGS

public static final java.lang.String[] TYPE_STRINGS
Strings for each of the state types. In order, these correspond to types {NO_TYPE, NORMAL, IN_CHILD, TERMINAL}.

This is public as a side-effect of the design, but the values shouldn't be accessed directly. Use getTypeString() or getTypeFromString() instead.

Method Detail

getType

public int getType()
Returns the states's type.

Returns:
The state type. The value will be one of {NO_TYPE, NORMAL, IN_CHILD, TERMINAL}.

getTypeString

public java.lang.String getTypeString()
Returns a string corresponding to the state's type.

Returns:
The string giving the state's type.

getTypeFromString

public int getTypeFromString(java.lang.String str)
Returns the state type matching the given string.

Does not change this state's type. (This method would be static, if static methods were allowed for interfaces.)

Parameters:
str - The string for the state type.
Returns:
The state type correponding to the given string. If no match was found, returns NO_TYPE.

getName

public java.lang.String getName()
Returns the state's name.

Returns:
The state's name.

setName

public void setName(java.lang.String newName)
Sets the state's name.

Parameters:
newName - The new name.

getTimeoutInMillis

public long getTimeoutInMillis()
Returns the state's timeout value.

The timeout value gives the amount of time that the conversation may remain in this state.

Returns:
The timout value, in milliseconds. If no timeout has been set, returns 0.

setTimeoutInMillis

public void setTimeoutInMillis(long millis)
Sets the state's timeout value.

The timeout value gives the amount of time that the conversation may remain in this state.

Parameters:
millis - The new timeout value, in milliseconds.

getNumTransitions

public int getNumTransitions()
Returns the number of transitions from this state (i.e., its out-degree).

Returns:
The number of transitions.

getTransitions

public java.util.Collection getTransitions()
Returns a Collection containing this state's transitions.

The elements of the Collection are type CpStateTransition.

Returns:
The state's transitions.

getTransitionsWithSender

public java.util.Collection getTransitionsWithSender(java.lang.String role)
Returns a Collection containing all of the transitions for which the given role is the sender of a message.

The elements of the Collection are type CpStateTransition.

Parameters:
role - The role in question.
Returns:
The transitions in which the given role sends a message.

getTransition

public CpStateTransition getTransition(java.lang.String transId)
Returns the transition with the given name.

Parameters:
transId - The transition name.
Returns:
The transition with the given name, or null if not found.

addTransition

public boolean addTransition(CpStateTransition newTrans)
Attempts to add the given transition to this state's transitions.

In order for the transition to be added, it must obey the connectivity constraints that determine what types of transition may be added to each type of state. See CpStateTransition for more information.

Parameters:
newTrans - the transition to add.
Returns:
true if the transition was addded, false if not.

hasTransitionWithSender

public boolean hasTransitionWithSender(java.lang.String role)
Indicates whether this state has a transition in which the given role sends a message.

This is meaningful only for normal states.

Returns:
true if such a transition exists, false if not.

getChildPolicyName

public java.lang.String getChildPolicyName()
Returns the name of the child policy to be loaded when this state is entered.

This is meaningful only for in-child states.

Returns:
The name of the child policy, or null if there is none.

setChildPolicyName

public boolean setChildPolicyName(java.lang.String newName)
Attempts to set the name of the child policy to be loaded when this state is entered.

This is allowed only for in-child states.

Parameters:
newName - The name of the child policy.
Returns:
true if the state is an in-child state, false if not.

getChildPolicyRole

public java.lang.String getChildPolicyRole(java.lang.String parentRole)
Returns the role of the child conversation policy which will be played by the agent that is playing the given role in the current conversation policy (i.e., the conversation policy of which this CpState is a state).

This is meaningful only for in-child states.

Parameters:
parentRole - The role in the current policy.
Returns:
The role in the child policy, or null if undefined.

setChildPolicyRole

public boolean setChildPolicyRole(java.lang.String parentRole,
                                  java.lang.String childRole)
Sets the role that will be played, in the child policy, by the agent that plays the given role in the current policy.

This is allowed only for in-child states.

Parameters:
parentRole - The role in the current policy.
childRole - The role in the child policy.
Returns:
true if this state is an in-child state, false if not.

getReturnCode

public java.lang.String getReturnCode()
Returns the state's return code.

This is meaningful only for terminal states.

Returns:
The return code, or null if undefined.

setReturnCode

public boolean setReturnCode(java.lang.String rc)
Sets the state's return code.

This is allowed only for terminal states.

Parameters:
rc - The return code.
Returns:
true if this state is a terminal state, false if not.

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

(C) Copyright IBM Corporation 1999, 2003