Chapter 29 Managing Persistent Component State

Persistence for stateful components

Stateful components collect client session data over successive client method invocations. Normally, state data is stored in memory using fields in the implementation class. However, instances of a component coded this way can run on one server only, and cannot support load balancing or failover. Implementing the component to use persistent state allows instances to participate in failover and load balancing.

To use persistent state management, a stateful component must be an EJB stateful session Bean or a component of another type that uses the control interface CtsComponents::ObjectControl.

You can manage persistence using these techniques:

Automatic persistence In this model, you define a state datatype in IDL or Java and implement component methods to receive state data read from the database and return state data to be written to the database. Jaguar calls your state access methods, and manages interaction with the database.
Java serialization This model can be used only in EJB stateful session Beans. To save persistent state, Jaguar serializes the component class instance and saves the binary data to the database.

Using Java serialization

To use Java serialization, configure the following fields on the Persistence Tab in the Component Properties window:

Persistence Choose Java Serialization.
Storage Component Enter or choose the name of the component that manages interaction with the remote database. See "Storage components" for more information.
Connection Cache Enter the name of a JDBC connection cache that connects to the database. The cache must have by-name access enabled and be installed on all servers where your component is installed.
Table Enter the name of a database table where the serialized data is to be stored. If you use Sybase Adaptive Server Enterprise or Adaptive Server Anywhere, Jaguar creates the table if it does not exist. When using another data server, you or your database administrator (DBA) must create the table manually. The table must have the schema described in "Table schema for binary storage".

Using automatic persistence

To use automatic persistence, configure the following properties fields on the Persistence Tab in the Component Properties window:

Persistence Choose Automatic Persistent State.
State Enter the name of an IDL structure or serializable Java class that stores component state. The structure or class must have one field for each field in the component that must be saved to the database.
You can enter the name of an IDL structure that does not exist; Jaguar Manager creates it when you close the Component Properties dialog box. Afterwards, navigate to the IDL definition and edit the structure as described in "Editing IDL types, exceptions, and interfaces".
State methods Enter the name of methods in your component that get and set state. If you specify no value, the default is getState,setState . Your component implementation must contain these methods, but they should not be listed in the component's client interfaces. The getState method returns an instance of the type specified by the State field, and the setState method accepts a parameter of this type. For example, if the State type is ShoppingCartState, the getState and setState methods might be defined as follows in Java:
```
private ShoppingCartState data;

ShoppingCartState getState()
{
    return data;
}

void setState(ShoppingCartState state)
{
    data = state;
}
```
Whenever the server needs to save component state to persistent storage, it calls the getState method. When the server has reloaded the component state from persistent storage, it calls the setState method. The server takes care of converting the specified State data type to and from a form suitable for persistent storage (for example, binary data). This feature is very powerful because any IDL datatype (or serializable Java class) can be used as the State type. In many cases, the most suitable State data type is an IDL struct type, which can be created in the IDL editor (required when using C++ or COM components), or generated automatically from a Java class or PowerBuilder structure type by the PowerJ or PowerBuilder deployment process.
Storage Component Enter or choose the name of the component that manages interaction with the remote database. See "Storage components" for more information.
Connection Cache Enter the name of a JDBC connection cache that connects to the database. The cache must have by-name access enabled and be installed on all servers where your component is installed.
Table Enter the name of a database table where the serialized data is to be stored. If you use Sybase Adaptive Server Enterprise or Adaptive Server Anywhere, Jaguar creates the table if it does not exist. When using another data server, you or your database administrator (DBA) must create the table manually. The table must have the schema described in "Table schema for binary storage".