Chapter 25 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.

How it works

State data can be stored either in memory or to a persistent data store:

In-memory storage uses a mirror-pair model where data is replicated between pairs of servers running in the cluster. In-memory storage offers better performance than persistent storage, but each client session has two points of failure (the originating server, and its mirror-pair twin). In-memory storage uses the EAServer message service to replicate data between servers in a mirror pair. See "Requirements for in-memory stateful failover" for more information.
Persistent storage uses a remote database to store component state. A component instance can failover to any other server in the cluster where the component is installed. Persistent storage requires a highly available database, otherwise the database itself can become a single point of failure.

The stateful failover architecture includes:

A storage component , which stores state data to a remote database or, for in-memory storage, calls the message service to replicate the data to the other server in the mirror pair. EAServer provides several storage components for database storage and for in-memory replication. You can also provide your own, custom implementation.
The component's state datatype , which is an IDL structure or serializable class that allows transfer of state data from the stateful component instance to the storage component. For EJB stateful session beans, the state type is the implementation class (which is serialized to save the state).
The component's state accessor methods , which the component or skeleton implements to interact with the storage component. When the client calls a business method, new state may be created in the component. After the business method returns, the storage component calls the get method to obtain the state data, passed as an instance of the state datatype. If the component fails over to another server, a new instance is created and the storage component calls the new instance's set method, providing saved state data to initialize the new instance with the client's session data.

For EJB stateful session beans, EAServer generates a skeleton with state accessor methods that get and set instance state using the standard EJB passivation and reactivation protocol. For components of other types, you must implement accessor methods and specify their names in component properties as described below

The server takes care of converting the specified state data type to and from a form suitable for persistent storage or in-memory replication. 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 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.

Supported component implementations

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. (See "Configuring a control interface".)

You can manage persistence using these techniques:

Using EJB activation and passivation

This model can be used only in EJB stateful session Beans. To save persistent state, the state accessor methods in the component skeleton serialize the component class instance and saves the binary data to the database. To restore state, the saved data is deserialized.
Using automatic persistence

Use this model for non-EJB components. In this model, you define a state datatype in IDL or Java and implement component methods to receive state data and return state data. The server calls your state access methods, and manages interaction with the database.

Using EJB activation and passivation

This stateful persistence model is how EAServer implements the standard EJB passivation and activation protocol. This model can be used only by EJB stateful session beans.

Configure the following fields on the Persistence Tab in the Component Properties window:

Persistence Choose Java Serialization.
Storage Component Specify the name of the storage component, as described in "Storage components".
Connection Cache If using persistent storage, enter the name of a JDBC connection cache that connects to the database. The cache must have by-name access enabled on the Cache tab in the Connection Cache Properties dialog box.
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, the server 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, you must define a state datatype to hold your component's instance state, implement accessor methods, and choose a storage component. Configure these 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 contain all data to be saved to database or replicated.

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, the storage component calls your component's getState method. When the server has reloaded the component state from persistent storage, the storage component calls your component's setState method. The server takes care of converting the specified State data type to and from a form suitable for storage (for example, binary data).
Storage Component Specify the name of the storage component, as described in "Storage components".
Connection Cache Enter the name of a JDBC connection cache that connects to the database. The cache must have by-name access enabled.
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, EAServer 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".