Sun GlassFish Enterprise Server v3 Prelude Developer's Guide

Chapter 8 Using Enterprise JavaBeans Technology

This chapter describes how Enterprise JavaBeans^TM (EJB^TM) technology is supported in the Sun GlassFish Enterprise Server. This chapter addresses the following topics:

For general information about enterprise beans, see “Part Three: Enterprise Beans” in the Java EE 5 Tutorial.

Note –

For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

For GlassFish v3 Prelude, only stateless session beans with local interfaces and entity beans that use the Java Persistence API are supported. Stateful, message-driven, and EJB 2.0 and 2.1 entity beans are not supported. Remote interfaces and remote business interfaces for any of the bean types are not supported.

Summary of EJB 3.1 Changes

The Enterprise Server supports and is compliant with the Sun Microsystems Enterprise JavaBeans (EJB) architecture as defined by the Enterprise JavaBeans Specification, v3.1, also known as JSR 318.

The main changes in the Enterprise JavaBeans Specification, v3.1 that impact enterprise beans in the Enterprise Server environment are as follows:

An EJB component need not implement any interface as long as it contains one of the component defining annotations or the XML equivalent. Essentially, the local business interface is optional. For example, the following is a simple no-interface bean:
```
@Stateless
public class HelloBean {
   public String sayHello(String msg) {
      return "Hello " + msg;
   }
}
```
Even though the bean doesn't implement any interface, the client can still inject (or look up) a reference to the session bean. The client still has to perform a JNDI lookup or inject a reference of the bean. More specifically, it cannot use the new operator to construct the bean.
```
@EJB HelloBean h;
...
h.sayHello("bob");
```
EJB classes can be packaged inside WAR files. These classes must reside under WEB-INF/classes. For example, the structure of a hello.war file might look like this:
```
index.jsp
META-INF/
   MANIFEST.MF
WEB-INF/
   web.xml
   classes/
      com/
         sun/
            v3/
               demo/
                  HelloEJB.class
                  HelloServlet.class
```
For more information about web applications, see Chapter 7, Developing Web Applications.

Value Added Features

The Enterprise Server provides a number of value additions that relate to EJB development. These capabilities are discussed in the following sections. References to more in-depth material are included.

Bean-Level Container-Managed Transaction Timeouts

Bean-Level Container-Managed Transaction Timeouts

The default transaction timeout for the domain is specified using the Transaction Timeout setting of the Transaction Service. A transaction started by the container must commit (or rollback) within this time, regardless of whether the transaction is suspended (and resumed), or the transaction is marked for rollback.

To override this timeout for an individual bean, use the optional cmt-timeout-in-seconds element in sun-ejb-jar.xml. The default value, 0, specifies that the default Transaction Service timeout is used. The value of cmt-timeout-in-seconds is used for all methods in the bean that start a new container-managed transaction. This value is not used if the bean joins a client transaction.

EJB Timer Service

The EJB Timer Service uses a database to store persistent information about EJB timers.

The EJB Timer Service in Enterprise Server is preconfigured to use an embedded version of the Java DB database.

Note –

If the optional JTS add-on component has not been downloaded from the Update Tool, you must reconfigure the JDBC resource named jdbc/__TimerPool. If the optional JTS add-on component has been downloaded, this is not necessary. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

In the Administration Console, open the Resources component and select JDBC Resources. For details, click the Help button in the Administration Console. Change the connection pool name for the JDBC resource named jdbc/__TimerPool to point to the same connection pool as the one you are using for the rest of your data. Then start the database.

To enable the timer service, deploy the following application:

as-install/lib/install/applications/ejb-timer-service-app.war

You can verify that it was deployed successfully by accessing the following URL:

http://localhost:8080/ejb-timer-service-app/timer

The EJB Timer Service configuration can store persistent timer information in any database supported by the Enterprise Server for persistence. For a list of the JDBC drivers currently supported by the Enterprise Server, see the Sun GlassFish Enterprise Server v3 Prelude Release Notes. For configurations of supported and other drivers, see Configuration Specifics for JDBC Drivers in Sun GlassFish Enterprise Server v3 Prelude Administration Guide.

To change the database used by the EJB Timer Service, set the EJB Timer Service’s Timer DataSource setting to a valid JDBC resource. You must also create the timer database table. DDL files are located in as-install/lib/install/databases.

Using the EJB Timer Service is equivalent to interacting with a single JDBC resource manager. If an EJB component or application accesses a database either directly through JDBC or indirectly (for example, through an entity bean’s persistence mechanism), and also interacts with the EJB Timer Service, its data source must be configured with an XA JDBC driver.

You can change the following EJB Timer Service settings. You must restart the server for the changes to take effect.

Minimum Delivery Interval - Specifies the minimum time in milliseconds before an expiration for a particular timer can occur. This guards against extremely small timer increments that can overload the server. The default is 7000.
Maximum Redeliveries - Specifies the maximum number of times the EJB timer service attempts to redeliver a timer expiration due for exception or rollback. The default is 1.
Redelivery Interval - Specifies how long in milliseconds the EJB timer service waits after a failed ejbTimeout delivery before attempting a redelivery. The default is 5000.

Using Session Beans

This section provides guidelines for creating session beans in the Enterprise Server environment. This section addresses the following topics:

Information on session beans is contained in the Enterprise JavaBeans Specification, v3.1.

About the Session Bean Containers

Like an entity bean, a session bean can access a database through Java Database Connectivity (JDBC) calls. A session bean can also provide transaction settings. These transaction settings and JDBC calls are referenced by the session bean’s container, allowing it to participate in transactions managed by the container.

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 Enterprise Server specific deployment descriptor file, sun-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 sun-ejb-jar.xml, see The sun-ejb-jar.xml File in Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

The Enterprise 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 Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

Session Bean Restrictions and Optimizations

This section discusses restrictions on developing session beans and provides some optimization guidelines.

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.

Handling Transactions With Enterprise Beans

This section describes the transaction support built into the Enterprise JavaBeans programming model for the Enterprise Server.

As a developer, you can write an application that updates data in multiple databases distributed across multiple sites. The site might use EJB servers from different vendors. This section provides overview information on the following topics:

Note –

For GlassFish v3 Prelude, global (XA) transactions are not supported unless the optional JTS add-on component is downloaded from the Update Tool. Without the JTS add-on component, only local transactions are supported. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

Flat Transactions

The Enterprise JavaBeans Specification, v3.0 requires support for flat (as opposed to nested) transactions. In a flat transaction, each transaction is decoupled from and independent of other transactions in the system. Another transaction cannot start in the same thread until the current transaction ends.

Flat transactions are the most prevalent model and are supported by most commercial database systems. Although nested transactions offer a finer granularity of control over transactions, they are supported by far fewer commercial database systems.

Global and Local Transactions

Understanding the distinction between global and local transactions is crucial in understanding the Enterprise Server support for transactions. See Transaction Scope.

Both local and global transactions are demarcated using the javax.transaction.UserTransaction interface, which the client must use. Local transactions bypass the transaction manager and are faster. For more information, see The Transaction Manager, the Transaction Synchronization Registry, and UserTransaction.

Administration and Monitoring

An administrator can control a number of domain-level Transaction Service settings. For details, see Configuring the Transaction Service.

The Transaction Timeout setting can be overridden by a bean. See Bean-Level Container-Managed Transaction Timeouts.

In addition, the administrator can monitor transactions using statistics from the transaction manager that provide information on such activities as the number of transactions completed, rolled back, or recovered since server startup, and transactions presently being processed.