Wednesday, August 02, 2006

Apache Tomcat Developer's Guide


Standard Directory Layout
root/ -- .html, .jsp files
--- WEB-INF/ -- web.xml
--- classes/ -- .class files
--- lib/ -- .jar files as library

Setup of Ant and Tomcat for Development

  • Configure the Ant custom tasks: The implementation code for the Ant custom tasks is in a JAR file named $CATALINA_HOME/server/lib/catalina-ant.jar. This file must be copied into the lib directory of your Ant installation.
  • Define one or more Tomcat users. --> Use the Manager web application, only user that has the security role manager can login. Tomcat users and roles are specified in a "database" called a Realm. The realm defines the interface between a servlet container and the associated user and role information. Tomcat4 defines a Java interface org.apache.catalina.Realm that can be implemented by "plug in" components to establish the connection between a servlet container and some existing authentication database or mechanism that already exists in the production environment. There are 4 ways to access different sources of authentication information: DataSourceRealm, JDBCRealm, JNDIRealm, and MemoryRealm ($CATALINA_HOME/conf/tomcat-users.xml). Source: .

Create Project Source Code Directory
mkdir myapp
cd myapp
mkdir docs
mkdir src
mkdir web
cd web
mkdir WEB-INF
cd ..
cvs import -m "Initial Project Creation" myapp myapp start
This set of commands creates the project directory, and defines it within your CVS repository. In the last line, the "Initial Project Creation" is a log message, the first myapp specifies the directory $CVSROOT/myapp to store the project file. The second myapp is a vendor tag, and the start is a release tag. These tags may fill no purpose in this context, but cvs requires them to be present.
The doc directory contains static documentation files to be copied to the docs sub-directory of the distribution. The src directory contains the Java source code to be compiled to the WEB-INF/classes sub-directory of the web application. The web directory contains static web page files.
Later, the project can be exported from the cvs directory using command:
cvs checkout myapp
When some modifications are made to the project files, these changes can be done on the repository using commands like this:
cvs add build.xml
cvs commit
The changes are local to your own development directory until you perform the commit.

Customize Project Properties
The customization is done by creating a file named in the project's top-level directory. The supported properties are listed in the build.xml file. A sample of this file can be got from this link. At a minimum, you will generally need to define the catalina.home property defining where Tomcat4 is installed, and the manager application username and password. You might end up with something like this:
# Context path to install this application on
# Tomcat4 installation directory
# Manager webapp username and password
In general, you will NOT want to check the file in to the CVS repository, because it is unique to each developer's environment. Note the DOUBLE slash in the fourth line, because the catalina.home variable is referenced as string in the build.xml file.

Describe the Web Application
A sample web descriptor can be found here.
cvs add web.xml
cvs commit

Edit Source Code and Pages
Whenever you wish to refresh your development directory to reflect the work performed by other developers, you can use the following cvs commands:
cd myapp
cvs update -dP
The commands to add new files to the repository are already listed above.

Build the Web Application
The Ant tool executes the default "compile" target in the build.xml file, which will compile any new or updated Java code.
cd myapp
To force the recompilation of the entire application, do this:
cd myapp
ant all

Test the Web Application
The quickest way to test the application is to use the custom Ant tasks that are included in the sample build.xml script.
Compile the application: use ant compile or ant (default).
Install the application: use ant install command. This tells Tomcat to immediately start running your application on the context path defined in app.path build property. Tomcat does NOT have to be restarted for this to take effect.
Test the application: use the browser or other testing tools to test the functionality of the application.
Modify and rebuild as needed: when you discover that some changes are required, make those changes in the original source files, not in the output build directory, and reissue the ant compile command. This ensures that your changes will be available to be saved later on, and the output build directory is deleted and recreated as necessary.
Reload the application: Tomcat will recognize changes in JSP pages automatically, but it will continue to use the old versions of any servlet or JavaBean classes until the application is reloaded. You can trigger this by executing the ant reload command.
Remove the application: you can use the ant remove command.
Check the applications: you can use the ant list command to list all the applications deployed on the server.

Creating a Release
Finally, it is time to create the distributed version of your web application that can be deployed on the production server. The following general steps are required:
(1) Issue the command ant all from the project source directory, to rebuild everything from scratch one last time.
(2) 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 at a later time.
(3) 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.
(4) Package the contents of the dist directory using the tar or zip utility, accroding to the standard release procedures.

Additional Information about CVS
cvs can access a repository by a variety of means. In order to distinguish various ways to access a repository, the repository name can start with an access method. The access method :local: means to access a repository directory. In Unix system, if the repository starts with '/', then :local: is assumed. Otherwise, either :ext: or :server: is assumed. But in Windows OS, you must specify the access method, like :local:C:/local/cvsroot.
To create a repository under windows, we can use:
cvs -d :local:C:/local/cvsroot/ init
Access Remote Repositories
The format for the name of the remote repository is:

No comments: