| Hongqing Liu | 7189829 | 2014-10-15 13:31:32 +0800 | [diff] [blame] | 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Application Developer's Guide (6.0.41) - Source Organization</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 2 | .noPrint {display: none;}
|
| 3 | td#mainBody {width: 100%;}
|
| 4 | </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="
|
| 5 | The Apache Tomcat Servlet/JSP Container
|
| Hongqing Liu | 7189829 | 2014-10-15 13:31:32 +0800 | [diff] [blame] | 6 | " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</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>Application Developer's Guide</h1><h2>Source Organization</h2><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 Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 7 | <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>
|
| 8 | </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>
|
| 9 |
|
| 10 | <blockquote><em>
|
| 11 | <p>The description below uses the variable name $CATALINA_BASE to refer the
|
| 12 | base directory against which most relative paths are resolved. If you have
|
| 13 | not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
|
| 14 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
|
| 15 | the directory into which you have installed Tomcat 6.</p>
|
| 16 | </em></blockquote>
|
| 17 |
|
| 18 | <p>A key recommendation of this manual is to separate the directory
|
| 19 | hierarchy containing your source code (described in this section) from
|
| 20 | the directory hierarchy containing your deployable application
|
| 21 | (described in the preceding section). Maintaining this separation has
|
| 22 | the following advantages:</p>
|
| 23 | <ul>
|
| 24 | <li>The contents of the source directories can be more easily administered,
|
| 25 | moved, and backed up if the "executable" version of the application
|
| 26 | is not intermixed.
|
| 27 | <br><br></li>
|
| 28 | <li>Source code control is easier to manage on directories that contain
|
| 29 | only source files.
|
| 30 | <br><br></li>
|
| 31 | <li>The files that make up an installable distribution of your
|
| 32 | application are much easier to select when the deployment
|
| 33 | hierarchy is separate.</li>
|
| 34 | </ul>
|
| 35 |
|
| 36 | <p>As we will see, the <code>ant</code> development tool makes the creation
|
| 37 | and processing of such directory hierarchies nearly painless.</p>
|
| 38 |
|
| 39 | <p>The actual directory and file hierarchy used to contain the source code
|
| 40 | of an application can be pretty much anything you like. However, the
|
| 41 | following organization has proven to be quite generally applicable, and is
|
| 42 | expected by the example <code>build.xml</code> configuration file that
|
| 43 | is discussed below. All of these components exist under a top level
|
| 44 | <em>project source directory</em> for your application:</p>
|
| 45 | <ul>
|
| 46 | <li><strong>docs/</strong> - Documentation for your application, in whatever
|
| 47 | format your development team is using.<br><br></li>
|
| 48 | <li><strong>src/</strong> - Java source files that generate the servlets,
|
| 49 | beans, and other Java classes that are unique to your application.
|
| 50 | If your source code is organized in packages (<strong>highly</strong>
|
| 51 | recommended), the package hierarchy should be reflected as a directory
|
| 52 | structure underneath this directory.<br><br></li>
|
| 53 | <li><strong>web/</strong> - The static content of your web site (HTML pages,
|
| 54 | JSP pages, JavaScript files, CSS stylesheet files, and images) that will
|
| 55 | be accessible to application clients. This directory will be the
|
| 56 | <em>document root</em> of your web application, and any subdirectory
|
| 57 | structure found here will be reflected in the request URIs required to
|
| 58 | access those files.<br><br></li>
|
| 59 | <li><strong>web/WEB-INF/</strong> - The special configuration files required
|
| 60 | for your application, including the web application deployment descriptor
|
| 61 | (<code>web.xml</code>, defined in the
|
| 62 | <a href="http://wiki.apache.org/tomcat/Specifications">Servlet Specification</a>),
|
| 63 | tag library descriptors for custom tag libraries
|
| 64 | you have created, and other resource files you wish to include within
|
| 65 | your web application. Even though this directory appears to be a
|
| 66 | subdirectory of your <em>document root</em>, the Servlet Specification
|
| 67 | prohibits serving the contents of this directory (or any file it contains)
|
| 68 | directly to a client request. Therefore, this is a good place to store
|
| 69 | configuration information that is sensitive (such as database connection
|
| 70 | usernames and passwords), but is required for your application to
|
| 71 | operate successfully.</li>
|
| 72 | </ul>
|
| 73 |
|
| 74 | <p>During the development process, two additional directories will be
|
| 75 | created on a temporary basis:</p>
|
| 76 | <ul>
|
| 77 | <li><strong>build/</strong> - When you execute a default build
|
| 78 | (<code>ant</code>), this directory will contain an exact image
|
| 79 | of the files in the web application archive for this application.
|
| 80 | Tomcat 6 allows you to deploy an application in an unpacked
|
| 81 | directory like this, either by copying it to the
|
| 82 | <code>$CATALINA_BASE/webapps</code> directory, or by <em>installing</em>
|
| 83 | it via the "Manager" web application. The latter approach is very
|
| 84 | useful during development, and will be illustrated below.
|
| 85 | <br><br></li>
|
| 86 | <li><strong>dist/</strong> - When you execute the <code>ant dist</code>
|
| 87 | target, this directory will be created. It will create an exact image
|
| 88 | of the binary distribution for your web application, including an license
|
| 89 | information, documentation, and README files that you have prepared.</li>
|
| 90 | </ul>
|
| 91 |
|
| 92 | <p>Note that these two directories should <strong>NOT</strong> be archived in
|
| 93 | your source code control system, because they are deleted and recreated (from
|
| 94 | scratch) as needed during development. For that reason, you should not edit
|
| 95 | any source files in these directories if you want to maintain a permanent
|
| 96 | record of the changes, because the changes will be lost the next time that a
|
| 97 | build is performed.</p>
|
| 98 |
|
| 99 | <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>
|
| 100 |
|
| 101 | <p>What do you do if your application requires JAR files (or other
|
| 102 | resources) from external projects or packages? A common example is that
|
| 103 | you need to include a JDBC driver in your web application, in order to
|
| 104 | operate.</p>
|
| 105 |
|
| 106 | <p>Different developers take different approaches to this problem.
|
| 107 | Some will encourage checking a copy of the JAR files you depend on into
|
| 108 | the source code control archives for every application that requires those
|
| 109 | JAR files. However, this can cause significant management issues when you
|
| 110 | use the same JAR in many applications - particular when faced with a need
|
| 111 | to upgrade to a different version of that JAR file.</p>
|
| 112 |
|
| 113 | <p>Therefore, this manual recommends that you <strong>NOT</strong> store
|
| 114 | a copy of the packages you depend on inside the source control archives
|
| 115 | of your applications. Instead, the external dependencies should be
|
| 116 | integrated as part of the process of <strong>building</strong> your
|
| 117 | application. In that way, you can always pick up the appropriate version
|
| 118 | of the JAR files from wherever your development system administrator has
|
| 119 | installed them, without having to worry about updating your application
|
| 120 | every time the version of the dependent JAR file is changed.</p>
|
| 121 |
|
| 122 | <p>In the example Ant <code>build.xml</code> file, we will demonstrate
|
| 123 | how to define <em>build properties</em> that let you configure the locations
|
| 124 | of the files to be copied, without having to modify <code>build.xml</code>
|
| 125 | when these files change. The build properties used by a particular
|
| 126 | developer can be customized on a per-application basis, or defaulted to
|
| 127 | "standard" build properties stored in the developer's home directory.</p>
|
| 128 |
|
| 129 | <p>In many cases, your development system administrator will have already
|
| 130 | installed the required JAR files into the <code>lib</code> directory of Tomcat.
|
| 131 | If this has been done, you need
|
| 132 | to take no actions at all - the example <code>build.xml</code> file
|
| 133 | automatically constructs a compile classpath that includes these files.</p>
|
| 134 |
|
| 135 | </blockquote></td></tr></table>
|
| 136 |
|
| 137 | </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>
|
| 138 |
|
| 139 | <p>As mentioned earlier, it is highly recommended that you place all of the
|
| 140 | source files that comprise your application under the management of a
|
| 141 | source code control system like the Concurrent Version System (CVS). If you
|
| 142 | elect to do this, every directory and file in the source hierarchy should be
|
| 143 | registered and saved -- but none of the generated files. If you register
|
| 144 | binary format files (such as images or JAR libraries), be sure to indicate
|
| 145 | this to your source code control system.</p>
|
| 146 |
|
| 147 | <p>We recommended (in the previous section) that you should not store the
|
| 148 | contents of the <code>build/</code> and <code>dist/</code> directories
|
| 149 | created by your development process in the source code control system. An
|
| 150 | easy way to tell CVS to ignore these directories is to create a file named
|
| 151 | <code>.cvsignore</code> (note the leading period) in your top-level source
|
| 152 | directory, with the following contents:</p>
|
| 153 | <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
| 154 | build
|
| 155 | dist
|
| 156 | build.properties
|
| 157 | </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
| 158 |
|
| 159 | <p>The reason for mentioning <code>build.properties</code> here will be
|
| 160 | explained in the <a href="processes.html">Processes</a> section.</p>
|
| 161 |
|
| 162 | <p>Detailed instructions for your source code control environment are beyond
|
| 163 | the scope of this manual. However, the following steps are followed when
|
| 164 | using a command-line CVS client:</p>
|
| 165 | <ul>
|
| 166 | <li>To refresh the state of your source code to that stored in the
|
| 167 | the source repository, go to your project source directory, and
|
| 168 | execute <code>cvs update -dP</code>.
|
| 169 | <br><br></li>
|
| 170 | <li>When you create a new subdirectory in the source code hierarchy, register
|
| 171 | it in CVS with a command like <code>cvs add {subdirname}</code>.
|
| 172 | <br><br></li>
|
| 173 | <li>When you first create a new source code file, navigate to the directory
|
| 174 | that contains it, and register the new file with a command like
|
| 175 | <code>cvs add {filename}</code>.
|
| 176 | <br><br></li>
|
| 177 | <li>If you no longer need a particular source code file, navigate to the
|
| 178 | containing directory and remove the file. Then, deregister it in CVS
|
| 179 | with a command like <code>cvs remove {filename}</code>.
|
| 180 | <br><br></li>
|
| 181 | <li>While you are creating, modifying, and deleting source files, changes
|
| 182 | are not yet reflected in the server repository. To save your changes in
|
| 183 | their current state, go to the project source directory
|
| 184 | and execute <code>cvs commit</code>. You will be asked to write a brief
|
| 185 | description of the changes you have just completed, which will be stored
|
| 186 | with the new version of any updated source file.</li>
|
| 187 | </ul>
|
| 188 |
|
| 189 | <p>CVS, like other source code control systems, has many additional features
|
| 190 | (such as the ability to tag the files that made up a particular release, and
|
| 191 | support for multiple development branches that can later be merged). See the
|
| 192 | links and references in the <a href="introduction.html">Introduction</a> for
|
| 193 | more information.</p>
|
| 194 |
|
| 195 | </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>
|
| 196 |
|
| 197 | <p>We will be using the <strong>ant</strong> tool to manage the compilation of
|
| 198 | our Java source code files, and creation of the deployment hierarchy. Ant
|
| 199 | operates under the control of a build file, normally called
|
| 200 | <code>build.xml</code>, that defines the processing steps required. This
|
| 201 | file is stored in the top-level directory of your source code hierarchy, and
|
| 202 | should be checked in to your source code control system.</p>
|
| 203 |
|
| 204 | <p>Like a Makefile, the <code>build.xml</code> file provides several
|
| 205 | "targets" that support optional development activities (such as creating
|
| 206 | the associated Javadoc documentation, erasing the deployment home directory
|
| 207 | so you can build your project from scratch, or creating the web application
|
| 208 | archive file so you can distribute your application. A well-constructed
|
| 209 | <code>build.xml</code> file will contain internal documentation describing
|
| 210 | the targets that are designed for use by the developer, versus those targets
|
| 211 | used internally. To ask Ant to display the project documentation, change to
|
| 212 | the directory containing the <code>build.xml</code> file and type:</p>
|
| 213 | <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
| 214 | ant -projecthelp
|
| 215 | </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
| 216 |
|
| 217 | <p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
|
| 218 | is provided that you can customize and install in the project source directory
|
| 219 | for your application. This file includes comments that describe the various
|
| 220 | targets that can be executed. Briefly, the following targets are generally
|
| 221 | provided:</p>
|
| 222 | <ul>
|
| 223 | <li><strong>clean</strong> - This target deletes any existing
|
| 224 | <code>build</code> and <code>dist</code> directories, so that they
|
| 225 | can be reconstructed from scratch. This allows you to guarantee that
|
| 226 | you have not made source code modifications that will result in
|
| 227 | problems at runtime due to not recompiling all affected classes.
|
| 228 | <br><br></li>
|
| 229 | <li><strong>compile</strong> - This target is used to compile any source code
|
| 230 | that has been changed since the last time compilation took place. The
|
| 231 | resulting class files are created in the <code>WEB-INF/classes</code>
|
| 232 | subdirectory of your <code>build</code> directory, exactly where the
|
| 233 | structure of a web application requires them to be. Because
|
| 234 | this command is executed so often during development, it is normally
|
| 235 | made the "default" target so that a simple <code>ant</code> command will
|
| 236 | execute it.
|
| 237 | <br><br></li>
|
| 238 | <li><strong>all</strong> - This target is a short cut for running the
|
| 239 | <code>clean</code> target, followed by the <code>compile</code> target.
|
| 240 | Thus, it guarantees that you will recompile the entire application, to
|
| 241 | ensure that you have not unknowingly introduced any incompatible changes.
|
| 242 | <br><br></li>
|
| 243 | <li><strong>javadoc</strong> - This target creates Javadoc API documentation
|
| 244 | for the Java classes in this web application. The example
|
| 245 | <code>build.xml</code> file assumes you want to include the API
|
| 246 | documentation with your app distribution, so it generates the docs
|
| 247 | in a subdirectory of the <code>dist</code> directory. Because you normally
|
| 248 | do not need to generate the Javadocs on every compilation, this target is
|
| 249 | usually a dependency of the <code>dist</code> target, but not of the
|
| 250 | <code>compile</code> target.
|
| 251 | <br><br></li>
|
| 252 | <li><strong>dist</strong> - This target creates a distribution directory for
|
| 253 | your application, including any required documentation, the Javadocs for
|
| 254 | your Java classes, and a web application archive (WAR) file that will be
|
| 255 | delivered to system administrators who wish to install your application.
|
| 256 | Because this target also depends on the <code>deploy</code> target, the
|
| 257 | web application archive will have also picked up any external dependencies
|
| 258 | that were included at deployment time.</li>
|
| 259 | </ul>
|
| 260 |
|
| 261 | <p>For interactive development and testing of your web application using
|
| 262 | Tomcat 6, the following additional targets are defined:</p>
|
| 263 | <ul>
|
| 264 | <li><strong>install</strong> - Tell the currently running Tomcat 6 to make
|
| 265 | the application you are developing immediately available for execution
|
| 266 | and testing. This action does not require Tomcat 6 to be restarted, but
|
| 267 | it is also not remembered after Tomcat is restarted the next time.
|
| 268 | <br><br></li>
|
| 269 | <li><strong>reload</strong> - Once the application is installed, you can
|
| 270 | continue to make changes and recompile using the <code>compile</code>
|
| 271 | target. Tomcat 6 will automatically recognize changes made to JSP pages,
|
| 272 | but not to servlet or JavaBean classes - this command will tell Tomcat
|
| 273 | to restart the currently installed application so that such changes are
|
| 274 | recognized.
|
| 275 | <br><br></li>
|
| 276 | <li><strong>remove</strong> - When you have completed your development and
|
| 277 | testing activities, you can optionally tell Tomcat 6 to remove this
|
| 278 | application from service.
|
| 279 | </li>
|
| 280 | </ul>
|
| 281 |
|
| 282 | <p>Using the development and testing targets requires some additional
|
| 283 | one-time setup that is described on the next page.</p>
|
| 284 |
|
| 285 | </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
|
| 286 | Copyright © 1999-2014, Apache Software Foundation
|
| 287 | </em></font></div></td></tr></table></body></html> |