| <?xml version="1.0"?> |
| <!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="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><em>Configure the Ant custom tasks</em>. The implementation code for the |
| Ant custom tasks is in a JAR file named |
| <code>$CATALINA_HOME/server/lib/catalina-ant.jar</code>, which must be |
| copied in to the <code>lib</code> directory of your Ant installation. |
| <br/><br/></li> |
| <li><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</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</code> role. |
| <br/><br/></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> |
| 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> |
| 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> |
| 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 5 is installed, and the manager application username and password. |
| You might end up with something like this:</p> |
| <source> |
| # Context path to install this application on |
| app.path=/hello |
| |
| # Tomcat 5 installation directory |
| catalina.home=/usr/local/apache-tomcat-5.5 |
| |
| # 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> |
| 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://java.sun.com/products/servlet">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> |
| 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> |
| 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> |
| 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> |
| 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><em>Start Tomcat 5 if needed</em>. If Tomcat 5 is not already running, |
| you will need to start it in the usual way. |
| <br/><br/></li> |
| <li><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. |
| <br/><br/></li> |
| <li><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.<br/><br/></li> |
| <li><em>Test the application</em>. Using your browser or other testing |
| tools, test the functionality of your application. |
| <br/><br/></li> |
| <li><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. |
| <br/><br/></li> |
| <li><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. |
| <br/><br/></li> |
| <li><em>Remove the application when you re 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.</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>Issue the command <code>ant all</code> from the project source |
| directory, to rebuild everything from scratch one last time. |
| <br/><br/></li> |
| <li>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.</li> |
| <li>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. |
| <br/><br/></li> |
| <li>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.</li> |
| </ul> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| </body> |
| </document> |