Surjey is a Web application for survey management. Currently, Surjey supports the ability for any user to create new surveys and edit existing ones, and to select, complete and submit a survey. Future revisions will support response summarization and collation, authentication of specific users for survey administration, and capture of user contact information.

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.

You must have all of the following installed and configured to interoperate:

• All minimum requirements described in the Administrator's Guide
• Java 2 Standard Edition (J2SE) SDK (1.4.1 through 1.4.2_08)
• Apache Logging Log4J 1.2.8 (1.2.7 through 1.2.8)

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:

• Apache Ant 1.5 (1.5.1 through 1.6.3)
• Apache Jakarta Cactus-13 (1.4.1 through 1.7)
• JUnit (3.8.1)

The numbers in parentheses are the version numbers that this application has been tested with.

There are two ways to obtain the source code from SourceForge:

• You can download a release archive file, which will be more stable.
• You can check out the module (using Anonymous CVS), which will be more current.

If you downloaded a release, you will need to dearchive it using an appropriate utility. 7-Zip is one such utility, and is also free, light-weight, and feature-rich.

After you have obtained the source code you will need to configure the application for your environment:

Rename the file example-build.properties to build.properties, and then adjust the values in that file as necessary for your environment.

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.

After you have configured the application, you will need to prepare the database and application server. You can do so by following these steps:

1. 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 the Ant db-init target, or you can execute the SQL script tools/db/init_database.sql. If you are using a different database, you can customize the SQL scripts in the tools/db directory, or inspect them to determine how to create the tables manually.

2. 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 jdbc/surjey and expects it to be of type javax.sql.DataSource.

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

After you have prepared your environment, you must build the application before you deploy it the first time, and whenever you want to test any changes you have made.

Building the application is very simple: Just use the Ant build target. This will compile the source code, and place the application files into the build directory.

After building the application, you will need to install/deploy it into your application server.

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.

If you are using a application server that supports installation of an "unpacked directory hierarchy", and you configured the build.loc property (as described under Configuring the Application), 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.

Otherwise, you can deploy the application by building the application WAR file using the Ant the Ant war target, and then deploying the WAR file, dist/surjey.war, into your application server.

After you have deployed 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.

Use the Ant test target to run all the tests. The results are located at:

doc/tests/report/index.html

If the tests have been run you can use the link above to view the results.

After you have succesfully tested the application, you may want to get started modifying the application's source code.

The following subdirectories are distributed with the application:

• config - Configuration files for the application and test suites

• web - Web files, including JSP, HTML, CSS, images, etc.

• doc - Documentation
  • src - Source code for user documentation

• src - Java source code of the application

• testsrc - Java source code for testing

• tools - Tools for development
  • sql - SQL Database scripts
  • tomcat - Tomcat-specific configuration

The following "working" directories are created by various Ant targets (indicated in parentheses), and all of these can be removed with the Ant clean target:

• bin - Compiled Java Bytecode and associated config files (compile)

• build - Application assembly area (build)

• dist - Release assembly area (war, release)

• doc - Documentation (doc, userdoc)
  • javadoc - Javadoc API documentation (doc, javadoc)
  • test - Output from tests (test)
    • results - Data from tests

• Source Code Documentation (Javadoc)
• Browse Source Code

Once you are finished with modifications, you should rebuild the application by following the instructions in Building the Application. 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.

The user and source code documentation is regenerated when the Ant doc target is executed.

At some point after making modifications and testing them, you may want to create a new release the application for widespread use.

1. Update the release.version property in the project.properties 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.
2. Use the Ant release target to create the new release. The Zip file created will be located in the dist directory.

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.

Use the Ant clean target to clean up the working directories (listed above).

Here are all the Ant targets available in the build file provided:

Target	Description	Dependencies
compile	Compile the source code	N/A
build	Assemble the Web Application (default target)	compile
test	Compile and run all tests	build
doc	Build all documentation	userdoc,javadoc
userdoc	Build only the user documentation	N/A
javadoc	Build only the API documentation	N/A
jsp	Compile JSP pages into the build	build
war	Assemble the WAR file	build
release	Create project distribution	war,doc
clean	Clean up working directories	N/A

Ant targets for database management:

Target	Description	Dependencies
db-init	Create database and load with sample data	db-create, db-load-tables
db-reinit	Remove and recreate tables, and reload with sample data	db-recreate, db-load-tables
db-create	Create database with empty tables	db-create-database, db-create-tables
db-recreate	Remove and recreate tables	db-remove-tables, db-create-tables
db-remove	Remove tables and database	db-remove-tables, db-remove-database
db-create-database	Create database	tools/db/create_database.sql
db-create-tables	Create tables	tools/db/create_tables.sql
db-load-tables	Load tables with sample data	tools/db/load_tables.sql
db-remove-tables	Remove tables	tools/db/remove_tables.sql
db-remove-database	Remove database	tools/db/remove_database.sql

All files provided with this application are
© 2004-5, Casey Heckman and Bennett Yates. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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 GNU General Public License for more details.