12 Using EJB 2.1 Session Bean API

This chapter describes the various options that you must configure in order to use an EJB 2.1 session bean.

Table 12-1 lists these options and indicates which are basic (applicable to most applications) and which are advanced (applicable to more specialized applications).

For more information, see:

Table 12-1 Configurable Options for an EJB 2.1 Session Bean

Options	Type
"Configuring Passivation"	Advanced
"Configuring Passivation Criteria"	Advanced
"Configuring Passivation Location"	Advanced
"Configuring Bean Instance Pool Size"	Basic
"Configuring Bean Instance Pool Timeouts for Session Beans"	Advanced
"Configuring a Transaction Timeout for a Session Bean"	Advanced
"Configuring a Lifecycle Callback Method for an EJB 2.1 Session Bean"	Basic

Configuring Passivation

You can enable and disable passivation for stateful session beans (see "Using Deployment XML").

You may choose to disable passivation for any of the following reasons:

Incompatible object types: if you cannot represent the non-transient attributes of your stateful session bean with object types supported by passivation (see "What Object Types Can Be Passivated?"), you can exchange increased memory consumption for the use of other object types by disabling passivation.
Performance: if you determine that passivation is a performance problem in your application, you can exchange increased memory consumption for improved performance by disabling passivation.
Secondary storage limitations: if you cannot provide sufficient secondary storage (see "Configuring Passivation Location"), you can exchange increased memory consumption for reduced secondary storage requirements by disabling passivation.

For more information, see:

Using Deployment XML

Table 12-2 lists the attributes, values, and defaults for configuring passivation in the server.xml file element sfsb-config.

Table 12-2 server.xml Element sfsb-config Passivation Configuration

Attribute	Values	Default
enable-passivation	"true", "false"	"true"

Configuring Passivation Criteria

You can specify under what conditions OC4J passivates a stateful session bean (see "Using Deployment XML").

For more information, see:

Using Deployment XML

Table 12-3 lists the attributes, values, and defaults for configuring passivation criteria in the orion-ejb-jar.xml file element session-deployment.

Table 12-3 orion-ejb-jar.xml Element session-deployment Passivation Criteria

Attribute	Values	Default
idletime	Positive, integer number of seconds before passivation occurs. To disable this criteria, specify a value of "never".	"300"
memory-threshold	Percentage of JVM memory that can be consumed before passivation occurs. To disable this criteria, specify a value of "never".	"80"
max-instances	Maximum positive integer number of bean instances allowed in memory—either instantiated or pooled. When this value is reached, OC4J attempts to passivate beans using the least recently used (LRU) algorithm. To allow an infinite number of bean instances, the `max-instances` attribute can be set to zero. Default is 0, which means infinite. This applies to both stateless and stateful session beans. To disable instance pooling, set `max-instances` to any negative number. This will create a new instance at the start of the EJB call and release it at the end of the call. See "Configuring Bean Instance Pool Size" for more information.	"0" (unlimited)
max-instances-threshold	Percentage of `max-instances` number of beans that can be in memory before passivation occurs. Specify an integer that is translated as a percentage. If you define that the `max-instances` is 100 and the `max-instances-threshold` is 90%, then when the active bean instances is greater than or equal to 90, passivation of beans occurs. Default: 90%. To disable, specify "never."	"90"
passivate-count	Positive, integer number of beans to be passivated if any of the resource thresholds (`memory-threshold` or `max-instances-threshold`) have been reached. Passivation of beans is performed using the least recently used algorithm. To disable this option, specify a value of "0".	One-third of `max-instances`
resource-check-interval	The frequency, as a positive, integer number of seconds, at which OC4J checks resource thresholds (`memory-threshold` or `max-instances-threshold`). To disable this option specify a value of "never".	"180"

Configuring Passivation Location

You can specify the directory and file name to which OC4J serializes a stateful session bean when passivated (see "Using Deployment XML").

For more information, see:

Using Deployment XML

Table 12-4 lists the attributes, values, and defaults for configuring passivation location in the orion-ejb-jar.xml file element session-deployment.

Table 12-4 orion-ejb-jar.xml Element session-deployment Passivation Location Configuration

Attribute	Values	Default
persistence-filename	Fully qualified path and file name of the file into which OC4J serializes bean instances during passivation.	`<OC4J_HOME>\j2ee\home\application-deployments\persistence`.

Configuring a Lifecycle Callback Method for an EJB 2.1 Session Bean

Table 12-5 lists the EJB 2.1 session bean callback methods you can specify (see "Using Java").

Table 12-5 EJB 2.1 Session Bean Lifecycle Callback Methods

Method	Description
`ejbCreate`	The container invokes this method to create an instance of the bean.
`ejbActivate`	The container invokes this method right after it reactivates the bean.
`ejbPassivate`	The container invokes this method right before it passivates the bean. You can turn off passivation for stateful session beans (see "Configuring Passivation").
`ejbRemove`	A container invokes this method before it ends the life of the session object. This method performs any required clean-up—for example, closing external resources such as file handles.
`setSessionContext`	This method associates a bean instance with its context information. The container calls this method after the bean creation. The enterprise bean can store the reference to the context object in an instance variable, for use in transaction management. Beans that manage their own transactions can use the session context to get the transaction context.

Session bean callback method signatures are defined in the javax.ejb.SessionBean interface.

Note:

Using EJB 2.1, you must implement all session bean callback methods. If you do not need to take any action, implement an empty method.

For more information, see "Callback Methods".

Using Java

Example 12-1 shows how to implement an EBJ 2.1 session bean callback method.

Example 12-1 EJB 2.1 Session Bean Callback Method Implementation

public void ejbActivate()
{
    // when bean is activated
}