When Does Stateful Session Bean Passivation Occur?

Passivation enables the container to preserve the conversational state of an inactive idle bean instance by serializing the bean and its state into a secondary storage and removing it from memory. Before passivation, the container invokes the ejbPassivate() method enabling the bean developer to clean up held resources, such as database connections, TCP/IP sockets, or any resources that cannot be transparently passivated using object serialization. The object types that can be serialized and passivated are listed at the end of this section.

Note: OC4J passivates only stateful session beans. Stateless session beans have no state to passivate and entity beans should have their state saved within the database.

When a client invokes one of the methods of the passivated bean instance, the preserved conversational state data is activated, by de-serializing the bean from secondary storage and brought back into memory. Before activation, the container invokes the ejbActivate() method so that the bean developer can restore the resources released during ejbPassivate(). For more information on passivation, see the EJB specification.

Passivation is enabled by default. You can turn off passivation for stateful session beans by setting the <sfsb-config> element in the server.xml file to false. A stateful session bean can passivate only certain object types, as designated in "Object Types Enabled for Passivation". If you do not prepare your stateful session beans for passivation by releasing all resources and only allowing state to exist within the allowed object types, then passivation will fail everytime. If you do not want to change your object types and do not mind not passivating the object, you can disable passivation. In another case, you may want to disable passivation for performance reasons: passivation carries an overhead with it, and if you desire speed and are not really worried about resources, then you can turn passivation off.

An example of how to turn off passivation is as follows:

<sfsb-config enable-passivation="false"/>

Note: See the <sfsb-config> element defined in the server.xml section of the Oracle Application Server Containers for J2EE User's Guide appendix for more information.

Passivation is invoked based on any combination of the following criteria:

• idle timeout expires

  You can set an idle timeout in seconds for each bean. When this timeout expires, passivation occurs. Set the idletime attribute in <session-deployment> to the appropriate number of seconds. Default: 300 seconds. (5 minutes). To disable, specify "never."

• out of resources

  Each of the following attributes in <session-deployment> define resource thresholds, when to check for those thresholds, and number of beans to passivate when the threshold is met.

  • memory-threshold - This attribute defines a threshold for how much used JVM memory is allowed before passivation should occur. Specify an integer that is translated as a percentage. When reached, beans are passivated, even if their idle timeout has not expired. Default: 80%. To disable, specify "never."

  • max-instances-threshold - This attribute defines a threshold for how many active beans exist in relation to the max-instances attribute definition. Specify an integer that is translated as a percentage. For example, if you define that the max-instances is 100 and the max-instances-threshold is 90%, then when the active bean instances reaches past 90, passivation of beans occurs. Default: 90%. To disable, specify "never."

  • resource-check-interval - The container checks all resources at this time interval. At this time, if any of the thresholds have been reached, passivation occurs. Default: 180 seconds (3 minutes). To disable, specify "never."

  • passivate-count - This attribute is an integer that defines the number of beans to be passivated if any of the resource thresholds have been reached. Passivation of beans is performed using the least recently used algorithm. Default: one-third of the max-instances attribute. You can disable this attribute by setting the count to zero or a negative number.

• The number of bean instances allowed is reached

  This number is set within the <session-deployment> max-instances attribute. The max-instances attribute controls the number of bean instances allowed in memory. When this value is reached, the container attempts to passivate the oldest bean instance from memory. If unsuccessful, the container waits the number of milliseconds set in the call-timeout attribute to see if a bean instance is removed from memory, either thru another passivation, calling the bean remove() method, or bean expiration, before a TimeoutExpiredException is thrown back to the client. Leave the max-instances value at zero to allow an infinite number of bean instances. Default is 0, which is infinite.

• OC4J instance termination

  All bean instances in the container's memory that are not passivated are serialized to the secondary storage. Upon OC4J start-up, these passivated beans are restored back to memory.

If the passivation serialization fails, then the container attempts to recover the bean back to memory as if nothing happened. No future passivation attempts will occur for any beans that fail passivation. Also, if activation fails, the bean and its references are completely removed from the container.

If new bean data is propagated to a passivated bean in a cluster, then the bean instance data is overwritten by the propagated data.

Object Types Enabled for Passivation

For serialization (during passivation) to the secondary storage to be successful, the conversational state of a bean must consist of only primitive values and the following special types:

• serializable objects

• null

• a reference to a component interface (EJBObject or EJBLocalObject)

• a reference to a home interface (EJBHome or EJBLocalHome)

• a reference to the SessionContext object

• a reference to the environment naming context

• a reference to the UserTransaction interface

• a reference to a resource manager connection factory

The bean developer is responsible for ensuring that all fields are of these types within the ejbPassivate() method. Any transient or non-serializable field should be set to null in this method.

Storage of Passivated EJBs

When OC4J passivates the stateful session bean, it is placed in the directory and filename designated by the persistence-filename attribute of the <session-deployment> element in the OC4J deployment descriptor. Passivation uses space within this directory to store the passivated beans. The default is the application-deployments/persistence directory. If passivation allocates large amounts of disk space, you may need to change the directory to a place on your system where you have the space available or turn off passivation.