Building collapsed EAR through Maven for Weblogic & Tomcat with OpenEJB aka TomEE

Introduction

For this tutorial I had the challenge to deploy the same Java enterprise application (e.g. EAR-file) on Oracle Weblogic as well as on Apache Tomcat.

First of all you have to know that Tomcat isn’t an application server.  It also doesn’t support the deployment of EAR-files, which is logical considering the first statement.  Luckily, since JEE6, there is the possibility of the collapsed EAR technique (see http://openejb.apache.org/collapsed-ear.html), which consist of repackaging the EAR-file into WAR-file which is deployable on Tomcat.  Tomcat doesn’t also support Enterprise Java Beans out of the box, so that’s were TomEE comes to the rescue. TomEE is a project which simplifies the usage of OpenEJB on Tomcat.

In this article I will mainly focus on Tomcat and less on Weblogic because it was more challeging to make it run on Tomcat.  The result is that the application will run on both servers.

The application uses Java Persistence Api 1.0 with Eclipse Link to connect to the database.  This is all exposed through EJB’s.  There is also the need to talk to a JMS Queue and process the messages via a Message Driven Bean.

The UI is done with Java Server Faces 2.  The application has of course to be unit tested.

Used technologies

The application uses several JEE technologies, namely:

• JPA or Java Persistence API 1.0 with Eclipse Link 1.1.0 as provider.
• EJB or Enterprise Java Beans 3.0 with OpenEJB 3.1.4 as provider.
• Bean Validation API 1.0 with Hibernate Validator 4.0.2 as provider.
• JMS or Java Messaging Service with ActiveMQ 5.2 as provider.
• JSF or Java Server Faces 2.0 with the Glassfish reference implemenation as provider.
• JAX-WS or Java API for XML Web Services with Glassfish Metro and Apache CXF as possible providers.

Configuration in 10 steps

1. Install Tomcat 6.0.35.
2. Copy ojdbc14-10.2.0.4.0.jar to %TOMCAT_INSTALL_DIR%/lib.
3. Copy eclipselink-1.1.0.jar to %TOMCAT_INSTALL_DIR%/lib.
4. Copy validation-api-1.0.0.GA.jar to %TOMCAT_INSTALL_DIR%/lib.
5. Copy hibernate-validator-4.0.2.GA.jar to %TOMCAT_INSTALL_DIR%/lib.
6. Copy slf4j-api-1.6.1.jar to %TOMCAT_INSTALL_DIR%/lib.
7. Copy openejb.war to %TOMCAT_INSTALL_DIR%/webapps.
8. Start Tomcat and once up-and-running, go to the following url with your browser (if Tomcat is running on localhost with port 8080, will vary depending on your installation): http://localhost:8080/openejb/installer.
9. Click on the ‘install’-button on the webpage, once installed, stop Tomcat.
10. Go to the %TOMCAT_INSTALL_DIR%/config directory and edit the the openejb.xml file. Under the Resource-element named “My JMS Resource Adapter” and before the Connector-element named “My JMS Connection Factory”, add the following resources in between as defined below:

<Resource id="jdbc/tomee-maven-demo-ds" type="DataSource">
  JdbcDriver oracle.jdbc.xa.client.OracleXADataSource
  JdbcUrl jdbc:oracle:thin:@localhost:1521:XE
  UserName scott
  Password scott
  JtaManaged true
</Resource>

<Resource id="jms/tomee-maven-demo-cf" type="javax.jms.ConnectionFactory">
  ResourceAdapter My JMS Resource Adapter
</Resource>

<Resource id="jms/tomee-maven-demo-q" type="javax.jms.Queue" />

Project setup

The project is divided into 4 different modules.

1. The jar module consists of  entity classes, the domain interface and service interface.
2. The ejb module contains the domain EJB’s storing the entities through JPA and eclipse link and the MDB’s processing the messages stored on the queue.
3. The war module contains the JSF 2 related stuff needed for the UI.
4. The ear module packages all the modules for deployment on an application server.

For clarification: I wanted to put the persistence.xml and orm.xml files inside the jar-file containing the EJB’s as those are the classes using the JPA entity manager.  Unfortunately it lead to class loading issues in Weblogic as the EJB jar is packaged directly under the EAR file. The entity classes are located under the APP-INF/lib (shared lib) directory within the ear which resulted in my entity classes not being found (e.g. ClassNotFoundException).  I’ve tried adding a reference to the jar containing the entity classes with the section within the persistence.xml file, but no avail. That’s why I putted those XML-files in the jar file containing the entity classes instead of the EJB jar.

Purpose

The purpose of this demo application is to develop an asynchronous webservice named MessageService.  The webservice puts the given message on a queue through an EJB called MessageMDBSender.  There is a Message Driven Bean named MessageMDB which will process any message posted on the queue and store them in the database through an EJB called MessageEJB.  That EJB uses JPA 1.0 with Eclipse Link to store the message into the database.  If the creation of the given message is successful, the webservice will send a callback to the client who send the initial request.

I’ve also added a soapUI project to allow the testing of the deployed asynchronous webservice on Tomcat

The code that is used to develop the asynchronous webservice is based on the example posted by Biemond, except I adapted the code to make it independent of the used webservice stack.

This means that the same code will work on Metro as well as on CXF, which is necessary as weblogic uses Metro and OpenEJB uses CXF. It also works with the Oracle SOA Suite for that manner.

Beside that I also wrote a class named CXFServlet in the test package of the war project. This class is also packaged with the war when building for Tomcat as I couldn’t figure out how to make the CXF webservices work out of the box with OpenEJB.  It seems that the webservices are deployed under the root of the Tomcat installation and not under the context root of the deployed web application.  If someone could tell me how to solve this issue that would we great as it would make the demo even simpler. Another problem that I encountered with OpenEjb and Tomcat is that the resource injection through env-entries in the ejb-jar.xml isn’t working. The same ejb-jar.xml file injects the env-entries correctly on Weblogic so I suspect there might be a bug there in the 3.1.4 release of OpenEJB. The injection also fails with unit tests.

To build the project for Weblogic, just type mvn clean install. Then deploy the generated ear-file to the application server.

To build the project for Tomcat, just type mvn clean install -Ptomcat. Then copy the generated war-file to the webapps directory of the Tomcat installation directory.

You can find the complete project on https://github.com/dabla/tomee-maven-demo.