IState2 interface
The IState2 interface represents a node, or state object, in the State tree. A state tree is a hierarchical data storage mechanism. It is used primarily for storing application data that needs to be distributed across server processes and clusters. For example, the session data your application creates and maintains is stored in nodes of a state tree.
Use a state tree in your application if it needs to maintain and share data in a multi-server environment running load-balanced application components. A node has the following attributes:
The IState2 interface defines methods for creating and deleting nodes, setting and retrieving node contents, and retrieving the attributes of a node.
To create a state tree, use the following methods:
Package
com.kivasoft
Methods
createStateChild( )
Creates a child node under the node on which this method is called.
Syntax
public IState2 createStateChild(
String pName,
int Timeout,
int dwFlags)
pName.
The name of the child node. If a child node with the given name already exists, this method returns an error.
Timeout.
The unit of timeout is seconds. The meaning of timeout depends on the timeout flag specified in dwFlags. A value of 0 means the contents of the node is saved until deleted explicitly. You can assign a non-zero timeout value only to child nodes that are leaf nodes. Parent nodes can only have a timeout value of 0.
dwFlags.
Specify one of the following flags, or 0 to use the default system settings:
The default scope is distributed and the default timeout is 60 seconds from the time the node was last accessed.
Usage
Use createStateChild( ) to add a child node to a state tree. The application component should already have created the root node of the tree with getStateTreeRoot( ) in the AppLogic class.
To create a new child node in a particular position of the tree, traverse the tree until you reach the node that will be the parent of the new child node. Then call createStateChild( ).
Rules
Tips
Return Value
An IState2 object, or null for failure.
Example
The following code shows how to create a child node if it doesn't already exist:
IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");
if (tree!=null)
{
IState2 child = tree.getStateChild("Best Female Vocal");
if (child == null)
{
child = tree.createStateChild("Best Female Vocal", 0,
GXSTATE.GXSTATE_DISTRIB);
deleteStateChild( )
Deletes a child node from a state tree.
Syntax
public int deleteStateChild(
String pName)
pName.
The name of the child node to delete.
Usage
Use deleteStateChild( ) to delete a child node from a state tree when your application no longer needs it. A child node can be deleted only from its parent node. For example, if the state tree has three levels and you want to delete a node at the third level, traverse the tree until you find its parent node at the second level. Then call deleteStateChild( ) to delete a specific node
Rule
You can delete a parent node only after deleting its child nodes.
Tip
To traverse the state tree to find the parent node of the child node to delete, use getStateChild( ). Each successive call to getStateChild( ) descends one level in the tree.
Return Value
GXE.SUCCESS if the method succeeds.
getStateChild( )
Gets a specified child node.
Syntax
public IState2 getStateChild(
String pName)
pName.
The name of the child node to get.
Usage
Use getStateChild( ) to retrieve a node whose content you want to get or update. Your application component can also use getStateChild( ) to traverse a state tree to find the parent node of child nodes to add or delete.
Return Value
An IState2 object, or null for failure.
getStateChildCount( )
Gets the count of children nodes.
Syntax
public int getStateChildCount(
int dwFlags) // parameter is currently unused.
Usage
Use this method to return the number of children at any given state node.
Return Value
An integer representing the number of children.
getStateContents( )
Gets the contents of the node.
Syntax
public IValList getStateContents()
Usage
Use getStateContents( ) to retrieve the contents of the node, or to check if the node contains contents before setting values in the node. This method retrieves the contents that were last saved in the distributed store with saveState( ).
Tips
Return Value
An IValList object that contains the contents, or null for failure.
getStateFlags( )
Gets the flags assigned to the node when it was created.
Syntax
public int getStateFlags()
Usage
Use getStateFlags( ) to retrieve the flag that represents the node's scope, lifetime, and timeout criteria. This flag is specified when the state node is created. The following table describes the valid session flags, which are static variables in the GXSTATE class:
Return Value
One of the flags listed in the previous table.
getStateName( )
Returns the name of the node.
Syntax
public String getStateName()
Usage
Use getStateName( ) when the name of the node is unknown and is required for subsequent operations.
Return Value
A string value representing the name of the current node.
getStateTimeout( )
Returns the node's timeout value in seconds.
Syntax
public int getStateTimeout()
Usage
Use getStateTimeout( ) in conjunction with getStateFlags( ) to determine if and when the contents of the node expires. A timeout value of 0 means the node contents are saved until the node is deleted explicitly.
Return Value
Integer representing the timeout value in seconds.
saveState( )
Saves updates to the node contents.
Syntax
public int saveState(
int dwFlags)
dwFlags.
Specify 0 (zero). Internal use only.
Usage
Use saveState( ) after you set or change the contents of a node. This method flushes the node contents into the distributed store.
Tip
The getStateContents( ) method retrieves the contents that were last saved in the distributed store with saveState( ). Therefore, if you update the contents of a node with setStateContents( ), but do not call saveState( ), getStateContents( ) will not return the content set with setStateContents( ).
Return Value
GXE.SUCCESS if the method succeeds.
setStateContents( )
Sets node contents.
Syntax
public int setStateContents(
IValList pContents)
pContents.
IValList of values to set in the current node.
Usage
Use setStateContents( ) to update the contents of a node.
Tips
Return Value
GXE.SUCCESS if the method succeeds.
Example
The following code shows how to create a child node and set its contents:
IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");
if (tree!=null)
{
IState2 child = tree.getStateChild("Best Female Vocal");
if (child == null)
{
child = tree.createStateChild("Best Female Vocal", 0,
GXSTATE.GXSTATE_DISTRIB);
}
if (child != null)
{
IValList val = GX.CreateValList();
val.setValString("winner", "Whitney Houston");
val.setValString("runner up", "Barbara Streisand");
child.setStateContents(val);
child.saveState(0);
}
|
Previous
