This section describes how session beans work within the EJB container, and provides design and development guidelines that are specific to session beans. For a description of the overall bean development process, see Implementing Enterprise Java Beans.
It is assumed that the reader is familiar with Java programming and session bean features and capabilities. For an introduction to session bean features and how they are typically used in applications, see Session EJBs Implement Business Logic and Session Bean Features.
The following sections describe the session bean life-cycle, design considerations, and instructions for key implementation tasks.
This section compares the key differences between stateless and stateful session beans.
Table 5-1 Comparing Stateless and Stateful Session Beans
Stateless Session Beans | Stateful Sessions Beans |
---|---|
Are pooled in memory, to save the overhead of creating a bean every time one is needed. WebLogic Server uses a bean instance when needed and puts it back in the pool when the work is complete. Stateless sessions beans provide faster performance than stateful beans. |
Each client creates a new instance of a bean, and eventually removes it. Instances may be passivated to disk if the cache fills up. An application issues an Stateful sessions beans do not perform as well as stateless sessions beans. |
Have no identity and no client association; they are anonymous. |
Are bound to particular client instances.Each bean has an implicit identity. Each time a client interacts with a stateful session bean during a session, it is the same object. |
Do not persist. The bean has no state between calls. |
Persist. A stateful session bean's state is preserved for the duration of a session. |
See Choosing Between Stateless and Stateful Beans for a discussion of when to use which type of session bean.
By default, no stateless session EJB instances exist in WebLogic Server at startup time. As individual beans are invoked, WebLogic Server initializes new instances of the EJB.
However, in a production environment, WebLogic Server can provide improved performance and throughput for stateless session EJBs by maintaining a free pool of unbound stateless session EJBs—instances that are not currently processing a method call. If an unbound instance is available to serve a request, response time improves, because the request does not have to wait for an instance to be created. The free pool improves performance by reusing objects and skipping container callbacks when it can.
Upon startup, WebLogic Server automatically creates and populates the free pool with the quantity of instances you specify in the bean's initial-beans-in-free-pool
deployment element in the weblogic-ejb-jar.xml
file. By default, initial-beans-in-free-pool
is set to 0.
Additionally, in this release of WebLogic Server, Administrators can initialize EJB pools on demand via the Administration Console. When an EJB's pool is initialized, it is reset to the state it was in immediately after the EJB was deployed. For more information, see "Initialize the idle bean cache and pool of an EJB" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
The following figure illustrates the WebLogic Server free pool, and the processes by which stateless EJBs enter and leave the pool. Dotted lines indicate the "state" of the EJB from the perspective of WebLogic Server.
Figure 5-1 WebLogic Server Free Pool Showing Stateless Session EJB Life Cycle
If you configure a pool, WebLogic Server will service method calls with an EJB instance from the free pool, if one is available. The EJB remains active for the duration of the client's method call. After the method completes, the EJB instance is returned to the free pool. Because WebLogic Server unbinds stateless session beans from clients after each method call, the actual bean class instance that a client uses may be different from invocation to invocation.
If all instances of an EJB class are active and max-beans-in-free-pool
has been reached, new clients requesting the EJB class will be blocked until an active EJB completes a method call. If the transaction times out (or, for non-transactional calls, if five minutes elapse), WebLogic Server throws a RemoteException
for a remote client or an EJBException
for a local client.
Note:
The maximum size of the free pool is limited by the value of themax-beans-in-free-pool
element, available memory, or the number of execute threads.You can configure the WebLogic Server to remove bean instances that have remained unused in the pool for a period of time specified in idle-timeout-seconds
element in the pool
element. When beans have been in the pool unused for the amount of time you specify in idle-timeout-seconds
, they are removed from the pool until the number of beans in the pool reaches the number specified in initial-beans-in-free-pool
; the number of beans in the pool will never fall below the number specified in initial-beans-in-free-pool
.
When an application requests a bean instance from the free pool, there are three possible outcomes:
An instance is available in the pool. WebLogic Server makes that instance available and your application proceeds with processing.
No instance is available in the pool, but the number of instances in use is less than max-beans-in-free-pool
. WebLogic Server allocates a new bean instance and gives it to you.
No instances are available in the pool and the number of instances in use is already max-beans-in-free-pool
. Your application must wait until either your transaction times out or a bean instance that already exists in the pool becomes available.
WebLogic Server uses a cache of bean instances to improve the performance of stateful session EJBs. The cache stores active EJB instances in memory so that they are immediately available for client requests. The cache contains EJBs that are currently in use by a client and instances that were recently in use. Stateful session beans in cache are bound to a particular client.
The following figure illustrates the WebLogic Server cache, and the processes by which stateful EJBs enter and leave the cache.
Figure 5-2 Stateful Session EJB Life Cycle
No stateful session EJB instances exist in WebLogic Server at startup. Before a client begins accessing a stateful session bean, it creates a new bean instance to use during its session with the bean. When the session is over the instance is destroyed. While the session is in progress, the instance is cached in memory.
Passivation is the process by which WebLogic Server removes an EJB instance from cache while preserving its state on disk. While passivated, EJBs are not in memory and are not immediately available for client requests, as they are when in the cache.
The EJB developer must ensure that a call to the ejbPassivate()
method leaves a stateful session bean in a condition such that WebLogic Server can serialize its data and passivate the instance. During passivation, WebLogic Server attempts to serialize any fields that are not declared transient
. This means that you must ensure that all non-transient
fields represent serializable objects, such as the bean's remote or home interface. EJB 2.1 specifies the field types that are allowed.
The rules that govern the passivation of stateful session beans vary, based on the value of the beans cache-type
element, which can be:
LRU
—least recently used, or eager passivation.
NRU
—not recently used, or as lazy passivation
The idle-timeout-seconds
and max-beans-in-cache
elements also affect passivation and removal behaviors, based on the value of cache-type
.
When you configure eager passivation for a stateful session bean by setting cache-type
to LRU
, the container passivates instances to disk:
As soon as an instance has been inactive for idle-timeout-seconds
, regardless of the value of max-beans-in-cache
.
When max-beans-in-cache
is reached, even though idle-timeout-seconds
has not expired.
The container removes a passivated instance from disk after it has been inactive for idle-timeout-seconds
after passivation. This is referred to as a lazy remove.
Note:
ejbRemove
may not be called on bean instances that are deleted after idle-timeout-seconds
is reached.When lazy passivation is configured by setting cache-type
to NRU
, the container avoids passivating beans, because of the associated systems overhead—pressure on the cache is the only event that causes passivation or eager removal of beans.
When the cache is full and a bean instance must be removed from the cache to make room for another instance, the container:
Note:
ejbRemove
may not be called on bean instances that are deleted after idle-timeout-seconds
is reached.Removes the bean instance from the cache without passivating it to disk if idle-timeout-seconds
has expired. This is referred to as a eager remove. An eager remove ensures that an inactive instance does not consume memory or disk resources.
Passivates the bean instance to disk if idle-timeout-seconds
has not expired.
When a stateful session bean is passivated, its state is stored in a file system directory. Each server instance has its own directory for storing the state of passivated stateful session beans, known as the persistent store directory. The persistent store directory contains one subdirectory for each passivated bean.
The persistent store directory is created by default in the server instance directory, for example:
D:\releases\<version>\bea\user_domains\mydomain\myserver\pstore\
The path to the persistence store is:
RootDirectory\ServerName\persistent-store-dir
where:
RootDirectory
—the directory where WebLogic Server runs.
RootDirectory
can be specified at server startup with the -Dweblogic.RootDirectory
property.
ServerName
—the name of the server instance.
persistent-store-dir
—the value of the of the persistent-store-dir
element in the <stateful-session-descriptor>
element of weblogic-ejb-jar.xml
. If no value is specified for <persistent-store-dir>
, the directory is named pstore
by default.
The persistent store directory contains a subdirectory, named with a hash code, for each passivated bean. For example, the subdirectory for a passivated bean in the example above might be:
D:\releases\810\bea\user_domains\mydomain\myserver\pstore\14t89gex0m2fr
In accordance with the EJB 2.x specification, simultaneous access to a stateful session EJB results in a RemoteException
. This access restriction on stateful session EJBs applies whether the EJB client is remote or internal to WebLogic Server. To override this restriction and configure a stateful session bean to allow concurrent calls, set the allow-concurrent-calls
deployment element.
If multiple servlet classes access a stateful session EJB, each servlet thread (rather than each instance of the servlet class) must have its own session EJB instance. To prevent concurrent access, a JSP/servlet can use a stateful session bean in request scope.
This section discusses some design decisions relevant to session beans.
Stateless session beans are a good choice if your application does not need to maintain state for a particular client between business method calls. WebLogic Server is multi-threaded, servicing multiple clients simultaneously. With stateless session beans, the EJB container is free to use any available, pooled bean instance to service a client request, rather than reserving an instance for each client for the duration of a session. This results in greater resource utilization, scalability and throughput.
Stateless session beans are preferred for their light-weight implementation. They are a good choice if your application's beans perform autonomous, distinct tasks without bean-to-bean interaction.
Stateful session beans are a good choice if you need to preserve the bean's state for the duration of the session.
For examples of applications of stateless and stateful session beans, see Stateless Session Beans and Stateful Session Beans.
When you choose values for initial-beans-in-free-pool
and max-beans-in-free-pool
you must weigh memory consumption against slowing down your application. If the number of stateless session bean instances is too high, the free pool contains inactive instances that consume memory. If the number is too low, a client may not obtain an instance when it needs it. This leads to client threads blocking until an instance frees up, slowing down the application.
Usually max-beans-in-free-pool
should be equal to the number of worker threads in the server instance, so that when a thread tries to do work an instance is available.
Chapter 4 takes you through session bean implementation step-by-step. This section explains the details of configuring WebLogic-Server specific session bean behavior by setting bean-specific deployment descriptor elements.
Table 5-2 summarizes the deployment descriptor elements you set to configure the behavior of a stateless session bean and how the bean behaves if you do not configure the element. All of the elements listed are sub-elements of the stateless-session-descriptor
element in weblogic-ejb-jar.xml
.
Table 5-3 summarizes the deployment descriptor elements you set to configure the behavior of a stateful session bean and how the bean behaves if you do not configure the element. All of the elements listed are sub-elements of the stateful-session-descriptor
element in weblogic-ejb-jar.xml
.
Table 5-2 WebLogic-Specific Features for Stateless Session EJBs
To control | Set the following weblogic-ejb-jar.xml element | Default behavior |
---|---|---|
The number of inactive instances of a stateless session bean that exist in WebLogic Server when it is started. |
WebLogic Server creates 0 beans in the free pool. |
|
The number of seconds a bean can be idle in the pool before WebLogic Server can remove it. Note: Idle beans can only be removed from the pool until the number of beans in the pool reaches |
WebLogic Server removes beans from the free pool when they have been idle for 600 seconds. |
|
The maximum size of the free pool of inactive stateless session beans. |
WebLogic Server limits the maximum number of beans in the free pool to 1000. |
|
How WebLogic Server replicates stateless session EJB instances in a cluster. |
The EJB can be deployed to multiple servers in a cluster. |
Table 5-3 WebLogic-Specific Features for Stateful Session EJBs
Behavior | weblogic-ejb-jar.xml element | Default |
---|---|---|
Whether multiple clients can simultaneously access a bean without triggering a See Configuring Concurrent Access to Stateful Session Beans. |
False—The server throws a |
|
Whether the EJB container can remove a stateful session bean within a transaction context without provoking an error. |
False—The server throws an exception when a stateful session bean is removed within a transaction context. |
|
The number of stateful been instances that can exist in cache. |
1000 |
|
The period of inactivity before a stateful session bean instance remains in cache (given that |
600 seconds |
|
The rules for removing a stateful session bean instance from the cache. |
NRU (not recently used)—For a description of this behavior, see Lazy Passivation (NRU). |
|
Where WebLogic Server stores the state of passivated stateful session bean instances. |
|
|
To support method failover, specify the idempotent methods for a clustered EJB. An idempotent method can be repeated with no negative side-effects. |
None |
|
Custom class to be used for routing home method calls. |
None |
|
Indicates if the bean home can be clustered. |
True |
|
Algorithm to use for load-balancing among replicas of the bean home. |
Algorithm specified by the property |
|
Indicates the replication used for stateful session beans in a cluster: in-memory or none. |
None |