You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Adib Saikali <ad...@gmail.com> on 2013/10/09 05:24:29 UTC
Proposal for a more flexible tomcat embedding api
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Proposal for a more flexible tomcat embedding api
Posted by Pid <pi...@pidster.com>.
Hi,
I've already got reasonably far with a similar idea.
https://github.com/pidster-dot-org/embed-apache-tomcat
There's a core utility for embedding Tomcat[1] and a JUnit Rule[2] for
testing that uses it, e.g.
1.
https://github.com/pidster-dot-org/embed-apache-tomcat/blob/master/embed-apache-tomcat-core/src/test/java/org/pidster/tomcat/embed/TomcatSimpleTest.java
2.
https://github.com/pidster-dot-org/embed-apache-tomcat/blob/master/embed-apache-tomcat-test/src/test/java/org/pidster/tomcat/embed/junit/TomcatServerRuleTest.java
I'd call it an alpha right now, because I need to nail the test coverage
and there's a few TODOs.
I've snuck it into Maven Central here:
http://search.maven.org/#search%7Cga%7C1%7Corg.pidster
I'd be interested to hear feedback from the list:
p
On 9 October 2013 16:36, Adib Saikali <ad...@gmail.com> wrote:
> I am creating the API in such a way that if an attribute was added to the
> component but not to the builder API the user of the API should be
> able to participate in the creation of the underlying tomcat component
> object and override its setting. They would have to write more code but
> could account for properties that are left out of the builder API. And when
> that happens the Java doc will encourage them to file a bug report to
> add the missing attributes to the builder api.
>
> I want a version 1.0 of the builder api to work with no changes to the
> existing
> tomcat apis. However, I am sure I will run into situations where changes
> to API
> might make the implementation easier, and or could be good cleanups for the
> tomcat itself, in which case I will open bug reports in bugzilla and
> explain issues
> so that they can be handled in the normal course of tomcat development.
>
> On 2013-10-09, at 6:59 AM, Mark Thomas <ma...@apache.org> wrote:
>
> > On 09/10/2013 04:24, Adib Saikali wrote:
> >
> > <snip/>
> >
> >> 1. Has anyone already done such as API?
> >
> > I'm not aware of any.
> >
> >> 2. Would the tomcat committers accept an implementation of this
> proposal into
> >> the tomcat distribution ?
> >
> > The main question for me is maintainability and how much work would be
> > required to handle any new attributes added to a component.
> >
> >> 3. there still time to include such an API in tomcat 8?
> >
> > The deadline depends on what API changes would be required to Tomcat. It
> > looks like none so could be added at any point.
> >
> >> 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?
> >
> > Again, it depends on the required API changes. The fewer the changes the
> > greater the chance of inclusion.
> >
> > Mark
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> > For additional commands, e-mail: dev-help@tomcat.apache.org
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
>
--
pidster.com
Re: Proposal for a more flexible tomcat embedding api
Posted by Adib Saikali <ad...@gmail.com>.
I am creating the API in such a way that if an attribute was added to the
component but not to the builder API the user of the API should be
able to participate in the creation of the underlying tomcat component
object and override its setting. They would have to write more code but
could account for properties that are left out of the builder API. And when
that happens the Java doc will encourage them to file a bug report to
add the missing attributes to the builder api.
I want a version 1.0 of the builder api to work with no changes to the existing
tomcat apis. However, I am sure I will run into situations where changes to API
might make the implementation easier, and or could be good cleanups for the
tomcat itself, in which case I will open bug reports in bugzilla and explain issues
so that they can be handled in the normal course of tomcat development.
On 2013-10-09, at 6:59 AM, Mark Thomas <ma...@apache.org> wrote:
> On 09/10/2013 04:24, Adib Saikali wrote:
>
> <snip/>
>
>> 1. Has anyone already done such as API?
>
> I'm not aware of any.
>
>> 2. Would the tomcat committers accept an implementation of this proposal into
>> the tomcat distribution ?
>
> The main question for me is maintainability and how much work would be
> required to handle any new attributes added to a component.
>
>> 3. there still time to include such an API in tomcat 8?
>
> The deadline depends on what API changes would be required to Tomcat. It
> looks like none so could be added at any point.
>
>> 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?
>
> Again, it depends on the required API changes. The fewer the changes the
> greater the chance of inclusion.
>
> Mark
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Proposal for a more flexible tomcat embedding api
Posted by Mark Thomas <ma...@apache.org>.
On 09/10/2013 04:24, Adib Saikali wrote:
<snip/>
> 1. Has anyone already done such as API?
I'm not aware of any.
> 2. Would the tomcat committers accept an implementation of this proposal into
> the tomcat distribution ?
The main question for me is maintainability and how much work would be
required to handle any new attributes added to a component.
> 3. there still time to include such an API in tomcat 8?
The deadline depends on what API changes would be required to Tomcat. It
looks like none so could be added at any point.
> 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?
Again, it depends on the required API changes. The fewer the changes the
greater the chance of inclusion.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org