Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

- Previous: EJB Timer Service
- Next: Using Read-Only Beans

# Using Session Beans

This section provides guidelines for creating session beans in the Application Server environment. This section addresses the following topics:

- About the Session Bean Containers

- Stateful Session Bean Failover

- Restrictions and Optimizations

Extensive information on session beans is contained in the chapters 6, 7, and 8 of the Enterprise JavaBeans Specification, v2.1.

## About the Session Bean Containers

Like an entity bean, a session bean can access a database through JavaTM Database Connectivity (JDBCTM) calls. A session bean can also provide transaction settings. These transaction settings and JDBC calls are referenced by the session bean’s container, allowing it to participate in transactions managed by the container.

A container managing stateless session beans has a different charter from a container managing stateful session beans.

### Stateless Container

The stateless container manages stateless session beans, which, by definition, do not carry client-specific states. All session beans (of a particular type) are considered equal.

A stateless session bean container uses a bean pool to service requests. The Application Server specific deployment descriptor file, `sun-ejb-jar.xml`, contains the properties that define the pool:

- `steady-pool-size`

- `resize-quantity`

- `max-pool-size`

- `pool-idle-timeout-in-seconds`

For more information about `sun-ejb-jar.xml`, see The sun-ejb-jar.xml File.

The Application Server provides the `wscompile` and `wsdeploy` tools to help you implement a web service endpoint as a stateless session bean. For more information about these tools, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

### Stateful Container

The stateful container manages the stateful session beans, which, by definition, carry the client-specific state. There is a one-to-one relationship between the client and the stateful session beans. At creation, each stateful session bean (SFSB) is given a unique session ID that is used to access the session bean so that an instance of a stateful session bean is accessed by a single client only.

Stateful session beans are managed using cache. The size and behavior of stateful session beans cache are controlled by specifying the following `sun-ejb-jar.xml` parameters:

- `max-cache-size`

- `resize-quantity`

- `cache-idle-timeout-in-seconds`

- `removal-timeout-in-seconds`

- `victim-selection-policy`

The `max-cache-size` element specifies the maximum number of session beans that are held in cache. If the cache overflows (when the number of beans exceeds `max-cache-size`), the container then passivates some beans or writes out the serialized state of the bean into a file. The directory in which the file is created is obtained from the EJB container using the configuration APIs.

For more information about `sun-ejb-jar.xml`, see The sun-ejb-jar.xml File.

The passivated beans are stored on the file system. The Session Store Location setting in the EJB container allows the administrator to specify the directory where passivated beans are stored. By default, passivated stateful session beans are stored in application-specific subdirectories created under domain-dir`/session-store`.

Note –

Make sure the `delete` option is set in the `server.policy` file, or expired file-based sessions might not be deleted properly. For more information about `server.policy`, see The server.policy File.

The Session Store Location setting also determines where the session state is persisted if it is not highly available; see Choosing a Persistence Store.

## Stateful Session Bean Failover

An SFSB’s state can be saved in a persistent store in case a server instance fails. The state of an SFSB is saved to the persistent store at predefined points in its life cycle. This is called checkpointing. If SFSB checkpointing is enabled, checkpointing generally occurs after any transaction involving the SFSB is completed, even if the transaction rolls back.

However, if an SFSB participates in a bean-managed transaction, the transaction might be committed in the middle of the execution of a bean method. Since the bean’s state might be undergoing transition as a result of the method invocation, this is not an appropriate instant to checkpoint the bean’s state. In this case, the EJB container checkpoints the bean’s state at the end of the corresponding method, provided the bean is not in the scope of another transaction when that method ends. If a bean-managed transaction spans across multiple methods, checkpointing is delayed until there is no active transaction at the end of a subsequent method.

The state of an SFSB is not necessarily transactional and might be significantly modified as a result of non-transactional business methods. If this is the case for an SFSB, you can specify a list of checkpointed methods. If SFSB checkpointing is enabled, checkpointing occurs after any checkpointed methods are completed.

The following sample application demonstrates SFSB session persistence:

    install-dir/samples/ee-samples/failover/apps/sfsbfailover

The following table lists the types of references that SFSB failover supports. All objects bound into an SFSB must be one of the supported types. In the table, No indicates that failover for the object type might not work in all cases and that no failover support is provided. However, failover might work in some cases for that object type. For example, failover might work because the class implementing that type is serializable.

Table 6–1 Object Types Supported for J2EE Stateful Session Bean State Failover

Java Object Type | Failover Support
--- | ---
Stateless session, stateful session, and entity bean local home reference, local object reference | Yes
Colocated and distributed stateless session, stateful session, and entity bean remote home reference, remote reference | Yes
JNDI Context | Yes, `InitialContext` and `java:comp/env`
UserTransaction | Yes, but if the instance that fails is never restarted, any prepared global transactions are lost and might not be correctly rolled back or committed
JDBC DataSource | No
Java Message Service (JMS) ConnectionFactory, Destination | No
JavaMailTM Session | No
Connection Factory | No
Administered Object | No
Web service reference | No
Serializable Java types | Yes

For more information about the `InitialContext`, see Accessing the Naming Context. For more information about transaction recovery, see Chapter 12, Using the Transaction Service. For more information about Administered Objects, see Creating Physical Destinations.

Note –

Idempotent URLs are supported along the HTTP path, but not the RMI-IIOP path. For more information, see Configuring Idempotent URL Requests and the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

If a server instance to which an RMI-IIOP client request is sent crashes during the request processing (before the response is prepared and sent back to the client), an error is sent to the client. The client must retry the request explicitly. When the client retries the request, the request is sent to another server instance in the cluster, which retrieves session state information for this client.

HTTP sessions can also be saved in a persistent store in case a server instance fails. In addition, if a distributable web application references an SFSB, and the web application’s session fails over, the EJB reference is also failed over. For more information, see Distributed Sessions and Persistence.

If an SFSB that uses session persistence is undeployed while the Application Server instance is stopped, the session data in the persistence store might not be cleared. To prevent this, undeploy the SFSB while the Application Server instance is running.

Configure SFSB failover by:

- Choosing a Persistence Store

- Enabling Checkpointing

- Specifying Methods to Be Checkpointed (optional)

### Choosing a Persistence Store

Two types of persistent storage are supported for passivation and checkpointing of the SFSB state:

- The local file system - Allows a single server instance to recover the SFSB state after a failure and restart. This store also provides passivation and activation of the state to help control the amount of memory used. This option is not supported in a production environment that requires SFSB state persistence. This is the default storage mechanism.

- The high-availability database (HADB) - Allows a cluster of server instances to recover the SFSB state if any server instance fails. The HADB is also used as the passivation and activation store. Use this option in a production environment that requires SFSB state persistence. For information about how to set up and configure this database, see the description of the `configure-ha-cluster` command in the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

Choose the persistence store in one of the following ways:

- To use the local file system, first disable availability. Select the Availability Service component under the relevant configuration in the Administration Console. Uncheck the Instance Level Availability box. Then select the EJB Container component and edit the Session Store Location value. The default is domain-dir`/session-store`.

- To use the HADB, select the Availability Service component under the relevant configuration in the Administration Console. Check the Instance Level Availability box. To enable availability for the EJB container, select the EJB Container Availability tab, then check the Availability Service box.

For more information, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

### Enabling Checkpointing

The following sections describe how to enable SFSB checkpointing:

- Server Instance and EJB Container Levels

- Application and EJB Module Levels

- SFSB Level

#### Server Instance and EJB Container Levels

To enable SFSB checkpointing at the server instance or EJB container level, see Choosing a Persistence Store.

#### Application and EJB Module Levels

To enable SFSB checkpointing at the application or EJB module level during deployment, use the `asadmin deploy` or `asadmin deploydir` command with the `--availabilityenabled` option set to `true`. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

#### SFSB Level

To enable SFSB checkpointing at the SFSB level, set `availability-enabled="true"` in the `ejb` element of the SFSB’s `sun-ejb-jar.xml` file as follows:

    <sun-ejb-jar>
       ...
       <enterprise-beans>
          ...
          <ejb availability-enabled="true">
             <ejb-name>MySFSB</ejb-name>
          </ejb>
       ...
       </enterprise-beans>
    </sun-ejb-jar>

### Specifying Methods to Be Checkpointed

If SFSB checkpointing is enabled, checkpointing generally occurs after any transaction involving the SFSB is completed, even if the transaction rolls back.

To specify additional optional checkpointing of SFSBs at the end of non-transactional business methods that cause important modifications to the bean’s state, use the checkpoint-at-end-of-method element within the `ejb` element in `sun-ejb-jar.xml`.

For example:

    <sun-ejb-jar>
       ...
       <enterprise-beans>
          ...
          <ejb availability-enabled="true">
             <ejb-name>ShoppingCartEJB</ejb-name>
             <checkpoint-at-end-of-method>
                <method>
                   <method-name>addToCart</method-name>
                </method>
             </checkpoint-at-end-of-method>
          </ejb>
          ...
       </enterprise-beans>
    </sun-ejb-jar>

The non-transactional methods in the `checkpoint-at-end-of-method` element can be:

- `create()` methods defined in the home interface of the SFSB, if you want to checkpoint the initial state of the SFSB immediately after creation

- For SFSBs using container managed transactions only, methods in the remote interface of the bean marked with the transaction attribute TX_NOT_SUPPORTED or TX_NEVER

- For SFSBs using bean managed transactions only, methods in which a bean managed transaction is neither started nor committed

Any other methods mentioned in this list are ignored. At the end of invocation of each of these methods, the EJB container saves the state of the SFSB to persistent store.

Note –

If an SFSB does not participate in any transaction, and if none of its methods are explicitly specified in the `checkpoint-at-end-of-method` element, the bean’s state is not checkpointed at all even if `availability-enabled="true"` for this bean.

For better performance, specify a small subset of methods. The methods chosen should accomplish a significant amount of work in the context of the J2EE application or should result in some important modification to the bean’s state.

## Restrictions and Optimizations

This section discusses restrictions on developing session beans and provides some optimization guidelines:

- Optimizing Session Bean Performance

- Restricting Transactions

### Optimizing Session Bean Performance

For stateful session beans, colocating the stateful beans with their clients so that the client and bean are executing in the same process address space improves performance.

### Restricting Transactions

The following restrictions on transactions are enforced by the container and must be observed as session beans are developed:

- A session bean can participate in, at most, a single transaction at a time.

- If a session bean is participating in a transaction, a client cannot invoke a method on the bean such that the `trans-attribute` element in the `ejb-jar.xml` file would cause the container to execute the method in a different or unspecified transaction context or an exception is thrown.

- If a session bean instance is participating in a transaction, a client cannot invoke the `remove` method on the session object’s home or component interface object or an exception is thrown.

- Previous: EJB Timer Service
- Next: Using Read-Only Beans

- © 2010, Oracle Corporation and/or its affiliates