tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Adib Saikali <>
Subject Proposal for a more flexible tomcat embedding api
Date Wed, 09 Oct 2013 03:24:29 GMT

I am a long time tomcat user over the past few months I have started to use 
embedded tomcat, in the process I have discovered a few limitations and I want 
to make the following proposal to fix these issues.

Tomcat Builder Proposal:

This proposal outlines a design for an API that will make embedding tomcat easy 
without sacrificing the ability to customize the tomcat configuration as provided by
 server.xml and files in /conf.

You are probably thinking that we already have Tomcat.class for making 
embedding easier. However, There are many settings that are easy to configure 
in server.xml which are not easy or not possible to configure with Tomcat.class for example.

  * Configuring multiple connectors 
  * Adding valves
  * Configuring a cluster
  * Defining Resources such as DataSources / Mail Sessions
  * Setting a default web.xml for tomcat
  * Setting the properties found in 

Bottom line is that when you want to embed tomcat with a production like custom configuration

the current tomcat class does not provide enough apis to make it possible to do what you want.

What I am proposing is a new embedding API under org.apache.tomcat.builder 
that will provide an embedding api with the following goals.

  * Everything that can be configured via server.xml, or or any file found
 in /conf folder can be configured via the tomcat builder api. As a user I can be 100% confident
 that I can programmatically control every aspect of tomcat. 

  * The API builds on the existing structure of the xml configuration and the 
existing documentation. Someone who knows how to do something with 
configuration files should be able to correctly guess how to do the same thing 
with the embedding API without having to read the Java doc or  sample code. 

  * The reference documentation for tomcat configuration should be applicable 
to the embedding api so that existing documentation does not need to be updated 
and can just be reused. 

  * One liner start that allows a default configuration of tomcat to be started with a single
line of java code 

  * Total control start where every aspect of the configuration is customized 

Proposed Design: 

 * A fluent API that mirrors the major objects exposed via the XML elements 
example objects are 

  * ServerBuilder 
  * ServiceConfiguration
  * EngineConfiguration
  * ContextConfiguration
  * ValveConfiguration
  * ResourceConfiguration
  * ConnectorConfiguration 
  * …. Etc 

 * The fluent API will make it possible to build a graph of the configuration 
objects quickly & easily then call a build() method to get the configured 
Server object that can be started. 

* A DefaultServerConfiguration class that provides the ability to start tomcat 
with one line call using default settings as configured in the default 
server.xml that ships with tomcat.

* The API will be implemented for both Tomcat 7 and Tomcat 8

* The API will just work on top on an existing build you should be able to drop a tomcat-builder.jar
into CATALINA_HOME\lib and have it be available

* The existing Tomcat class will not be touched. 
Simple start example Usage:

DefaultServer server = new DefaultServer();
server.deployAppDir("src/main/webapp", 7777).start();

Fluent Api with Customization Example:

ServerBuilder serverBuilder = new ServerBuilder();
Server server =;

Code Repo: contains a very early version of 
this API it is just work in progress after only a few hours of work there is 
enough there to get a better idea of what I am proposing.

If you are wondering why as a user why you want to embed tomcat please refer to my slides
on this topic from. 

 * Java One 2013 -
 * Toronto JUG -

What I am looking for are answers to the following questions.

 1. Has anyone already done such as API?

 2. Would the tomcat committers accept an implementation of this proposal into 
the tomcat distribution ? 

 3. there still time to include such an API in tomcat 8?

 4.  Is there any chance that such a jar would be included in the core tomcat 7 
distribution as an add on jar in a future 7.x point release?


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message