With special thanks to Mark Thomas, ASF/VMware for reviewing.
This document will describe all of the necessary pre-requisites to get started in developing, customizing and contributing to the Apache Tomcat Project. The reader will have a broad overview of what is involved, and learn the process by which they will get a better understand of how the internals of how the Apache Tomcat application server works. Those new to the Apache Tomcat project, or contributing to an open source project may find this article helpful.
Apache Tomcat is the de-facto, open-source application server. It is distributed under the Apache License, Version 2.0 and is true open source. Many organizations use Tomcat as their production's application server, and it is enterprise grade even in its open source form. Over half of Fortune 500 companies use Apache Tomcat as their platform for their production business websites, including notables such as E-Trade.com, Walmart.com, and The Weather Channel. There are commercially supported versions of Apache Tomcat as well. In this how-to article, we will use the open source version as an example.
When developing for Apache Tomcat, it can make it easier to code when using an Integrated Development Environment. This allows you to keep your source code organized, and adds useful features such as syntax validation that will allow you to program more efficiently.
This is a necessary step before you start modifying the code, or going to the forums. Do a brief scan through ALL of the documentation. This way you will know where everything is at a minimum, and save yourself and others time asking and answering questions on the mailing list. If there is something that you cannot find even after you’ve read and searched the documentation, or you have an anomalous problem, then you should take your issue to the mailing list. People aren’t likely to help a lazy person who wants to skip the reading. At a bare minimum, read the table of contents of the Tomcat documentation so that you know where to go.
Many folks have different preferences for what they like to use for their IDE. Depending on your preference and what you are comfortable with, it will vary. I suggest trying all of the main IDE’s and seeing which one you like best. Some recommendations are Netbeans, Eclipse, and IntelliJ. Some developers prefer to use a simple text editor such as vi, emacs, or jEdit.
You will want to set up a local SCM because the Tomcat project only accepts patches and modifications in the form of patches. Having a local repository enabled the developer to version their code and track changes. When doing this, it makes it much easer to work off the main Subversion repository. Most users will want to do this if they are heavily modifying Tomcat’s code. Although access to the main Subversion SCM for Tomcat is world readable, only ASF comitters can push code to this repository.
First, you will have to decide which version of Tomcat you would like to work on. This will vary depending on your individual or organizational requirements, but generally you will want to work on the latest or previous revision of Tomcat.
According to Mark Thomas, one of the lead developers on the Tomcat project, bugs get fixed in the latest version of Tomcat and then back-ported. “At a minimum, we like patches for the latest version”, says Mark Thomas.
Apache Ant is a Java build tool. It will allow you to execute a pre-defined set of actions and configurations according to something you are trying to achieve. The Apache Tomcat project uses ant for this, and although it is not required, it is highly suggested to use ant tasks to automate your builds. Also, many IDE’s support ant integration allowing you to call ant from within your IDE, and boosting productivity.
The advantage of using ant is that it can be automated further with continuous integration servers, such as Hudson, and maintains consistent configurations of build parameters. Ant tasks are defined as targets, and a given target could be a compile, run jUnit or TestNG tests. The main configuration file for ant is in build.xml in the Tomcat source tree. Some standard actions are compile, build, clean, and run tests.
Now is the hardest part. You have to decide if and what you want to modify Tomcat to do. It may be that you want to add custom MBeans to your Tomcat server to monitor some very specific method of interaction with your server environment. In most cases, most committers will be contributing to the project and helping to make Tomcat better. This brings us to getting started with Bugzilla.
The ASF Bugzilla is where the Tomcat community searches and files bugs or software enhancements. This is where most people will be submitting patches, and attaching them to a bug or enhancement request, and then one of the main Apache committers will be checking it into the project if they and the community vote on it. Apache projects are a meritocracy. A meritocracy is government by merit. For more information about how the ASF works, see http://www.apache.org/foundation/how-it-works.html#meritocracy.
The Apache Tomcat Project uses Bugzilla for logging and maintaining it’s inventory of bugs. The Tomcat Bugzilla is not only limited to tracking bugs and enhancement request for Apache Tomcat, but all Apache projects. It should be noted that some projects may use Apache’s JIRA system.
NOTE: A user does not need a Bugzilla account to search and read bugs. A user only needs an account to submit a bug through the Bugzilla system. Anyone can submit a bug by attaching a Subversion diff as a file to the mailing list explaining the issue for review.
Apache Tomcat is a prime example of one of the most successful open source projects, and is highly useful and utilized by many of the Fortune 500 companies for performing their daily business functions. As a developer or system administrator, it is key to know the internals of the application, even if you are not going to be modifying the application server platform itself. Knowing the internals of an application server will reveal to you how threading works, database access, how the application server interacts with the JVM, clustering, session management, and deployments. If you’ve made it to the end of this document you should have a good idea of entails getting involved in the Tomcat project, and why you should.
The Anatomy of a Bug https://issues.apache.org/bugzilla/docs/en/html/bug_page.html
About the Apache Software Foundation http://www.apache.org/foundation/
Apache Tomcat Discussion Lists http://tomcat.apache.org/bugreport.html#Apache_Tomcat_discussion_lists
Subversion SCM http://subversion.tigris.org/
Apache Ant http://ant.apache.org/