Using Session Beans

This section provides guidelines for creating session beans in the GlassFish Server environment.

The following topics are addressed here:

• About the Session Bean Containers

• Stateful Session Bean Failover

• Session Bean Restrictions and Optimizations

Information on session beans is contained in the Enterprise JavaBeans Specification, v3.1.

About the Session Bean Containers

Like an entity bean, a session bean can access a database through Java Database Connectivity (JDBC) 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.

The following topics are addressed here:

• Stateless Container

• Stateful Container

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 GlassFish Server specific deployment descriptor file, glassfish-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 glassfish-ejb-jar.xml, see The glassfish-ejb-jar.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.

The GlassFish 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 Oracle GlassFish Server 3.1-3.1.1 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 glassfish-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 glassfish-ejb-jar.xml, see The glassfish-ejb-jar.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.

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.

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 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 8-1 Object Types Supported for Java EE Stateful Session Bean State Failover

For more information about the InitialContext, see Accessing the Naming Context. For more information about transaction recovery, see Chapter 15, Using the Transaction Service. For more information about Administered Objects, see Administering JMS Physical Destinations in Oracle GlassFish Server 3.1 Administration Guide.

Configure SFSB failover by:

• Choosing a Persistence Store

• Enabling Checkpointing

• Specifying Methods to Be Checkpointed

Choosing a Persistence Store

The following 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 if availability is not enabled.

• Other servers - Uses other server instances in the cluster for session persistence. Clustered server instances replicate session state. Each backup instance stores the replicated data in memory. This is the default storage mechanism if availability is enabled.

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 Availability Service box. Then select the EJB Container component and edit the Session Store Location value. The default is domain-dir/session-store.

• To use other servers, select the Availability Service component under the relevant configuration in the Administration Console. Check the Availability Service box. To enable availability for the EJB container, select the EJB Container Availability tab, then check the Availability Service box. All instances in an GlassFish Server cluster should have the same availability settings to ensure consistent behavior.

For more information about SFSB state persistence, see the Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide.

Using the --keepstate Option

If you are using the file system for persistence, you can use the --keepstate option of the asadmin redeploy command to retain the SFSB state between redeployments.

The default for --keepstate is false. This option is supported only on the default server instance, named server. It is not supported and ignored for any other target.

Some changes to an application between redeployments prevent this feature from working properly. For example, do not change the set of instance variables in the SFSB bean class.

If any active SFSB instance fails to be preserved or restored, none of the SFSB instances will be available when the redeployment is complete. However, the redeployment continues and a warning is logged.

To preserve active state data, GlassFish Server serializes the data and saves it in memory. To restore the data, the class loader of the newly redeployed application deserializes the data that was previously saved.

For more information about the asadmin redeploy command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

Using the --asyncreplication Option

If you are using replication on other servers for persistence, you can use the --asyncreplication option of the asadmin deploy command to specify that SFSB states are first buffered and then replicated using a separate asynchronous thread. If --asyncreplication is set to true (default), performance is improved but availability is reduced. If the instance where states are buffered but not yet replicated fails, the states are lost. If set to false, performance is reduced but availability is guaranteed. States are not buffered but immediately transmitted to other instances in the cluster.

For more information about the asadmin deploy command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

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 Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

SFSB Level

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

<glassfish-ejb-jar>
   ...
   <enterprise-beans>
      ...
      <ejb availability-enabled="true">
         <ejb-name>MySFSB</ejb-name>
      </ejb>
   ...
   </enterprise-beans>
</glassfish-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 glassfish-ejb-jar.xml.

For example:

<glassfish-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>
</glassfish-ejb-jar>

For details, see checkpoint-at-end-of-method in Oracle GlassFish Server 3.1 Application Deployment Guide.

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

• create methods defined in the home or business 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.

Session Bean Restrictions and Optimizations

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

• Optimizing Session Bean Performance

• Restricting Transactions

• EJB Singletons

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 (or @TransactionAttribute annotation) 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 business interface object, or an exception is thrown.

EJB Singletons

EJB Singletons are created for each server instance in a cluster, and not once per cluster.