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.
Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide.
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 9–1 Object Types Supported for Java EE Stateful Session Bean State Failover
Java Object Type |
Failover Support |
---|---|
Colocated or distributed stateless session, stateful session, or entity bean 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 |
JavaMail Session |
No |
Connection Factory |
No |
Administered Object |
No |
Web service reference |
No |
Serializable Java types |
Yes |
Extended persistence context |
No |
For more information about the InitialContext, see Accessing the Naming Context. For more information about transaction recovery, see Chapter 16, Using the Transaction Service. For more information about Administered Objects, see Creating Physical Destinations.
Idempotent URLs are supported along the HTTP path, but not the RMI-IIOP path. For more information, see Configuring Idempotent URL Requests.
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 Enterprise Server instance is stopped, the session data in the persistence store might not be cleared. To prevent this, undeploy the SFSB while the Enterprise Server instance is running.
Configure SFSB failover by:
Specifying Methods to Be Checkpointed (optional)
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.
Other servers - Uses other server instances in the cluster for session persistence. Clustered server instances replicate session state in a ring topology. Each backup instance stores the replicated data in memory.
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 GlassFish Enterprise Server 2.1 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 Admin 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 Admin 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 Enterprise Server cluster should have the same availability settings to ensure consistent behavior.
To use the HADB, you must first have the HADB installed and the enterprise profile selected. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide. For information about HADB, see the description of the configure-ha-cluster command in the Sun GlassFish Enterprise Server 2.1 Reference Manual. Then you must enable availability as described in the previous item.
For more information, see the Sun GlassFish Enterprise Server 2.1 High Availability Administration Guide.
The following sections describe how to enable SFSB checkpointing:
To enable SFSB checkpointing at the server instance or EJB container level, see Choosing a Persistence Store.
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 GlassFish Enterprise Server 2.1 Reference Manual.
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>
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>
For details, see checkpoint-at-end-of-method in Sun GlassFish Enterprise Server 2.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.
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 Java EE application or should result in some important modification to the bean’s state.