Upgrade your application to JBoss EJB 3.0 Proposed Final Draft (PFD)

Since July 2005, JBoss has release several release candidates (RCs) for EJB 3.0. They have became hugely popular and many JBoss users have even used EJB 3.0 in production systems (that includes JBoss's own JBoss Network and JBoss Labs production sites!). However, as any beta/preview technology, EJB 3.0 is still pretty much a work-in-progress with API changes between RC releases to reflect the latest specification updates. Fortunately, those API changes are typically minor and cosmitic (i.e., does not alter the underlying POJO application model). It is relatively easy to keep up with those changes.

We highly recommend you to keep your EJB 3.0 applications updated and run them under the latest EJB 3.0 framework release -- It not only helps to prepare your application ready for the final JBoss EJB 3.0 v1.0 release, but also enables you to take advantage of many performance enhancements and bug fixes. All our EJB 3.0 documentation and demos will be kept in sync with the latest framework release.

In this document, we will cover how to upgrade your existing EJB 3.0 applications to conform with the EJB 3.0 Final Proposed Draft specification. We do not want to overwhelm you with minor changes that may or may not affect your application. Instead, we will primarily cover the relatively significant changes that affects most applications, and then point you to relevant parts of the documentation and the specification itself for finer details.

A little background

In this document, we will cover EJB 3.0 specifications and their JBoss implementation modules released after 2005. They are:

• The most recent specification is the EJB 3.0 Proposed Final Draft (PFD) released in Dec 2005. It should be very close to the final v1.0 specification scheduled to be released before May 2006. JBoss AS 4.0.4 supports PFD out-of-the-box. If you are running an earlier version of JBoss AS 4.0.x, you can install the JBoss EJB 3.0 RC5 module to upgrade to PFD. Note that JBoss EJB 3.0 RC4 also implements the PFD but RC5 contains numerous bug fixes.

• The EJB 3.0 Public Review was released in June 2005. The JBoss EJB 3.0 RC3 module implements this version of the specification. You have to download it and install it into your JBoss AS 4.0.x in order to use it. If you are currently using JBoss EJB 3.0, you are most likely on this release. We recommend all RC3 users to upgrade to the PFD.

• The EJB 3.0 Early Draft Review 2 (EDR2) was released in Feb 2005. The JBoss AS 4.0.3 (including SP1) supports this specification release out-of-the-box. The standalone JBoss EJB 3.0 modules for EDR2 are Beta1, RC1 and RC2.

A very good resource to find out detailed API changes is the EJB 3.0 specification itself. At the end of the specification, there are a few pages of changelog that records the changes between specification releases.

If you use EJB 3.0 session beans and message driven beans

If you are migrating from the Public Review specification (JBoss EJB 3.0 RC3):

• The biggest change is for the session bean client. You can no longer use the bean interface FQN as the JNDI name to obtain a bean stub. Instead, you have to use a JNDI string composed of the EAR file base name (if there is an EAR file), theunqualified bean implementation class name, and the "local/remote" distinction of the stub interface. Or, alternatively, you can use the @RemoteBinding and @LocalBinding annoltations to specify an arbitary JNDI name for the bean. See this tutorial for more details.

• You can, however, still use the @EJB annotation to inject an session bean interface into another session. But if there are multiple bean classes implementing the same interface, you need to specify the beanName/jndiName attribute of the @EJB annotation. Or the runtime would throw an exception. See this tutorial for details.

• There is no need to package session beans in a .ejb3 archive. A regulare JAR archive would suffice.
  

• The "activateConfig" attribute on the @MessageDriven annotation (or on the @Consumer annotation for JBoss message driven POJOs) is now "activationConfig". See this tutorial for details.
  

• The @Interceptor annotation is now @Interceptors. You can now specify multiple class level interceptors as well as method level interceptors. Please see this tutorial for more details.

• The session bean life cycle methods are can now be specified in the interceptor class.

• Please see this wiki page for more information. Add to it if you have more!

If you are migrating from the EDR2 specification (JBoss EJB 3.0 Beta1/RC1/RC2):

• You can specify local and remote interfaces for a session bean using the @Local and @Remote annotations on the bean implementation class. There is no need to annotate the interfaces themselves. Please see here for an example.

• The JBoss JMX POJO annotations are now strcutured much like session bean annotations (e.g., @Management --> @Local and @Service --> @Stateless). See this tutorial for details.

• Except for EntityManager objects and session bean stubs, all JNDI resources are injected into a session bean via the @Resource annotation. You can let the container figure out the right object to inject based on the variable name and type. Or, you can specify the injected resource's JNDI name in the mappedName attribute. See this tutorial for more details. You can also inject resources into interceptor classes now.
  

• You can now throw custom exceptions tagged by @ApplicationException to trigger transaction rollback.

If you use EJB 3.0 entity beans

• There is no need for the .par file anymore. You can simply package entity bean classes in a JAR file and place the persistence.xml file under the META-INF directory in the JAR archive. You can package session bean classes in the same JAR file. Please see this tutorial for more details.

• The persistence.xml file has a different schema and you have to specify the datasource for every persistence context. Please see this tutorial for an example.

• Please see here for numerous updates on the O/R mapping annotations. Most noticablly, the @Id(generator=GeneratorType) annotation is now two annotations @Id and @GeneratedValue.

• In most cases, you now need to specify "unitName" in @PersistenceContext to inject an EntityManager, even if you only have one persistence context defined in this application. To get around this, you can define a scoped class loader for the EAR application in the jboss-app.xml file.
  

• The extended EntityManager lifecycle is now in sync with its host stateful session bean. There is no need to set the flush mode to NEVER on each stateful method to archive long running transactions. See this tutorial for details.

• In fact, there are only two flush modes right now: AUTO and COMMIT. Please see this tutorial for explanations.