Gecko [ edgpens.lpkmn.gov.my ]

Name	Size	Permission
sample	[ DIR ]	drwxrwxrwx
build.xml.txt	16.78 KB	-rw-rw-rw-
deployment.html	17.17 KB	-rw-rw-rw-
index.html	6.31 KB	-rw-rw-rw-
installation.html	7.67 KB	-rw-rw-rw-
introduction.html	7.25 KB	-rw-rw-rw-
processes.html	18.5 KB	-rw-rw-rw-
source.html	20.47 KB	-rw-rw-rw-
web.xml.txt	6.27 KB	-rw-rw-rw-

Code Editor : source.html

<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Application Developer's Guide (7.0.107) - Source Organization</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
 .noPrint {display: none;}
 td#mainBody {width: 100%;}
</style><style type="text/css">
code {background-color:rgb(224,255,255);padding:0 0.1em;}
code.attributeName, code.propertyName {background-color:transparent;}

table {
 border-collapse: collapse;
 text-align: left;
}
table *:not(table) {
 /* Prevent border-collapsing for table child elements like <div> */
 border-collapse: separate;
}

th {
  text-align: left;
}

div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
 background-color: transparent;
}
div.codeBox {
 overflow: auto;
 margin: 1em 0;
}
div.codeBox pre {
 margin: 0;
 padding: 4px;
 border: 1px solid #999;
 border-radius: 5px;
 background-color: #eff8ff;
 display: table; /* To prevent <pre>s from taking the complete available width. */
 /*
 When it is officially supported, use the following CSS instead of display: table
 to prevent big <pre>s from exceeding the browser window:
 max-width: available;
 width: min-content;
 */
}

div.codeBox pre.wrap {
  white-space: pre-wrap;
}

table.defaultTable tr, table.detail-table tr {
    border: 1px solid #CCC;
}

table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
    background-color: #FAFBFF;
}

table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
    background-color: #EEEFFF;
}

table.defaultTable th, table.detail-table th {
  background-color: #88b;
  color: #fff;
}

table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
  padding: 5px 8px;
}

p.notice {
 border: 1px solid rgb(255, 0, 0);
 background-color: rgb(238, 238, 238);
 color: rgb(0, 51, 102);
 padding: 0.5em;
 margin: 1em 2em 1em 1em;
}
</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><tr><td><a href="https://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
 The Apache Tomcat Servlet/JSP Container
 " border="0"></a></td><td><h1>Apache Tomcat 7</h1>Version 7.0.107, Nov 18 2020</td><td><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"><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td width="20%" valign="top" nowrap class="noPrint">Links<ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">App Dev Guide Home</a></li><li><a href="https://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul>Contents<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><td width="80%" valign="top" align="left" id="mainBody"><h1>Source Organization</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Table of Contents"></a><a name="Table_of_Contents">Table of Contents</a></td></tr><tr><td><blockquote>
<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>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Directory Structure"></a><a name="Directory_Structure">Directory Structure</a></td></tr><tr><td><blockquote>

The description below uses the variable name $CATALINA_BASE to refer the
 base directory against which most relative paths are resolved. If you have
 not configured Tomcat for multiple instances by setting a CATALINA_BASE
 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
 the directory into which you have installed Tomcat.

A key recommendation of this manual is to separate the directory
hierarchy containing your source code (described in this section) from
the directory hierarchy containing your deployable application
(described in the preceding section). Maintaining this separation has
the following advantages:
<ul>
<li>The contents of the source directories can be more easily administered,
 moved, and backed up if the "executable" version of the application
 is not intermixed.
 </li>
<li>Source code control is easier to manage on directories that contain
 only source files.
 </li>
<li>The files that make up an installable distribution of your
 application are much easier to select when the deployment
 hierarchy is separate.</li>
</ul>

As we will see, the <code>ant</code> development tool makes the creation
and processing of such directory hierarchies nearly painless.

The actual directory and file hierarchy used to contain the source code
of an application can be pretty much anything you like. However, the
following organization has proven to be quite generally applicable, and is
expected by the example <code>build.xml</code> configuration file that
is discussed below. All of these components exist under a top level
project source directory for your application:
<ul>
<li>docs/ - Documentation for your application, in whatever
 format your development team is using. </li>
<li>src/ - Java source files that generate the servlets,
 beans, and other Java classes that are unique to your application.
 If your source code is organized in packages (highly
 recommended), the package hierarchy should be reflected as a directory
 structure underneath this directory. </li>
<li>web/ - The static content of your web site (HTML pages,
 JSP pages, JavaScript files, CSS stylesheet files, and images) that will
 be accessible to application clients. This directory will be the
 document root of your web application, and any subdirectory
 structure found here will be reflected in the request URIs required to
 access those files. </li>
<li>web/WEB-INF/ - The special configuration files required
 for your application, including the web application deployment descriptor
 (<code>web.xml</code>, defined in the
 <a href="https://wiki.apache.org/tomcat/Specifications">Servlet Specification</a>),
 tag library descriptors for custom tag libraries
 you have created, and other resource files you wish to include within
 your web application. Even though this directory appears to be a
 subdirectory of your document root, the Servlet Specification
 prohibits serving the contents of this directory (or any file it contains)
 directly to a client request. Therefore, this is a good place to store
 configuration information that is sensitive (such as database connection
 usernames and passwords), but is required for your application to
 operate successfully.</li>
</ul>

During the development process, two additional directories will be
created on a temporary basis:
<ul>
<li>build/ - When you execute a default build
 (<code>ant</code>), this directory will contain an exact image
 of the files in the web application archive for this application.
 Tomcat allows you to deploy an application in an unpacked
 directory like this, either by copying it to the
 <code>$CATALINA_BASE/webapps</code> directory, or by installing
 it via the "Manager" web application. The latter approach is very
 useful during development, and will be illustrated below.
 </li>
<li>dist/ - When you execute the <code>ant dist</code>
 target, this directory will be created. It will create an exact image
 of the binary distribution for your web application, including an license
 information, documentation, and README files that you have prepared.</li>
</ul>

Note that these two directories should NOT be archived in
your source code control system, because they are deleted and recreated (from
scratch) as needed during development. For that reason, you should not edit
any source files in these directories if you want to maintain a permanent
record of the changes, because the changes will be lost the next time that a
build is performed.

<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><a name="External Dependencies"></a><a name="External_Dependencies">External Dependencies</a></td></tr><tr><td><blockquote>

What do you do if your application requires JAR files (or other
 resources) from external projects or packages? A common example is that
 you need to include a JDBC driver in your web application, in order to
 operate.

Different developers take different approaches to this problem.
 Some will encourage checking a copy of the JAR files you depend on into
 the source code control archives for every application that requires those
 JAR files. However, this can cause significant management issues when you
 use the same JAR in many applications - particular when faced with a need
 to upgrade to a different version of that JAR file.

Therefore, this manual recommends that you NOT store
 a copy of the packages you depend on inside the source control archives
 of your applications. Instead, the external dependencies should be
 integrated as part of the process of building your
 application. In that way, you can always pick up the appropriate version
 of the JAR files from wherever your development system administrator has
 installed them, without having to worry about updating your application
 every time the version of the dependent JAR file is changed.

In the example Ant <code>build.xml</code> file, we will demonstrate
 how to define build properties that let you configure the locations
 of the files to be copied, without having to modify <code>build.xml</code>
 when these files change. The build properties used by a particular
 developer can be customized on a per-application basis, or defaulted to
 "standard" build properties stored in the developer's home directory.

In many cases, your development system administrator will have already
 installed the required JAR files into the <code>lib</code> directory of Tomcat.
 If this has been done, you need
 to take no actions at all - the example <code>build.xml</code> file
 automatically constructs a compile classpath that includes these files.

</blockquote></td></tr></table>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="Source Code Control"></a><a name="Source_Code_Control">Source Code Control</a></td></tr><tr><td><blockquote>

As mentioned earlier, it is highly recommended that you place all of the
source files that comprise your application under the management of a
source code control system like the Concurrent Version System (CVS). If you
elect to do this, every directory and file in the source hierarchy should be
registered and saved -- but none of the generated files. If you register
binary format files (such as images or JAR libraries), be sure to indicate
this to your source code control system.

We recommended (in the previous section) that you should not store the
contents of the <code>build/</code> and <code>dist/</code> directories
created by your development process in the source code control system. An
easy way to tell CVS to ignore these directories is to create a file named
<code>.cvsignore</code> (note the leading period) in your top-level source
directory, with the following contents:
<div class="codeBox"><pre><code>build
dist
build.properties</code></pre></div>

The reason for mentioning <code>build.properties</code> here will be
explained in the <a href="processes.html">Processes</a> section.

Detailed instructions for your source code control environment are beyond
the scope of this manual. However, the following steps are followed when
using a command-line CVS client:
<ul>
<li>To refresh the state of your source code to that stored in the
 the source repository, go to your project source directory, and
 execute <code>cvs update -dP</code>.
 </li>
<li>When you create a new subdirectory in the source code hierarchy, register
 it in CVS with a command like <code>cvs add {subdirname}</code>.
 </li>
<li>When you first create a new source code file, navigate to the directory
 that contains it, and register the new file with a command like
 <code>cvs add {filename}</code>.
 </li>
<li>If you no longer need a particular source code file, navigate to the
 containing directory and remove the file. Then, deregister it in CVS
 with a command like <code>cvs remove {filename}</code>.
 </li>
<li>While you are creating, modifying, and deleting source files, changes
 are not yet reflected in the server repository. To save your changes in
 their current state, go to the project source directory
 and execute <code>cvs commit</code>. You will be asked to write a brief
 description of the changes you have just completed, which will be stored
 with the new version of any updated source file.</li>
</ul>

CVS, like other source code control systems, has many additional features
(such as the ability to tag the files that made up a particular release, and
support for multiple development branches that can later be merged). See the
links and references in the <a href="introduction.html">Introduction</a> for
more information.

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><a name="BUILD.XML Configuration File"></a><a name="BUILD.XML_Configuration_File">BUILD.XML Configuration File</a></td></tr><tr><td><blockquote>

We will be using the ant tool to manage the compilation of
our Java source code files, and creation of the deployment hierarchy. Ant
operates under the control of a build file, normally called
<code>build.xml</code>, that defines the processing steps required. This
file is stored in the top-level directory of your source code hierarchy, and
should be checked in to your source code control system.

Like a Makefile, the <code>build.xml</code> file provides several
"targets" that support optional development activities (such as creating
the associated Javadoc documentation, erasing the deployment home directory
so you can build your project from scratch, or creating the web application
archive file so you can distribute your application. A well-constructed
<code>build.xml</code> file will contain internal documentation describing
the targets that are designed for use by the developer, versus those targets
used internally. To ask Ant to display the project documentation, change to
the directory containing the <code>build.xml</code> file and type:
<div class="codeBox"><pre><code>ant -projecthelp</code></pre></div>

To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
is provided that you can customize and install in the project source directory
for your application. This file includes comments that describe the various
targets that can be executed. Briefly, the following targets are generally
provided:
<ul>
<li>clean - This target deletes any existing
 <code>build</code> and <code>dist</code> directories, so that they
 can be reconstructed from scratch. This allows you to guarantee that
 you have not made source code modifications that will result in
 problems at runtime due to not recompiling all affected classes.
 </li>
<li>compile - This target is used to compile any source code
 that has been changed since the last time compilation took place. The
 resulting class files are created in the <code>WEB-INF/classes</code>
 subdirectory of your <code>build</code> directory, exactly where the
 structure of a web application requires them to be. Because
 this command is executed so often during development, it is normally
 made the "default" target so that a simple <code>ant</code> command will
 execute it.
 </li>
<li>all - This target is a short cut for running the
 <code>clean</code> target, followed by the <code>compile</code> target.
 Thus, it guarantees that you will recompile the entire application, to
 ensure that you have not unknowingly introduced any incompatible changes.
 </li>
<li>javadoc - This target creates Javadoc API documentation
 for the Java classes in this web application. The example
 <code>build.xml</code> file assumes you want to include the API
 documentation with your app distribution, so it generates the docs
 in a subdirectory of the <code>dist</code> directory. Because you normally
 do not need to generate the Javadocs on every compilation, this target is
 usually a dependency of the <code>dist</code> target, but not of the
 <code>compile</code> target.
 </li>
<li>dist - This target creates a distribution directory for
 your application, including any required documentation, the Javadocs for
 your Java classes, and a web application archive (WAR) file that will be
 delivered to system administrators who wish to install your application.
 Because this target also depends on the <code>deploy</code> target, the
 web application archive will have also picked up any external dependencies
 that were included at deployment time.</li>
</ul>

For interactive development and testing of your web application using
Tomcat, the following additional targets are defined:
<ul>
<li>install - Tell the currently running Tomcat to make
 the application you are developing immediately available for execution
 and testing. This action does not require Tomcat to be restarted, but
 it is also not remembered after Tomcat is restarted the next time.
 </li>
<li>reload - Once the application is installed, you can
 continue to make changes and recompile using the <code>compile</code>
 target. Tomcat will automatically recognize changes made to JSP pages,
 but not to servlet or JavaBean classes - this command will tell Tomcat
 to restart the currently installed application so that such changes are
 recognized.
 </li>
<li>remove - When you have completed your development and
 testing activities, you can optionally tell Tomcat to remove this
 application from service.
 </li>
</ul>

Using the development and testing targets requires some additional
one-time setup that is described on the next page.

</blockquote></td></tr></table></td></tr><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><td colspan="2"><div align="center">
 Copyright &copy; 1999-2020, Apache Software Foundation
 </div></td></tr></table></body></html>

${this.title}

Code Editor : source.html