Return-Path: X-Original-To: apmail-tomcat-dev-archive@www.apache.org Delivered-To: apmail-tomcat-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 09554E66E for ; Wed, 5 Dec 2012 20:21:58 +0000 (UTC) Received: (qmail 99737 invoked by uid 500); 5 Dec 2012 20:21:55 -0000 Delivered-To: apmail-tomcat-dev-archive@tomcat.apache.org Received: (qmail 99553 invoked by uid 500); 5 Dec 2012 20:21:55 -0000 Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Tomcat Developers List" Delivered-To: mailing list dev@tomcat.apache.org Received: (qmail 99533 invoked by uid 99); 5 Dec 2012 20:21:54 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Dec 2012 20:21:54 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Dec 2012 20:21:36 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 34B142388ABB for ; Wed, 5 Dec 2012 20:21:13 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1417624 [3/38] - in /tomcat/site/trunk/docs/tomcat-8.0-doc: ./ api/ appdev/ appdev/sample/ appdev/sample/docs/ appdev/sample/src/ appdev/sample/src/mypackage/ appdev/sample/web/ appdev/sample/web/WEB-INF/ appdev/sample/web/images/ architec... Date: Wed, 05 Dec 2012 20:21:01 -0000 To: dev@tomcat.apache.org From: rjung@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20121205202113.34B142388ABB@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html Wed Dec 5 20:20:35 2012 @@ -0,0 +1,327 @@ +Application Developer's Guide (8.0.0-dev) - Development Processes

+ The Apache Tomcat Servlet/JSP Container
+

Apache Tomcat 8

Version 8.0.0-dev, Dec 5 2012

Links

Contents

Development Processes

Table of Contents

+
Development Processes
One-Time Setup of Ant and Tomcat for Development
Create Project Source Code Directory
Edit Source Code and Pages
Build the Web Application
Test Your Web Application
Creating a Release
+

Development Processes

+ +
Although application development can take many forms, this manual proposes +a fairly generic process for creating web applications using Tomcat. The +following sections highlight the commands and tasks that you, as the developer +of the code, will perform. The same basic approach works when you have +multiple programmers involved, as long as you have an appropriate source code +control system and internal team rules about who is working on what parts +of the application at any given time.
+ +
The task descriptions below assume that you will be using CVS for source +code control, and that you have already configured access to the appropriate +CVS repository. Instructions for doing this are beyond the scope of this +manual. If you are using a different source code control environment, you +will need to figure out the corresponding commands for your system.
+ + +
One-Time Setup of Ant and Tomcat for Development
+ +
In order to take advantage of the special Ant tasks that interact with the +Manager web application, you need to perform the following tasks +once (no matter how many web applications you plan to develop).
+
+
Configure the Ant custom tasks. The implementation code for the + Ant custom tasks is in a JAR file named + $CATALINA_HOME/lib/catalina-ant.jar, which must be + copied in to the lib directory of your Ant installation. +

+
Define one or more Tomcat users. The Manager web + application runs under a security constraint that requires a user to be + logged in, and have the security role manager-script assigned + to him or her. How such users are defined depends on which Realm you have + configured in Tomcat's conf/server.xml file -- see the + Realm Configuration HOW-TO for more + information. You may define any number of users (with any username + and password that you like) with the manager-script role. +

+
+ +
+ + +
Create Project Source Code Directory
+ +
The first step is to create a new project source directory, and customize +the build.xml and build.properties files you will +be using. The directory structure is described in the +previous section, or you can use the +sample application as a starting point.
+ +
Create your project source directory, and define it within your CVS +repository. This might be done by a series of commands like this, where +{project} is the name under which your project should be +stored in the CVS repository, and {username} is your login username:
+
+cd {my home directory}
+mkdir myapp <-- Assumed "project source directory"
+cd myapp
+mkdir docs
+mkdir src
+mkdir web
+mkdir web/WEB-INF
+cvs import -m "Initial Project Creation" {project} \
+    {username} start
+
+ +
Now, to verify that it was created correctly in CVS, we will perform a +checkout of the new project:
+
+cd ..
+mv myapp myapp.bu
+cvs checkout {project}
+
+ +
Next, you will need to create and check in an initial version of the +build.xml script to be used for development. For getting +started quickly and easily, base your build.xml on the +basic build.xml file, included with this manual, +or code it from scratch.
+
+cd {my home directory}
+cd myapp
+emacs build.xml     <-- if you want a real editor :-)
+cvs add build.xml
+cvs commit
+
+ +
Until you perform the CVS commit, your changes are local to your own +development directory. Committing makes those changes visible to other +developers on your team that are sharing the same CVS repository.
+ +
The next step is to customize the Ant properties that are +named in the build.xml script. This is done by creating a +file named build.properties in your project's top-level +directory. The supported properties are listed in the comments inside +the sample build.xml script. At a minimum, you will generally +need to define the catalina.home property defining where +Tomcat is installed, and the manager application username and password. +You might end up with something like this:
+
+# Context path to install this application on
+app.path=/hello
+
+# Tomcat 7 installation directory
+catalina.home=/usr/local/apache-tomcat-7.0
+
+# Manager webapp username and password
+manager.username=myusername
+manager.password=mypassword
+
+ +
In general, you will not want to check the +build.properties file in to the CVS repository, because it +is unique to each developer's environment.
+ +
Now, create the initial version of the web application deployment +descriptor. You can base web.xml on the +basic web.xml file, or code it from scratch.
+
+cd {my home directory}
+cd myapp/web/WEB-INF
+emacs web.xml
+cvs add web.xml
+cvs commit
+
+ +Note that this is only an example web.xml file. The full definition +of the deployment descriptor file is in the +Servlet Specification. + +
+ + +
Edit Source Code and Pages
+ +
The edit/build/test tasks will generally be your most common activities +during development and maintenance. The following general principles apply. +As described in Source Organization, newly created +source files should be located in the appropriate subdirectory, under your +project source directory.
+ +
Whenever you wish to refresh your development directory to reflect the +work performed by other developers, you will ask CVS to do it for you:
+
+cd {my home directory}
+cd myapp
+cvs update -dP
+
+ +
To create a new file, go to the appropriate directory, create the file, +and register it with CVS. When you are satisfied with it's contents (after +building and testing is successful), commit the new file to the repository. +For example, to create a new JSP page:
+
+cd {my home directory}
+cd myapp/web        <-- Ultimate destination is document root
+emacs mypage.jsp
+cvs add mypage.jsp
+... build and test the application ...
+cvs commit
+
+ +
Java source code that is defined in packages must be organized in a +directory hierarchy (under the src/ subdirectory) that +matches the package names. For example, a Java class named +com.mycompany.mypackage.MyClass.java should be stored in file +src/com/mycompany/mypackage/MyClass.java. +Whenever you create a new subdirectory, don't forget to +register it with CVS.
+ +
To edit an existing source file, you will generally just start editing +and testing, then commit the changed file when everything works. Although +CVS can be configured to required you to "check out" or "lock" a file you +are going to be modifying, this is generally not used.
+ +
+ + +
Build the Web Application
+ +
When you are ready to compile the application, issue the following +commands (generally, you will want a shell window open that is set to +the project source directory, so that only the last command is needed):
+
+cd {my home directory}
+cd myapp        <-- Normally leave a window open here
+ant
+
+ +
The Ant tool will be execute the default "compile" target in your +build.xml file, which will compile any new or updated Java +code. If this is the first time you compile after a "build clean", +it will cause everything to be recompiled.
+ +
To force the recompilation of your entire application, do this instead:
+
+cd {my home directory}
+cd myapp
+ant all
+
+ +
This is a very good habit immediately before checking in changes, to +make sure that you have not introduced any subtle problems that Javac's +conditional checking did not catch.
+ +
+ + +
Test Your Web Application
+ +
To test your application, you will want to install it under Tomcat. The +quickest way to do that is to use the custom Ant tasks that are included in +the sample build.xml script. Using these commands might follow +a pattern like this:
+
+
Start Tomcat if needed. If Tomcat is not already running, + you will need to start it in the usual way. +

+
Compile your application. Use the ant compile + command (or just ant, since this is the default). Make + sure that there are no compilation errors. +

+
Install the application. Use the ant install + command. This tells Tomcat to immediately start running your app on + the context path defined in the app.path build property. + Tomcat does NOT have to be restarted for this to + take effect.

+
Test the application. Using your browser or other testing + tools, test the functionality of your application. +

+
Modify and rebuild as needed. As you discover that changes + are required, make those changes in the original source + files, not in the output build directory, and re-issue the + ant compile command. This ensures that your changes will + be available to be saved (via cvs commit) later on -- + the output build directory is deleted and recreated as necessary. +

+
Reload the application. Tomcat will recognize changes in + JSP pages automatically, but it will continue to use the old versions + of any servlet or JavaBean classes until the application is reloaded. + You can trigger this by executing the ant reload command. +

+
Remove the application when you re done. When you are through + working on this application, you can remove it from live execution by + running the ant remove command.
+
+ +
Do not forget to commit your changes to the source code repository when +you have completed your testing!
+ +
+ + +
Creating a Release
+ +
When you are through adding new functionality, and you've tested everything +(you DO test, don't you :-), it is time to create the distributable version +of your web application that can be deployed on the production server. The +following general steps are required:
+
+
Issue the command ant all from the project source + directory, to rebuild everything from scratch one last time. +

+
Use the cvs tag command to create an identifier for + all of the source files utilized to create this release. This allows + you to reliably reconstruct a release (from sources) at a later + time.
+
Issue the command ant dist to create a distributable + web application archive (WAR) file, as well as a JAR file containing + the corresponding source code. +

+
Package the contents of the dist directory using the + tar or zip utility, according to + the standard release procedures used by your organization.
+
+ +
+ + +

Comments

Notice: This is not a Q&A section. + The Apache Comments System is explained + here. + Comments should be pointed towards suggestions on improving the documentation + or server, and may be removed again by our moderators if they are either + implemented or considered invalid/off-topic. + Questions on how to manage Apache Tomcat should be directed + to our mailing lists.

\ No newline at end of file Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/processes.html ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml Wed Dec 5 20:20:35 2012 @@ -0,0 +1,514 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/build.xml ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt Wed Dec 5 20:20:35 2012 @@ -0,0 +1,17 @@ + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +This is a dummy README file for the sample +web application. Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/docs/README.txt ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html Wed Dec 5 20:20:35 2012 @@ -0,0 +1,46 @@ + + + + +Sample Application + + +

Sample Application

+ The example app has been packaged as a war file and can be downloaded + here (Note: make sure your browser doesn't + change file extension or append a new one). +

+ The easiest way to run this application is simply to move the war file + to your CATALINA_HOME/webapps directory. Tomcat will automatically + expand and deploy the application for you. You can view it with the + following URL (assuming that you're running tomcat on port 8080 + as is the default): +
+ http://localhost:8080/sample +

+ If you just want to browse the contents, you can unpack the war file + with the jar command. +

+        jar -xvf sample.war
+

+ + \ No newline at end of file Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/index.html ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/sample.war URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/sample.war?rev=1417624&view=auto ============================================================================== Binary file - no diff available. Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/sample.war ------------------------------------------------------------------------------ svn:mime-type = application/zip Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java Wed Dec 5 20:20:35 2012 @@ -0,0 +1,84 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package mypackage; + +import java.io.IOException; +import java.io.PrintWriter; + +import javax.servlet.ServletException; +import javax.servlet.http.HttpServlet; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; + + +/** + * Simple servlet to validate that the Hello, World example can + * execute servlets. In the web application deployment descriptor, + * this servlet must be mapped to correspond to the link in the + * "index.html" file. + * + * @author Craig R. McClanahan + */ + +public final class Hello extends HttpServlet { + + private static final long serialVersionUID = 1L; + + /** + * Respond to a GET request for the content produced by + * this servlet. + * + * @param request The servlet request we are processing + * @param response The servlet response we are producing + * + * @exception IOException if an input/output error occurs + * @exception ServletException if a servlet error occurs + */ + @Override + public void doGet(HttpServletRequest request, + HttpServletResponse response) + throws IOException, ServletException { + + response.setContentType("text/html"); + PrintWriter writer = response.getWriter(); + + writer.println(""); + writer.println(""); + writer.println("Sample Application Servlet Page"); + writer.println(""); + writer.println(""); + + writer.println(""); + writer.println(""); + writer.println(""); + writer.println(""); + writer.println(""); + writer.println("

"); + writer.println("

Sample Application Servlet

"); + writer.println("This is the output of a servlet that is part of"); + writer.println("the Hello, World application."); + writer.println("

"); + + writer.println(""); + writer.println(""); + + } + + +} Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/src/mypackage/Hello.java ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/WEB-INF/web.xml URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/WEB-INF/web.xml?rev=1417624&view=auto ============================================================================== Binary file - no diff available. Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/WEB-INF/web.xml ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/WEB-INF/web.xml ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/WEB-INF/web.xml ------------------------------------------------------------------------------ svn:mime-type = application/xml Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp Wed Dec 5 20:20:35 2012 @@ -0,0 +1,39 @@ + + + +Sample Application JSP Page + + + + + + + + +

+ +	+ Sample Application JSP Page +This is the output of a JSP page that is part of the Hello, World +application. +

+ +<%= new String("Hello!") %> + + + Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/hello.jsp ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/images/tomcat.gif URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/images/tomcat.gif?rev=1417624&view=auto ============================================================================== Binary file - no diff available. Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/images/tomcat.gif ------------------------------------------------------------------------------ svn:mime-type = image/gif Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html Wed Dec 5 20:20:35 2012 @@ -0,0 +1,44 @@ + + + +Sample "Hello, World" Application + + + + + + + + +

+ +	+ Sample "Hello, World" Application + This is the home page for a sample application used to illustrate the +source directory organization of a web application utilizing the principles +outlined in the Application Developer's Guide. +

+ +

To prove that they work, you can execute either of the following links:

To a JSP page.
To a servlet.

+ + + Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/sample/web/index.html ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html?rev=1417624&view=auto ============================================================================== --- tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html (added) +++ tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html Wed Dec 5 20:20:35 2012 @@ -0,0 +1,325 @@ +Application Developer's Guide (8.0.0-dev) - Source Organization

Apache Tomcat 8

Version 8.0.0-dev, Dec 5 2012

Links

Contents

Source Organization

Table of Contents

+
Directory Structure
External Dependencies
Source Code Control
BUILD.XML Configuration File
+

Directory Structure

+ +
+
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:
+
+
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. +

+
Source code control is easier to manage on directories that contain + only source files. +

+
The files that make up an installable distribution of your + application are much easier to select when the deployment + hierarchy is separate.
+
+ +
As we will see, the ant 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 build.xml configuration file that +is discussed below. All of these components exist under a top level +project source directory for your application:
+
+
docs/ - Documentation for your application, in whatever + format your development team is using.

+
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.

+
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.

+
web/WEB-INF/ - The special configuration files required + for your application, including the web application deployment descriptor + (web.xml, defined in the + Servlet Specification), + 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.
+
+ +
During the development process, two additional directories will be +created on a temporary basis:
+
+
build/ - When you execute a default build + (ant), 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 + $CATALINA_BASE/webapps directory, or by installing + it via the "Manager" web application. The latter approach is very + useful during development, and will be illustrated below. +

+
dist/ - When you execute the ant dist + 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.
+
+ +
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.
+ +
External Dependencies
+ +
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 build.xml 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 build.xml + 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 lib directory of Tomcat. + If this has been done, you need + to take no actions at all - the example build.xml file + automatically constructs a compile classpath that includes these files.
+ +
+ +

Source Code Control

+ +
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 build/ and dist/ 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 +.cvsignore (note the leading period) in your top-level source +directory, with the following contents:
+
+build
+dist
+build.properties
+
+ +
The reason for mentioning build.properties here will be +explained in the Processes 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:
+
+
To refresh the state of your source code to that stored in the + the source repository, go to your project source directory, and + execute cvs update -dP. +

+
When you create a new subdirectory in the source code hierarchy, register + it in CVS with a command like cvs add {subdirname}. +

+
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 + cvs add {filename}. +

+
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 cvs remove {filename}. +

+
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 cvs commit. 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.
+
+ +
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 Introduction for +more information.
+ +

BUILD.XML Configuration File

+ +
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 +build.xml, 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 build.xml 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 +build.xml 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 build.xml file and type:
+
+ant -projecthelp
+
+ +
To give you a head start, a basic build.xml file +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:
+
+
clean - This target deletes any existing + build and dist 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. +

+
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 WEB-INF/classes + subdirectory of your build 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 ant command will + execute it. +

+
all - This target is a short cut for running the + clean target, followed by the compile target. + Thus, it guarantees that you will recompile the entire application, to + ensure that you have not unknowingly introduced any incompatible changes. +

+
javadoc - This target creates Javadoc API documentation + for the Java classes in this web application. The example + build.xml file assumes you want to include the API + documentation with your app distribution, so it generates the docs + in a subdirectory of the dist directory. Because you normally + do not need to generate the Javadocs on every compilation, this target is + usually a dependency of the dist target, but not of the + compile target. +

+
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 deploy target, the + web application archive will have also picked up any external dependencies + that were included at deployment time.
+
+ +
For interactive development and testing of your web application using +Tomcat, the following additional targets are defined:
+
+
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. +

+
reload - Once the application is installed, you can + continue to make changes and recompile using the compile + 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. +

+
remove - When you have completed your development and + testing activities, you can optionally tell Tomcat to remove this + application from service. +
+
+ +
Using the development and testing targets requires some additional +one-time setup that is described on the next page.
+ +

Comments

Notice: This is not a Q&A section. + The Apache Comments System is explained + here. + Comments should be pointed towards suggestions on improving the documentation + or server, and may be removed again by our moderators if they are either + implemented or considered invalid/off-topic. + Questions on how to manage Apache Tomcat should be directed + to our mailing lists.

\ No newline at end of file Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/source.html ------------------------------------------------------------------------------ svn:keywords = Author Date Id Revision Added: tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/web.xml.txt URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/appdev/web.xml.txt?rev=1417624&view=auto ============================================================================== Binary file - no diff available. --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org For additional commands, e-mail: dev-help@tomcat.apache.org