<?xml version="1.0"?>
<doc title="Developer's Guide">
  <overview>
    <p>
      This document describes information developers will need in order to
      get started modifying and enhancing the application.
      Generally, you should follow these instructions in
      the order they appear in this document.
    </p>
  </overview>
  <toc/>
  <section title="Minimum Requirements" id="reqmts">
    <p>
      You must have all of the following installed and configured to interoperate:
    </p>
    <ul>
      <li><link dest="admin_guide.html#reqmts">All minimum requirements described in the Administrator's Guide</link></li>
      <li><link dest="http://java.sun.com/j2se/">Java 2 Standard Edition (J2SE) SDK (1.4.1 through 1.4.2_08)</link></li>
      <li><link dest="http://logging.apache.org/log4j/docs/">Apache Logging Log4J 1.2.8 (1.2.7 through 1.2.8)</link></li>
    </ul>
    <p>
      The following software is technically not required but is strongly
      recommended, since it will make your life much easier if you want to
      rebuild and test the application:
    </p>
    <ul>
      <li><link dest="http://jakarta.apache.org/ant/">Apache Ant 1.5 (1.5.1 through 1.6.3)</link></li>
      <li><link dest="http://jakarta.apache.org/cactus/">Apache Jakarta Cactus-13 (1.4.1 through 1.7)</link></li>
      <li><link dest="http://www.junit.org/">JUnit (3.8.1)</link></li>
    </ul>
    <p>
      The numbers in parentheses are the version numbers that this application has
      been tested with.
    </p>
  </section>

  <section title="Obtaining the Source Code" id="obtain">
    <p>
      There are two ways to obtain the source code from SourceForge:
      <ul>
        <li>
          You can
          <link dest="http://sourceforge.net/project/showfiles.php?group_id=34187">download a release archive file</link>,
          which will be more stable.
        </li>
        <li>
          You can
          <link dest="https://sourceforge.net/cvs/?group_id=34187">check out the module</link>
          (using Anonymous CVS),
          which will be more current.
        </li>
      </ul>
    </p>
    <p>
      If you downloaded a release, you will need to dearchive it using
      an appropriate utility.
      <link dest="http://www.7-zip.org/">7-Zip</link> is one such utility,
      and is also free, light-weight, and feature-rich.
    </p>
  </section>

  <section title="Configuring The Application" id="config">
    <p>
      After you have <link dest="#obtain">obtained the source code</link>
      you will need to configure the application for your environment:
    </p>
    <p>
      Rename the file <file>example-build.properties</file> to
      <file>build.properties</file>, and then adjust the values in
      that file as necessary for your environment.
    </p>
    <p>
      If you do not want to hard-code any of these properties
      into the file, you may instead specify them as environment
      variables, or on the command line when you run Ant.
      See the Ant documentation for more information.
    </p>
    <infobox label="Required Properties">
      The following properties are required:
      <map>
        <headings><key>Property</key><value>Description</value></headings>
        <mapping><key><ant_property>java.home</ant_property></key><value>The directory where the JDK is installed.</value></mapping>
        <mapping><key><ant_property>j2ee.home</ant_property></key><value>The directory where the J2EE SDK is installed.</value></mapping>
        <mapping><key><ant_property>jstl.home</ant_property></key><value>The directory where JSTL is installed.</value></mapping>
        <mapping><key><ant_property>cactus.home</ant_property></key><value>The directory where Apache Jakarta Cactus is installed.</value></mapping>
        <mapping><key><ant_property>log4j.jar</ant_property></key><value>The full path to the Log4J JAR file.</value></mapping>
      </map>
      The following properties are required only if you intend to use the
      database targets, which begin with "db-" (recommended):
      <map>
        <headings><key>Property</key><value>Description</value></headings>
        <mapping><key><ant_property>jdbc.driver.class</ant_property></key><value>The name of the JDBC driver class being used.</value></mapping>
        <mapping><key><ant_property>jdbc.driver.jar</ant_property></key><value>The path to the JAR file containing the JDBC driver class.</value></mapping>
        <mapping><key><ant_property>jdbc.dburl</ant_property></key><value>The JDBC URL that refers to the database server.</value></mapping>
        <mapping><key><ant_property>jdbc.dbname</ant_property></key><value>The name of the database on the database server.</value></mapping>
        <mapping><key><ant_property>jdbc.username</ant_property></key><value>The username to access the database.</value></mapping>
        <mapping><key><ant_property>jdbc.password</ant_property></key><value>The password associated with username.</value></mapping>
        <mapping><key><ant_property></ant_property></key><value></value></mapping>
      </map>
    </infobox>
    <infobox label="Optional Properties">
      The following properties are optional and may be useful:
      <map>
        <headings><key>Property</key><value>Description</value></headings>
        <mapping><key><ant_property>build.loc</ant_property></key><value>The directory where the application is built.  See the "Building in Unpacked Directory" section below. The default is "./build".</value></mapping>
        <mapping><key><ant_property>testsfile</ant_property></key><value>The name of a file that contains the names of tests to be run.  See the "Controlling Tests" section below.  The default is <i>undefined</i></value></mapping>
        <mapping><key><ant_property>project.shortname</ant_property></key><value>The name to use when building the WAR and Zip files. The default is "surjey".</value></mapping>
        <mapping><key><ant_property>jspc.verbosity</ant_property></key><value>The verboseness of the JSP compiler for the "jsp" target.  The format of this property should match that of the <code>verbose</code> attribute of the <code>jspc</code> Ant task.  See the documentation of that task for more information. The default is "0".</value></mapping>
      </map>
    </infobox>
    <infobox label="Building in Unpacked Directory">
      <p>
        If you are using an application server that supports
        auto-deployment using an unpacked directory hierarchy, you can
        speed/ease development by setting the
        <ant_property>build.loc</ant_property> property to the
        name of the folder where you want the unpacked directory deployed.
      </p>
      <p>
        For example, if you are using Tomcat, this would be:
        <indent><code>CATALINA_HOME/webapps/CONTEXT_PATH</code></indent>
        where <code>CATALINA_HOME</code> is the directory in which Tomcat
        is installed, and <code>CONTEXT_PATH</code> is the context path you
        want Tomcat to use for the application.
      </p>
    </infobox>
    <infobox label="Controlling Tests">
      During development, if you want to run only a subset of all the
      tests, you can use the <ant_property>testsfile</ant_property> to
      specify the name of a file that contains the names of the tests
      to be run.
      Each line of the file is interpreted as an include pattern, as
      described in the Ant documentation.
      <warnbox label="WARNING">
        If this property is specified, then only the tests named in the
        file will be executed.
      </warnbox>
    </infobox>
  </section>

  <section title="Preparing Your Environment" id="prep">
    <p>
      After you have <link dest="#config">configured the application</link>,
      you will need to prepare the database and application server.
      You can do so by following these steps:
    </p>
    <ol>
      <li class="spaced">
        Create the database, and populate it with some sample data.
        If you are using MySQL for your database, you can do this quickly and
        easily using <ant_cmd>db-init</ant_cmd>, or you can execute the SQL
        script <file>tools/db/init_database.sql</file>.
        If you are using a different database, you can customize the SQL scripts
        in the <file>tools/db</file> directory, or inspect them to determine how
        to create the tables manually.
      </li>
      <li class="spaced">
        <p>
          Configure your application server to add the database as a resource
          for the context of this application (or a wider context if you
          desire).
          The application expects to access the database using the
          resource named <code>jdbc/surjey</code> and expects it to be of
          type <code>javax.sql.DataSource</code>.
        </p>
        <p>
          The details of this configuration will vary from one application
          server to the next, and thus are beyond the scope of this document.
          Most likely this configuration will require stopping and restarting
          the application server (if it is already started).
        </p>
      </li>
    </ol>
  </section>

  <section title="Building the Application" id="build">
    <p>
      After you have <link dest="#prep">prepared your environment</link>,
      you must build the application before you deploy it the first
      time, and whenever you want to test any changes you have made.
    </p>
    <p>
      Building the application is very simple:
      Just use <ant_cmd>build</ant_cmd>.
      This will compile the source code, and place the application files
      into the <file>build</file> directory.
    </p>
  </section>

  <section title="Deploying the Application" id="deploy">
    <p>
      After <link dest="#build">building the application</link>,
      you will need to install/deploy it into your application server.
    </p>
    <p>
      Unfortunately, since there is no standard application
      deployment/installation mechanism (or even a specification),
      this process is different from one application server to the next.
    </p>
    <p>
      If you are using a application server that supports installation
      of an "unpacked directory hierarchy", and you configured the
      <ant_property>build.loc</ant_property> property (as described under
      <link dest="#config">Configuring the Application</link>),
      then the application files will already be updated/created when
      you built the application.
      However, you may need to notify the application server that the
      application exists or has changed, and this may require restarting
      the application, and possibly the application server.
      Refer to the documentation for your application server for more
      information.
    </p>
    <p>
      Otherwise, you can deploy the application by building the
      application WAR file using the Ant <ant_cmd>war</ant_cmd>,
      and then deploying the WAR file, <file>dist/surjey.war</file>,
      into your application server.
    </p>
  </section>

  <section title="Testing the Application" id="test">
    <p>
      After you have
      <link dest="#deploy">deployed</link>
      the application, you should run the
      tests, which use in-container testing with Cactus.
      If you attempt to run the tests prior to deployment, all
      of the tests will fail.
    </p>
    <p>
      Use <ant_cmd>test</ant_cmd> to run all the tests.
      The results are located at:
      <indent>
        <file>
          <link dest="./tests/report/index.html">doc/tests/report/index.html</link>
        </file>
      </indent>
      If the tests have been run you can use the link above to view the
      results.
    </p>
  </section>

  <section title="Modifying the Application" id="modify">
    <p>
      After you have succesfully
      <link dest="#test">tested the application</link>,
      you may want to get started modifying the
      application's source code.
    </p>
    <toc/>
    <section title="Source Directories" id="modify-dirs">
      <p>
        The following subdirectories are distributed with the application:
      </p>
      <filelist name="config">
        <desc>Configuration files for the application and test suites</desc>
      </filelist>
      <filelist name="web">
        <desc>Web files, including JSP, HTML, CSS, images, etc.</desc>
      </filelist>
      <filelist name="doc">
        <desc>Documentation</desc>
        <filelist name="src">
          <desc>Source code for user documentation</desc>
        </filelist>
      </filelist>
      <filelist name="src">
        <desc>Java source code of the application</desc>
      </filelist>
      <filelist name="testsrc">
        <desc>Java source code for testing</desc>
      </filelist>
      <filelist name="tools">
        <desc>Tools for development</desc>
        <filelist name="sql">
          <desc>SQL Database scripts</desc>
        </filelist>
        <filelist name="tomcat">
          <desc>Tomcat-specific configuration</desc>
        </filelist>
      </filelist>
    </section>

    <section title="Working Directories" id="modify-work-dirs">
      <p>
        The following "working" directories are created by various
        Ant targets (indicated in parentheses),
        and all of these can be removed with <ant_cmd>clean</ant_cmd>:
      </p>

      <filelist name="bin">
        <desc>Compiled Java Bytecode and associated config files (<ant_target>compile</ant_target>)</desc>
      </filelist>
      <filelist name="build">
        <desc>Application assembly area (<ant_target>build</ant_target>)</desc>
      </filelist>
      <filelist name="dist">
        <desc>Release assembly area (<ant_target>war</ant_target>, <ant_target>release</ant_target>)</desc>
      </filelist>
      <filelist name="doc">
        <desc>Documentation (<ant_target>doc, userdoc</ant_target>)</desc>
        <filelist name="javadoc">
          <desc>Javadoc API documentation (<ant_target>doc, javadoc</ant_target>)</desc>
        </filelist>
        <filelist name="test">
          <desc>Output from tests (<ant_target>test</ant_target>)</desc>
          <filelist name="results">
            <desc>Data from tests</desc>
          </filelist>
        </filelist>
      </filelist>
    </section>

    <section title="Source Code" id="modify-source">
      <ul>
        <li><link dest="javadoc/index.html">Source Code Documentation (Javadoc)</link></li>
        <li><link dest="../src/">Browse Source Code</link></li>
      </ul>
    </section>

    <section title="Rebuilding the Application" id="modify-rebuild">
      <p>
        Once you are finished with modifications, you should
        rebuild the application by following the instructions in
        <link dest="#build">Building the Application</link>.
        Note that if your application is deployed, you may have to direct the
        application server to reload it.
        Some older servers may have to be restarted.
      </p>
    </section>
  </section>

  <section title="Rebuilding the Documentation" id="doc">
    <p>
      The user and source code documentation is regenerated when
      <ant_cmd>doc</ant_cmd> is executed.
    </p>
  </section>

  <section title="Creating a Release" id="release">
    <p>
      At some point after making <link dest="#modify">modifications</link>
      and <link dest="#test">testing them</link>, you may want to create a
      new release the application for widespread use.
    </p>
    <ol>
      <li>
        Update the <ant_property>release.version</ant_property> property in
        the <file>project.properties</file> file.
        If you are part of the development team working on this application,
        you should commit that changed file to the CVS repository to ensure
        that all releases are synchronized.
        This version number is used in the generated documentation and in
        the release file name.
      </li>
      <li>
        Use <ant_cmd>release</ant_cmd> to create the new release.
        The Zip file created will be located in the <file>dist</file>
        directory.
      </li>
    </ol>
  </section>

  <section title="Cleaning Up" id="clean">
    <p>
      You should clean up any time you intend to stop working on a project
      for some time, as you will not need the files in the working directories.
      Note that all files in the working directories can be regenerated, so
      there is never any danger in losing work by cleaning.
    </p>
    <p>
      Use <ant_cmd>clean</ant_cmd> to clean up the working
      directories (listed above).
    </p>
  </section>

  <section title="Summary of Ant Targets" id="targets">
    <p>
      Here are all the Ant targets available in the build file provided:
    </p>
    <map>
      <headings><key>Target</key><value>Description</value><value>Dependencies</value></headings>
      <mapping><key><ant_target>compile</ant_target></key><value>Compile the source code</value><value>N/A</value></mapping>
      <mapping><key><ant_target>build  </ant_target></key><value>Assemble the Web Application (default target)</value><value><ant_target>compile</ant_target></value></mapping>
      <mapping><key><ant_target>test   </ant_target></key><value>Compile and run all tests</value><value><ant_target>build</ant_target></value></mapping>
      <mapping><key><ant_target>doc    </ant_target></key><value>Build all documentation</value><value><ant_target>userdoc</ant_target>,<ant_target>javadoc</ant_target></value></mapping>
      <mapping><key><ant_target>userdoc</ant_target></key><value>Build only the user documentation</value><value>N/A</value></mapping>
      <mapping><key><ant_target>javadoc</ant_target></key><value>Build only the API documentation</value><value>N/A</value></mapping>
      <mapping><key><ant_target>jsp    </ant_target></key><value>Compile JSP pages into the build</value><value><ant_target>build</ant_target></value></mapping>
      <mapping><key><ant_target>war    </ant_target></key><value>Assemble the WAR file</value><value><ant_target>build</ant_target></value></mapping>
      <mapping><key><ant_target>release</ant_target></key><value>Create project distribution</value><value><ant_target>war</ant_target>,<ant_target>doc</ant_target></value></mapping>
      <mapping><key><ant_target>clean  </ant_target></key><value>Clean up working directories</value><value>N/A</value></mapping>
    </map>
    <p>Ant targets for database management:</p>
    <map>
      <headings><key>Target</key><value>Description</value><value>Dependencies</value></headings>
      <mapping><key><ant_target>db-init    </ant_target></key><value>Create database and load with sample data</value><value><ant_target>db-create</ant_target>, <ant_target>db-load-tables</ant_target></value></mapping>
      <mapping><key><ant_target>db-reinit  </ant_target></key><value>Remove and recreate tables, and reload with sample data</value><value><ant_target>db-recreate</ant_target>, <ant_target>db-load-tables</ant_target></value></mapping>
      <mapping><key><ant_target>db-create  </ant_target></key><value>Create database with empty tables</value><value><ant_target>db-create-database</ant_target>, <ant_target>db-create-tables</ant_target></value></mapping>
      <mapping><key><ant_target>db-recreate</ant_target></key><value>Remove and recreate tables</value><value><ant_target>db-remove-tables</ant_target>, <ant_target>db-create-tables</ant_target></value></mapping>
      <mapping><key><ant_target>db-remove  </ant_target></key><value>Remove tables and database</value><value><ant_target>db-remove-tables</ant_target>, <ant_target>db-remove-database</ant_target></value></mapping>
      <mapping><key><ant_target>db-create-database</ant_target></key><value>Create database</value><value><file>tools/db/create_database.sql</file></value></mapping>
      <mapping><key><ant_target>db-create-tables  </ant_target></key><value>Create tables</value><value><file>tools/db/create_tables.sql</file></value></mapping>
      <mapping><key><ant_target>db-load-tables    </ant_target></key><value>Load tables with sample data</value><value><file>tools/db/load_tables.sql</file></value></mapping>
      <mapping><key><ant_target>db-remove-tables  </ant_target></key><value>Remove tables</value><value><file>tools/db/remove_tables.sql</file></value></mapping>
      <mapping><key><ant_target>db-remove-database</ant_target></key><value>Remove database</value><value><file>tools/db/remove_database.sql</file></value></mapping>
    </map>
  </section>

  <section title="License and Copyright Information" id="license">
    <p>
      <copyright/>
    </p>
    <p>
      This program is free software; you can redistribute it and/or modify
      it under the terms of the <link dest="license.txt">GNU General Public License</link> as published by
      the Free Software Foundation; either version 2 of the License, or
      (at your option) any later version.
    </p>
    <p>
      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      <link dest="license.txt">GNU General Public License</link> for more details.
    </p>
  </section>

</doc>
