TomEE: Tomcat with Java EE Extensions

Apache TomEE can be downloaded in various ways, including as a standalone Java EE application server or as a bundled WAR file that can be published with Tomcat7. TomEE adds the OpenEJB container to Tomcat7 but also includes, for example, the Apache CXF implementation of the JAX-RS API and a JMS provider. TomEE, like Tomcat, can be installed anywhere on the filesystem, and the TomEE directory structure is almost identical to that of Tomcat7. TomEE is designed with simplicity in mind. The Java world is awash with options and, with respect to JASes, TomEE is one worth considering.

Managing the TomEE Web Server and EJB Container

In a TomEE installation, the web server can be started and stopped independently of the EJB components, which includes the EJB container. A typical startup scenario would be:

• In TomEE_HOME/bin, run the startup script:

  % shartup.sh  ;; startup.bat under Windows

• In the same directory, run the startup script for the EE components:

  % tomee.sh start

The TomEE web server would be stopped in the usual way:

% shutdown.sh ;; shutdown.bat under Windows

The TomEE EE components are stopped with this command:

% tomee.sh stop

The TomEE web server furnishes the usual Tomcat7 web console (localhost:8080), which also includes a TomEE web console (localhost:8080/tomee) for the distinctly EE components.

Porting the predictionsEJB Web Service to TomEE

The two .java files in the predictionsEJB service, Prediction.java (see Example 7-6) and PredictionEJB.java (see Example 7-8), are completely unchanged in the port from GlassFish to TomEE. The configuration files, however, are different. The TomEE configuration files are the persistence.xml file (see Example 7-10), the same name as in GlassFish, and the openejb.xml file (see Example 7-11).

Example 7-10. The persistence.xml document for the TomEE port of the predictionsEJB service

<persistence>
  <persistence-unit name = "predictionsDB">
    <jta-data-source>predictionsDB</jta-data-source>
    <class>predEJB.Prediction</class>                       
    <properties>
      <property name  = "openjpa.jdbc.SynchronizeMappings"  
                value = "buildSchema(ForeignKeys=true)"/>   
    </properties>
  </persistence-unit>
</persistence>

In the persistence.xml document, lines 2 and 3 ensure that the OpenJPA provider automatically generates whatever database tables are required to persist Prediction instances. The configuration document also names the @Entity class Prediction (line 1) whose instances are mapped to table rows.

Example 7-11. The openejb.xml for the TomEE port of the predictionsEJB service

<Resource id = "predictionsDB" type = "DataSource">  
  JdbcDriver = org.hsqldb.jdbcDriver                 
  JdbcUrl = jdbc:hsqldb:mem:predictionsDB            
</Resource>

The second configuration document, openejb.xml, names the DataSource (line 1); specifies the JDBC driver (line 2), in this case the driver for the HSQLDB database, a convenient RDBMS with, by default, in-memory tables; and ends with the JNDI name (line 3) of the database system. The HSQLDB system comes with TomEE. TomEE documentation covers sample Resource configuration for various other popular database systems such as Derby, MySQL, and PostgreSQL. The two configuration files shown here must occur in the META-INF subdirectory of the deployed JAR file. The deployment options and details are laid out in the next section.

TomEE, like GlassFish, provides a JAR file with the required Java EE packages such as javax.persistence. All of the TomEE libraries come as JAR files and most of these are in the TomEE_HOME/lib directory, which contains more than 100 JAR files, including the files for the Apache CXF implementation of JAX-RS. There is also the directory TomEE_HOME/endorsed, which holds a few additional JAR files. The TomEE JAR for the core Java EE packages is named javaee-api-N-tomcat.jar, with a version number where the N occurs. This JAR, roughly the TomEE counterpart of the GlassFish file javaee.jar, can be used for compilation.

Deploying an EJB in a WAR File

TomEE comes with the familiar TomEE_HOME/webapps subdirectory already in place. The subdirectory TomEE_HOME/apps is not present but can be created manually, and the TomEE_HOME/bin/tomee.sh command has deploy and undeploy options that can be used to deploy EAR files whose contents are one or more JAR files, each with its own EJB. The deploy and undeploy options target the apps subdirectory, which TomEE supports for backwards compatibility with versions of Java EE earlier than 6. Under Java EE 6, the same Java class loader can load the contents of servlets and EJBs; hence, the Java EE 6 specification enables EJB deployment in a WAR file. This style of deployment is preferred practice in TomEE. The deployment details for the predictionsEJB service under TomEE can be summarized as follows:

• A standard WAR can be built using the (perhaps slightly modified) Ant script from earlier chapters. A web.xml document is not required. Suppose that the name of this file is pred.war. The two configuration files can be inserted into the WAR file subdirectory META-INF:

  % jar uf pred.war META-INF/*.xml  ;; persistence.xml and openejb.xml

  The resulting WAR structure is:

  META-INF/MANIFEST.MF
  META-INF/openejb.xml
  META-INF/persistence.xml
  WEB-INF/classes/predEJB/PredictionEJB.class
  WEB-INF/classes/predEJB/Prediction.class

• The WAR file is copied to TomEE_HOME/webapps for deployment. A website or a servlet-based service would be deployed in exactly the same way.

• The usual client-side artifacts can be constructed with the wsimport utility:

  % wsimport -p clientEJB -keep \
    http://localhost:8080/pred/webservices/PredictionEJB?wsdl

The TomEE endpoint URL for an EJB service differs slightly from the GlassFish endpoint. In particular, the TomEE URI in this example is /pred/webservices/PredictionEJB: the URI begins with the slash and the name of the WAR file (/pred), the term webservices is appended (/pred/webservices), and then the name of the @WebService class is appended to yield /pred/webservices/PredictionEJB. The very same ClientEJB used for the GlassFish deployment of predictionsEJB (see Example 7-9) can be used, once recompiled against the wsimport-generated artifacts to get the correct endpoint URL, against the TomEE deployment. It is a nice TomEE touch to support conventional WAR deployment of even EJBs, including EJB-based web services.