You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@locus.apache.org on 2000/08/09 07:50:42 UTC
cvs commit: jakarta-tomcat/proposals/tomcat-4.0 catalina-proposal.html jasper-proposal.html source-proposal.html
craigmcc 00/08/08 22:50:41
Added: proposals/tomcat-4.0 catalina-proposal.html
jasper-proposal.html source-proposal.html
Log:
Proposals for development of Tomcat 4.0 (see upcoming message to the
TOMCAT-DEV mailing list describing them further).
Revision Changes Path
1.1 jakarta-tomcat/proposals/tomcat-4.0/catalina-proposal.html
Index: catalina-proposal.html
===================================================================
<html>
<head>
<title>Proposal for Using Catalina in Tomcat 4.0</title>
</head>
<body bgcolor="white">
<div align="center">
<h1>Proposal for Using Catalina in Tomcat 4.0</h1>
<h2>$Id: catalina-proposal.html,v 1.1 2000/08/09 05:50:41 craigmcc Exp $</h2>
</div>
<h2>Introduction</h2>
<p>As many Tomcat developers are aware, development on a next generation
version of Apache JServ was in progress when Sun announced their contribution
of the Java Server Web Development Kit (JSWDK) source code to the Apache
Software Foundation in June 1999. Among other things, this caused interest
in further development of Apache JServ to dwindle, on the (reasonable)
assumption that Tomcat -- the code eventually delivered in October 1999 --
would become a natural successor to Apache JServ, with support for similar
functionality but providing the key enhancements of support for the current
versions of the servlet and JSP specifications.</p>
<p>When the code was delivered in October, it was obvious that its heritage
and purpose were not in conformance with the stated goals of the Jakarta
project ("commercial quality server solutions" and "world class implementation
of the Java Servlet 2.2 and JSP 1.1 Specifications" -- both quotes from the
home page at <http://jakarta.apache.org>). Although there have been
improvements in functionality, quality, and performance since that time, these
improvements have been relatively small in scale compared to the fundamental
problems of the code base -- very poor internal organization and documentation,
"spaghetti code" implementation of much of the functionality, substantial
numbers of bugs in key features, and a general lack of maintainability.</p>
<h2>Background</h2>
<p>When it became obvious that "evolutionary" changes to the existing code base
would take more effort and time than a "revolutionary" change to a new code
base, considerable effort was (and continues to be) expended to create a new
code base for the servlet container portion of Tomcat, based in large part
on the design direction that Apache JServ was already headed. In addition,
a set of goal statements was explicitly described. These goals (and the
Catalina architectural design that implements them) have been presented --
with very positive reception -- at several recent trade shows (ApacheCon in
March, O'Reilly Java Conference in March, JavaOne in June, and O'Reilly
Open Source Conference in July). Briefly, the goals cover the following
general areas:</p>
<ul>
<li>Create a servlet container useful in diverse deployment environments,
including (but not limited to):
<ul>
<li>Stand alone "application server"</li>
<li>Connected to an existing web server</li>
<li>Integrated in a full function application server (typically
providing the full suite of J2EE capabilities)</li>
<li>Integrated in a development tool</li>
<li>Embedded in a hardware device or software application (such as
providing the administrative user interface for a router or a
firewall)</li>
<li>Providing simultaneous support for non-HTTP protocols on the
same server infrastructure</li>
</ul></li>
<li>Support customizable functionality via plug-in components:
<ul>
<li>Internal architecture based on components, described by Java
interfaces</li>
<li>Implementation classes configurable at run time (with
appropriate defaults)</li>
<li>Component configuration based on JavaBeans property APIs</li>
<li>Optional component lifecycle support and events
provided in a consistent manner</li>
</ul>
<li>Support extensible request processing:
<ul>
<li>At various levels (entire server, virtual host, web
application/servlet context, or individual servlet)</li>
<li>Example applications: security (authentication and access control),
customized logging, resource management and transaction support,
and performance measurement</li>
<li>Configurable at run time</li>
</ul></li>
</ul>
<p>High level diagrams of the Catalina component architecture are included
in the session notes for the conference web sites mentioned above. In
particular, the JavaOne presentation can be downloaded from:
<code><http://jsp.java.sun.com/javaone/javaone2000/pdfs/TS-953.pdf></code>.
<p>The existing implementation of these goals is present in the
<code>proposals/catalina</code> directory of the <code>jakarta-tomcat</code>
CVS module. It passes 100% of the servlet tests (and 100% of the JSP tests
in conjunction with the JSP portions of Tomcat 3.x) from the
<code>jakarta-watchdog</code> test suite that validates conformance to the
servlet 2.2 and JSP 1.1 specifications.</p>
<h2>Comparison With Tomcat 3.X</h2>
<p>This section will be fairly brief, because the entire source code for
both Tomcat 3.x and Catalina is available for anyone to peruse and compare
for themselves. However, several key points are worthy of mention
(in alphabetical order):</p>
<ul>
<li><strong>Code Design</strong> - Many who have reviewed the source code
of Catalina and Tomcat 3.x have commented on Catalina's clean coding
style, overall consistency, and straightforward implementation of the
features of a servlet container. Such characteristics are not usually
evident in the code for Tomcat 3.x (although the current code base is
definitely an improvement over the original). This makes code
maintenance, especially by someone not intimately familiar with Tomcat,
tougher than it needs to be.</li>
<li><strong>Documentation</strong> - Catalina exhibits substantially better
and more complete documentation than Tomcat in many important areas,
including: overall architecture diagrams, complete JavaDoc comments,
and a substantial start towards documentation of server configuration
options in <code>conf/server.xml</code>. Tomcat currently includes a
more complete User's Guide, although it is in need of better organization
and presentation no matter what code base we use.</li>
<li><strong>Functionality</strong> - Compared to Tomcat 3.x, Catalina already
supports significant additional functionality in many areas, including:
<ul>
<li>HTTP/1.1 support in stand-alone mode (requires a web server to support
this for Tomcat 3.x).</li>
<li>DIGEST-based authentication, as well as BASIC and FORM authenitication
supported by Tomcat.</li>
<li>Request processing functionality (Valves in Catalina, versus
RequestInterceptors in Tomcat) that is configurable on a per-server,
per-virtual-host, or per-web-application level. The set of request
interceptors in Tomcat 3.x is currently global to all web applications
installed in a particular instance.</li>
<li>Valves support request and response filtering via wrappers, which
enables a much richer universe of functionality than the request
interceptors of Tomcat 3.x.</li>
<li>Support for non-HTTP protocols is possible in Catalina. Tomcat
assumes that every request is an HttpServletRequest, and every
response is an HttpServletResponse.</li>
<li>Abstraction of resource support (ServletContext.getResources() and
friends) so that Catalina can support resources loaded from a file
system, a JAR file, or (with the addition of customized components)
any other source -- such as BLOB objects in a database. Tomcat 3.x
is tied to loading resources only from a file system.</li>
<li>Configurable support for caching of recently accessed resources
(such as HTML pages and images) that can dramatically improve
performance of web applications which are predominantly dynamic
(but have some static components), or where the application is
loaded from a location where access is relatively slow (such as
a JAR file on a remote server).</li>
<li>The file-serving servlet in Catalina optionally supports full
WebDAV Level 2 functionality (see <http://www.webdav.org> for more
information), supporting web site management from clients like
Microsoft Office 2000.</li>
</ul>
At present, Tomcat 3.x has one very significant functional feature that
is not yet completed in Catalina -- support for the web server connectors
to Apache, Microsoft IIS, Netscape/iPlanet, and AOLServer. Work is
already under way to port the existing Tomcat 3.x connectors to Catalina,
and it is anticipated that this work will be completed in a timely
manner.</li>
<li><strong>Goals</strong> - The Catalina architecture was designed from its
inception to meet an articulated set of high level goals (see above).
The original goal of the Tomcat 3.x code base (prior to turning the
code over to Apache) was to produce a reference implementation, and
the Tomcat 3.x code has suffered churn in its architecture in part
because no such goals have been stated to compare it against.</li>
<li><strong>Maturity</strong> - Ironically, substantial portions of the
Catalina code base have been in their current organizational design
for much longer than the corresponding Tomcat code base. This is
partly due to the incremental way in which changes have occurred in
the Tomcat code base over the last year or so (including multiple
different approaches to some functional issues), but primarily due to
starting from a stable set of design goals. Tomcat 3.x continues to
exhibit an embarassing number of implementation bugs (for example, the
way that automatic reloading works when changes in Java class files are
detected is still fundamentally flawed in Tomcat 3.2).
Tomcat 3.x, of course, has been tested in "real life" by substantial
numbers of people, whereas Catalina has been tested primarily by
pioneers. It is to be expected that implementation bugs exist in
Catalina -- although experience in fixing Catalina bugs to date has
been that nearly all of them are relatively localized implementation
problems, not issues that require fundamental design changes.</li>
<li><strong>Performance</strong> - No formal benchmarks have been published
by the Tomcat development team describing the performance of Tomcat 3.x
or Catalina. (In addition, I would take any benchmark that purports to
predict how *your* application will perform on a particular server with a
very large grain of salt :-). However, simple tests with tools like
ApacheBench and Microsoft's stress test indicate that Catalina is
faster than Tomcat on serving static resources (substantially faster if
caching is enabled, basically on par with Apache itself), and within a few
percentage points on serving "Hello, World" type servlets and JSP pages.
Only modest efforts to tune Catalina have taken place to date (compared
to the substantial -- and successful -- tuning efforts expended between
Tomcat 3.1 and 3.2), so it can be assumed that there is still significant
room for improvement through the usual techniques of isolating hot spots
and optimizing them.</li>
</ul>
<h2>The Catalina Proposal</h2>
<p>Given this background, and the fact that initial public drafts of the
Servlet 2.3 and JSP 1.2 specifications is imminent, it is timely for us to
make a decision to use Catalina as the code base for Tomcat 4.0 (supporting
the features of the new specifications), while continuing to support the
Tomcat 3.x code base for as long as is appropriate. The associated proposal
for organizing the source code repository for Tomcat 4.0 development shows
how this dual track development approach can be supported easily.</p>
1.1 jakarta-tomcat/proposals/tomcat-4.0/jasper-proposal.html
Index: jasper-proposal.html
===================================================================
<html>
<head>
<title>Proposal for Development of Jasper in Tomcat 4.0</title>
</head>
<body bgcolor="white">
<div align="center">
<h1>Proposal for Development of Jasper in Tomcat 4.0</h1>
<h2>$Id: jasper-proposal.html,v 1.1 2000/08/09 05:50:41 craigmcc Exp $</h2>
</div>
<h2>Introduction</h2>
<p>The specification for JavaServer Pages<sup>TM</sup> (JSP) version 1.2 is
likely to require, among other things, exposing the internal structure of a
JSP page to custom tag libraries at page translation time. This will require
some substantial changes to the existing Jasper code base, and offers us the
opportunity to improve its internal organization and functionality.
Prior to undertaking these efforts, it is appropriate for us to discuss
and agree on the high level goals we wish to achieve, and the proposed overall
architecture of the new code.</p>
<p>This document proposes a set of goal statements, along with related
assumptions and implications, for the purpose of gaining consensus and
agreement at a high level. It also includes a first cut at an overall
architecture (subject to change if the goals change during the process of
consensus building)</p>
<p>Jasper is, and is proposed to remain, the component of Tomcat that compiles
and executes JSP pages. If the proposal on source code organization is also
accepted, it will live in a "jasper" subdirectory of the new
<code>jakarta-tomcat-4.0</code> CVS module.</p>
<h2>High Level Goals for Next Generation Jasper</h2>
<p>The statements in the following sections describe goals by which we can
measure the completeness and success of the efforts to develop the next
major version of the JSP page compiler and runtime environment currently known
as Jasper.</p>
<h3>Specification Compliance</h3>
<p>The result of this coding effort will support 100% of the required
functionality described in the JSP 1.2 specification (to be available as
an initial public draft fairly soon), as well as the relevant portions of
the Servlet 2.3 specification (to be available at the same time).</p>
<ul>
<li>The means by which specification conformance is tested shall include
passing 100% of the JSP tests in the <strong>jakarta-watchdog</strong> test
suite, as it is evolved to include tests for all the new features.</li>
<li>The servlet and JSP API classes against which Jasper is compiled and
executed shall be the most current version of the API classes for
JSP 1.2 and Servlet 2.3 that have been checked in to the
<strong>jakarta-servletapi</strong> repository while these specifications
are in public review. After the specifications are final, the final
versions of the API classes, as amended for any formally adopted errata
on the specifications after the are final, will be utilized.</li>
<li>In addition, Jasper shall provide a web application containing unit tests
to validate the functionality of its own behavior, above and beyond the
specification requirements.</li>
</ul>
<h3>Compiler Environment and Requirements</h3>
<p>The JSP page compiler component of Jasper shall operate in the following
environments:</p>
<ul>
<li>It shall be possible to execute the JSP page compiler, and produce the
corresponding servlet classes representing these pages, from a command
line application (currently <code>jspc</code>), without having to be
executed within a servlet container.</li>
<li>It shall be possible to embed the JSP page compiler as a servlet in any
servlet container conforming to the Servlet 2.3 Specification (not just
Tomcat). Among other things, this implies that there shall be no internal
code dependencies within Jasper on any classes in the
<code>org.apache.tomcat.*</code> package hierarcy.</li>
<li>When embedded as a servlet, the JSP page compiler shall support both
on-demand page compilation (when it detects that the source code of a
page has been changed) or on-request page compilation (based on the
reserved precompilation request URIs described in the JSP 1.2
specification).</li>
<li>When embedded as a servlet, the JSP page compiler shall support
optional compilation of JSP pages in the entire web application, or within
designated portions of the context-relative URI space, in response to
an "application startup" event.</li>
<li>It shall be feasible for servlet containers (such as Tomcat) to support
mechanisms for improved performance of the JSP page compiler that depend
on internal knowledge of the JSP page compiler and its classes if it
chooses to do so. Therefore, the key features and integration points
of the JSP page compiler shall be exposed through interfaces that can
remain stable across enhancements to the Jasper code base.</li>
<li>It shall be possible to embed the JSP page compiler inside a development
tool in such a way that JSP pages can be translated on request from within
that tool.</li>
</ul>
<p>The JSP page compiler component of Jasper shall support the following
high level functional capabilities:</p>
<ul>
<li>The compiler shall accept input pages in either the JSP syntax or the
XML syntax, as described by the JSP 1.2 Specification.</li>
<li>It shall be possible to use the appropriate portions of the compiler
(principally the parser) to build a tool that translates a page in
JSP syntax into a corresponding page using the XML syntax.</li>
<li>When executed in a stand-alone environment, or from within a development
tool, the JSP page compiler shall include the optional ability to generate
elements to be included in the web application deployment descriptor
(<code>WEB-INF/web.xml</code>) of the web application in which these
servlets will be included.</li>
<li>When executed from within a servlet container, the JSP page compiler
shall support the option to retain intermediate versions of the translated
source code (such as the internal XML representation and the Java source
code representation) after translation is complete.</li>
<li>The JSP page compiler shall support configurable properties and plugins
for customizing its functionality, including (but not limited to):
<ul>
<li>The mechanism by which Java class names for the generated servlet
are created.</li>
<li>The package name into which generated servlets are placed.</li>
<li>The processing performed for scriptlets, so that languages other than
Java can be used. The standard Jasper page compiler shall support
Java language scriptlets.</li>
<li>The Java compiler to be used for translating Java source code into
the corresponding servlet class file.</li>
</ul>
</li>
<li>The JSP page compiler shall support the optional generation of debugging
information (such as line and column numbers) that will assist the runtime
environment in identifying error locations in the original JSP page.
Initially, this debugging information shall be similar to that generated
by Jasper in Tomcat 3.2; however, once the JSR-045 specification (related
to adding debugging information to Java class files for non-Java languages)
is available in public draft, it shall be possible to configure the
generation of debugging information in this format as well.</li>
<li>The JSP page compiler shall support the ability to generate servlets
that extend a developer-provided superclass (rather than the default one
available in the runtime support classes included with Jasper), as
required by the JSP 1.2 specification. However, the organization of the
generated servlet code, and associated runtime support classes, should be
optimized for the case where the default superclass will be utilized.</li>
<li>To the maximum degree feasible, translation errors shall be reported
in terms of line and column numbers from the original JSP source page,
rather than line numbers in the generated servlet.</li>
<li>The JSP page compiler shall generate servlets that conform to all of the
requirements described below in section "Runtime Environment and
Requirements."</li>
</ul>
<h3>Runtime Environment and Requirements</h3>
<p>The servlet classes produced by the JSP page compiler (no matter which
mode the compiler itself was executed in) shall operate in the following
environments:</p>
<ul>
<li>The generated servlet classes may depend on runtime support classes that
are specific to Jasper. These runtime support classes shall be available
in a JAR file that can be included in the <code>WEB-INF/lib</code>
directory of a web application in which the generated servlet classes
will be executed, or made available as server extensions by whatever means
are supported by the servlet container they are deployed into.
<li>It shall be possible to deploy the generated servlet classes, and the
associated runtime support classes described above, on any servlet
container conforming to the Servlet 2.3 Specification (not just Tomcat).
Among other things, this implies that there shall be no internal code
dependencies in the generated servlet classes, or the runtime support
classes, on any classes in the <code>org.apache.tomcat.*</code>
package hierarchy.</li>
<li>It shall be feasible for servlet containers (such as Tomcat) to support
mechanisms for improved performance of the generated servlets that depend
on internal knowledge of the JSP page compiler, the servlet classes that
it generates, and the runtime support classes, if it chooses to do so.
Therefore, key features and integration points of the generated servlet
classes and runtime support classes shall be exposed through interfaces
that can remain stable across enhancements to the Jasper code base.</li>
<li>The generated servlet classes shall have no runtime dependencies on any
classes in the JSP page compiler. It shall be possible to run them in
a web application where all JSP pages have been precompiled, and no
runtime JSP page compilation is available. It shall also be possible
to run them (and recompile them if necessary) in an environment where
runtime JSP page compilation is available.</li>
<li>The generated servlet classes shall operate under the class loader and
security domain (if any) established by the servlet container in which
they are deployed.</li>
</ul>
<p>The servlet classes produced by the JSP page compiler (no what what
environment it was executed in) shall support the following high level
functional capabilities:</p>
<ul>
<li>To the maximum degree feasible, runtime exceptions shall be reported
in terms of line and column numbers from the original JSP source page,
rather than line numbers in the generated servlet.</li>
<li>Stack traces produced in response to translation or runtime errors may
be logged (via <code>ServletContext.log()</code>), but shall not be
reported back to clients whose requests triggered the errors.</li>
</ul>
<h2>Overall Architecture Proposal</h2>
<p>The following diagram contains the first cut at an overall architecture
for the next generation Jasper compiler, taking into account the goals
described earlier.</p>
<p><strong>FIXME - image containing the architecture diagram</strong></p>
<p>As you can see, the compiler is divided into several phases, with the
functionality described below:</p>
<ul>
<li><strong>Parser</strong> - Accept as input a page in either JSP syntax or
XML syntax, as described by the specification. Produce as output a DOM
view of the underlying page, as well as related source file debugging
information that can be passed along to be included in the servlet class
that is ultimately generated.</li>
<li><strong>Transformer</strong> - Accept as input the DOM and debugging
information provided by the Parser, and support the translation time
transformations described in the JSP 1.2 specification. The output will
be a revised DOM tree (transformed in place?) and revised debugging
information.</li>
<li><strong>Generator</strong> - Accept as input the (possibly transformed
and validated) DOM and debugging information from the Transformer, and
generate the source code for a Java servlet that implements the desired
functionality of the JSP page.</li>
<li><strong>Translator</strong> - Accept as input the Java servlet produced
by the Generator, and compile it with the configured Java compiler to
produce a servlet class file for this page.</li>
<li><strong>Deployer</strong> - If this page is being compiled in a stand
alone environment, the Deployer phase can be invoked to produce the
appropriate additions to the web application deployment descriptor
(<code>web.xml</code>), and a JAR file containing the compiled page
classes, to be included in a web application.</li>
</ul>
<p>The following points should be kept in mind when considering how to
implement the phases described above:</p>
<ul>
<li>At first blush, it would appear that the Parser could use a standard
JAXP-compatible DOM parser (with validation enabled) when reading XML
input. However, this will not be feasible for the following reasons:
<ul>
<li>Any JSP page (in XML syntax) that uses custom tag libraries will
not be possible to validate, because the custom tag attributes
themselves are not available in the DTD of the JSP page itself.</li>
<li>If you use a non-validating DOM parser, there is no access to source
line and column number information.
</ul>
Therefore, it appears that we should implement two parser front ends
(one for each syntax) that generate SAX events, and build a common parser
back end that produces the DOM and debugging information to be handed on
to the Transformer.</li>
<li>The front end for JSP syntax can be based on the existing parser code in
Jasper, after modifying to produce output in the expected format.</li>
<li>It should be easy to add a command-line tool that takes the DOM as input
and produces a page source file (in XML syntax) as output. This would be
useful for developers who wish to switch from JSP syntax to XML syntax
without having to manually recode all of their pages.</li>
<li>The Transformer phase will also likely support the concept of validators
that examine the DOM of the page for consistency with application
standards. Therefore, it can also cause fatal translation time errors.
</li>
<li>Since we are not using a validating XML parser for the reasons described
above, we should consider using an internal validator at this stage to
check for "validity" of the DOM in the XML sense (proper nesting of
elements, no unknown attributes, and so on).</li>
<li>The Generator should be able to produce debugging information that is
similar to that produced by the current version of Jasper, for backwards
compatibility. In addition, it should track with the published results
of JSR 45, under which original line number information for any language
being translated into Java will be optionally included in the class file
itself.</li>
<li>At a minimum, the Translator phase should support Jikes and the built in
Java compiler from the JDK (as is supported by the current version of
Jasper). To the maximum degree feasible, we should also support plug in
of different Java compilers through some appropriate interface.</li>
<li>Deployer support is something that can be done in a minimal fashion early
on (similar to what <code>jspc</code> does now), but I envision enhanced
capabilities in this area being added later.</li>
</ul>
<p>Although it is too early for detailed source code design, I would suggest
that the source modules for each phase of the JSP page compiler be organized
into a separate Java package (such as <code>org.apache.jasper.generator</code>
for the Java code generation phase). Interfaces that describe cross-phase
information flows can be defined in the <code>org.apache.jasper</code>
package, with implementations provided by the phase that actually produces
that information.</p>
<p>In a similar manner, the runtime support classes that a generated page
may depend on should be organized into a single Java package (such as
<code>org.apache.jasper.runtime</code>), to facilitate easy packaging as a
JAR file, and to discourage dependencies on other Jasper internals.</p>
</body>
</html>
1.1 jakarta-tomcat/proposals/tomcat-4.0/source-proposal.html
Index: source-proposal.html
===================================================================
<html>
<head>
<title>Proposal for Tomcat 4.0 Source Code Organization</title>
</head>
<body bgcolor="white">
<div align="center">
<h1>Proposal for Tomcat 4.0 Source Code Organization</h1>
<h2>$Id: source-proposal.html,v 1.1 2000/08/09 05:50:41 craigmcc Exp $</h2>
</div>
<h2>Introduction</h2>
<p>Once Sun announced the contribution of the source code for the Java
Server Web Development Kit (JSWDK) at JavaOne in 1999, the primary focus
was on delivering code that was functionally complete, and could be built.
Little attention was expended to creating a source code module and directory
organization that made it easy to manage the concurrent development of
maintenance and enhancement support on an existing major version of the
software, while simultaneously supporting development on a new major version.
</p>
<p>In addition, all of the code was placed in a single CVS module, and the
source code for logically distinct components of the overall Tomcat suite
were intermixed. Also, the build scripts were optimized to create an entire
Tomcat distribution, with no provision for creating subsets of the entire
suite when all of the components are not required.</p>
<p>This proposal describes an overall CVS module and source code organization
designed to facilitate continued support of the existing Tomcat 3.x code base
(in the current CVS module), while setting up a development environment for the
next major version of Tomcat (version 4.0) that will, among other things,
incorporate support for the new Servlet 2.3 and JSP 1.2 specifications, which
will enter their public review periods shortly.</p>
<p>Implementing the new source code organization described by this proposal
has many advantages, including the following:</p>
<ul>
<li>Support and enhancement of the existing Tomcat 3.x code base can continue
uninterrupted, without disruptions caused by development on the next major
version. This is important because many developers (and server vendors)
have adopted Tomcat 3.x (or plan to adopt Tomcat 3.2 shortly) into their
environments, and will need continued support until they choose to migrate
to Tomcat 4.x at some future date.</li>
<li>Work to integrate support for the new features of the Servlet 2.3 and
JSP 1.2 specifications can begin immediately, without concern about
compromising the existing Tomcat builds.</li>
<li>The proposed source code organization clearly separates the various
components of Tomcat into logically distinct subdirectory structures,
which are almost completely self contained. This will facilitate
understanding (especially for new developers) by supporting focus on
one component at a time.</li>
<li>The components of Tomcat can be built individually by utilizing the build
scripts within the corresponding subdirectories, while complete or subset
distributions can be created by using the build scripts in the top
level directory.</li>
</ul>
<p>Note that the proposed directory structure (see following section) assumes
that the proposal to use Catalina as the source code base for the servlet
container component of Tomcat is accepted.</p>
<p>There are precedents for the proposed CVS organization at several levels
within the Apache universe. Among these precedents are:</p>
<ul>
<li>Separation of the source trees of the Apache web server itself, based
on the major version (1.2, 1.3, and 2.0).</li>
<li>Organization of a particular project into cooperating subprojects where
you can build just the subprojects you need, or the entire suite, as
is done in the <code>jakarta-taglibs</code> project.</li>
</ul>
<p>Given those precedents, it is also be appropriate to rename the current
CVS repository module from <code>jakarta-tomcat</code> to
<code>jakarta-tomcat-3.0</code>, to make clear the scope of the code that
is contained within it.</p>
<h2>Proposed Source CVS Modules</h2>
<p>This proposal envisions that there will be three top-level CVS modules
visible in the Apache CVS repository:</p>
</ul>
<li><strong><code>jakarta-servletapi</code></strong> - The existing module
containing the servlet API implementation classes for the "current" and
"under development" versions of the servlet and JSP specifications.</li>
<li><strong><code>jakarta-tomcat-3.0</code></strong> - The existing module
containing the source code for use in supporting and enhancing the
Tomcat 3.x code base as long as is required, renamed for consistency.</li>
<li><strong><code>jakarta-tomcat-4.0</code></strong> - A new module containing
the code for the next major release of Tomcat, which will be based on the
Catalina and Jasper proposals, and organized as described below.</li>
</ul>
<h3>The <code>jakarta-servletapi</code> Module</h3>
<p>The <code>jakarta-servletapi</code> module was separated from the Tomcat
module several months ago, to provide an easily accessible means for anyone
who needs them to acquire and build a set of classes that conform to the
servlet and JSP specifications. It is proposed that this module continue to
be used for this purpose, according to the following policies:</p>
<ul>
<li>At any point in time, the main branch of <code>jakarta-servletapi</code>
will be the servlet and JSP implementation classes for the currently
final versions of the specifications (2.2 and 1.1, respectively, at the
time of this writing).</li>
<li>From time to time, errata to the servlet and JSP specifications will be
published. In some cases, errata will include changes to the servlet
and JSP classes, or their corresponding Javadocs. Such changes will be
marked with a CVS tag that corresponds to the errata version(s) that
include it (errata to a particular specification are cumulative), so that
users can conveniently request the classes that correspond to the original
specs, or to any particular errata that have been subsequently published.
<li>When new specifications are released for initial public review, a branch
in this module will be created (starting from the most recent classes
for the current official specifications), on which the changes required
by the new specification versions will be committed.</li>
<li>As errata or revised specification drafts are published for the new
specification versions, tags will be used to match classes to document
versions in a manner similar to that described for errata to the current
final specifications.</li>
<li>When the new specification becomes final, the old "main" branch will be
migrated to an archival branch (which now represents the previous versions
of the specification), and the branch used for the specs under development
will become the main line branch.</li>
</ul>
<p>Note that, although this is a separate CVS source module, it is part of the
Tomcat project from an administrative viewpoint. Among other things, this
means that anyone who is a committer for the <code>jakarta-tomcat</code>
module may have commit access to <code>jakarta-servletapi</code> as well by
simply asking -- no vote is required.</p>
<h3>The <code>jakarta-tomcat-3.0</code> Module</h3>
<p>The existing <code>jakarta-tomcat</code> module is proposed to continue
as it currently exists (except for being renamed), for use in supporting the
Tomcat 3.x code base for as long as this is appropriate.</p>
<p>The <code>proposals/catalina</code> directory in this module will be
abandoned once the conversions and imports have been performed into the
"catalina" subdirectory of the new CVS module described in the following
section.</p>
<h3>The <code>jakarta-tomcat-4.0</code> Module</h3>
<p>A new module will be created to contain the source code for what will
ultimately be distributed as Tomcat 4.0. Besides separating the development
of this code from maintenance on the existing Tomcat version, creating a new
module offers us the opportunity to organize the new source code in a modular
manner, and facilitates building only those portions of the entire Tomcat
suite that a particular developer is interested in.</p>
<p>Note that, although this is a separate CVS source module, it is part of the
Tomcat project from an administrative viewpoint. Among other things, this
means that anyone who is a committer for the current
<code>jakarta-tomcat</code> module will automatically be granted committer
access to the <code>jakarta-tomcat-4.0</code> module as well.</p>
<p>The top level directory in this module shall contain subdirectories for
each major component of Tomcat (as described below), plus build scripts that
are used to integrate the major components with required external components,
and produce distributions. It shall be possible to build at least the
following distribution targets:</p>
<ul>
<li>The entire Tomcat suite, including servlet container, JSP support, and
included web applications, pretty much equivalent to the
<code>build dist</code> target of the current Tomcat module.</li>
<li>A minimal servlet container, with no JSP support and no included web
applications.</li>
<li>A distribution of the JSP environment suitable for use on any
servlet container compatible with the 2.3 specification.</li>
<li>A distribution of the web applications that are currently included in
the official Tomcat distribution (root, examples, and so on).</li>
<li>A web application distribution of the user (and system administrator)
documentation related to installing and configuring the entire Tomcat
suite.</li>
<li>A web application distribution containing developer oriented documentation
(and Javadoc API files) for the entire Tomcat suite.</li>
</ul>
<p>To support these goals, the following directory structure (within the
<code>jakarta-tomcat-4.0</code> module) is proposed:</p>
<pre>
jakarta-tomcat-4.0/
README Overall installation and build
instructions, and description of the
source module directory structure
build.bat, build.sh, build.xml Convenience build scripts that
construct the distributions
described above, relying on the
build scripts in each subdirectory
for the detailed work
admin/ ADMINISTRATIVE WEB APPLICATION
build.bat, build.sh, build.xml Build scripts
src/ Java source code
org/
apache/
tomcat/
admin/
web/ Static resources (html, jsp, etc.)
WEB-INF/ Configuration files (web.xml, etc.)
catalina/ SERVLET CONTAINER
build.bat, build.sh, build.xml Build scripts
bin/ Binaries and shell scripts
conf/ Configuration files
doc/
developer/ Developer documentation
user/ User and administrator documentation
src/ Java source code
org/
apache/
catalina/
common/ COMMONLY USED COMPONENTS
(such as XmlMapper)
bin/ Binaries and shell scripts
conf/ Configuration files
doc/
developer/ Developer documentation
src/ Java source code
org/
apache/
tomcat/
common/
examples/ EXAMPLES WEB APPLICATION
build.bat, build.sh, build.xml Build scripts
src/ Java source code
org/
apache/
tomcat/
examples/
web/ Static resources (html, jsp, etc.)
WEB-INF/ Configuration files (web.xml, etc.)
jasper/ JSP COMPILER AND RUNTIME SYSTEM
build.bat, build.sh, build.xml Build scripts
bin/ Binaries and shell scripts
conf/ Configuration files
doc/
developer/ Developer documentation
user/ User documentation
src/ Java source code
org/
apache/
jasper/
native/ NATIVE C CODE COMPONENTS
Makefile Make file to build all of the
native components
aolserver/ AOLserver integration
apache/ Generic Apache integration
apache1.3/ Apache 1.3 integration
apache2.0/ Apache 2.0 integration
iis/ Microsoft IIS integration
jk/ Common integration libraries
jni_connect/ Common integration libraries
netscape/ Netscape/iPlanet integration
nt_service/ "Install As NT Service" application
root/ ROOT WEB APPLICATION
build.bat, build.sh, build.xml Build scripts
src/ Java source code
org/
apache/
tomcat/
examples/
web/ Static resources (html, jsp, etc.)
WEB-INF/ Configuration files (web.xml, etc.)
test/ TEST WEB APPLICATION
build.bat, build.sh, build.xml Build scripts
src/ Java source code
org/
apache/
tomcat/
examples/
web/ Static resources (html, jsp, etc.)
WEB-INF/ Configuration files (web.xml, etc.)
webdav/ WEBDAV WEB APPLICATION
build.bat, build.sh, build.xml Build scripts
src/ Java source code
org/
apache/
tomcat/
webdav/
web/ Static resources (html, jsp, etc.)
WEB-INF/ Configuration files (web.xml, etc.)
</pre>
</body>
</html>