What is a Session Bean?

A session bean is an EJB 3.0 or EJB 2.1 enterprise bean component created by a client for the duration of a single client/server session. A session bean performs operations for the client. Although a session bean can be transactional, it is not recoverable should a system failure occur. Session bean objects are either stateless (see "What is a Stateless Session Bean?") or stateful: maintaining conversational state across method calls and transactions (see "What is a Stateful Session Bean?"). If a session bean maintains state, then OC4J manages this state if the object must be removed from memory ("When Does Stateful Session Bean Passivation Occur?"). However, the session bean object itself must manage its own persistent data.

From a client's perspective, a session bean is a nonpersistent object that implements some business logic running on the application server. For example, in an on-line store application, you can use a session bean to implement a ShoppingCartBean that provides a Cart interface that the client uses to invoke such methods as purchaseItem and checkout.

Each client is allocated its own session object. A client does not directly access instances of the session bean's class: a client accesses a session object through the session bean's home ("Implementing the Home Interfaces") and component ("Implementing the Component Interfaces") interfaces. The client of a session bean may be a local client, a remote client, or a Web service client (stateless session bean only), depending on the interface provided by the bean and used by the client.

OC4J maintains a session context for each session bean instance (see "What is Session Context?") that you use to make callback requests to the container.

This section describes the following:

What is a Stateless Session Bean?
What is a Stateful Session Bean?
What is Session Context?

For more information, see the following:

What is a Stateless Session Bean?

A stateless session bean is a session bean with no conversational state. All instances of a particular stateless session bean class are identical.

A stateless session bean and its client do not share state or identity between method invocations. A stateless session bean is strictly a single invocation bean. It is employed for reusable business services that are not connected to any specific client, such as generic currency calculations, mortgage rate calculations, and so on. Stateless session beans may contain client-independent, read-only state across a call. Subsequent calls are handled by other stateless session beans in the pool. The information is used only for the single invocation.

OC4J maintains a pool of these stateless beans to service multiple clients. An instance is taken out of the pool when a client sends a request. There is no need to initialize the bean with any information.

The client of a stateless session bean may be a Web service client. Only a stateless session bean may provide a Web service client view.

For more information, see the following:

What is the Stateless Session Bean Life Cycle?

Figure 1-3 shows the life cycle of a stateless session bean. Annotations (such as @PostConstruct) are applicable to EJB 3.0 stateless session beans only.

Figure 1-3 Stateless Session Bean Life Cycle

Description of "Figure 1-3 Stateless Session Bean Life Cycle"

The life cycle for EJB 3.0 and EBJ 2.1 stateless session beans are identical. The difference is in how you register life cycle callback methods (see Table 1-7 and Table 1-8).

Table 1-7 lists the optional EJB 3.0 stateless session bean life cycle callback methods you can define using annotations. For EJB 3.0 stateless session beans, you do not need to implement these methods.

Table 1-7 Life Cycle Methods for an EJB 3.0 Stateless Session Bean

Annotation	Description
`@PostConstruct`	This optional method is invoked for a stateful session bean before the first business method invocation on the bean. This is at a point after which any dependency injection has been performed by the container.
`@PreDestroy`	This optional method is invoked for a stateful session bean when the instance is in the process of being removed by the container. The instance typically releases any resources that it has been holding.

Table 1-8 lists the EJB 2.1 life cycle methods, as specified in the javax.ejb.SessionBean interface, that a stateful session bean must implement. For EJB 2.1 stateful session beans, you must at the least provide an empty implementation for all callback methods.

Table 1-8 Life Cycle Methods for an EJB 2.1 Stateless Session Bean

EJB Method	Description
`ejbCreate`	The container invokes this method right before it creates the bean. Use this method to initialize nonclient-specific information such as retrieving a data source.
`ejbActivate`	This method is never called for a stateless session bean. Provide an empty implementation only.
`ejbPassivate`	This method is never called for a stateless session bean. Provide an empty implementation only.
`ejbRemove`	The container invokes this method before it ends the life of the stateless session bean. Use this method to perform any required clean-up (for example, closing external resources such as a data source).
`setSessionContext`	The container invokes this method after it first instantiates the bean. Use this method to obtain a reference to the context of the bean. For more information, see "Implementing the setSessionContext Method".

For more information, see the following:

What is a Stateful Session Bean?

A stateful session bean is a session bean that maintains conversational state.

Stateful session beans are useful for conversational sessions, in which it is necessary to maintain state, such as instance variable values or transactional state, between method invocations. These session beans are mapped to a single client for the life of that client.

A stateful session bean maintains its state between method calls. Thus, there is one instance of a stateful session bean created for each client. Each stateful session bean contains an identity and a one-to-one mapping with an individual client.

When the container determines that it must remove a stateful session bean from memory (in order to release resources), the container maintains the bean's state by passivation (serializing the bean to disk). This is why the state that you passivate must be serializable. However, this information does not survive system failures. When the bean instance is requested again by its client, the container activates the previously passivated bean instance.

The type of state that is saved does not include resources. The container invokes the ejbPassivate method within the bean to provide the bean with a chance to clean up its resources, such as sockets held, database connections, and hash tables with static information. All these resources can be reallocated and re-created during the ejbActivate method.

Note:

You can turn off passivation for stateful session beans (see "Configuring Passivation").

If the bean instance fails, the state can be lost, unless you take action within your bean to continually save state. However, if you must make sure that state is persistently saved in the case of failovers, you may want to use an entity bean for your implementation. Alternatively, you could also use the SessionSynchronization interface to persist the state transactionally.

For example, a stateful session bean could implement the server side of a shopping cart on-line application, which would have methods to return a list of objects that are available for purchase, put items in the customer's cart, place an order, change a customer's profile, and so on.

For more information, see the following:

What is the Life Cycle of a Stateful Session Bean?

Figure 1-4 shows the life cycle of a stateful session bean. Annotations (such as @PostConstruct) are applicable to EJB 3.0 stateful session beans only.

Figure 1-4 Stateful Session Bean Life Cycle

Description of "Figure 1-4 Stateful Session Bean Life Cycle"

The life cycle for EJB 3.0 and EBJ 2.1 stateful session beans are identical. The difference is in how you register life cycle callback methods (see Table 1-9 and Table 1-10).

Table 1-9 lists the optional EJB 3.0 stateful session bean life cycle callback methods you can define using annotations. For EJB 3.0 stateful session beans, you do not need to implement these methods.

Table 1-9 Life Cycle Methods for an EJB 3.0 Stateful Session Bean

Annotation	Description
`@PostConstruct`	This optional method is invoked for a stateful session bean before the first business method invocation on the bean. This is at a point after which any dependency injection has been performed by the container.
`@PreDestroy`	This optional method is invoked for a stateful session bean when the instance is in the process of being removed by the container. The instance typically releases any resources that it has been holding.
`@PrePassivate`	The container invokes this method right before it passivates a stateful session bean. For more information, see the following: "When Does Stateful Session Bean Passivation Occur?" "What Object Types can be Passivated?" "Where is a Passivated Stateful Session Bean Stored?"
`@PostActivate`	The container invokes this method right after it reactivates a formerly passivated stateful session bean.

Table 1-10 lists the EJB 2.1 life cycle methods, as specified in the javax.ejb.SessionBean interface, that a stateful session bean must implement. For EJB 2.1 stateful session beans, you must at the least provide an empty implementation for all callback methods.

Table 1-10 Life Cycle Methods for an EJB 2.1 Stateful Session Bean

EJB Method	Description
`ejbCreate`	The container invokes this method right before it creates the bean. Stateless session beans must do nothing in this method. Stateful session beans can initiate state in this method.
`ejbActivate`	The container invokes this method right after it reactivates the bean.
`ejbPassivate`	The container invokes this method right before it passivates the bean. For more information, see the following: "When Does Stateful Session Bean Passivation Occur?" "What Object Types can be Passivated?" "Where is a Passivated Stateful Session Bean Stored?"
`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`	The container invokes this method after it first instantiates the bean. Use this method to obtain a reference to the context of the bean. For more information, see "Implementing the setSessionContext Method".

For more information, see the following:

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 PrePassivate or 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. Only certain object types can be serialized and passivated (see "What Object Types can be Passivated?").

Passivation is enabled by default. For more information on enabling and disabling passivation, see "Configuring Passivation".

OC4J will passivate stateful session beans when any combination of the following criteria is met:

exceed idle timeout;
exceed threshold for maximum number of instances or exceed absolute maximum number of instances;
exceed threshold for maximum JVM memory consumption;
shutdown OC4J instance.

Passivation of beans is performed using the least recently used algorithm: of the beans eligible for passivation, OC4J passivates the least used first.

In addition, you can specify how frequently OC4J checks this criterion and the number of instances to passivate when the criterion is met.

For information on configuring this criterion, see "Configuring Passivation Criteria".

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.

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

A stateful session bean can passivate only certain object types, as designated in "What Object Types can be Passivated?". If you do not prepare your stateful session beans for passivation by releasing all resources and only letting state to exist within the allowed object types, then passivation will always fail.

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

What Object Types can be Passivated?

When a stateful session bean is passivated, it is serialized to secondary storage. To be successful, the conversational state of a bean must consist of only primitive values and the following data types:

serializable object (you do not need to declare the field type as serializable as long as the field is initialized with a subclass of the field type that is serializable);
null;
reference to an EJB business interface;
reference to an EJB remote interface, even if the stub class is not serializable;
reference to an EJB remote home interface, even if the stub class is not serializable;
reference to an EJB local interface, even if it is not serializable;
reference to an EJB local home interface, even if it is not serializable;
reference to the SessionContext object, even if it is not serializable;
reference to the environment naming context (that is, the java:comp/env JNDI context) or any of its subcontexts;
reference to the UserTransaction interface;
reference to resource manager connection factory;
reference to an EntityManager object, even if it is not serializable;
reference to an EntityManagerFactory object, even if it is not serializable;
reference to javax.ejb.Timer object;
An object that is not directly serializable, but becomes serializable by replacing a reference to an EJB business interface, EJB home and component interfaces, the reference to the SessionContext object, the reference to the java:comp/env JNDI context and its subcontexts, the reference to the UserTransaction interface, and the reference to the EntityManager, EntityManagerFactory, or both by serializable objects during the object's serialization.

You are responsible for ensuring that all nontransient fields are of these types after the PrePassivate method (see "Configuring a Life Cycle Callback Interceptor Method on an EJB 3.0 Session Bean") or ejbPassivate method (see "Configuring a Life Cycle Callback Method for an EJB 2.1 Session Bean") completes. Within this method, you must set all transient or nonserializable fields to null.

Where is a Passivated Stateful Session Bean Stored?

By default, when OC4J passivates a stateful session bean, it writes the serialized instance to <OC4J_HOME>\j2ee\home\persistence.

Passivation uses space within this directory to store the passivated beans. 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 (see "Configuring Passivation Location").

What is Session Context?

OC4J maintains a javax.ejb.SessionContext for each session bean instance and makes this session context available to the beans. The bean may use the methods in the session context to make callback requests to the container. In addition, you can use the methods inherited from EJBContext (see "What is EJB Context?").

For more information, see the following:

OC4J initializes the session context after it first instantiates the bean. It is the bean provider's responsibility to enable the bean to retrieve the session context. The container will never call this method from within a transaction context. If the bean does not save the session context at this point, the bean will never gain access to the session context.

When the container calls this method, it passes the reference of the SessionContext object to the bean. The bean can then store the reference for later use.

If the session bean instance stores in its conversational state an object reference to the SessionContext (either with a setSessionContext method or using resource injection), OC4J can save and restore the reference across the instance's passivation. OC4J can replace the original SessionContext object with a different and functionally equivalent SessionContext object during activation.

Note:

OC4J does not support SessionContext method getInvokedBusinessInterface. If you call this method, OC4J throws an UnsupportedOperationException.