Surjey 0.3.1 Developer's Guide Overview top of document 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. Contents top of document Minimum Requirements Obtaining the Source Code Configuring The Application Preparing Your Environment Building the Application Deploying the Application Testing the Application Modifying the Application Rebuilding the Documentation Creating a Release Cleaning Up Summary of Ant Targets License and Copyright Information Minimum Requirements top of 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. Obtaining the Source Code top of document 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. Configuring The Application top of document 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. Required Properties The following properties are required:
Property | Description
--- | ---
java.home | The directory where the JDK is installed.
j2ee.home | The directory where the J2EE SDK is installed.
jstl.home | The directory where JSTL is installed.
cactus.home | The directory where Apache Jakarta Cactus is installed.
log4j.jar | The full path to the Log4J JAR file.
The following properties are required only if you intend to use the database targets, which begin with "db-" (recommended):
Property | Description
--- | ---
jdbc.driver.class | The name of the JDBC driver class being used.
jdbc.driver.jar | The path to the JAR file containing the JDBC driver class.
jdbc.dburl | The JDBC URL that refers to the database server.
jdbc.dbname | The name of the database on the database server.
jdbc.username | The username to access the database.
jdbc.password | The password associated with username.
Optional Properties The following properties are optional and may be useful:
Property | Description
--- | ---
build.loc | The directory where the application is built. See the "Building in Unpacked Directory" section below. The default is "./build".
testsfile | The name of a file that contains the names of tests to be run. See the "Controlling Tests" section below. The default is undefined
project.shortname | The name to use when building the WAR and Zip files. The default is "surjey".
jspc.verbosity | The verboseness of the JSP compiler for the "jsp" target. The format of this property should match that of the `verbose` attribute of the `jspc` Ant task. See the documentation of that task for more information. The default is "0".
Building in Unpacked Directory If you are using an application server that supports auto-deployment using an unpacked directory hierarchy, you can speed/ease development by setting the build.loc property to the name of the folder where you want the unpacked directory deployed. For example, if you are using Tomcat, this would be: `CATALINA_HOME/webapps/CONTEXT_PATH` where `CATALINA_HOME` is the directory in which Tomcat is installed, and `CONTEXT_PATH` is the context path you want Tomcat to use for the application. Controlling Tests During development, if you want to run only a subset of all the tests, you can use the testsfile 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. WARNING If this property is specified, then only the tests named in the file will be executed. Preparing Your Environment top of document After you have configured the application, you will need to prepare the database and application server. You can do so by following these steps: 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. 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). Building the Application top of document 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. Deploying the Application top of document 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. Testing the Application top of document 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. Modifying the Application top of document After you have succesfully tested the application, you may want to get started modifying the application's source code. Contents Source Directories Working Directories Source Code Rebuilding the Application Source Directories 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 Working Directories 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 Source Code Documentation (Javadoc) Browse Source Code Rebuilding the Application 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. Rebuilding the Documentation top of document The user and source code documentation is regenerated when the Ant doc target is executed. Creating a Release top of document At some point after making modifications and testing them, you may want to create a new release the application for widespread use. 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. Use the Ant release target to create the new release. The Zip file created will be located in the dist directory. Cleaning Up top of document 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). Summary of Ant Targets top of document 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
License and Copyright Information top of document 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. © 2004-5, Casey Heckman and Bennett Yates. All rights reserved.