webapps/docs/appdev/processes.xml - tomcat80 - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   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.
 -->
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="processes.html">

   &project;

   <properties>
     <author email="craigmcc@apache.org">Craig R. McClanahan</author>
     <title>Development Processes</title>
   </properties>

 <body>

 <section name="Table of Contents">
 <toc/>
 </section>

 <section name="Development Processes">

 <p>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.</p>

 <p>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.</p>


 <subsection name="One-Time Setup of Ant and Tomcat for Development">

 <p>In order to take advantage of the special Ant tasks that interact with the
 <em>Manager</em> web application, you need to perform the following tasks
 once (no matter how many web applications you plan to develop).</p>
 <ul>
 <li><p><em>Configure the Ant custom tasks</em>.  The implementation code for the
     Ant custom tasks is in a JAR file named
     <code>$CATALINA_HOME/lib/catalina-ant.jar</code>, which must be
     copied in to the <code>lib</code> directory of your Ant installation.
     </p></li>
 <li><p><em>Define one or more Tomcat users</em>.  The <em>Manager</em> web
     application runs under a security constraint that requires a user to be
     logged in, and have the security role <code>manager-script</code> assigned
     to him or her.  How such users are defined depends on which Realm you have
     configured in Tomcat's <code>conf/server.xml</code> file -- see the
     <a href="../realm-howto.html">Realm Configuration HOW-TO</a> for more
     information.  You may define any number of users (with any username
     and password that you like) with the <code>manager-script</code> role.
     </p></li>
 </ul>

 </subsection>


 <subsection name="Create Project Source Code Directory">

 <p>The first step is to create a new project source directory, and customize
 the <code>build.xml</code> and <code>build.properties</code> files you will
 be using.  The directory structure is described in <a href="source.html">the
 previous section</a>, or you can use the
 <a href="sample/">sample application</a> as a starting point.</p>

 <p>Create your project source directory, and define it within your CVS
 repository.  This might be done by a series of commands like this, where
 <code>{project}</code> is the name under which your project should be
 stored in the CVS repository, and {username} is your login username:</p>
 <source><![CDATA[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]]></source>

 <p>Now, to verify that it was created correctly in CVS, we will perform a
 checkout of the new project:</p>
 <source><![CDATA[cd ..
 mv myapp myapp.bu
 cvs checkout {project}]]></source>

 <p>Next, you will need to create and check in an initial version of the
 <code>build.xml</code> script to be used for development.  For getting
 started quickly and easily, base your <code>build.xml</code> on the
 <a href="build.xml.txt">basic build.xml file</a>, included with this manual,
 or code it from scratch.</p>
 <source><![CDATA[cd {my home directory}
 cd myapp
 emacs build.xml     <-- if you want a real editor :-)
 cvs add build.xml
 cvs commit]]></source>

 <p>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.</p>

 <p>The next step is to customize the Ant <em>properties</em> that are
 named in the <code>build.xml</code> script.  This is done by creating a
 file named <code>build.properties</code> in your project's top-level
 directory.  The supported properties are listed in the comments inside
 the sample <code>build.xml</code> script.  At a minimum, you will generally
 need to define the <code>catalina.home</code> property defining where
 Tomcat is installed, and the manager application username and password.
 You might end up with something like this:</p>
 <source><![CDATA[# Context path to install this application on
 app.path=/hello

 # Tomcat installation directory
 catalina.home=/usr/local/apache-tomcat-<version-major-minor/>

 # Manager webapp username and password
 manager.username=myusername
 manager.password=mypassword]]></source>

 <p>In general, you will <strong>not</strong> want to check the
 <code>build.properties</code> file in to the CVS repository, because it
 is unique to each developer's environment.</p>

 <p>Now, create the initial version of the web application deployment
 descriptor.  You can base <code>web.xml</code> on the
 <a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
 <source><![CDATA[cd {my home directory}
 cd myapp/web/WEB-INF
 emacs web.xml
 cvs add web.xml
 cvs commit]]></source>

 Note that this is only an example web.xml file.  The full definition
 of the deployment descriptor file is in the
 <a href="http://wiki.apache.org/tomcat/Specifications">Servlet Specification.</a>

 </subsection>


 <subsection name="Edit Source Code and Pages">

 <p>The edit/build/test tasks will generally be your most common activities
 during development and maintenance.  The following general principles apply.
 As described in <a href="source.html">Source Organization</a>, newly created
 source files should be located in the appropriate subdirectory, under your
 project source directory.</p>

 <p>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:</p>
 <source><![CDATA[cd {my home directory}
 cd myapp
 cvs update -dP]]></source>

 <p>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:</p>
 <source><![CDATA[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]]></source>

 <p>Java source code that is defined in packages must be organized in a
 directory hierarchy (under the <strong>src/</strong> subdirectory) that
 matches the package names.  For example, a Java class named
 <code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
 <code>src/com/mycompany/mypackage/MyClass.java</code>.
 Whenever you create a new subdirectory, don't forget to
 register it with CVS.</p>

 <p>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.</p>

 </subsection>


 <subsection name="Build the Web Application">

 <p>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):</p>
 <source><![CDATA[cd {my home directory}
 cd myapp        <-- Normally leave a window open here
 ant]]></source>

 <p>The Ant tool will be execute the default "compile" target in your
 <code>build.xml</code> 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.</p>

 <p>To force the recompilation of your entire application, do this instead:</p>
 <source><![CDATA[cd {my home directory}
 cd myapp
 ant all]]></source>

 <p>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.</p>

 </subsection>


 <subsection name="Test Your Web Application">

 <p>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 <code>build.xml</code> script.  Using these commands might follow
 a pattern like this:</p>
 <ul>
 <li><p><em>Start Tomcat if needed</em>.  If Tomcat is not already running,
     you will need to start it in the usual way.
     </p></li>
 <li><p><em>Compile your application</em>.  Use the <code>ant compile</code>
     command (or just <code>ant</code>, since this is the default).  Make
     sure that there are no compilation errors.
     </p></li>
 <li><p><em>Install the application</em>.  Use the <code>ant install</code>
     command.  This tells Tomcat to immediately start running your app on
     the context path defined in the <code>app.path</code> build property.
     Tomcat does <strong>NOT</strong> have to be restarted for this to
     take effect.
     </p></li>
 <li><p><em>Test the application</em>.  Using your browser or other testing
     tools, test the functionality of your application.
     </p></li>
 <li><p><em>Modify and rebuild as needed</em>.  As you discover that changes
     are required, make those changes in the original <strong>source</strong>
     files, not in the output build directory, and re-issue the
     <code>ant compile</code> command.  This ensures that your changes will
     be available to be saved (via <code>cvs commit</code>) later on --
     the output build directory is deleted and recreated as necessary.
     </p></li>
 <li><p><em>Reload the application</em>.  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 <code>ant reload</code> command.
     </p></li>
 <li><p><em>Remove the application when you are done</em>.  When you are through
     working on this application, you can remove it from live execution by
     running the <code>ant remove</code> command.
     </p></li>
 </ul>

 <p>Do not forget to commit your changes to the source code repository when
 you have completed your testing!</p>

 </subsection>


 <subsection name="Creating a Release">

 <p>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:</p>
 <ul>
 <li><p>Issue the command <code>ant all</code> from the project source
     directory, to rebuild everything from scratch one last time.
     </p></li>
 <li><p>Use the <code>cvs tag</code> 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.
     </p></li>
 <li><p>Issue the command <code>ant dist</code> to create a distributable
     web application archive (WAR) file, as well as a JAR file containing
     the corresponding source code.
     </p></li>
 <li><p>Package the contents of the <code>dist</code> directory using the
     <strong>tar</strong> or <strong>zip</strong> utility, according to
     the standard release procedures used by your organization.
     </p></li>
 </ul>

 </subsection>


 </section>

 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	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.
	-->
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="processes.html">

	&project;

	<properties>
	<author email="craigmcc@apache.org">Craig R. McClanahan</author>
	<title>Development Processes</title>
	</properties>

	<body>

	<section name="Table of Contents">
	<toc/>
	</section>

	<section name="Development Processes">

	<p>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.</p>

	<p>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.</p>


	<subsection name="One-Time Setup of Ant and Tomcat for Development">

	<p>In order to take advantage of the special Ant tasks that interact with the
	<em>Manager</em> web application, you need to perform the following tasks
	once (no matter how many web applications you plan to develop).</p>
	<ul>
	<li><p><em>Configure the Ant custom tasks</em>. The implementation code for the
	Ant custom tasks is in a JAR file named
	<code>$CATALINA_HOME/lib/catalina-ant.jar</code>, which must be
	copied in to the <code>lib</code> directory of your Ant installation.
	</p></li>
	<li><p><em>Define one or more Tomcat users</em>. The <em>Manager</em> web
	application runs under a security constraint that requires a user to be
	logged in, and have the security role <code>manager-script</code> assigned
	to him or her. How such users are defined depends on which Realm you have
	configured in Tomcat's <code>conf/server.xml</code> file -- see the
	<a href="../realm-howto.html">Realm Configuration HOW-TO</a> for more
	information. You may define any number of users (with any username
	and password that you like) with the <code>manager-script</code> role.
	</p></li>
	</ul>

	</subsection>


	<subsection name="Create Project Source Code Directory">

	<p>The first step is to create a new project source directory, and customize
	the <code>build.xml</code> and <code>build.properties</code> files you will
	be using. The directory structure is described in <a href="source.html">the
	previous section</a>, or you can use the
	<a href="sample/">sample application</a> as a starting point.</p>

	<p>Create your project source directory, and define it within your CVS
	repository. This might be done by a series of commands like this, where
	<code>{project}</code> is the name under which your project should be
	stored in the CVS repository, and {username} is your login username:</p>
	<source><![CDATA[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]]></source>

	<p>Now, to verify that it was created correctly in CVS, we will perform a
	checkout of the new project:</p>
	<source><![CDATA[cd ..
	mv myapp myapp.bu
	cvs checkout {project}]]></source>

	<p>Next, you will need to create and check in an initial version of the
	<code>build.xml</code> script to be used for development. For getting
	started quickly and easily, base your <code>build.xml</code> on the
	<a href="build.xml.txt">basic build.xml file</a>, included with this manual,
	or code it from scratch.</p>
	<source><![CDATA[cd {my home directory}
	cd myapp
	emacs build.xml <-- if you want a real editor :-)
	cvs add build.xml
	cvs commit]]></source>

	<p>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.</p>

	<p>The next step is to customize the Ant <em>properties</em> that are
	named in the <code>build.xml</code> script. This is done by creating a
	file named <code>build.properties</code> in your project's top-level
	directory. The supported properties are listed in the comments inside
	the sample <code>build.xml</code> script. At a minimum, you will generally
	need to define the <code>catalina.home</code> property defining where
	Tomcat is installed, and the manager application username and password.
	You might end up with something like this:</p>
	<source><![CDATA[# Context path to install this application on
	app.path=/hello

	# Tomcat installation directory
	catalina.home=/usr/local/apache-tomcat-<version-major-minor/>

	# Manager webapp username and password
	manager.username=myusername
	manager.password=mypassword]]></source>

	<p>In general, you will <strong>not</strong> want to check the
	<code>build.properties</code> file in to the CVS repository, because it
	is unique to each developer's environment.</p>

	<p>Now, create the initial version of the web application deployment
	descriptor. You can base <code>web.xml</code> on the
	<a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
	<source><![CDATA[cd {my home directory}
	cd myapp/web/WEB-INF
	emacs web.xml
	cvs add web.xml
	cvs commit]]></source>

	Note that this is only an example web.xml file. The full definition
	of the deployment descriptor file is in the
	<a href="http://wiki.apache.org/tomcat/Specifications">Servlet Specification.</a>

	</subsection>


	<subsection name="Edit Source Code and Pages">

	<p>The edit/build/test tasks will generally be your most common activities
	during development and maintenance. The following general principles apply.
	As described in <a href="source.html">Source Organization</a>, newly created
	source files should be located in the appropriate subdirectory, under your
	project source directory.</p>

	<p>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:</p>
	<source><![CDATA[cd {my home directory}
	cd myapp
	cvs update -dP]]></source>

	<p>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:</p>
	<source><![CDATA[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]]></source>

	<p>Java source code that is defined in packages must be organized in a
	directory hierarchy (under the <strong>src/</strong> subdirectory) that
	matches the package names. For example, a Java class named
	<code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
	<code>src/com/mycompany/mypackage/MyClass.java</code>.
	Whenever you create a new subdirectory, don't forget to
	register it with CVS.</p>

	<p>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.</p>

	</subsection>


	<subsection name="Build the Web Application">

	<p>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):</p>
	<source><![CDATA[cd {my home directory}
	cd myapp <-- Normally leave a window open here
	ant]]></source>

	<p>The Ant tool will be execute the default "compile" target in your
	<code>build.xml</code> 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.</p>

	<p>To force the recompilation of your entire application, do this instead:</p>
	<source><![CDATA[cd {my home directory}
	cd myapp
	ant all]]></source>

	<p>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.</p>

	</subsection>


	<subsection name="Test Your Web Application">

	<p>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 <code>build.xml</code> script. Using these commands might follow
	a pattern like this:</p>
	<ul>
	<li><p><em>Start Tomcat if needed</em>. If Tomcat is not already running,
	you will need to start it in the usual way.
	</p></li>
	<li><p><em>Compile your application</em>. Use the <code>ant compile</code>
	command (or just <code>ant</code>, since this is the default). Make
	sure that there are no compilation errors.
	</p></li>
	<li><p><em>Install the application</em>. Use the <code>ant install</code>
	command. This tells Tomcat to immediately start running your app on
	the context path defined in the <code>app.path</code> build property.
	Tomcat does <strong>NOT</strong> have to be restarted for this to
	take effect.
	</p></li>
	<li><p><em>Test the application</em>. Using your browser or other testing
	tools, test the functionality of your application.
	</p></li>
	<li><p><em>Modify and rebuild as needed</em>. As you discover that changes
	are required, make those changes in the original <strong>source</strong>
	files, not in the output build directory, and re-issue the
	<code>ant compile</code> command. This ensures that your changes will
	be available to be saved (via <code>cvs commit</code>) later on --
	the output build directory is deleted and recreated as necessary.
	</p></li>
	<li><p><em>Reload the application</em>. 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 <code>ant reload</code> command.
	</p></li>
	<li><p><em>Remove the application when you are done</em>. When you are through
	working on this application, you can remove it from live execution by
	running the <code>ant remove</code> command.
	</p></li>
	</ul>

	<p>Do not forget to commit your changes to the source code repository when
	you have completed your testing!</p>

	</subsection>


	<subsection name="Creating a Release">

	<p>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:</p>
	<ul>
	<li><p>Issue the command <code>ant all</code> from the project source
	directory, to rebuild everything from scratch one last time.
	</p></li>
	<li><p>Use the <code>cvs tag</code> 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.
	</p></li>
	<li><p>Issue the command <code>ant dist</code> to create a distributable
	web application archive (WAR) file, as well as a JAR file containing
	the corresponding source code.
	</p></li>
	<li><p>Package the contents of the <code>dist</code> directory using the
	<strong>tar</strong> or <strong>zip</strong> utility, according to
	the standard release procedures used by your organization.
	</p></li>
	</ul>

	</subsection>


	</section>

	</body>
	</document>