TomcatExpert

Getting Started with Apache Tomcat Development

posted by MSacks on August 9, 2010 07:22 AM

With special thanks to Mark Thomas, ASF/VMware for reviewing.

Overview

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.

What is Apache Tomcat?

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. 

Before you get started

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.

Read the documentation

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.

Setting up your IDE

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.

  • Step 1. Download your IDE
  • Step 2. Set up IDE for Java development (some IDE’s require this)
  • Step 3. Organize your directory structure accordingly
  • Step 4. Set up a local Software Configuration Management System

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.

Pull the source

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.

Using Apache Ant for Development and Build Tasks

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.

Modify the code to your needs

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.

ASF 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.

  • Step 1. Log in to https://issues.apache.org/bugzilla/
  • Step 2. Click on the “New Account” link to enter your information and create a new account
  • Step 3. Log in with the newly created account and click “Search”
  • Step 4. In the Product drop-down, Tomcat N (N being the version number) will be able for selection. Bugs can be searched by some criteria such as being open or closed.
  • Step 5. Pick a bug or enhancement request and start working on it, or submit something completely new
  • Step 6. Attach a patch directly to the Bugzilla ticket in diff format. For more information on how to submit a patch, see http://tomcat.apache.org/bugreport.html#Patches_and_enhancement_requests.

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.

Conclusion

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.

Further Reading

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/

Matthew Sacks is an Application System Administrator at Edmunds.com, and focuses on administering, monitoring and managing high-volume, high-traffic production Web sites. He is also the Founder and Editor of TheBitsource.com, a blog on System Administration, Web Application Development and Software Engineering. He is an active member in the USENIX The Advanced Computing Systems Professional and Technical Association, and has contributed to such publications as Linux Pro Magazine, Sys Admin Magazine, and InformIT.

Comments

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.