Chapter 29 Managing Persistent Component State

Persistence for entity components

An entity component is an EJB entity Bean or a component of another type that implements the CtsComponents::ObjectControl interface. Entity components present an object view of relational data to clients; each instance of an entity component maps to a row in a database relation.

Entity components can be EJB entity Beans implemented according to the EJB 1.0 or 1.1 standard (see Chapter 8, "Creating Enterprise JavaBean Components"). You can also implement CORBA entity components by following these requirements:

Use CtsComponents::ObjectControl as the component's control interface.
Define a primary key type for the component. See "Allowable primary key types" for more information.
Create a home interface for the component with a findByPrimaryKey method and, optionally, additional finder and create methods. See "Patterns for finder methods" for more information.

For an entity component, you can manage persistence using these techniques:

Component managed In this technique, you implement the code that reads and writes persistent data and maps the relational column values to fields in the implementation class. This model corresponds to the Bean Managed Persistence model required by the EJB 1.1 specification, but has been extended to support other component types.
Automatic persistence In this technique, Jaguar server manages the storage and retrieval of persistent data.
Generated class In this technique, a generated C++ or Java class saves and restores component state from a remote database. Jaguar Manager does not generate such classes, but third-party tool vendors can use this option. The generated class can inherit from or delegate to the component's implementation class to save and restore component state.

Using component-managed persistence

To use component-managed persistence, you must configure the component's persistence properties and implement the required methods from the EntityBean or CtsComponents::ObjectControl interfaces. Display the Component Properties window in Jaguar Manager and configure the following fields on the Persistence tab:

Persistence Choose Component Class.
Primary Key Enter the name of the primary key type (see "Allowable primary key types").

In most cases, no other persistence settings are required. You can delegate to Jaguar's built-in storage components rather than implementing your own database access code. If you do so, configure the Storage Component, Connection Cache, and Table fields (see "Storage components"). Delegation requires that you use the CtsComponents::DataStream and CtsComponents::Storage interfaces. See the generated Interface Repository documentation on your Jaguar server (in the html/ir subdirectory) for descriptions of these interfaces.

Using automatic persistence

When using automatic persistence, Jaguar manages all interaction with the remote database. There are two options for database storage when using automatic persistence:

Using mapped fields In the mapped table model, you define a mapping from a database table to fields in your component implementation class. When a write to the database is required, Jaguar server reads the field values; after reading new data from the database, Jaguar assigns new field values for each mapped database column. This model corresponds to the Container Managed Persistence model required by the EJB 1.1 specification, but has been extended to support other component types.
Using binary storage In this model, you define state-accessor methods and an IDL state type. Jaguar calls your state-accessor methods before writing data to the database and after reading from the database. The state data is stored in an encoded binary form. Because the relational data is encoded, this model does not support finder methods other than findByPrimaryKey.

Identifying the storage technique The component uses mapped field storage if the value of the Table field on the Persistence tab begins with map: , for example, map:MyTable .

To configure automatic persistence:

Configure Persistence tab properties

Display the Component Properties window in Jaguar Manager and configure the following fields on the Persistence tab:

Persistence Choose Automatic Persistent State.
Primary Key Enter the name of the primary key type (see "Allowable primary key types"). If you have imported an EJB entity Bean, the primary key has been defined already.
State Enter the name of an IDL structure or serializable Java class that stores component state. If you have imported an EJB entity Bean, the state has been defined already. The structure or class must have one field for each field in the component that is to be stored in the database, excluding fields that are part of the primary key. If you are using mapped table fields, use the same field names in the State type as used in your component implementation. Fields for an IDL structure can use any type listed in "Supported Java, IDL, and JDBC/SQL types".
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 If you are creating an EJB entity Bean, enter "default". If you are creating an entity component of another type, 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;
}
```
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 If using mapped table fields, enter:
```
map:table
```
Where table is the database table name. If you are using binary storage, simply enter the table name.

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.

For mapped tables, the table column types must agree with the mapped fields. "Supported Java, IDL, and JDBC/SQL types" lists the supported JDBC/SQL types and the corresponding Java and IDL field types.

For binary storage, "Table schema for binary storage" describes the required table schema.
Timestamp When you are using mapped table fields, the Timestamp setting determines how the server uses optimistic concurrency control to prevent overlapping updates to the same column. Specify one of the following:
- A column name The name of a column in the mapped table that serves as a timestamp. By default, Jaguar uses a 4-byte integer timestamp and explicitly increments the value with each update. You can also use a 16-byte binary value, for which Jaguar generates globally unique 16-byte ID values. To use 16-byte binary timestamps, you must set the com.sybase.jaguar.component.ts.length property to binary(16) .
- "None" Enter "none" to disable optimistic concurrency control. This setting is not recommended.
- No value If you leave the Timestamp field blank, Jaguar uses all column values to perform optimistic concurrency control.
For best performance, use a 4-byte integer timestamp column. The timestamp column need not be mapped to the component's persistent state fields. Other processes that update the mapped table must increment the timestamp with each update.

Specify field to column mapping properties

If the table's primary key maps to a single field in the implementation class (which must be the same type as the component's primary key), display the All Properties tab and configure the properties in the following table:

Table 29-1:
Property name	Value
mapField:[key] (For single-column keys only.)	The database column name.
`com.sybase.jaguar. component.key.field`	The name of the component field that the key maps to.

To map database fields to columns, display the All Properties tab and define properties to map database columns to fields in the implementation class, using the name/value patterns listed in the table below:

Table 29-2: Mapping database columns to class fields
For columns of this type	Property name	Value
Key fields (enter one property for each key field)	mapField:field[key] Where field is the name of the field in the implementation class that this key column maps to.	The database column name.
Non-key fields (enter one property for each field)	mapField:field Where field is the name of the field that this key column maps to.	The database column name.

You can optionally append a SQL type name to column names, in square brackets. For example, to specify the column type must be varbinary(1024), enter:

icon[varbinary(1024)]

The type name is used during automatic table creation. This feature is useful when a Java type can map to multiple SQL types; in that case, Jaguar defaults to the type with minimal storage requirements when creating the table. Varchar columns default to 100 bytes length, and varbinary columns default to 255 bytes. Specify a type name to override the default.

Specify finder-method queries

Each finder method in the component's home interface requires a database query to select a set of primary keys. For example, the findByPrimaryKey method selects the key that matches the input parameter. A findAll method might return all keys in the table.

Jaguar can correctly infer the query required to execute the findByPrimaryKey method. For other finder methods, you must enter properties to specify the query. Display the All Properties tab and define new properties for each finder method. Name each property mapQuery:method , where method is the finder method name. For the value, enter a query to select primary key values with a filter appropriate for the semantics of the finder method. You can use the following placeholders to represent column and table names and parameter values:

Placeholder	To indicate
[key]	The table's primary key (which can consist of multiple columns).
[table]	The name of the table.
@param	Reference the value of parameter param in the finder method's IDL signature. If the component was imported from an EJB JAR file, the parameter names will not match those in the original Java implementation. Instead, they are p0, p1, and so forth.
@param.fieldName	If method parameter param is not a simple type, reference the value of field fieldName.

The following are examples of queries using placeholders. This query returns all rows in a table:

select [key] from [table]

This query uses the value of the expiryDate parameter to filter a range of closingDate column values:

select [key] from [table] where closingDate < @expiryDate