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) - Source Organization</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>Source Organization</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Directory_Structure">Directory Structure</a><ol><li><a href="#External_Dependencies">External Dependencies</a></li></ol></li><li><a href="#Source_Code_Control">Source Code Control</a></li><li><a href="#BUILD.XML_Configuration_File">BUILD.XML Configuration File</a></li></ul>
6 
</div><h3 id="Directory_Structure">Directory Structure</h3><div class="text">
7 
 
8 
    <p><em>The description below uses the variable name $CATALINA_BASE to refer the
9 
    base directory against which most relative paths are resolved. If you have
10 
    not configured Tomcat for multiple instances by setting a CATALINA_BASE
11 
    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
12 
    the directory into which you have installed Tomcat.</em></p>
13 
 
14 
<p>A key recommendation of this manual is to separate the directory
15 
hierarchy containing your source code (described in this section) from
16 
the directory hierarchy containing your deployable application
17 
(described in the preceding section).  Maintaining this separation has
18 
the following advantages:</p>
19 
<ul>
20 
<li><p>The contents of the source directories can be more easily administered,
21 
    moved, and backed up if the "executable" version of the application
22 
    is not intermixed.
23 
    </p></li>
24 
<li><p>Source code control is easier to manage on directories that contain
25 
    only source files.
26 
    </p></li>
27 
<li><p>The files that make up an installable distribution of your
28 
    application are much easier to select when the deployment
29 
    hierarchy is separate.</p></li>
30 
</ul>
31 
 
32 
<p>As we will see, the <code>ant</code> development tool makes the creation
33 
and processing of such directory hierarchies nearly painless.</p>
34 
 
35 
<p>The actual directory and file hierarchy used to contain the source code
36 
of an application can be pretty much anything you like.  However, the
37 
following organization has proven to be quite generally applicable, and is
38 
expected by the example <code>build.xml</code> configuration file that
39 
is discussed below.  All of these components exist under a top level
40 
<em>project source directory</em> for your application:</p>
41 
<ul>
42 
<li><strong>docs/</strong> - Documentation for your application, in whatever
43 
    format your development team is using.<br><br></li>
44 
<li><strong>src/</strong> - Java source files that generate the servlets,
45 
    beans, and other Java classes that are unique to your application.
46 
    If your source code is organized in packages (<strong>highly</strong>
47 
    recommended), the package hierarchy should be reflected as a directory
48 
    structure underneath this directory.<br><br></li>
49 
<li><strong>web/</strong> - The static content of your web site (HTML pages,
50 
    JSP pages, JavaScript files, CSS stylesheet files, and images) that will
51 
    be accessible to application clients.  This directory will be the
52 
    <em>document root</em> of your web application, and any subdirectory
53 
    structure found here will be reflected in the request URIs required to
54 
    access those files.<br><br></li>
55 
<li><strong>web/WEB-INF/</strong> - The special configuration files required
56 
    for your application, including the web application deployment descriptor
57 
    (<code>web.xml</code>, defined in the
58 
    <a href="https://cwiki.apache.org/confluence/display/TOMCAT/Specifications">Servlet Specification</a>),
59 
    tag library descriptors for custom tag libraries
60 
    you have created, and other resource files you wish to include within
61 
    your web application.  Even though this directory appears to be a
62 
    subdirectory of your <em>document root</em>, the Servlet Specification
63 
    prohibits serving the contents of this directory (or any file it contains)
64 
    directly to a client request.  Therefore, this is a good place to store
65 
    configuration information that is sensitive (such as database connection
66 
    usernames and passwords), but is required for your application to
67 
    operate successfully.</li>
68 
</ul>
69 
 
70 
<p>During the development process, two additional directories will be
71 
created on a temporary basis:</p>
72 
<ul>
73 
<li><strong>build/</strong> - When you execute a default build
74 
    (<code>ant</code>), this directory will contain an exact image
75 
    of the files in the web application archive for this application.
76 
    Tomcat allows you to deploy an application in an unpacked
77 
    directory like this, either by copying it to the
78 
    <code>$CATALINA_BASE/webapps</code> directory, or by <em>installing</em>
79 
    it via the "Manager" web application.  The latter approach is very
80 
    useful during development, and will be illustrated below.
81 
    <br><br></li>
82 
<li><strong>dist/</strong> - When you execute the <code>ant dist</code>
83 
    target, this directory will be created.  It will create an exact image
84 
    of the binary distribution for your web application, including an license
85 
    information, documentation, and README files that you have prepared.</li>
86 
</ul>
87 
 
88 
<p>Note that these two directories should <strong>NOT</strong> be archived in
89 
your source code control system, because they are deleted and recreated (from
90 
scratch) as needed during development.  For that reason, you should not edit
91 
any source files in these directories if you want to maintain a permanent
92 
record of the changes, because the changes will be lost the next time that a
93 
build is performed.</p>
94 
 
95 
  <div class="subsection"><h4 id="External_Dependencies">External Dependencies</h4><div class="text">
96 
 
97 
  <p>What do you do if your application requires JAR files (or other
98 
  resources) from external projects or packages?  A common example is that
99 
  you need to include a JDBC driver in your web application, in order to
100 
  operate.</p>
101 
 
102 
  <p>Different developers take different approaches to this problem.
103 
  Some will encourage checking a copy of the JAR files you depend on into
104 
  the source code control archives for every application that requires those
105 
  JAR files.  However, this can cause significant management issues when you
106 
  use the same JAR in many applications - particular when faced with a need
107 
  to upgrade to a different version of that JAR file.</p>
108 
 
109 
  <p>Therefore, this manual recommends that you <strong>NOT</strong> store
110 
  a copy of the packages you depend on inside the source control archives
111 
  of your applications.  Instead, the external dependencies should be
112 
  integrated as part of the process of <strong>building</strong> your
113 
  application.  In that way, you can always pick up the appropriate version
114 
  of the JAR files from wherever your development system administrator has
115 
  installed them, without having to worry about updating your application
116 
  every time the version of the dependent JAR file is changed.</p>
117 
 
118 
  <p>In the example Ant <code>build.xml</code> file, we will demonstrate
119 
  how to define <em>build properties</em> that let you configure the locations
120 
  of the files to be copied, without having to modify <code>build.xml</code>
121 
  when these files change.  The build properties used by a particular
122 
  developer can be customized on a per-application basis, or defaulted to
123 
  "standard" build properties stored in the developer's home directory.</p>
124 
 
125 
  <p>In many cases, your development system administrator will have already
126 
  installed the required JAR files into the <code>lib</code> directory of Tomcat.
127 
  If this has been done, you need
128 
  to take no actions at all - the example <code>build.xml</code> file
129 
  automatically constructs a compile classpath that includes these files.</p>
130 
 
131 
  </div></div>
132 
 
133 
</div><h3 id="Source_Code_Control">Source Code Control</h3><div class="text">
134 
 
135 
<p>As mentioned earlier, it is highly recommended that you place all of the
136 
source files that comprise your application under the management of a
137 
source code control system.  If you elect to do this, every directory and file
138 
in the source hierarchy should be registered and saved -- but none of the
139 
generated files.  If you register binary format files (such as images or JAR
140 
libraries), be sure to indicate this to your source code control system.</p>
141 
 
142 
<p>We recommended (in the previous section) that you should not store the
143 
contents of the <code>build/</code> and <code>dist/</code> directories
144 
created by your development process in the source code control system. Source
145 
code control systems typically provide mechanisms to ignore these directories
146 
(Git uses a <code>.gitignore</code> file, Subversion uses the
147 
<code>svn:ignore</code> property, CVS uses a <code>.cvsignore</code> file, etc.)
148 
You should configure your source code control system to ignore:</p>
149 
<ul>
150 
  <li>build</li>
151 
  <li>dist</li>
152 
  <li>build.properties</li>
153 
</ul>
154 
 
155 
<p>The reason for mentioning <code>build.properties</code> here will be
156 
explained in the <a href="processes.html">Processes</a> section.</p>
157 
 
158 
<p>Detailed instructions for your source code control environment are beyond
159 
the scope of this manual.</p>
160 
 
161 
</div><h3 id="BUILD.XML_Configuration_File">BUILD.XML Configuration File</h3><div class="text">
162 
 
163 
<p>We will be using the <strong>ant</strong> tool to manage the compilation of
164 
our Java source code files, and creation of the deployment hierarchy.  Ant
165 
operates under the control of a build file, normally called
166 
<code>build.xml</code>, that defines the processing steps required.  This
167 
file is stored in the top-level directory of your source code hierarchy, and
168 
should be checked in to your source code control system.</p>
169 
 
170 
<p>Like a Makefile, the <code>build.xml</code> file provides several
171 
"targets" that support optional development activities (such as creating
172 
the associated Javadoc documentation, erasing the deployment home directory
173 
so you can build your project from scratch, or creating the web application
174 
archive file so you can distribute your application.  A well-constructed
175 
<code>build.xml</code> file will contain internal documentation describing
176 
the targets that are designed for use by the developer, versus those targets
177 
used internally.  To ask Ant to display the project documentation, change to
178 
the directory containing the <code>build.xml</code> file and type:</p>
179 
<div class="codeBox"><pre><code>ant -projecthelp</code></pre></div>
180 
 
181 
<p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
182 
is provided that you can customize and install in the project source directory
183 
for your application.  This file includes comments that describe the various
184 
targets that can be executed.  Briefly, the following targets are generally
185 
provided:</p>
186 
<ul>
187 
<li><strong>clean</strong> - This target deletes any existing
188 
    <code>build</code> and <code>dist</code> directories, so that they
189 
    can be reconstructed from scratch.  This allows you to guarantee that
190 
    you have not made source code modifications that will result in
191 
    problems at runtime due to not recompiling all affected classes.
192 
    <br><br></li>
193 
<li><strong>compile</strong> - This target is used to compile any source code
194 
    that has been changed since the last time compilation took place.  The
195 
    resulting class files are created in the <code>WEB-INF/classes</code>
196 
    subdirectory of your <code>build</code> directory, exactly where the
197 
    structure of a web application requires them to be.  Because
198 
    this command is executed so often during development, it is normally
199 
    made the "default" target so that a simple <code>ant</code> command will
200 
    execute it.
201 
    <br><br></li>
202 
<li><strong>all</strong> - This target is a short cut for running the
203 
    <code>clean</code> target, followed by the <code>compile</code> target.
204 
    Thus, it guarantees that you will recompile the entire application, to
205 
    ensure that you have not unknowingly introduced any incompatible changes.
206 
    <br><br></li>
207 
<li><strong>javadoc</strong> - This target creates Javadoc API documentation
208 
    for the Java classes in this web application.  The example
209 
    <code>build.xml</code> file assumes you want to include the API
210 
    documentation with your app distribution, so it generates the docs
211 
    in a subdirectory of the <code>dist</code> directory.  Because you normally
212 
    do not need to generate the Javadocs on every compilation, this target is
213 
    usually a dependency of the <code>dist</code> target, but not of the
214 
    <code>compile</code> target.
215 
    <br><br></li>
216 
<li><strong>dist</strong> - This target creates a distribution directory for
217 
    your application, including any required documentation, the Javadocs for
218 
    your Java classes, and a web application archive (WAR) file that will be
219 
    delivered to system administrators who wish to install your application.
220 
    Because this target also depends on the <code>deploy</code> target, the
221 
    web application archive will have also picked up any external dependencies
222 
    that were included at deployment time.</li>
223 
</ul>
224 
 
225 
<p>For interactive development and testing of your web application using
226 
Tomcat, the following additional targets are defined:</p>
227 
<ul>
228 
<li><strong>install</strong> - Tell the currently running Tomcat to make
229 
    the application you are developing immediately available for execution
230 
    and testing.  This action does not require Tomcat to be restarted, but
231 
    it is also not remembered after Tomcat is restarted the next time.
232 
    <br><br></li>
233 
<li><strong>reload</strong> - Once the application is installed, you can
234 
    continue to make changes and recompile using the <code>compile</code>
235 
    target.  Tomcat will automatically recognize changes made to JSP pages,
236 
    but not to servlet or JavaBean classes - this command will tell Tomcat
237 
    to restart the currently installed application so that such changes are
238 
    recognized.
239 
    <br><br></li>
240 
<li><strong>remove</strong> - When you have completed your development and
241 
    testing activities, you can optionally tell Tomcat to remove this
242 
    application from service.
243 
    </li>
244 
</ul>
245 
 
246 
<p>Using the development and testing targets requires some additional
247 
one-time setup that is described on the next page.</p>
248 
 
249 
</div></div></div></div></div><footer><div id="footer">
250 
    Copyright &copy; 1999-2025, The Apache Software Foundation
251 
    <br>
252 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
253 
    are either registered trademarks or trademarks of the Apache Software
254 
    Foundation.
255 
    </div></footer></div></body></html>