Open source Java projects: TomEE

Scale to enterprise with the Java EE 6 Web container built on Tomcat

1 2 Page 2
Page 2 of 2
  • JtaManaged: Determines whether the data source should be JTA managed or user managed. If set to true (the default value), then the data source will automatically join any ongoing transactions. Calling begin/commit/rollback or setAutoCommit on the data source or connection will not be allowed. If you need to perform these functions yourself, set JtaManaged to false.
  • JdbcDriver: The class name of the JDBC driver. The default configuration is set to use Hypersonic DB so the default value is org.hsqldb.jdbcDriver.
  • JdbcUrl: The JDBC URL that defines how to connect to the database. 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 will be sent to the JDBC driver when establishing new connections. The format of the string must be [propertyName=property;]*
  • DefaultAutoCommit: Defines whether or not transactions are automatically committed. The default value is true.
  • DefaultReadOnly: The default state for determining whether or not connections to the database should be read-only. Some databases do not support read-only connections, which case this value will not be passed in.
  • DefaultTransactionIsolation: If the transaction isolation level is not set then this is the value that it is configured to. Valid values are NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, and SERIALIZABLE. The default value is database dependent.
  • InitialSize: The initial number of connections to create in the pool. The default value is 0.
  • MaxActive: The maximum number of connections that can be active in this connection pool at any given time. The default value is 20.
  • MaxIdle: The maximum number of connections that can be idle in the connection pool without extra connections being released. The default is 20, but you can set a negative number to mean unlimited.
  • MinIdle: The minimum number of connections that can remain idle in the pool without extra ones being created. The default value is 0, which creates none.
  • MaxWait: The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. The default value is -1, which waits indefinitely.
  • ValidationQuery: The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row.
  • TestOnBorrow: If true then connections will be validated before being returned from the pool. If the validation fails, the connection is destroyed, and a new connection will be retrieved from the pool (and validated). The default value is true.
  • TestOnReturn: If true then connections will be validated before being returned to the pool. If the validation fails, the connection is destroyed instead of being returned to the pool. The default value is false.
  • TestWhileIdle: If true then connections will be validated by the idle connection evictor (if any). If the validation fails, the connection is destroyed and removed from the pool. The default value is false.
  • TimeBetweenEvictionRunsMillis: The number of milliseconds to sleep between runs of the idle connection evictor thread. When set to a negative number, no idle connection evictor thread will be run. The default value is -1.
  • NumTestsPerEvictionRun: The number of connections to examine during each run of the idle connection evictor thread (if any). Default value is 3.
  • MinEvictableIdleTimeMillis: The minimum amount of time in milliseconds a connection may sit idle in the pool before it is eligible for eviction by the idle connection evictor (if any). Default value is 1800000.
  • PoolPreparedStatements: If true then a statement pool is created for each Connection and PreparedStatements are pooled. The default value is false.
  • MaxOpenPreparedStatements: The maximum number of open statements that can be allocated from the statement pool at the same time, or zero for no limit. The default value is 0.
  • AccessToUnderlyingConnectionAllowed: If true the raw physical connection to the database can be accessed by the application. The default value is false.

That's a long list, but if you're working with TomEE it will be important that you understand what each parameter means and the impact of its default behavior. Listing 1, an example of a database connection being created for a movie 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 source named "moviesdb," which runs on localhost. Because the size parameters are not included, this connection pool will have a maximum of 20 connections 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 wiring is 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, either defined in your container or in your application's configuration files, into components in your application. For example, if you define a database connection pool in your environment, that database connection pool gets injected into your classes via resource resolution. TomEE's process of resolving resources can be summarized as follows:

  • If the @Resource name attribute is not present then TomEE matches the variable name to a resource name (as shown in Listing 2)
  • If the @Resource name attribute is present then TomEE matches the resource by its explicit name (as shown in Listing 3)
  • The application can explicitly look-up the resource in JNDI using 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 to other resources:

  1. Define a <Resource> element in the conf/tomee.xml file with the type of resource you want to configure.
  2. Define the required name/value pairs to configure the resource (resource-type dependent) inside the body of the <Resource> node
  3. Wire the resource into your application using an @Resource annotation

Below is a sample listing of the valid resource types (see Resources for a complete listing):

  • ActiveMQResourceAdapter
  • javax.jms.ConnectionFactory
  • javax.jms.Queue
  • javax.jms.Topic
  • org.omg.CORBA.ORB
  • javax.mail.Session

Listing 4 shows the configuration for an ActiveMQ resource adapter, a JMS connection factory, and a Queue and Topic.

Listing 4. A sample JMS configuration

<Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
        BrokerXmlConfig =  xbean:file:conf/activemq.xml
        ServerUrl       =  tcp://someHostName:61616
    </Resource>

    <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">
        ResourceAdapter = MyJmsResourceAdapter
    </Resource>

    <Container id="MyJmsMdbContainer" ctype="MESSAGE">
        ResourceAdapter = MyJmsResourceAdapter
    </Container>

    <Resource id="FooQueue" type="javax.jms.Queue"/>
    <Resource id="BarTopic" type="javax.jms.Topic"/>

Note that TomEE manages references and dependencies between resources. You can then wire these resources into your application using the @Resource annotation, as shown in Listing 5. Note that the rules for resource-resolution, defined above, hold true here.

Listing 5. Wiring in a JMS resources

public MyClass {
   ...
   @Resource
   private ConnectionFactory myJmsConnectionFactory;

   @Resource(name = "fooQueue", type = javax.jmx.Queue.class)
   private Queue fooQueue;
   
   @Resource(name = "barTopic", type = javax.jmx.Topic.class)
   private Queue fooQueue;
}

In conclusion: TomEE or just Tomcat?

TomEE is a Java EE 6 Web Profile-compliant container that builds on the simplicity of Tomcat and adds to its enterprise capabilities. The development strategy of keeping things simple and retaining the essence of Tomcat has resulted in a very lightweight container that starts up quickly and does not add to the memory requirements of Tomcat. Thus, TomEE provides a solution for organizations looking to embrace enterprise-scale technologies but deploy to a reasonably sized environment.

For developers and shops needing to decide between TomEE and Tomcat, I would break it down this way:

  • Tomcat is a web container, meaning that it supports the Servlet specification, JSP and JSF specifications, and provides support for JDBC. If these capabilities satisfy the requirements of your application then by all means stick with Tomcat.
  • TomEE is a true enterprise deployment platform; it provides a lightweight and inexpensive infrastructure for building enterprise applications that must leverage technologies like JMS, JTA, JPA, and EJBs.

It is possible (as discussed in detail here) to utilize Tomcat as an enterprise server. I am currently working on a large-scale application and we are deploying to a variation of Tomcat. But in order to meet our application's needs, we have also incorporated a separate Enterprise Service Bus (ESB), client messaging technologies, and liberal use of web services. So we assembled the technologies that we wanted to use into Tomcat -- functionality that TomEE would have provided out of the the box. (Our case illustrates another reason for using Tomcat, which is that our application isn't entirely open source. We needed the flexibility that Tomcat provides.)

Coming up next in the Open source Java projects series: GitHub!

Learn more about this topic

More about deployment servers, containers, and platforms on JavaWorld

From Apache's OpenEJB/TomEE homepage

More from JavaWorld

1 2 Page 2
Page 2 of 2