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.
| One-Time Setup of Ant and Tomcat for Development |
In order to take advantage of the special Ant tasks that interact with the
Manager web application, you need to perform the following tasks
once (no matter how many web applications you plan to develop).
- 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, which must be
copied in to the lib directory of your Ant installation.
- Define one or more Tomcat users. The Manager web
application runs under a security constraint that requires a user to be
logged in, and have the security role
manager assigned to
him or her. How such users are defined depends on which Realm you have
configured in Tomcat's conf/server.xml file -- see the
Realm Configuration HOW-TO for more
information. You may define any number of users (with any username
and password that you like) with the manager role.
|
| Create Project Source Code Directory |
The first step is to create a new project source directory, and customize
the build.xml and build.properties files 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.
The next step is to customize the Ant properties that are
named in the build.xml script. This is done by creating a
file named build.properties in your project's top-level
directory. The supported properties are listed in the comments inside
the sample build.xml script. At a minimum, you will generally
need to define the catalina.home property defining where
Tomcat 5 is installed, and the manager application username and password.
You might end up with something like this:
| | | |
# Context path to install this application on
app.path=/hello
# Tomcat 5 installation directory
catalina.home=/usr/local/jakarta-tomcat-5.0
# Manager webapp username and password
manager.username=myusername
manager.password=mypassword
| | | | |
In general, you will not want to check the
build.properties file in to the CVS repository, because it
is unique to each developer's environment.
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
| | | | |
|
| 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.
|
| Test Your Web Application |
To test your application, you will want to install it under Tomcat. The
quickest way to do that is to use the custom Ant tasks that are included in
the sample build.xml script. Using these commands might follow
a pattern like this:
- Start Tomcat 5 if needed. If Tomcat 5 is not already running,
you will need to start it in the usual way.
- Compile your application. Use the
ant compile
command (or just ant, since this is the default). Make
sure that there are no compilation errors.
- Install the application. Use the
ant install
command. This tells Tomcat to immediately start running your app on
the context path defined in the app.path build property.
Tomcat does NOT have to be restarted for this to
take effect.
- Test the application. Using your browser or other testing
tools, test the functionality of your application.
- Modify and rebuild as needed. As you discover that changes
are required, make those changes in the original source
files, not in the output build directory, and re-issue the
ant compile command. This ensures that your changes will
be available to be saved (via cvs commit) later on --
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 when you re done. When you are through
working on this application, you can remove it from live execution by
running the
ant remove command.
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.
|
|
