Session EJBs
Contents
- Stateless Versus Stateful Session Beans
- Pooling and Caching for Stateless Session EJBs
- Caching for Stateful Session EJBs
- Design Decisions for Session Beans
- Implementing Session Beans
See Also
- Understanding Session EJBs
- Session Beans Best Practices
- Implementing Enterprise Java Beans
- Choosing Between Stateless and Stateful Beans
Stateless Versus Stateful Session Beans
Pooling and Caching for Stateless Session EJBs
WLS uses a free pool that stores unbound stateless session EJBs, improving performance by reusing objects and skipping container callbacks.
To improve response time, WLS can create a free pool of unbound stateless session EJBs during startup by setting the initial-beans-in-free-pool element in weblogic-ejb-jar.xml. By default, initial-beans-in-free-pool is set to 0.
If you configure a pool, WLS 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 WLS 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), WLS throws a RemoteException for a remote client or an EJBException for a local client. Note that the maximum size of the free pool is limited by the value of the max-beans-in-free-pool element, available memory, or the number of execute threads.
When an application requests a bean instance from the free pool, there are three possible outcomes:
- An instance is available in the pool. WLS 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 then max-beans-in-free-pool. WLS 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. You application must wait until either your transaction times out or a bean instance that already exists in the pool becomes available.
Caching for Stateful Session EJBs
WLS 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. Active EJBs consist of instances that are currently in use by a client, as well as instances that were recently in use.
Stateful Session EJB Creation
No stateful session EJB instances exist in WLS at startup time. 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 instances is cached in memory.
Stateful Session EJB Passivation
Passivation is the process by which WLS 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 where WLS can serialize its data and passivate the bean's instance. During passivation, WLS attempts to serialize any fields that are not declared transient. EJB 2.1 specifies the field types that are allowed.
Controlling Passivation
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, referred to as eager passivation.
- NRU - not recently used, referred to 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.
Eager Passivation (LRU)
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.
- 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.
Lazy Passivation (NRU)
When lazy passivation is configured by setting cache-type to NRU, the container avoids passivating beans, because of the associated systems overhead. The container:
- Removes a bean instance from cache when idle-timeout-seconds expires, and does not passivate it to disk. This is referred to as a eager remove. An eager remove ensures that an inactive instance does not consume memory or disk resources.
- Passivates instances to disk when max-beans-in-cache is reached, even though idle-timeout-seconds has not expired. (When cache-type is NRU, reaching max-beans-in-cache is the only event that causes passivation.)
- Removes a passivated instance from disk after it has been inactive for idle-timeout-seconds after passivation.
Specifying the Persistent Store Directory for Passivated Beans
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 in the server instance directory, for example:
RootDirectory\persistent-store-dir
where:
- RootDirectory - is the directory where WLS runs, for example: D:\releases\700GA\bea\user_domains\mydomain.
RootDirectory can be set using at server startup using the -Dweblogic.RootDirectory property.
- ServerName - is the name of the server instance.
- persistent-store-dir - is the value of the of the persistent-store-dir element in the <stateful-session-descriptor> stanza of weblogic-ejb-jar.xml. If no value is specified for <persistent-store-dir>, the directory is named pstore by default.
For example, given the root directory and server name shown above, if you do not define <persistent-store-dir>, the path of the persistence directory is:
D:\releases\700GA\bea\user_domains\mydomain\myserver\pstore
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\700GA\bea\user_domains\mydomain\myserver\pstore\14t89gex0m2fr
Concurrent Access to Stateful Session Beans
In accordance with the EJB 2.0 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 WLS. To override this restriction, set allow-concurrent-calls deployment descriptor element to specify that a stateful session bean instance allow concurrent method calls.
If multiple servlet classes access a 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.
Design Decisions for Session Beans
This section discusses some design decisions relevant to session beans.
Choosing Between Stateless and Stateful 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. WLS 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.
Choosing the Optimal Free Pool Setting for Stateless Session Beans
When you choose values for initial-beans-in-free-pool and max-beans-in-free-pool 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.
Implementing Session Beans
Implementing Enterprise Java Beans, 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.
WebLogic-Specific Configurable Behaviors for Stateless Session Beans
Table 5-1 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.
To control
Set the following weblogic-ejb-jar.xml element(s)
Default behavior
The number of inactive instances of a stateless session bean that exist in WLS when it is started. See Pooling for Stateless Session EJBs. initial-beans-in-free-pool WLS creates 0 beans in the free pool. The maximum size of the free pool of inactive stateless session beans. max-beans-in-free-pool WLS limits the maximum number of beans in the free pool to 1000. How WLS replicates stateless session EJB instances in a cluster.See Reliability and Availability Features. stateless-clustering home-is-clusterable home-load-algorithm home-call-router-class-name stateless-bean-is-clusterable stateless-bean-load-algorithm stateless-bean-call-router-class-name stateless-bean-methods-are-idempotent The EJB can be deployed to multiple servers in a cluster.
WebLogic-Specific Configurable Behaviors for Stateful Session Beans
Table 5-2 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.
Behavior
weblogic-ejb-jar.xml element
Default
Whether multiple clients can simultaneously access a bean without triggering a Remote Exception. See Concurrent Access to Stateful Session Beans. allow-concurrent-callsin the stateful-session-descriptor stanza False - The server throws a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server. Whether the EJB container can remove a stateful session bean within a transaction context without provoking an error. allow-remove-during-transaction in the stateful-session-descriptor stanza 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. max-beans-in-cachein the stateful-session-cache stanza 1000 The period of inactivity before a stateful session bean instance remains in cache (given that max-beans-in-cache has not been reached), and after passivation, remains on disk idle-timeout-secondsin the stateful-session-cache stanza 600 seconds The rules for removing a stateful session bean instance from the cache. cache-typein the stateful-session-cache stanza NRU (not recently used) - For a description of this behavior, see Lazy Passivation (NRU). Where WLS stores the state of passivated stateful session bean instances persistent-store-dirin the stateful-session-descriptor stanza
To support method failover, specify the idempotent methods for a clustered EJB. An idempotent method can be repeated with no negative side-effects. idempotent-methods in the weblogic-ejb-jar stanza None Custom class to be used for routing home method calls. home-call-router-class-name in the stateful-session-clustering stanza None Indicates if the bean home can be clustered. home-is-clusterablein the stateful-session-clustering stanza True Algorithm to use for load-balancing among replicas of the bean home. home-load-algorithmin the stateful-session-clustering stanza Algorithm specified by the property weblogic.cluster.defaultLoadAlgorithm Indicates the replication used for stateful session beans in a cluster: in-memory or none. replication-typein the stateful-session-clustering stanza None
