Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Application Developer's Guide (9.0.112) - Development Processes</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Application Developer's Guide</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">App Dev Guide Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Contents</h2><ul><li><a href="index.html">Contents</a></li><li><a href="introduction.html">Introduction</a></li><li><a href="installation.html">Installation</a></li><li><a href="deployment.html">Deployment</a></li><li><a href="source.html">Source Code</a></li><li><a href="processes.html">Processes</a></li><li><a href="sample/">Example App</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Development Processes</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Development_Processes">Development Processes</a><ol><li><a href="#One-Time_Setup_of_Ant_and_Tomcat_for_Development">One-Time Setup of Ant and Tomcat for Development</a></li><li><a href="#Create_Project_Source_Code_Directory">Create Project Source Code Directory</a></li><li><a href="#Edit_Source_Code_and_Pages">Edit Source Code and Pages</a></li><li><a href="#Build_the_Web_Application">Build the Web Application</a></li><li><a href="#Test_Your_Web_Application">Test Your Web Application</a></li><li><a href="#Creating_a_Release">Creating a Release</a></li></ol></li></ul>
6 
</div><h3 id="Development_Processes">Development Processes</h3><div class="text">
7 
 
8 
<p>Although application development can take many forms, this manual proposes
9 
a fairly generic process for creating web applications using Tomcat.  The
10 
following sections highlight the commands and tasks that you, as the developer
11 
of the code, will perform.  The same basic approach works when you have
12 
multiple programmers involved, as long as you have an appropriate source code
13 
control system and internal team rules about who is working on what parts
14 
of the application at any given time.</p>
15 
 
16 
<p>The task descriptions below do not assume any particular source code control
17 
system but simply identify when and what source code control tasks are typically
18 
performed. You will need to identify the appropriate source code control
19 
commands for your system.</p>
20 
 
21 
 
22 
<div class="subsection"><h4 id="One-Time_Setup_of_Ant_and_Tomcat_for_Development">One-Time Setup of Ant and Tomcat for Development</h4><div class="text">
23 
 
24 
<p>In order to take advantage of the special Ant tasks that interact with the
25 
<em>Manager</em> web application, you need to perform the following tasks
26 
once (no matter how many web applications you plan to develop).</p>
27 
<ul>
28 
<li><p><em>Configure the Ant custom tasks</em>.  The implementation code for the
29 
    Ant custom tasks is in a JAR file named
30 
    <code>$CATALINA_HOME/lib/catalina-ant.jar</code>, which must be
31 
    copied in to the <code>lib</code> directory of your Ant installation.
32 
    </p></li>
33 
<li><p><em>Define one or more Tomcat users</em>.  The <em>Manager</em> web
34 
    application runs under a security constraint that requires a user to be
35 
    logged in, and have the security role <code>manager-script</code> assigned
36 
    to then.  How such users are defined depends on which Realm you have
37 
    configured in Tomcat's <code>conf/server.xml</code> file -- see the
38 
    <a href="../realm-howto.html">Realm Configuration How-To</a> for more
39 
    information.  You may define any number of users (with any username
40 
    and password that you like) with the <code>manager-script</code> role.
41 
    </p></li>
42 
</ul>
43 
 
44 
</div></div>
45 
 
46 
 
47 
<div class="subsection"><h4 id="Create_Project_Source_Code_Directory">Create Project Source Code Directory</h4><div class="text">
48 
 
49 
<p>The first step is to create a new project source directory, and customize
50 
the <code>build.xml</code> and <code>build.properties</code> files you will
51 
be using.  The directory structure is described in <a href="source.html">the
52 
previous section</a>, or you can use the
53 
<a href="sample/">sample application</a> as a starting point.</p>
54 
 
55 
<p>Create your project source directory, and define it within your source code
56 
control system. This might be done by a series of commands like this:</p>
57 
<div class="codeBox"><pre><code>cd {my home directory}
58 
mkdir myapp &lt;-- Assumed "project source directory"
59 
cd myapp
60 
mkdir docs
61 
mkdir src
62 
mkdir web
63 
mkdir web/WEB-INF
64 
cvs or svn or git ... &lt;-- Add this structure to the appropriate repository
65 
</code></pre></div>
66 
 
67 
<p>To verify that the project was created correctly in the source code control
68 
repository, you may wish to check out the project to a separate directory and
69 
confirm that all the expected contents are present.</p>
70 
 
71 
<p>Next, you will need to create and check in an initial version of the
72 
<code>build.xml</code> script to be used for development.  For getting
73 
started quickly and easily, base your <code>build.xml</code> on the
74 
<a href="build.xml.txt">basic build.xml file</a>, included with this manual,
75 
or code it from scratch.</p>
76 
<div class="codeBox"><pre><code>cd {my home directory}
77 
cd myapp
78 
emacs build.xml     &lt;-- if you want a real editor :-)
79 
cvs or svn or git ... &lt;-- Add this file to the repository
80 
</code></pre></div>
81 
 
82 
<p>The next step is to customize the Ant <em>properties</em> that are
83 
named in the <code>build.xml</code> script.  This is done by creating a
84 
file named <code>build.properties</code> in your project's top-level
85 
directory.  The supported properties are listed in the comments inside
86 
the sample <code>build.xml</code> script.  At a minimum, you will generally
87 
need to define the <code>catalina.home</code> property defining where
88 
Tomcat is installed, and the manager application username and password.
89 
You might end up with something like this:</p>
90 
<div class="codeBox"><pre><code># Context path to install this application on
91 
app.path=/hello
92 
 
93 
# Tomcat installation directory
94 
catalina.home=/usr/local/apache-tomcat-9.0
95 
 
96 
# Manager webapp username and password
97 
manager.username=myusername
98 
manager.password=mypassword</code></pre></div>
99 
 
100 
<p>In general, you will <strong>not</strong> want to check the
101 
<code>build.properties</code> file in to the source code control repository,
102 
because it is unique to each developer's environment.</p>
103 
 
104 
<p>Now, create the initial version of the web application deployment
105 
descriptor.  You can base <code>web.xml</code> on the
106 
<a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
107 
<div class="codeBox"><pre><code>cd {my home directory}
108 
cd myapp/web/WEB-INF
109 
emacs web.xml
110 
cvs or svn or git ... &lt;-- Add this file to the repository
111 
</code></pre></div>
112 
 
113 
Note that this is only an example web.xml file.  The full definition
114 
of the deployment descriptor file is in the
115 
<a href="https://cwiki.apache.org/confluence/display/TOMCAT/Specifications">Servlet Specification.</a>
116 
 
117 
</div></div>
118 
 
119 
 
120 
<div class="subsection"><h4 id="Edit_Source_Code_and_Pages">Edit Source Code and Pages</h4><div class="text">
121 
 
122 
<p>The edit/build/test tasks will generally be your most common activities
123 
during development and maintenance.  The following general principles apply.
124 
As described in <a href="source.html">Source Organization</a>, newly created
125 
source files should be located in the appropriate subdirectory, under your
126 
project source directory.</p>
127 
 
128 
<p>You should regularly refresh your development directory to reflect the
129 
work performed by other developers.</p>
130 
 
131 
<p>To create a new file, go to the appropriate directory and create the file.
132 
When you are satisfied with its contents (after building and testing is
133 
successful), add the new file to the repository. For example, to create a new
134 
JSP page:</p>
135 
<div class="codeBox"><pre><code>cd {my home directory}
136 
cd myapp/web        &lt;-- Ultimate destination is document root
137 
emacs mypage.jsp
138 
... build and test the application ...
139 
cvs or svn or git ... &lt;-- Add this file to the repository
140 
</code></pre></div>
141 
 
142 
<p>Java source code that is defined in packages must be organized in a directory
143 
hierarchy (under the <strong>src/</strong> subdirectory) that matches the
144 
package names.  For example, a Java class named
145 
<code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
146 
<code>src/com/mycompany/mypackage/MyClass.java</code>.
147 
Whenever you create a new file, don't forget to add it to the source code
148 
control system.</p>
149 
 
150 
<p>To edit an existing source file, you will generally just start editing
151 
and testing, then commit the changed file when everything works.</p>
152 
 
153 
</div></div>
154 
 
155 
 
156 
<div class="subsection"><h4 id="Build_the_Web_Application">Build the Web Application</h4><div class="text">
157 
 
158 
<p>When you are ready to compile the application, issue the following
159 
commands (generally, you will want a shell window open that is set to
160 
the project source directory, so that only the last command is needed):</p>
161 
<div class="codeBox"><pre><code>cd {my home directory}
162 
cd myapp        &lt;-- Normally leave a window open here
163 
ant</code></pre></div>
164 
 
165 
<p>The Ant tool will be execute the default "compile" target in your
166 
<code>build.xml</code> file, which will compile any new or updated Java
167 
code.  If this is the first time you compile after a "build clean",
168 
it will cause everything to be recompiled.</p>
169 
 
170 
<p>To force the recompilation of your entire application, do this instead:</p>
171 
<div class="codeBox"><pre><code>cd {my home directory}
172 
cd myapp
173 
ant all</code></pre></div>
174 
 
175 
<p>This is a very good habit immediately before checking in changes, to
176 
make sure that you have not introduced any subtle problems that Javac's
177 
conditional checking did not catch.</p>
178 
 
179 
</div></div>
180 
 
181 
 
182 
<div class="subsection"><h4 id="Test_Your_Web_Application">Test Your Web Application</h4><div class="text">
183 
 
184 
<p>To test your application, you will want to install it under Tomcat.  The
185 
quickest way to do that is to use the custom Ant tasks that are included in
186 
the sample <code>build.xml</code> script.  Using these commands might follow
187 
a pattern like this:</p>
188 
<ul>
189 
<li><p><em>Start Tomcat if needed</em>.  If Tomcat is not already running,
190 
    you will need to start it in the usual way.
191 
    </p></li>
192 
<li><p><em>Compile your application</em>.  Use the <code>ant compile</code>
193 
    command (or just <code>ant</code>, since this is the default).  Make
194 
    sure that there are no compilation errors.
195 
    </p></li>
196 
<li><p><em>Install the application</em>.  Use the <code>ant install</code>
197 
    command.  This tells Tomcat to immediately start running your app on
198 
    the context path defined in the <code>app.path</code> build property.
199 
    Tomcat does <strong>NOT</strong> have to be restarted for this to
200 
    take effect.
201 
    </p></li>
202 
<li><p><em>Test the application</em>.  Using your browser or other testing
203 
    tools, test the functionality of your application.
204 
    </p></li>
205 
<li><p><em>Modify and rebuild as needed</em>.  As you discover that changes
206 
    are required, make those changes in the original <strong>source</strong>
207 
    files, not in the output build directory, and re-issue the
208 
    <code>ant compile</code> command.  This ensures that your changes will be
209 
    available to be saved (via your chosen source code control system) later on
210 
    -- the output build directory is deleted and recreated as necessary.
211 
    </p></li>
212 
<li><p><em>Reload the application</em>.  Tomcat will recognize changes in
213 
    JSP pages automatically, but it will continue to use the old versions
214 
    of any servlet or JavaBean classes until the application is reloaded.
215 
    You can trigger this by executing the <code>ant reload</code> command.
216 
    </p></li>
217 
<li><p><em>Remove the application when you are done</em>.  When you are through
218 
    working on this application, you can remove it from live execution by
219 
    running the <code>ant remove</code> command.
220 
    </p></li>
221 
</ul>
222 
 
223 
<p>Do not forget to commit your changes to the source code repository when
224 
you have completed your testing!</p>
225 
 
226 
</div></div>
227 
 
228 
 
229 
<div class="subsection"><h4 id="Creating_a_Release">Creating a Release</h4><div class="text">
230 
 
231 
<p>When you are through adding new functionality, and you've tested everything
232 
(you DO test, don't you :-), it is time to create the distributable version
233 
of your web application that can be deployed on the production server.  The
234 
following general steps are required:</p>
235 
<ul>
236 
<li><p>Issue the command <code>ant all</code> from the project source
237 
    directory, to rebuild everything from scratch one last time.
238 
    </p></li>
239 
<li><p>Use the source code control system to tag the current state of the code
240 
    to create an identifier for all of the source files utilized to create this
241 
    release.  This allows you to reliably reconstruct a release (from sources)
242 
    at a later time.
243 
    </p></li>
244 
<li><p>Issue the command <code>ant dist</code> to create a distributable
245 
    web application archive (WAR) file, as well as a JAR file containing
246 
    the corresponding source code.
247 
    </p></li>
248 
<li><p>Package the contents of the <code>dist</code> directory using the
249 
    <strong>tar</strong> or <strong>zip</strong> utility, according to
250 
    the standard release procedures used by your organization.
251 
    </p></li>
252 
</ul>
253 
 
254 
</div></div>
255 
 
256 
 
257 
</div></div></div></div></div><footer><div id="footer">
258 
    Copyright &copy; 1999-2025, The Apache Software Foundation
259 
    <br>
260 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
261 
    are either registered trademarks or trademarks of the Apache Software
262 
    Foundation.
263 
    </div></footer></div></body></html>