Introduction For Developers

Introduction
Eclipse
Build the application
Installing
License
JavaDocs

Introduction

Before you start working on the Web Survey Toolbox, you must follow the directions on this page to set up the project. It will help you set up your development environment, build the code base, and install the survey manager for the first time.

If you want to be a developer, you should:

1. Join SourceForge
2. Contact Aaron Powers and request to be added to the Web Survey Toolbox project
3. Read through the directions on this page to help you get started, checking out the code and setting up your development environment.

If you have any trouble with these directions or figuring anything else out, feel free to ask Aaron Powers for help or clarifications.

IDEs
We use multiple IDEs. We use and recommend Eclipse for most coding work, but it's not your only option. We simultaneously use NetBeans Matisse, the new GUI builder tool in NetBeans 5.0, for our recent GUIs.

Eclipse
We recommend using Eclipse (at least version 3.1) as your IDE, though it's not required (you'll have to do more work, though). If you use Eclipse, it's easy to set up your project and keep the code in the recommended format.

1. Go to the menu: File -> New -> Project.
2. Choose "CVS" -> "Checkout Project From CVS".  Follow the Wizard and use the CVS information you can get from the SourceForge project. For more details on how to check out the project from CVS with Eclipse, click here.
3. When you've checked out the project, set up the standard code formatting so that you'll use the same code style as the rest of the project members. Go to "Window" -> "Preferences" -> "Java" -> "Code Style".
   1. From there, go to "Code Formatter" and import the XML settings file in your project to format code, "jspsurveylib/EclipseStandardCodeFormatting.xml".
   2. From there, go to "Code Templates" and import the XML settings file for new files, etc, in "jspsurveylib/EclispeStandardCodeTemplates.xml".  You may want to change a few of the templates so that they have your name as the file creator instead.
4. (Optional step, but highly recommended especially if you're not experienced with Tomcat) Install the Sysdeo Eclipse Tomcat plugin -- if you use Apache Tomcat, this plugin is highly recommended -- it's great for debugging and launching of Tomcat webapps. After installing, restart Eclipse and go to Window -> Preferences -> Tomcat and change the settings for your installation of Tomact.
5. Check that eclipse does not have any compilation errors before you do anything else. Find the "Problems" tab and make sure the list does not contain any red X's.
   If you get any errors, fix them.
   You may get errors about the PDA/WTK files and missing imports -- if you don't have the wireless toolkit installed and you don't plan on editing the PDA version of WebSurveyToolbox, you can simply delete these files from your classpath and ignore the resulting compliation errors (right-click your project, select "Properties" and "Java Build Path" and remove the offending libraries from the list so that the project will build).
   If you get an error saying "Project jspsurveylib is missing required Java project: 'ekit'", follow these steps to fix it.
6. Go to the menu: Window -> Show View -> Ant
7. Right click in the main empty area and select "Add Buildfiles"
8. Browse to jspsurveylib/build.xml
9. Double-click "Webapps" to build most of the project. (If you want to build the J2ME/PDA code, click "buildAll" instead).

You're done setting up Eclipse! Code, and enjoy.

CVS Without Eclipse
If you want to check out the code with CVS without using Eclipse, see Introduction to SourceForge Project CVS Services for Developers and Basic Introduction to CVS and SourceForge Project CVS Services. Then read the next section on using "NetBeans or Other IDE".

NetBeans Or Other IDE
In other IDEs, follow these directions to set up the repository. NetBeans Matisse, the new GUI builder tool in NetBeans 5.0, is used for developing new UIs.

1. Check out the code from CVS (see above).
2. Add the library jar files. These are all in the lib/ folder and its subdirectories. You can all of them *EXCEPT* lib/optional/retroweaver-rt.jar -- you don't want to add that one because it's used only for backwards compatibility with Java 1.4 and should only be used in builds that are "retroweaved" to Java 1.4.
3. Add the Wireless Toolkit if you want to compile or use the PDA related version. (In NetBeans, you need to either (a) work around the cmu/survey/pda files, or (b) install the NetBeans Mobility Pack or wireless toolkit and add it to your build path. (TODO: This has not been tested in NetBeans, please comment on it to us).
4. Code formatting: When you edit the code without Eclipse, the code formatting may not be forced to the standard in the repository. Make sure that you put the right headers on any new files and format your code in a similar manner to the existing code.
5. Build the project. Using Ant, open up jspsurveylib/build.xml and build target "Webapps" to build most of the project. (If you want to build the J2ME/PDA code, click "buildAll" instead). (TODO: This has not been tested in NetBeans, please comment on it to us).

Building and Running Applications

Short Directions: Use ant to build jspsurveylib/build.xml, target "Webapps" (not buildAll unless you're also working on the J2ME/PDA version). Follow the directions under Eclipse or NetBeans/Other IDEs above to build this.

Longer Description:

jspsurveylib/build.xml is the main build file for packaging the applications, jars, etc. Most scripts will work under under Linux, Mac OS X, and also under Windows using Cygwin. If you use Windows and don't have cygwin, you should install it.

The main build script is the ANT "build.xml" script at the top level, which will package all projects. It will not compile the classes -- you must have compiled the package in your IDE, such as Eclipse or NetBeans. (Eclipse automatically compiles for you).

These are the primary sections/scripts:

Survey Manager

To build the Survey Manager, the main start point, follow the directions above to open build.xml and build target Webapps.This builds everything you need to run. After running this build target, the survey manager will be ready to run through tomcat (which you should have set up using the directions above).

This will update the jar files, sign jar files, copy some files for the Survey Template into the Survey Manager (so all duplicate files should only be updated in jspsurveylib/Webapps/SurveyTemplate). It doesn't zip the survey manager into a release file -- that is done by jspsurveylib/Webapps/SurveyManager/WEB-INF/PackageSurveyManagerToZip.sh.

Survey Editor

The Survey Editor can be run immediately after a compile -- there's nothing extra needed. It can be run with jspsurveylib/SurveyEditor.sh (Unix/Linux) or jspsurveylib/SurveyEditor.bat (Windows)-- or in your development environment, you may simply want to run the class cmu.survey.editor.gui.Editor.

Installing

Apache Tomcat, MySQL, and Installation
See the Installation Directions for how to install the applications in general, and what you'll need to run the program on your machine (you should probably have done this already before joining the development team).

Apache Tomcat Configuration
If you want to use Apache Tomcat with the webapps in the CVS repository without copying them into the tomcat webapps folder, you can do that.
These directions assume you're using the default install of Apache Tomcat -- if not, these directions may not be correct.
To do so, edit jakarta-tomcat-***/conf/server.xml and add the following lines at the end of the file, right before the last "</Host>" (change the paths below to the right paths on your computer):

Restart Apache Tomcat. From then on go to "http://localhost:8080/surveymanager" to visit the survey manager, to "http://localhost:8080/SurveyTemplate" to access the survey template, and to "http://localhost:8080/ClusteringSurvey" to access the clustering survey.

Bug Database

There is a central bug database. Contact Aaron Powers for information and to request access to it.

Bugs will be automatically sent to this database. So, while you're developing, you shouldn't send

When you initialize each web application, it will ask you for a MySQL connection to a database. If you are making changes, please uncheck "Automatically send bug reports to developers" so that it doesn't submit bugs in your version of the code.

License Files
By working on this project, you agree to make your contributions open-sounce. Please read Licensing and make sure you agree to release your contributions under it. The boilerplate license should go at the top of all source code files. (In Eclipse, this is automatically taken care of by the XML templates file mentioned above).

Java Docs

The JavaDocs are available online.

The main active and past developers and their main projects are:

FAQ

Q: I only want to edit the survey editor GUI. Do I need to do the full build process?

A: No, you can completely skip the build process if you want. You can make your changes and run the editor independently, and completely skip build.xml. Of course, it won't make it into the survey manager's web start launch until someone puts it there, though. But you can ask another developer to do this after you check it in to the repository.

Q: When I launch the survey editor after the build, it says it is missing a jar file (like j2ee.jar).

A: Make sure that jspsurveylib/build.properties's JNLP_COPYING=long, so that the ant build will build the full jar files. It could also be set to "short" in your Java App. Also, you'll need to get a certificate to sign these with for your builds, or else you won't be able to launch it.

Credits
Written by Aaron Powers. Last updated May, 2006.