Hi,
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 catalina.properties
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 catalina.properties 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();
serverBuilder.jspOn().shutdownPort(8006).shutdownString("shutdown");
Server server = serverBuilder.build();
server.start();
server.await();
Code Repo:
https://github.com/asaikali/tomcat-builder 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 - https://bitbucket.org/asaikali/javaone-tomcat-embedding
* Toronto JUG - https://bitbucket.org/asaikali/tjug-tomcat-embedding
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?
Cheers
Adib
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
