Open source Java projects: TomEE

Apache TomEE aims to provide application developers with abest-of-breed technology stack that can be deployed to a simple and lightweightJava EE container. In this return to the Open source Java projects series,author Steven Haines introduces TomEE, explains how it differs from Tomcat, andhelps you set it up in your development environment. He then walks through theprocess of configuring TomEE to integrate resources such as database connectionpools and JMS destinations -- bread and butter for todays enterprise apps.
Tomcat is a popular choice among lightweight, open source application servers,but for developers seeking a more enterprise-ready app server, the options havebeen mostly commercial. With TomEE, Apache hopes to change all that -- and thensome. In this installment in the Open source Java projects series, Ill go underthe hood of TomEE to explain how it differs from plain old Tomcat. Youll alsohave the opportunity to meet TomEE (pronounced "Tommy") hands-on, witha deep-dive review of what is required to configure TomEE to host yourapplication. Since the main benefit of using TomEE over Tomcat is its supportfor enterprise technologies, Ill show you how to configure various types ofresources, as well as the process to wire those resources into yourapplication.
About TomEE
You might recognize TomEE from its parent project, OpenEJB. TomEE started outas the integration of Tomcat with OpenEJB, but that definition proved toonarrow. As explained on the TomEE homepage, EJB itself is an expansivespecification, including support for most of the Java specs used in enterpriseJava development today. But TomEE builds on top of OpenEJBs integration withJMS, Web services, connectors, Servlets, JPA, JDBC, and Java Transactions andSecurity, adding support for ActiveMQ, CXF, MyFaces, and OpenJPA.
In evolving TomEE to be Tomcat plus Java Enterprise Edition, TomEEs open sourcedevelopment team worked with three key design principles:
•    Dont mess with Tomcat
•    Keep it simple
•    Avoid architectural overhead
The goal was to add enterprise features to Tomcat without incurring additionalruntime requirements or startup time for larger applications. Based on recentlypublished benchmarks for TomEE 1.0, it looks like they succeeded. The followingstatistics compare the start times of applications in TomEE versus otherdeployment environments:
•    Rails 3.3 Custom (44mb WAR): 21.3% of beta2 startup time(369% faster)
•    Lift/Scala sample app (23mb WAR): 43.8% of beta2 startuptime (128% faster)
•    Confluence 3.5.5 (149mb unpacked): 37.6% of beta2 startuptime (166% faster)
TomEE and TomEE Plus
Its no secret that the Java EE technology stack is very large. This poses avariety of challenges, but can make it especially difficult for non-commercialvendors like Apache, that cannot necessarily afford the infrastructure overheadof implementing a full-stack Java EE application. So, with Java 6, the JCPintroduced Java EE certification profiles.
If your application only requires those technologies, then you can takeadvantage of TomEEs lightweight, low-overhead container. Projects that need alittle more might consider using TomEE+, which is currently not Java EE 6Certified. TomEE+ includes support for SOAP and RESTful web services, as wellas JMS and the Java EE Connector Architecture. See the OpenEJB homepage for anup-to-date matrix comparing features available in Tomcat, TomEE, TomEE Plus,and OpenEJB.
You can download TomEE or TomEE+ from the TomEE homepage. Note that I usedTomEE+ for the sample application, though you should be able to follow alongwith either version.
TomEE in your development environment
After youve downloaded TomEE or TomEE+, decompress it to a directory on yourcomputer. Just like Tomcat, TomEE requires that you install a JDK and configurea JAVA_HOME environment variable. The JAVA_HOME environment variable shouldpoint to the root of the directory in which you installed the JDK and youshould add the JAVA_HOME/bin directory to your PATH environment variable.
You can set the JAVA_HOME on Windows with the following command (assuming thatyou installed your JDK in C:Program FilesJava):
The TomEE log file is much larger than a traditional Tomcat log file becauseTomEE is starting far more services than Tomcat. An informational message thatstates "Server startup in xxx ms" indicates that the server startedsuccessfully. To validate that TomEE is running, open a web browser to the"tomee" web context on the machine on which TomEE is running, forexample:
Application deployment with TomEE
Deploying application artifacts to TomEE is very similar to deploying toTomcat: simply copy your WAR or EAR file to the tomee/webapps folder. WhenTomEE sees your WAR or EAR file, it will explode your archive into a directorywith the same name, but without the .war or .ear extension.
TomEE supports a new feature introduced with Java EE 6, which is the ability todeploy your EJBs and web artifacts in a single web archive (WAR file). Thepurpose of doing this is to enable your web application and your EJBs to sharethe same classloader and third-party libraries (such as Spring), and to allowservlets to see EJB classes and EJBs to see servlet classes. For packagingpurposes, the web.xml and ejb-jar.xml files live in the same WAR file.
This new packaging scheme is quite a difference from J2EE and even Java EE 5,which both required a strict separation between EJBs and Web code. If you stillneed these layers of separation, you can package your WAR file and EJB JARfiles inside an EAR file. If you do not need the separation, however, it ismore performant and much easier to configure all your classes in the samearchive while sharing the same class loader.
Defining external resources
An enterprise application would be pretty useless if it never interacted withany external resources. There are two basic strategies for defining resources:
•    Container managed
•    Application managed
Container managed resources are configured in the container, outside of theapplication itself. The application subsequently acquires those resources fromthe container when it needs them. Application managed resources are defined atthe application-level, usually through configuration files. They are wired intothe application on load or when needed.
The benefit of container managed resources is that the same application can runin different environments with just a few simple environmental configurationchanges. For example, in a QA environment an application might be configured topersist data to and from a QA database and publish messages to QA topics; butin a User Acceptance Testing (UAT) environment those external resources wouldbe different. Having the environmental configuration performed on the containeralso removes the risk that the application will inadvertently point to thewrong environment (such as deploying an application to a production environmentthat is pointing to a QA database). Finally, most monitoring tools provide theability to automatically discover container managed resources that publishresource metrics via Java Management Extensions (JMX). Most production supportteams for medium- to large-scale applications configure resources at thecontainer-level.
The benefits to defining resources inside the application are primarily withrespect to ease-of-deployment. It is far easier to deploy an application thatknows about all of its dependencies than it is to deploy one whose collectionof resources must be externally defined. Some projects get around this bycombining the two approaches; for instance, the application might define theresource, such as configuring a database connection pool, but then extract theJDBC URL from the deployment environment.
Defining a container-managed database connection pool
Database connections are probably the most common resource to configure for anenterprise application, so well try configuring a database connection as a wayof learning more about TomEE.
The first step is to copy your JDBC driver (JAR or ZIP file) to the tomee/libfolder so that the classloader will be able to find it when TomEE starts up.Next, you must configure the database connection in a Resource> XML node inthe tomee/conf/tomee.xml file.
To create a data source, define a Resource> node with a type of"DataSource," as shown here:
Resource id="MyDataSource" type="DataSource">
/Resource>
The body of this node accepts a simple set of name-value pairs that configurethe data source.
Database configuration example
Resource configuration is a huge topic, so I direct you to the TomEE homepagefor complete documentation. Well practice with a database configuration, whichincludes all of the options summarized below.
•    JtaManaged: Determines whether the data source should beJTA managed or user managed. If set to true (the default value), then the datasource will automatically join any ongoing transactions. Callingbegin/commit/rollback or setAutoCommit on the data source or connection willnot be allowed. If you need to perform these functions yourself, set JtaManagedto false.
•    JdbcDriver: The class name of the JDBC driver. The defaultconfiguration is set to use Hypersonic DB so the default value isorg.hsqldb.jdbcDriver.
•    JdbcUrl: The JDBC URL that defines how to connect to thedatabase. The default value is jdbc:hsqldb:file:data/hsqldb/hsqldb.
•    UserName: The database username. The default value is sa.
•    Password: The password for the specified username.
•    ConnectionProperties: The connection properties that willbe sent to the JDBC driver when establishing new connections. The format of thestring must be [propertyName=property;]*
•    DefaultAutoCommit: Defines whether or not transactions areautomatically committed. The default value is true.
•    DefaultReadOnly: The default state for determining whetheror not connections to the database should be read-only. Some databases do notsupport read-only connections, which case this value will not be passed in.
•    DefaultTransactionIsolation: If the transaction isolationlevel is not set then this is the value that it is configured to. Valid valuesare NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, and SERIALIZABLE.The default value is database dependent.
•    InitialSize: The initial number of connections to create inthe pool. The default value is 0.
•    MaxActive: The maximum number of connections that can beactive in this connection pool at any given time. The default value is 20.
•    MaxIdle: The maximum number of connections that can be idlein the connection pool without extra connections being released. The default is20, but you can set a negative number to mean unlimited.
•    MinIdle: The minimum number of connections that can remainidle in the pool without extra ones being created. The default value is 0,which creates none.
•    MaxWait: The maximum number of milliseconds that the poolwill wait (when there are no available connections) for a connection to bereturned before throwing an exception. The default value is -1, which waitsindefinitely.
•    ValidationQuery: The SQL query that will be used tovalidate connections from this pool before returning them to the caller. Ifspecified, this query MUST be an SQL SELECT statement that returns at least onerow.
•    TestOnBorrow: If true then connections will be validatedbefore being returned from the pool. If the validation fails, the connection isdestroyed, and a new connection will be retrieved from the pool (andvalidated). The default value is true.
•    TestOnReturn: If true then connections will be validatedbefore being returned to the pool. If the validation fails, the connection isdestroyed instead of being returned to the pool. The default value is false.
•    TestWhileIdle: If true then connections will be validatedby the idle connection evictor (if any). If the validation fails, theconnection is destroyed and removed from the pool. The default value is false.
•    TimeBetweenEvictionRunsMillis: The number of millisecondsto sleep between runs of the idle connection evictor thread. When set to a negativenumber, no idle connection evictor thread will be run. The default value is -1.
•    NumTestsPerEvictionRun: The number of connections toexamine during each run of the idle connection evictor thread (if any). Defaultvalue is 3.
•    MinEvictableIdleTimeMillis: The minimum amount of time inmilliseconds a connection may sit idle in the pool before it is eligible foreviction by the idle connection evictor (if any). Default value is 1800000.
•    PoolPreparedStatements: If true then a statement pool iscreated for each Connection and PreparedStatements are pooled. The defaultvalue is false.
•    MaxOpenPreparedStatements: The maximum number of openstatements that can be allocated from the statement pool at the same time, orzero for no limit. The default value is 0.
•    AccessToUnderlyingConnectionAllowed: If true the rawphysical connection to the database can be accessed by the application. Thedefault value is false.
Thats a long list, but if youre working with TomEE it will be important thatyou understand what each parameter means and the impact of its defaultbehavior. Listing 1, an example of a database connection being created for amovie database in MySQL, demonstrates a realistic database configuration.
Listing 1. Sample database configuration
Resource id="moviesDatabase" type="DataSource">
  JdbcDriver com.mysql.jdbc.Driver    
  JdbcUrl jdbc:mysql:localhost:3306/moviesdb    
  UserName sa    
  Password secret    
  JtaManaged true    
/Resource>
This example creates a JDBC connection pool pointing to a MySQL data sourcenamed "moviesdb," which runs on localhost. Because the sizeparameters are not included, this connection pool will have a maximum of 20connections and prepared statements will not be cached.
Once you have the resource defined you can import it into your code as follows:
Listing 2. Matching the variable name by its resource name
@Resource DataSource moviesDatabase
If needed, your resource reference could be more explicit about how the wiringis resolved:
Listing 3. Matching the variable name by its explicit name
@Resource(name = "moviesDatabase", type = javax.sql.DataSource.class)DataSource database;
Resource resolution
The purpose of resolving resources is to inject the correct resources, eitherdefined in your container or in your applications configuration files, intocomponents in your application. For example, if you define a databaseconnection pool in your environment, that database connection pool getsinjected into your classes via resource resolution. TomEEs process of resolvingresources can be summarized as follows:
•    If the @Resource name attribute is not present then TomEEmatches the variable name to a resource name (as shown in Listing 2)
•    If the @Resource name attribute is present then TomEE matchesthe resource by its explicit name (as shown in Listing 3)
•    The application can explicitly look-up the resource in JNDIusing an InitialContext and resource-ref> elements in its web.xml file.
Defining other types of resources
Now we can apply what we know about defining the database connection pool to toother resources:
1.    Define a Resource> element in the conf/tomee.xml filewith the type of resource you want to configure.
2.    Define the required name/value pairs to configure theresource (resource-type dependent) inside the body of the Resource> node
3.    Wire the resource into your application using an @Resourceannotation