Ken Saks's Blog

One of the most common requests we hear from Enterprise JavaBeans developers is for improved unit testing support. The two biggest issues they raise are :

• Testing Local Session Beans is difficult since they're only accessible by way of the Remote EJB tier or the web tier.
• Regardless of bean type, it would be simpler to allow client code to run in the same JVM as the components under test.

Some Java EE implementations have solved these problems by adding a Java SE execution mode in which clients instantiate EJB components within the same JVM. While this is a great start, more work is needed to raise the level of portability and ensure broader support.

We've been discussing this topic extensively in the EJB 3.1 Expert Group. Here's an early look at a proposed solution we're calling Embeddable EJB :

The Embeddable EJB API allows client code to instantiate an EJB container that runs within its own JVM and classloader. The client uses a spec-defined bootstrapping API to start the container and identify the set of enterprise bean components for execution.

The embeddable EJB container provides a managed environment with support for the same basic services that exist within a Java EE runtime : injection, access to a component environment, container-managed transactions, container-managed persistence contexts, etc. In general, enterprise bean components are unaware of the kind of managed environment in which they are running. This allows maximum reusability of bean components across a wide range of testing and deployment scenarios without significant rework.

Let's look at an example. Here's a simple Stateless session bean that uses Java Persistence to implement some bank account operations :

   1:  @Stateless

   2:  public class AccountBean {

   3:   

   4:    @PersistenceContext EntityManager em;

   5:   

   6:    public void createAccount(int acctId) {

   7:   

   8:      Account account = new Account(acctId);

   9:   

  10:      em.persist(account);  

  11:   

  12:    }

  13:    ... 

  14:  }

Note that this is just a normal stateless session bean. It exposes business methods through a no-interface view. The bean implementation uses injection, container-managed transactions, and Java Persistence. There is no special API it must use to be capable of embeddable execution.

Here is some test code to execute the bean in an embeddable container :

   1:   

   2:  // Instantiate an embeddable EJB container and search the

   3:  // JVM class path for eligible EJB modules or directories

   4:  EJBContainer ejbC = EJBContainer.createEJBContainer();

   5:   

   6:  // Get a naming context for session bean lookups

   7:  Context ctx = ejbC.getNamingContext();

   8:          

   9:  // Retrieve a reference to the AccountBean using a

  10:  // portable global JNDI name (more on this later!)  

  11:  AccountBean ab = (AccountBean) 

  12:      ctx.lookup("java:global/account/AccountBean");

  13:   

  14:  // Test the account

  15:   

  16:  Account a1 = ab.createAccount(1234);

  17:   

  18:  ...

  19:   

  20:  // Shutdown the embeddable container

  21:  ejbC.close();    

  22:   

Next we prepare the following three .jars :

• account.jar
  An ejb-jar containing the AccountBean class and its associated persistence artifacts.


• client.jar
  A .jar containing the test client class.


• vendor.jar
  A vendor-provided .jar file containing the necessary system classes.

All that's left to do is start the JVM using a normal java command :

% java -cp account.jar:client.jar:vendor.jar com.acme.AccountTest

It's important that we support starting the JVM with a plain java command. Not only is it easily understood by developers but it ensures straightforward integration with existing test frameworks and IDEs. We also plan to support an "exploded" directory form of the ejb-jar to reduce the number of packaging steps.

There are more details to work out but we think this is a good first step. As always, let us know your feedback by leaving comments here or by sending email to jsr-318-comments@jcp.org.