Development Processes

Although application development can take many forms, this manual proposes a fairly generic process for creating web applications using Tomcat. The following sections highlight the commands and tasks that you, as the developer of the code, will perform. The same basic approach works when you have multiple programmers involved, as long as you have an appropriate source code control system and internal team rules about who is working on what parts of the application at any given time.

The task descriptions below assume that you will be using CVS for source code control, and that you have already configured access to the appropriate CVS repository. Instructions for doing this are beyond the scope of this manual. If you are using a different source code control environment, you will need to figure out the corresponding commands for your system.

Create Project Source Code Directory

The first step is to create a new project source directory, and customize the build.xml and build script you will be using. The directory structure is described in the previous section, or you can use the sample application as a starting point. Create your project source directory, and define it within your CVS repository. This might be done by a series of commands like this, where {project} is the name under which your project should be stored in the CVS repository, and {username} is your login username: cd {my home directory} mkdir myapp <-- Assumed "project source directory" cd myapp mkdir docs mkdir src mkdir web mkdir web/WEB-INF cvs import -m "Initial Project Creation" {project} \ {username} start Now, to verify that it was created correctly in CVS, we will perform a checkout of the new project: cd .. mv myapp myapp.bu cvs checkout {project} Next, you will need to create and check in an initial version of the build.xml script to be used for development. For getting started quickly and easily, base your build.xml on the basic build.xml file, included with this manual, or code it from scratch. cd {my home directory} cd myapp emacs build.xml <-- if you want a real editor :-) cvs add build.xml cvs commit Until you perform the CVS commit, your changes are local to your own development directory. Committing makes those changes visible to other developers on your team that are sharing the same CVS repository. Now, create the initial version of the web application deployment descriptor. You can base web.xml on the basic web.xml file, or code it from scratch. cd {my home directory} cd myapp/web/WEB-INF emacs web.xml cvs add web.xml cvs commit

Customize for Tomcat Location

In order for Tomcat to recognize your application, you must deploy it as described under Deployment. Any of the proposed techniques can be used. For our purposes, we will assume that you are using the unpacked directory hierarchy approach, and a build.xml script based on the example included with this manual. In order to successfully execute the deploy target, you must ensure that the catalina.home property receives the correct value, which must be the pathname of the directory into which you have installed Tomcat 4. You can make this customization by one of the following techniques: Change the property definition in the build.xml file so that it reflects the Tomcat 4 location. The modified property setting might look like this: <property name="catalina.home" value="/usr/local/jakarta-tomcat-4.0"/> Set up a build.properties file in your top-level source directory that defines the location oF Tomcat. For example, the file might contain: catalina.home=/usr/local/jakarta-tomcat-4.0 The first technique would be appropriate if all of your developers are sharing a common copy of Tomcat 4 for their deployment and testing. If, however, each developer is using their own copy of Tomcat 4, in separate directories, the latter technique is preferred (because it lets each developer define their own value for the catalina.home property. NOTE - If you utilize the build.properties approach, be sure that you do NOT check in the build.properties file for any of your developers in to the source code archives. For this reason, the .cvsignore file you created earlier should include this filename.

Edit Source Code and Pages

The edit/build/test tasks will generally be your most common activities during development and maintenance. The following general principles apply. As described in Source Organization, newly created source files should be located in the appropriate subdirectory, under your project source directory. Whenever you wish to refresh your development directory to reflect the work performed by other developers, you will ask CVS to do it for you: cd {my home directory} cd myapp cvs update -dP To create a new file, go to the appropriate directory, create the file, and register it with CVS. When you are satisfied with it's contents (after building and testing is successful), commit the new file to the repository. For example, to create a new JSP page: cd {my home directory} cd myapp/web <-- Ultimate destination is document root emacs mypage.jsp cvs add mypage.jsp ... build and test the application ... cvs commit Java source code that is defined in packages must be organized in a directory hierarchy (under the src/ subdirectory) that matches the package names. For example, a Java class named com.mycompany.mypackage.MyClass.java should be stored in file src/com/mycompany/mypackage/MyClass.java. Whenever you create a new subdirectory, don't forget to register it with CVS. To edit an existing source file, you will generally just start editing and testing, then commit the changed file when everything works. Although CVS can be configured to required you to "check out" or "lock" a file you are going to be modifying, this is generally not used.

Build the Web Application

When you are ready to compile the application, issue the following commands (generally, you will want a shell window open that is set to the project source directory, so that only the last command is needed): cd {my home directory} cd myapp <-- Normally leave a window open here ant The Ant tool will be execute the default "compile" target in your build.xml file, which will compile any new or updated Java code. If this is the first time you compile after a "build clean", it will cause everything to be recompiled. To force the recompilation of your entire application, do this instead: cd {my home directory} cd myapp ant all This is a very good habit immediately before checking in changes, to make sure that you have not introduced any subtle problems that Javac's conditional checking did not catch.

Test Your Web Application

To test your application, you will want to deploy it under Tomcat. If you have customized the catalina.home property as described above, this is very easy. First, deploy the application into Tomcat: cd {my home directory} cd myapp ant deploy and then restart Tomcat. To access your application, point your browser at http://localhost:8080/myapp/ and begin testing. When you discover something that needs to change, fix it in the source directory (not in the Tomcat deployment directory), redeploy, and restart Tomcat. Do not forget to commit your changes to the source code repository when you have completed your testing!

Creating a Release

When you are through adding new functionality, and you've tested everything (you DO test, don't you :-), it is time to create the distributable version of your web application that can be deployed on the production server. The following general steps are required: Issue the command ant all from the project source directory, to rebuild everything from scratch one last time. Use the cvs tag command to create an identifier for all of the source files utilized to create this release. This allows you to reliably reconstruct a release (from sources) at a later time. Issue the command ant dist to create a distributable web application archive (WAR) file, as well as a JAR file containing the corresponding source code. Package the contents of the dist directory using the tar or zip utility, according to the standard release procedures used by your organization.