Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-uid / webapps / docs / appdev / source.html
blob: cc9810f797c1b8d012934dc7776f7569c7b2f644 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Application Developer's Guide (7.0.77) - Source Organization</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]80 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]81 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">App Dev Guide Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Contents</strong></p><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></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Source Organization</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]82<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>
83</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Directory Structure"><!--()--></a><a name="Directory_Structure"><strong>Directory Structure</strong></a></font></td></tr><tr><td><blockquote>
84
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]85 <p><em>The description below uses the variable name $CATALINA_BASE to refer the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]86 base directory against which most relative paths are resolved. If you have
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]87 not configured Tomcat for multiple instances by setting a CATALINA_BASE
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]88 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]89 the directory into which you have installed Tomcat.</em></p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]90
91<p>A key recommendation of this manual is to separate the directory
92hierarchy containing your source code (described in this section) from
93the directory hierarchy containing your deployable application
94(described in the preceding section). Maintaining this separation has
95the following advantages:</p>
96<ul>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]97<li><p>The contents of the source directories can be more easily administered,
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]98 moved, and backed up if the "executable" version of the application
99 is not intermixed.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]100 </p></li>
101<li><p>Source code control is easier to manage on directories that contain
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]102 only source files.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]103 </p></li>
104<li><p>The files that make up an installable distribution of your
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]105 application are much easier to select when the deployment
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]106 hierarchy is separate.</p></li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]107</ul>
108
109<p>As we will see, the <code>ant</code> development tool makes the creation
110and processing of such directory hierarchies nearly painless.</p>
111
112<p>The actual directory and file hierarchy used to contain the source code
113of an application can be pretty much anything you like. However, the
114following organization has proven to be quite generally applicable, and is
115expected by the example <code>build.xml</code> configuration file that
116is discussed below. All of these components exist under a top level
117<em>project source directory</em> for your application:</p>
118<ul>
119<li><strong>docs/</strong> - Documentation for your application, in whatever
120 format your development team is using.<br><br></li>
121<li><strong>src/</strong> - Java source files that generate the servlets,
122 beans, and other Java classes that are unique to your application.
123 If your source code is organized in packages (<strong>highly</strong>
124 recommended), the package hierarchy should be reflected as a directory
125 structure underneath this directory.<br><br></li>
126<li><strong>web/</strong> - The static content of your web site (HTML pages,
127 JSP pages, JavaScript files, CSS stylesheet files, and images) that will
128 be accessible to application clients. This directory will be the
129 <em>document root</em> of your web application, and any subdirectory
130 structure found here will be reflected in the request URIs required to
131 access those files.<br><br></li>
132<li><strong>web/WEB-INF/</strong> - The special configuration files required
133 for your application, including the web application deployment descriptor
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]134 (<code>web.xml</code>, defined in the
135 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet Specification</a>),
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]136 tag library descriptors for custom tag libraries
137 you have created, and other resource files you wish to include within
138 your web application. Even though this directory appears to be a
139 subdirectory of your <em>document root</em>, the Servlet Specification
140 prohibits serving the contents of this directory (or any file it contains)
141 directly to a client request. Therefore, this is a good place to store
142 configuration information that is sensitive (such as database connection
143 usernames and passwords), but is required for your application to
144 operate successfully.</li>
145</ul>
146
147<p>During the development process, two additional directories will be
148created on a temporary basis:</p>
149<ul>
150<li><strong>build/</strong> - When you execute a default build
151 (<code>ant</code>), this directory will contain an exact image
152 of the files in the web application archive for this application.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]153 Tomcat allows you to deploy an application in an unpacked
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]154 directory like this, either by copying it to the
155 <code>$CATALINA_BASE/webapps</code> directory, or by <em>installing</em>
156 it via the "Manager" web application. The latter approach is very
157 useful during development, and will be illustrated below.
158 <br><br></li>
159<li><strong>dist/</strong> - When you execute the <code>ant dist</code>
160 target, this directory will be created. It will create an exact image
161 of the binary distribution for your web application, including an license
162 information, documentation, and README files that you have prepared.</li>
163</ul>
164
165<p>Note that these two directories should <strong>NOT</strong> be archived in
166your source code control system, because they are deleted and recreated (from
167scratch) as needed during development. For that reason, you should not edit
168any source files in these directories if you want to maintain a permanent
169record of the changes, because the changes will be lost the next time that a
170build is performed.</p>
171
172 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="External Dependencies"><!--()--></a><a name="External_Dependencies"><strong>External Dependencies</strong></a></font></td></tr><tr><td><blockquote>
173
174 <p>What do you do if your application requires JAR files (or other
175 resources) from external projects or packages? A common example is that
176 you need to include a JDBC driver in your web application, in order to
177 operate.</p>
178
179 <p>Different developers take different approaches to this problem.
180 Some will encourage checking a copy of the JAR files you depend on into
181 the source code control archives for every application that requires those
182 JAR files. However, this can cause significant management issues when you
183 use the same JAR in many applications - particular when faced with a need
184 to upgrade to a different version of that JAR file.</p>
185
186 <p>Therefore, this manual recommends that you <strong>NOT</strong> store
187 a copy of the packages you depend on inside the source control archives
188 of your applications. Instead, the external dependencies should be
189 integrated as part of the process of <strong>building</strong> your
190 application. In that way, you can always pick up the appropriate version
191 of the JAR files from wherever your development system administrator has
192 installed them, without having to worry about updating your application
193 every time the version of the dependent JAR file is changed.</p>
194
195 <p>In the example Ant <code>build.xml</code> file, we will demonstrate
196 how to define <em>build properties</em> that let you configure the locations
197 of the files to be copied, without having to modify <code>build.xml</code>
198 when these files change. The build properties used by a particular
199 developer can be customized on a per-application basis, or defaulted to
200 "standard" build properties stored in the developer's home directory.</p>
201
202 <p>In many cases, your development system administrator will have already
203 installed the required JAR files into the <code>lib</code> directory of Tomcat.
204 If this has been done, you need
205 to take no actions at all - the example <code>build.xml</code> file
206 automatically constructs a compile classpath that includes these files.</p>
207
208 </blockquote></td></tr></table>
209
210</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Source Code Control"><!--()--></a><a name="Source_Code_Control"><strong>Source Code Control</strong></a></font></td></tr><tr><td><blockquote>
211
212<p>As mentioned earlier, it is highly recommended that you place all of the
213source files that comprise your application under the management of a
214source code control system like the Concurrent Version System (CVS). If you
215elect to do this, every directory and file in the source hierarchy should be
216registered and saved -- but none of the generated files. If you register
217binary format files (such as images or JAR libraries), be sure to indicate
218this to your source code control system.</p>
219
220<p>We recommended (in the previous section) that you should not store the
221contents of the <code>build/</code> and <code>dist/</code> directories
222created by your development process in the source code control system. An
223easy way to tell CVS to ignore these directories is to create a file named
224<code>.cvsignore</code> (note the leading period) in your top-level source
225directory, with the following contents:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]226<div class="codeBox"><pre><code>build
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]227dist
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]228build.properties</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]229
230<p>The reason for mentioning <code>build.properties</code> here will be
231explained in the <a href="processes.html">Processes</a> section.</p>
232
233<p>Detailed instructions for your source code control environment are beyond
234the scope of this manual. However, the following steps are followed when
235using a command-line CVS client:</p>
236<ul>
237<li>To refresh the state of your source code to that stored in the
238 the source repository, go to your project source directory, and
239 execute <code>cvs update -dP</code>.
240 <br><br></li>
241<li>When you create a new subdirectory in the source code hierarchy, register
242 it in CVS with a command like <code>cvs add {subdirname}</code>.
243 <br><br></li>
244<li>When you first create a new source code file, navigate to the directory
245 that contains it, and register the new file with a command like
246 <code>cvs add {filename}</code>.
247 <br><br></li>
248<li>If you no longer need a particular source code file, navigate to the
249 containing directory and remove the file. Then, deregister it in CVS
250 with a command like <code>cvs remove {filename}</code>.
251 <br><br></li>
252<li>While you are creating, modifying, and deleting source files, changes
253 are not yet reflected in the server repository. To save your changes in
254 their current state, go to the project source directory
255 and execute <code>cvs commit</code>. You will be asked to write a brief
256 description of the changes you have just completed, which will be stored
257 with the new version of any updated source file.</li>
258</ul>
259
260<p>CVS, like other source code control systems, has many additional features
261(such as the ability to tag the files that made up a particular release, and
262support for multiple development branches that can later be merged). See the
263links and references in the <a href="introduction.html">Introduction</a> for
264more information.</p>
265
266</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="BUILD.XML Configuration File"><!--()--></a><a name="BUILD.XML_Configuration_File"><strong>BUILD.XML Configuration File</strong></a></font></td></tr><tr><td><blockquote>
267
268<p>We will be using the <strong>ant</strong> tool to manage the compilation of
269our Java source code files, and creation of the deployment hierarchy. Ant
270operates under the control of a build file, normally called
271<code>build.xml</code>, that defines the processing steps required. This
272file is stored in the top-level directory of your source code hierarchy, and
273should be checked in to your source code control system.</p>
274
275<p>Like a Makefile, the <code>build.xml</code> file provides several
276"targets" that support optional development activities (such as creating
277the associated Javadoc documentation, erasing the deployment home directory
278so you can build your project from scratch, or creating the web application
279archive file so you can distribute your application. A well-constructed
280<code>build.xml</code> file will contain internal documentation describing
281the targets that are designed for use by the developer, versus those targets
282used internally. To ask Ant to display the project documentation, change to
283the directory containing the <code>build.xml</code> file and type:</p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]284<div class="codeBox"><pre><code>ant -projecthelp</code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]285
286<p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
287is provided that you can customize and install in the project source directory
288for your application. This file includes comments that describe the various
289targets that can be executed. Briefly, the following targets are generally
290provided:</p>
291<ul>
292<li><strong>clean</strong> - This target deletes any existing
293 <code>build</code> and <code>dist</code> directories, so that they
294 can be reconstructed from scratch. This allows you to guarantee that
295 you have not made source code modifications that will result in
296 problems at runtime due to not recompiling all affected classes.
297 <br><br></li>
298<li><strong>compile</strong> - This target is used to compile any source code
299 that has been changed since the last time compilation took place. The
300 resulting class files are created in the <code>WEB-INF/classes</code>
301 subdirectory of your <code>build</code> directory, exactly where the
302 structure of a web application requires them to be. Because
303 this command is executed so often during development, it is normally
304 made the "default" target so that a simple <code>ant</code> command will
305 execute it.
306 <br><br></li>
307<li><strong>all</strong> - This target is a short cut for running the
308 <code>clean</code> target, followed by the <code>compile</code> target.
309 Thus, it guarantees that you will recompile the entire application, to
310 ensure that you have not unknowingly introduced any incompatible changes.
311 <br><br></li>
312<li><strong>javadoc</strong> - This target creates Javadoc API documentation
313 for the Java classes in this web application. The example
314 <code>build.xml</code> file assumes you want to include the API
315 documentation with your app distribution, so it generates the docs
316 in a subdirectory of the <code>dist</code> directory. Because you normally
317 do not need to generate the Javadocs on every compilation, this target is
318 usually a dependency of the <code>dist</code> target, but not of the
319 <code>compile</code> target.
320 <br><br></li>
321<li><strong>dist</strong> - This target creates a distribution directory for
322 your application, including any required documentation, the Javadocs for
323 your Java classes, and a web application archive (WAR) file that will be
324 delivered to system administrators who wish to install your application.
325 Because this target also depends on the <code>deploy</code> target, the
326 web application archive will have also picked up any external dependencies
327 that were included at deployment time.</li>
328</ul>
329
330<p>For interactive development and testing of your web application using
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]331Tomcat, the following additional targets are defined:</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]332<ul>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]333<li><strong>install</strong> - Tell the currently running Tomcat to make
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]334 the application you are developing immediately available for execution
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]335 and testing. This action does not require Tomcat to be restarted, but
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]336 it is also not remembered after Tomcat is restarted the next time.
337 <br><br></li>
338<li><strong>reload</strong> - Once the application is installed, you can
339 continue to make changes and recompile using the <code>compile</code>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]340 target. Tomcat will automatically recognize changes made to JSP pages,
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]341 but not to servlet or JavaBean classes - this command will tell Tomcat
342 to restart the currently installed application so that such changes are
343 recognized.
344 <br><br></li>
345<li><strong>remove</strong> - When you have completed your development and
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]346 testing activities, you can optionally tell Tomcat to remove this
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]347 application from service.
348 </li>
349</ul>
350
351<p>Using the development and testing targets requires some additional
352one-time setup that is described on the next page.</p>
353
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]354</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
355 on improving documentation for Apache Tomcat.<br><br>
356 If you have trouble and need help, read
357 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
358 and ask your question on the tomcat-users
359 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
360 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
361 The Apache Comments System is explained <a href="../comments.html">here</a>.
362 Comments may be removed by our moderators if they are either
363 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
364 var comments_shortname = 'tomcat';
365 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/appdev/source.html';
366 (function(w, d) {
367 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
368 d.write('<div id="comments_thread"><\/div>');
369 var s = d.createElement('script');
370 s.type = 'text/javascript';
371 s.async = true;
372 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
373 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
374 }
375 else {
376 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
377 }
378 })(window, document);
379 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
380 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]381 </em></font></div></td></tr></table></body></html>