8 Using Enterprise JavaBeans Technology

Pooling Parameters

One of the most important parameters for GlassFish Server pooling is steady-pool-size. When steady-pool-size is set to a value greater than 0, the container not only pre-populates the bean pool with the specified number of beans, but also attempts to ensure that this number of beans is always available in the free pool. This ensures that there are enough beans in the ready-to-serve state to process user requests.

Note that the steady-pool-size and max-pool-size parameters only govern the number of instances that are pooled over a long period of time. They do not necessarily guarantee that the number of instances that may exist in the JVM at a given time will not exceed the value specified by max-pool-size. For example, suppose an idle stateless session container has a fully-populated pool with a steady-pool-size of 10. If 20 concurrent requests arrive for the EJB component, the container creates 10 additional instances to satisfy the burst of requests. The advantage of this is that it prevents the container from blocking any of the incoming requests. However, if the activity dies down to 10 or fewer concurrent requests, the additional 10 instances are discarded.

Another parameter, pool-idle-timeout-in-seconds, allows the administrator to specify the amount of time a bean instance can be idle in the pool. When pool-idle-timeout-in-seconds is set to greater than 0, the container removes or destroys any bean instance that is idle for this specified duration.

Caching Parameters

GlassFish Server provides a way that completely avoids caching of entity beans, using commit option C. Commit option C is particularly useful if beans are accessed in large number but very rarely reused. For additional information, refer to Commit Options.

The GlassFish Server caches can be either bounded or unbounded. Bounded caches have limits on the number of beans that they can hold beyond which beans are passivated. For stateful session beans, there are three ways (LRU, NRU and FIFO) of picking victim beans when cache overflow occurs. Caches can also passivate beans that are idle (not accessed for a specified duration).

Stateless Container

The stateless container manages stateless session beans, which, by definition, do not carry client-specific states. All session beans (of a particular type) are considered equal.

A stateless session bean container uses a bean pool to service requests. The GlassFish Server specific deployment descriptor file, glassfish-ejb-jar.xml, contains the properties that define the pool:

• steady-pool-size

• resize-quantity

• max-pool-size

• pool-idle-timeout-in-seconds

For more information about glassfish-ejb-jar.xml, see "The glassfish-ejb-jar.xml File" in Oracle GlassFish Server Application Deployment Guide.

The GlassFish Server provides the wscompile and wsdeploy tools to help you implement a web service endpoint as a stateless session bean. For more information about these tools, see the Oracle GlassFish Server Reference Manual.

Stateful Container

The stateful container manages the stateful session beans, which, by definition, carry the client-specific state. There is a one-to-one relationship between the client and the stateful session beans. At creation, each stateful session bean (SFSB) is given a unique session ID that is used to access the session bean so that an instance of a stateful session bean is accessed by a single client only.

Stateful session beans are managed using cache. The size and behavior of stateful session beans cache are controlled by specifying the following glassfish-ejb-jar.xml parameters:

• max-cache-size

• resize-quantity

• cache-idle-timeout-in-seconds

• removal-timeout-in-seconds

• victim-selection-policy

The max-cache-size element specifies the maximum number of session beans that are held in cache. If the cache overflows (when the number of beans exceeds max-cache-size), the container then passivates some beans or writes out the serialized state of the bean into a file. The directory in which the file is created is obtained from the EJB container using the configuration APIs.

For more information about glassfish-ejb-jar.xml, see "The glassfish-ejb-jar.xml File" in Oracle GlassFish Server Application Deployment Guide.

The passivated beans are stored on the file system. The Session Store Location setting in the EJB container allows the administrator to specify the directory where passivated beans are stored. By default, passivated stateful session beans are stored in application-specific subdirectories created under domain-dir/session-store.

The Session Store Location setting also determines where the session state is persisted if it is not highly available; see Choosing a Persistence Store.

Choosing a Persistence Store

The following types of persistent storage are supported for passivation and checkpointing of the SFSB state:

• The local file system - Allows a single server instance to recover the SFSB state after a failure and restart. This store also provides passivation and activation of the state to help control the amount of memory used. This option is not supported in a production environment that requires SFSB state persistence. This is the default storage mechanism if availability is not enabled.

• Other servers - Uses other server instances in the cluster for session persistence. Clustered server instances replicate session state. Each backup instance stores the replicated data in memory. This is the default storage mechanism if availability is enabled.

Choose the persistence store in one of the following ways:

• To use the local file system, first disable availability. Select the Availability Service component under the relevant configuration in the Administration Console. Uncheck the Availability Service box. Then select the EJB Container component and edit the Session Store Location value. The default is domain-dir/session-store.

• To use other servers, select the Availability Service component under the relevant configuration in the Administration Console. Check the Availability Service box. To enable availability for the EJB container, select the EJB Container Availability tab, then check the Availability Service box. All instances in an GlassFish Server cluster should have the same availability settings to ensure consistent behavior.

For more information about SFSB state persistence, see the Oracle GlassFish Server High Availability Administration Guide.

Enabling Checkpointing

The following sections describe how to enable SFSB checkpointing:

• Server Instance and EJB Container Levels

• Application and EJB Module Levels

• SFSB Level

<glassfish-ejb-jar>
   ...
   <enterprise-beans>
      ...
      <ejb availability-enabled="true">
         <ejb-name>MySFSB</ejb-name>
      </ejb>
   ...
   </enterprise-beans>
</glassfish-ejb-jar>

Specifying Methods to Be Checkpointed

If SFSB checkpointing is enabled, checkpointing generally occurs after any transaction involving the SFSB is completed, even if the transaction rolls back.

To specify additional optional checkpointing of SFSBs at the end of non-transactional business methods that cause important modifications to the bean's state, use the checkpoint-at-end-of-method element within the ejb element in glassfish-ejb-jar.xml.

For example:

<glassfish-ejb-jar>
   ...
   <enterprise-beans>
      ...
      <ejb availability-enabled="true">
         <ejb-name>ShoppingCartEJB</ejb-name>
         <checkpoint-at-end-of-method>
            <method>
               <method-name>addToCart</method-name>
            </method>
         </checkpoint-at-end-of-method>
      </ejb>
      ...
   </enterprise-beans>
</glassfish-ejb-jar>

For details, see "checkpoint-at-end-of-method" in Oracle GlassFish Server Application Deployment Guide.

The non-transactional methods in the checkpoint-at-end-of-method element can be the following:

• create methods defined in the home or business interface of the SFSB, if you want to checkpoint the initial state of the SFSB immediately after creation

• For SFSBs using container managed transactions only, methods in the remote interface of the bean marked with the transaction attribute TX_NOT_SUPPORTED or TX_NEVER

• For SFSBs using bean managed transactions only, methods in which a bean managed transaction is neither started nor committed

Any other methods mentioned in this list are ignored. At the end of invocation of each of these methods, the EJB container saves the state of the SFSB to persistent store.

Optimizing Session Bean Performance

For stateful session beans, colocating the stateful beans with their clients so that the client and bean are executing in the same process address space improves performance.

Restricting Transactions

The following restrictions on transactions are enforced by the container and must be observed as session beans are developed:

• A session bean can participate in, at most, a single transaction at a time.

• If a session bean is participating in a transaction, a client cannot invoke a method on the bean such that the trans-attribute element (or @TransactionAttribute annotation) in the ejb-jar.xml file would cause the container to execute the method in a different or unspecified transaction context or an exception is thrown.

• If a session bean instance is participating in a transaction, a client cannot invoke the remove method on the session object's home or business interface object, or an exception is thrown.

EJB Singletons

EJB Singletons are created for each server instance in a cluster, and not once per cluster.

Invoking a Transactional Method

Invoking any transactional method invokes ejbLoad.

Refreshing Periodically

Use the refresh-period-in-seconds element in the glassfish-ejb-jar.xml file to refresh a read-only bean periodically.

• If the value specified in refresh-period-in-seconds is zero or not specified, which is the default, the bean is never refreshed (unless a transactional method is accessed).

• If the value is greater than zero, the bean is refreshed at the rate specified.

By default, a single timer is used for all instances of a read-only bean. When that timer fires, all bean instances are marked as expired and are refreshed from the database the next time they are used.

Use the -Dcom.sun.ejb.containers.readonly.relative.refresh.mode=true flag to refresh each bean instance independently upon access if its refresh period has expired. The default is false. Note that each instance still has the same refresh period. This additional level of granularity can improve the performance of read-only beans that do not need to be refreshed at the same time.

To set this flag, use the asadmin create-jvm-options command. For example:

asadmin create-jvm-options -Dcom.sun.ejb.containers.readonly.relative.refresh.mode=true

Refreshing Programmatically

Typically, beans that update any data that is cached by read-only beans need to notify the read-only beans to refresh their state. Use ReadOnlyBeanNotifier to force the refresh of read-only beans.

To do this, invoke the following methods on the ReadOnlyBeanNotifier bean:

public interface ReadOnlyBeanNotifier extends java.rmi.Remote {
   refresh(Object PrimaryKey) throws RemoteException;
 }

The implementation of the ReadOnlyBeanNotifier interface is provided by the container. The bean looks up ReadOnlyBeanNotifier using a fragment of code such as the following example:

com.sun.appserv.ejb.ReadOnlyBeanHelper helper = 
  new com.sun.appserv.ejb.ReadOnlyBeanHelper();
com.sun.appserv.ejb.ReadOnlyBeanNotifier notifier = 
  helper.getReadOnlyBeanNotifier("java:comp/env/ejb/ReadOnlyCustomer");
notifier.refresh(PrimaryKey);

For a local read-only bean notifier, the lookup has this modification:

helper.getReadOnlyBeanLocalNotifier("java:comp/env/ejb/LocalReadOnlyCustomer");

Beans that update any data that is cached by read-only beans need to call the refresh methods. The next (non-transactional) call to the read-only bean invokes ejbLoad.

For Javadoc tool pages relevant to read-only beans, go to http://glassfish.java.net/nonav/docs/v3/api/ and click on the com.sun.appserv.ejb package.

Connection Factory and Destination

A message-driven bean is a client to a Connector inbound resource adapter. The message-driven bean container uses the JMS service integrated into the GlassFish Server for message-driven beans that are JMS clients. JMS clients use JMS Connection Factory- and Destination-administered objects. A JMS Connection Factory administered object is a resource manager Connection Factory object that is used to create connections to the JMS provider.

The mdb-connection-factory element in the glassfish-ejb-jar.xml file for a message-driven bean specifies the connection factory that creates the container connection to the JMS provider.

The jndi-name element of the ejb element in the glassfish-ejb-jar.xml file specifies the JNDI name of the administered object for the JMS Queue or Topic destination that is associated with the message-driven bean.

Message-Driven Bean Pool

The container manages a pool of message-driven beans for the concurrent processing of a stream of messages. The glassfish-ejb-jar.xml file contains the elements that define the pool (that is, the bean-pool element):

• steady-pool-size

• resize-quantity

• max-pool-size

• pool-idle-timeout-in-seconds

For more information about glassfish-ejb-jar.xml, see "The glassfish-ejb-jar.xml File" in Oracle GlassFish Server Application Deployment Guide.

Domain-Level Settings

You can control the following domain-level message-driven bean settings in the EJB container:

Initial and Minimum Pool Size

Specifies the initial and minimum number of beans maintained in the pool. The default is 0.

Maximum Pool Size

Specifies the maximum number of beans that can be created to satisfy client requests. The default is 32.

Pool Resize Quantity

Specifies the number of beans to be created if a request arrives when the pool is empty (subject to the Initial and Minimum Pool Size), or the number of beans to remove if idle for more than the Idle Timeout. The default is 8.

Idle Timeout

Specifies the maximum time in seconds that a bean can remain idle in the pool. After this amount of time, the bean is destroyed. The default is 600 (10 minutes). A value of 0 means a bean can remain idle indefinitely.

For information on monitoring message-driven beans, click the Help button in the Administration Console. Select the Stand-Alone Instances component, select the instance from the table, and select the Monitor tab. Or select the Clusters component, select the cluster from the table, select the Instances tab, select the instance from the table, and select the Monitor tab.

Pool Tuning and Monitoring

The message-driven bean pool is also a pool of threads, with each message-driven bean instance in the pool associating with a server session, and each server session associating with a thread. Therefore, a large pool size also means a high number of threads, which impacts performance and server resources.

When configuring message-driven bean pool properties, make sure to consider factors such as message arrival rate and pattern, onMessage method processing time, overall server resources (threads, memory, and so on), and any concurrency requirements and limitations from other resources that the message-driven bean accesses.

When tuning performance and resource usage, make sure to consider potential JMS provider properties for the connection factory used by the container (the mdb-connection-factory element in the glassfish-ejb-jar.xml file). For example, you can tune the GlassFish Server Message Queue flow control related properties for connection factory in situations where the message incoming rate is much higher than max-pool-size can handle.

Refer to "Administering the Monitoring Service" in Oracle GlassFish Server Administration Guide for information on how to get message-driven bean pool statistics.

The onMessage Runtime Exception

Message-driven beans, like other well-behaved MessageListeners, should not, in general, throw runtime exceptions. If a message-driven bean's onMessage method encounters a system-level exception or error that does not allow the method to successfully complete, the Enterprise JavaBeans Specification, v3.0 provides the following guidelines:

• If the bean method encounters a runtime exception or error, it should simply propagate the error from the bean method to the container.

• If the bean method performs an operation that results in a checked exception that the bean method cannot recover, the bean method should throw the javax.ejb.EJBException that wraps the original exception.

• Any other unexpected error conditions should be reported using javax.ejb.EJBException (javax.ejb.EJBException is a subclass of java.lang.RuntimeException).

Under container-managed transaction demarcation, upon receiving a runtime exception from a message-driven bean's onMessage method, the container rolls back the container-started transaction and the message is redelivered. This is because the message delivery itself is part of the container-started transaction. By default, the GlassFish Server container closes the container's connection to the JMS provider when the first runtime exception is received from a message-driven bean instance's onMessage method. This avoids potential message redelivery looping and protects server resources if the message-driven bean's onMessage method continues misbehaving. To change this default container behavior, use the cmt-max-runtime-exceptions property of the MDB container. Here is an example asadmin set command that sets this property:

asadmin set server-config.mdb-container.property.cmt-max-runtime-exceptions="5"

For more information about the asadmin set command, see the Oracle GlassFish Server Reference Manual.

The cmt-max-runtime-exceptions property specifies the maximum number of runtime exceptions allowed from a message-driven bean's onMessage method before the container starts to close the container's connection to the message source. By default this value is 1; -1 disables this container protection.

A message-driven bean's onMessage method can use the javax.jms.Message.getJMSRedelivered method to check whether a received message is a redelivered message.