Migrating EJB 2.x applications to EJB 3.0

Gradually and iteratively adopt the benefits of the newest EJB specification

Enterprise JavaBeans 3.0 simplifies the enterprise bean architecture and provides enhanced and more powerful features. The new specification leverages the annotations metadata facility introduced in Java 5, persistence and object-relational mapping best practices from tools such as Hibernate and TopLink, and the Dependency Injection pattern made popular by lightweight Java frameworks such as Spring.

This article discusses possible migration strategies for moving applications written using EJB 2.1 or an earlier specification to an EJB 3.0-based architecture. The possible migration paths are evaluated from both the perspectives of design and implementation. This article does not intend to be exhaustive in illustrating the migration options. After reading this article, you should be able to choose the best option, within your own specific context, for migrating the legacy EJB code to the new specification.

This article assumes you are familiar with the enterprise bean, Java 5, and object-relational mapping features and concepts.

EJB 2.1 to EJB 3.0: What has changed?

To provide a context for this article's discussion of possible migration paths, I begin by discussing the changes in the new specification in the context of each of the different bean types and then at a generic level pertinent across multiple bean types.

Session bean

In EJB 2.1 and earlier specifications, two interfaces—the home and the local, or remote, business interfaces—and the bean implementation class were required for each session bean. The home interface was required to extend the EJBHome or the EJBLocalHome interface and declare the lifecycle method, such as create(). The local, or remote, business interface was required to extend the EJBObject or the EJBLocalObject interface and declare the business methods. The bean implementation class itself was an EnterpriseBean type and, in the case of session beans, extended the SessionBean sub-interface. Callback method implementations in the bean class had to be provided so that the container could trigger them on occurrence of the appropriate lifecycle events. In addition, critical elements of the bean, including its transaction and security definition, and whether it was stateful or stateless, were defined in the associated deployment descriptors.

Listing 1 illustrates an example of a stateful session bean defined using the EJB 2.1 specification.

Listing 1. An EJB 2.1-based banking service stateful session bean


public interface BankingService extends EJBObject { public void deposit(int accountId, float amount) throws RemoteException; public void withdraw(int accountId, float amount)throws RemoteException; public float getBalance(int accountId) throws RemoteException;

public void doServiceLogout() throws RemoteException; }

public interface BankingServiceHome extends EJBHome { public BankingService create() throws CreateException, RemoteException; }

public class BankingServiceEJB implements SessionBean {

public void deposit(int accountId, float amount) throws RemoteException { //Business logic to deposit the specified amount and update the balance }

public void withdraw(int accountId, float amount)throws RemoteException { //Business logic to withdraw the desired amount and update the balance }

public float getBalance(int accountId) throws RemoteException { //Business logic to get the current balance }

public void doServiceLogout() throws RemoteException { //Service completion and logout logic }

public void ejbCreate(){} public void ejbActivate(){} public void ejbPassivate(){} public void ejbRemove(){} public void setSessionContext(SessionContext context){}


In the EJB 3.0 specification, a session bean needs to define only a business interface and a bean implementation class. The home interface has been removed. The business interface is a regular Java interface, also sometimes called POJI, or the plain-old Java interface. The business interface does not need to extend the EJBObject or the EJBLocalObject interface; instead, if required, it could be defined within the interface hierarchy that represents the business domain model.

The bean implementation class is a regular Java class, also sometimes called a POJO, or a plain-old Java object. It does not implement an EnterpriseBean type. The declaration and the configuration in the deployment descriptor can be defined within the Java code, using the annotations metadata facility. In addition, default values are provided for most configurations, thus minimizing the bean-specific configuration requirements. Under the new specification, one could deploy session beans without any ejb-jar.xml deployment descriptors, though they still exist and could be used if the developer prefers that to the annotations model.

In the case of EJB 3.0 session beans that implement a Web service, the methods exposed as Web service operations are annotated with the WebMethod descriptor. Session beans that serve as Web service endpoints are annotated as a WebService.

Listing 2 illustrates the earlier example (from Listing 1) of the stateful session bean using the EJB 3.0 specification.

Listing 2. An EJB 3.0-based banking service stateful session bean


@Remote public interface BankingService { public void deposit(int accountId, float amount); public void withdraw(int accountId, float amount); public float getBalance(int accountId); publlic void doServiceLogout();


@Stateful public class BankingServiceBean implements BankingService {

public void deposit(int accountId, float amount) { //Business logic to deposit the specified amount and update the balance }

public void withdraw(int accountId, float amount) { //Business logic to withdraw the desired amount and update the balance }

public float getBalance(int accountId) { //Business logic to get the current balance }

@Remove public void doServiceLogout () { //Service completion and logout logic }


Message-driven beans

In EJB 2.1, a message-driven bean class implemented the MessageDrivenBean interface and the message listener interface. The callback methods were implemented in the bean class and the container, on a particular event called the corresponding method. Message-driven beans never involved the concept of a home and a remote, or local, interface.

In EJB 3.0, the MessageDriven annotation is used to mark and specify a message-driven bean. The deployment descriptor can also be used to specify a bean as message-driven. Thus, it is not required for the bean class to implement the MessageDrivenBean interface. The business interface of a message-driven bean is the message listener interface that corresponds to the message type that the bean is a listener for. In the case of Java Message Service, javax.jms.MessageListener is the message listener interface or the business interface. The bean class needs to implement the message listener interface or annotate the message listener interface using the MessageDriven annotation.

The new specification supports callback methods (PostConstruct and PreDestroy), provides the Dependency Injection pattern for access to resources, and allows interceptor method definition for message-driven beans.

Entity beans

EJB 2.1 and earlier specifications required the definition of a home and remote interface, and the implementation of the bean class for an entity bean, similar to that of a session bean type. For a container-managed persistence (CMP) and container-managed relationship (CMR) scenario, the mappings and definitions were specified in the deployment descriptors.

The EJB 3.0 specification radically changes the earlier concepts and implementation of entity beans from heavyweight enterprise bean objects, with home and remote/local interfaces, to a lightweight persistent domain object in line with the object-relational mapping concepts. A later discussion on migration in this article discusses and details some of these changes.

More changes—relevant to multiple bean types

The EJB 3.0 specification introduces an important change in the way enterprise beans are accessed and called. The earlier service locator pattern that utilized JNDI (Java Naming and Directory Interface) lookups is now replaced with the Dependency Injection pattern. Thus, the complexity around JNDI API usage is removed from the bean developer's and client's viewpoint.

EJB 3.0 also introduces the concept of interceptors. Interceptor methods intercept a business method invocation or a lifecycle event callback. Interceptor methods could be defined either on the bean class or on the interceptor class associated with the bean or both.

Listing 3 illustrates the usage of AroundInvoke, an interceptor annotation.

Listing 3


@Stateful public class BankingServiceBean implements BankingService {

public void deposit(int accountId, float amount) { .... }

.... .... .... .... @Remove public void doServiceLogout () { .... }

@AroundInvoke public Object auditBankingService(InvocationContext inv) throws Exception { try { Object nextEntry = inv.proceed();

//Log the method name and parameters by using getMethod() on the InvocationContext instance. //The getMethod() returns the method of the bean class for which the interceptor was invoked. //The return type for getMethod() is a Method class, the reference to which can be used to get additional //method-related information. Target and context data can also be obtained using the InvocationContext instance.

return nextEntry; } catch (Exception ex) {

//Exception handling code goes here.

} }


Migrating to EJB 3.0

The EJB 3.0 (Java Specification Request 220) expert group specifically identified easy migration as an objective and hence provided for both backward compatibility and interoperability between enterprise bean components written in the old and the new specifications. This also makes it possible for EJB 2.x and earlier beans to be gradually and incrementally modified to utilize the EJB 3.0 specification. Interestingly enough, an entire chapter titled "Compatibility and Migration" is included in the EJB 3.0 simplified API specification document.

Some of the possible migration strategies are discussed below.

New functionality in EJB 3.0 with existing code in the old specification

An existing EJB application can be deployed in a container that supports EJB 3.0. The old bean components could be deployed and used without any modification.

EJB 2.x components could call EJB 3.0 components and vice-versa. Some scenarios where the client and server parts of the bean components are of different specifications are discussed below.

EJB 2.x and earlier clients of EJB 3.0 components

Enterprise bean components, which need to work with EJB 2.1 and earlier specifications, don't need to be written using old specifications any more. EJB 3.0 beans can utilize metadata annotations to make them work with older clients that expect to access them using the home and the remote interface. The methods required as per older specifications are mapped to corresponding methods in the enterprise bean written using the EJB 3.0 specification. As an example, the create() method as desired in the old specification could now map to a method that initializes the bean. This example was presented by Linda DeMichiel, one of the specification leads, as part of her Java One 2005 presentation on EJB 3.0.

EJB 3.0 clients of EJB 2.x components

EJB 3.0 beans can access EJB 2.1 and earlier beans. Dependency injection is utilized to inject the EJB 2.1 component references. JNDI lookup calls are avoided. Once a handle is gained to the injected EJB home interface, the create() method is called to instantiate and subsequently utilize the bean.

Listing 4 presents an example where an EJB 3.0 client accesses an EJB 2.1 component.

Listing 4


.... ....

@EJB BankingServiceHome bsHome; BankingService bs = bsHome.create(); .... bs.deposit(....); .... bs.getBalance(....); .... bs.doServiceLogout(); .... ....

1 2 Page 1
Page 1 of 2