source: nutchez-0.1/tomcat/webapps/docs/appdev/printer/source.html @ 149

Last change on this file since 149 was 66, checked in by waue, 15 years ago

NutchEz - an easy way to nutch

File size: 19.4 KB
Line 
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
14hierarchy containing your source code (described in this section) from
15the directory hierarchy containing your deployable application
16(described in the preceding section).  Maintaining this separation has
17the 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
32and processing of such directory hierarchies nearly painless.</p>
33
34<p>The actual directory and file hierarchy used to contain the source code
35of an application can be pretty much anything you like.  However, the
36following organization has proven to be quite generally applicable, and is
37expected by the example <code>build.xml</code> configuration file that
38is 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
70created 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
88your source code control system, because they are deleted and recreated (from
89scratch) as needed during development.  For that reason, you should not edit
90any source files in these directories if you want to maintain a permanent
91record of the changes, because the changes will be lost the next time that a
92build 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
135source files that comprise your application under the management of a
136source code control system like the Concurrent Version System (CVS).  If you
137elect to do this, every directory and file in the source hierarchy should be
138registered and saved -- but none of the generated files.  If you register
139binary format files (such as images or JAR libraries), be sure to indicate
140this to your source code control system.</p>
141
142<p>We recommended (in the previous section) that you should not store the
143contents of the <code>build/</code> and <code>dist/</code> directories
144created by your development process in the source code control system.  An
145easy 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
147directory, 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>
149build
150dist
151build.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
155explained in the <a href="processes.html">Processes</a> section.</p>
156
157<p>Detailed instructions for your source code control environment are beyond
158the scope of this manual.  However, the following steps are followed when
159using 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
186support for multiple development branches that can later be merged).  See the
187links and references in the <a href="introduction.html">Introduction</a> for
188more 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
193our Java source code files, and creation of the deployment hierarchy.  Ant
194operates under the control of a build file, normally called
195<code>build.xml</code>, that defines the processing steps required.  This
196file is stored in the top-level directory of your source code hierarchy, and
197should 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
201the associated Javadoc documentation, erasing the deployment home directory
202so you can build your project from scratch, or creating the web application
203archive file so you can distribute your application.  A well-constructed
204<code>build.xml</code> file will contain internal documentation describing
205the targets that are designed for use by the developer, versus those targets
206used internally.  To ask Ant to display the project documentation, change to
207the 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>
209ant -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>
213is provided that you can customize and install in the project source directory
214for your application.  This file includes comments that describe the various
215targets that can be executed.  Briefly, the following targets are generally
216provided:</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
257Tomcat 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
278one-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 &copy; 1999-2008, Apache Software Foundation
282        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.