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