What follows is a how to guide for using the OpenEJB Tomcat plug-in. A complete list of new features is available at the download link http://openejb.apache.org/download.html.

Currently the main reason for using OpenEJB 3 is to facilitate testing by embedding the container in unit tests even if you're eventually deploying to a different JEE server. OpenEJB 3 even provides for changing the JNDI naming schemes to help target servers like Glassfish and WebLogic. However, by using the Tomcat plug-in (OpenEJB basically deploys as a typical Web application war file) the possibilities go beyond unit testing. OpenEJB 3 simplifies the learning (and teaching) of EJB 3 by letting developers new to JEE/EJB avoid dealing with specific JEE application server configuration, packaging, and deployment details, and focus on coding and testing EJBs just as easily as servlets in Web applications. They can migrate to using EJBs slowly without making major changes to existing non-JEE Web applications. It provides a migration path to JEE 5 by using OpenEJB in their current Tomcat-based environments. OpenEJB also still supports EJB 2.x.

Download the Tomcat integration plug-in, openejb.war, from http://openejb.apache.org/download.html. You can deploy this war file and access the main installation Web page from http://127.0.0.1:8080/openejb/installer.

Optionally, if you play on the bleeding edge you can build the code from source to get the latest features. You can check out openejb3 as follows: svn co http://svn.apache.org/repos/asf/openejb/trunk/openejb3 and build using maven: mvn -Dmaven.{test,itest}.skip -Dassemble clean install. Once you've successfully built OpenEJB you'll have built the snapshot files for Tomcat located at openejb3/assembly/openejb-tomcat/target/. Rename the openejb-tomcat-3.0.0-SNAPSHOT.war file to openejb.war before deploying.

Once deployed, follow the instructions at http://127.0.0.1:8080/openejb/installer and press the install button. Note: this may modify your catalina.sh or catalina.bat files required for the OpenEJB3-Tomcat plug-in (depending if you're running Java 5 or 6 because of the way OpenJPA is initialized). So it won't work if you're not using different startup scripts, e.g., running Tomcat from your IDE may require extra steps that I'll describe below.

After a successful installation (indicated via the OpenEJB installer/Web admin Web pages) you can now package your EJBs and Web components together (also known as a "collapsed EAR" format) in a war file or folder - see Figure 1).

The OpenEJB Web administrator is currently work in progress but as an API so you can add Web admin beans to add custom functionality.

Okay, we'll now look at an example application, a typical online order processing system. The following code fragments illustrate the use of (by way of a servlet - we'll ignore Web frameworks for now) a session bean and entities (using JPA with a JTA transaction type) and show example use of EJB 3 annotations such as @EJB, @Stateless, @Entity, @PersistanceContext, @OneToOne, @OneToMany, @ManyToOne, @NamedQueries, and @JoinColumn.

You'll note the entity manager is injected into the SLSB (stateless session bean) via the PersistenceContext annotation (see Listing 1).

Listing 2 illustrates one of the entities and in this case representing a line item.

And here's the servlet that uses an EJB. In this case for simplicity's sake we'll populate the products table if it's initially empty (see Listing 3).

Listing 4 is the JPA configuration file. It's deployed along with the Web application in WEB-INF/classesMETA-INF.

Customer orders can be entered manually from a JSP form (an example is provided with the downloadable code) but for quickly populating the database (and avoiding any discussion of Web frameworks at this point) we'll mimic several entries such as new customers, orders, and their line item entries from a specific servlet (without using any Web forms) (see Figure 2). So an example order from a random customer with a random number of line items is placed every time you access the servlet at http://127.0.0.1:8080/ejb3example/order. You can also view the orders from a particular customer directly from a specific servlet request as such: http://127.0.0.1:8080/ejb3example/query?email=emall@address.

To run this in an IDE without using the catalina.sh/bat script or the start-up scripts, you specify the following configuration parameters:

Main class: org.apache.catalina.startup.Bootstrap
Working directory: (your Tomcat home folder)
VM arguments: -javaagent:Webapps/openejb/lib/openejb-javaagent-3.0-beta-1.jar
(not required with Java 6).
Program arguments: start
And add to the runtime classpath: [tomcat folder]/bin/bootstrap.jar

And to compile the application, add the following jars to your project's classpath unless JEE support is already available for your IDE project. From Tomcat's lib folder: servlet-api.jar, from openejb's lib folder: geronimo-ejb_3.0_spec-1.0.jar, geronimo-jpa_3.0_spec-1.1.jar.

One thing to watch for is if you're running a plug-in or IDE tool that manages it's own copy of Tomcat's server.xml, e.g., Eclipse's "servers" then add the OpenEJB Listener to the top of server.xml (next to the other listeners): <Listener className="org.apache.openejb.loader.OpenEJBListener" />.

Another debugging trick I recommend is to edit and debug code by having Tomcat auto-deploy as you make changes and you'd use your project's workspace as a deployed Web app in Tomcat by adding the following context file to Tomcat's conf/Catalina/localhost folder (while Tomcat is stopped). For example, for a Web app called ejb3example its context file would be called ejb3example.xml with its docBase redirected to your project's workspace:

<Context path="/ejb3example" docBase="/myworkspace/ejb3example" reloadable="true">
</Context>

This will let you to edit your EJBs. And as you save your edits, you'll see Tomcat hot-deploy your changes and you can continue debugging (obviously this has its limitations as some application states may or may not change, but you can always stop and run Tomcat again and still avoid the deploy cycle).

Conclusion
If you're planning to migrate to JEE 5, using an embedded EJB container such as OpenEJB 3 makes it easy to develop and test your EJBs without having to change platforms or port your Web apps to a new environment. You can also define JMS and Web Service endpoints with annotations, customize JNDI naming conventions to match other JEE app servers, add interceptors, and even inject types that go beyond the EJB 3 specifications. OpenEJB 3 makes JEE development easier for the experienced developer and introduces EJB 3 in a more accessible manner for those new to and learning JEE.