Source Code Readme & FAQ

Version 1.0
October 10, 2000


The easyscout.org source code is now released under the GNU public license.  A copy of the GNU license has been included with this distribution, and a condition of downloading the source code is that you have read and understand this license.

The license ensures that the EasyScout source code will always remain free.  By free, I mean that the program allows you to find out how it is created, find bugs and report them, and most importantly, create your own enhancements.  Although I cannot force users to send their enhancements back to me, I humbly ask you to do so.  I will include most changes back into the main source tree so all users can benefit from our work.  However, I reserve the right to choose what does and does not make it into the primary source tree.

The license does ensure, however, that all users who build upon the EasyScout source must also release under the GPL.  This means that they must release the source code and allow others to copy, modify, and improve their work.

Let me repeat -- if you modify the EasyScout source, you must release the code for your changes to comply with the GNU public license.  You cannot release the program, run a site with it, or do much else without also releasing the full source code.

I also ask that those who modify the source do not fork the source code.  Please reincorporate changes back into the original code by e-mailing them to me.  Forking will cause a whole host of problems that our users should not have to deal with.

Good luck.  I wish you the best and hope that the source code is useful to you.

-- Dr. Conan C. Albrecht
-- conan@warp.cx


Why did you release the source under the GPL?

First of all, I released the source code so that others could help in the effort.  The goal is to provide free, stable, and easy-to-use recording software to the BSA community at large.  I welcome all help in this effort.

I released the code under the GPL because this license provides freedom.  I firmly believe in free software and its principles.  Free source code increases program stability, security, and functionality faster than most companies can compete with.   The GPL protects this freedom by enforcing that modifying authors provide the source code as well and do not link with non-free modules.

I also hope the program is educational to Scouts around the world.  Looking at the source code should be helpful to others who want to learn Java and/or servlets.

Doesn't releasing the code undermine security?

Acutally it is quite the reverse.  I think open source solutions are more secure because others can verify the security models and code.  There is nothing hidden in the code -- no back doors or otherwise.   EasyScout uses triple-DES encryption for troop files and keeps the key in a very secure file.

If you do find errors in my security model, please let me know immediately so they can be fixed without delay.

I am the IS manager for my council/troop/group.  Can I host my own installation of EasyScout?

I encourage IS managers to install and test out EasyScout so they are comfortable with it.  This is one reason I released as open source.  However, I strongly discourage outside groups hosting EasyScout because of security concerns.  Most IS managers are not security experts and might leave open holes in their web servers.  No matter how secure the source code is, a poor or even good installation can open holes to hackers and expose your data to the world.

A common installation allows for better security because more eyes are watching it.  When holes are found, they are plugged immediately.  I prefer to let the combined expertise of all the users ensure security, rather than several installations with few users.

Why did you write the program in Java?

First, because I enjoy programming Java more than any other language (for the moment, anyway).  It is powerful, structured, and Internet-savvy.  Java servlets provide a very powerful and scalable solution for server-side programming.  The code is quite readable and is portable across many platforms.

Why did you use Servlets (as opposed to perl, ASP, JSP, PHP, ...)?

Servlets are very powerful.  They allow for different MIME types to be returned (text, html, images, pdf, etc.).  They also allow the developer to program in a traditional format with a main program entry point.  They allow full control over the implementation of program logic and user interfaces.

I enjoy perl and use it for scripting, but I feel it gets unwieldy in large projects.  EasyScout might eventually become very large, and perl is much less structured than Java.

HTML scripting languages in general, such as ASP, JSP, Cold Fusion, etc., are great for mostly static pages with little dynamic content, but less effective for truely dynamic programs such as EasyScout.  For web-based but full programs, I prefer to come at the problem from the programming side, rather than from the HTML side.  Servlets keep the feel of a real program, with thread flow, etc.  Scripting languages that embed code into the pages often become a "house of cards" with interdependencies throughout the pages.  I know that some people can program these languages quite dynamically, but I prefer just to structure it more like a traditional program.

I don't use ASP because it is proprietary, costly, and runs only on Windows.  I prefer more open solutions when they can be used.

What Java IDE do you use?  Is EasyScout linked to any specific IDE, such as JBuilder, Visual Cafe, etc?

EasyScout is created using pure Java.  It is not tied to any IDE or any web server.  It uses no proprietary classes other than those included in the main distribution.  Therefore, it should work in any IDE.

I actually use the AnyJ development environment because it is very nice and is free for Linux.  However, I have used JBuilder, Visual Cafe, and a number of others and find they each have unique strengths.

What is the cx.scout package all about?

Java packages keep things neat and orderly, especially when your code is combined with someone elses code.  cx.warp is my own domain.  cx stands for Christmas Island (off the coast of Australia), a country that sells domain names to anyone in the world.  The server is actually located in St. Louis, and I live in Utah.  EasyScout is for the Boy Scouts of America right now.

OK, I downloaded the source code.  Where do I start?

The best place to start is the cx/warp/scout/EasyScout.java file.  This is the entry point for all calls to the program.  When the http://www.easyscout.org/servlet/ES file is called (ES is just an extension of EasyScout), the web server starts in the service method of this class.

The service method validates the user (either through the user's username/password or the user's session id) and then runs a switch-type statement on the "action" paramter.  I know some programmers might see this as rudimentary, it actually works quite well and keeps things simple.  It also keeps things secure since every call comes in through the same place.

How do I test my own installation of the program?

EasyScout should run without problems on any Servlet-enabled web server.  It runs well on Apache Tomcat, IBM Websphere, and the JRun plugin.  For non-production installations (i.e. development on your personal machine), I suggest VQ Server from VQSoft.  VQ Server is a lightweight, java-based web server that is perfect for development and even for small web servers.  It is very easy to setup and manage.

The production site currently runs on Apache Tomcat, which has been perfect so far.  The Apache project is a wonderful example of open source success.

What is the z= parameter?  What is sessioning?

EasyScout uses sessioning.  When users log in, the program validates their username and password and then assigns a session id.  This id is cached in a TimedHashtable and is kept for 30 minutes beyond its last use.  All further interaction with the program is done via the session id (sent by the "z" parameter).

Session ids are important because they prevent a user's password from crossing the network unnecessarily.  In addition, once the session times out (or the user logs out), the id is of no good to any hacker that gains access to it.

I have used session ids with several programs and have found them very useful.  I do not store them in cookies because not all browsers allow cookies.  URL rewriting is also a possibility, but some servers don't meet the standards as well as others, so URL rewriting usually works.  To ensure portability and simplicity, I explicitly send the z-parameter with every call.

What is the DataGate?  Why all the interfaces?

EasyScout uses interfaces for all access to data.  This allows different persistence mechanisms to be "plugged in" on the back end without affecting program code.

The program currently uses a file-based system.  I prefer file-based systems when I can get away with it (i.e. for smaller installations) beceause they are simpler than full databases.  Databases require setup, configuration, and disk space.  Further, they can crash or become corrupted.  I am not against databases; I just think developers should justify their use rather than simply assuming they are the best solution for everything.

However, I realize that EasyScout may get the userbase to warrant a full database.  If this time ever comes, we simply need to implement the interfaces for JDBC use and the program should work without any other changes.

What are the top development priorities?

Right now, the following need to be done:

  1. Implement better support for activities.  EasyScout's recording of activities is too simplistic and needs to capture more information.
  2. Improve the statistics page.  The statistics page should include graphical representations of the troop's progress.  The code for creating PNG and GIF graphics is in the com.keypoint and cx.warp.graphics packages, respectively.
  3. Design PDF-formatted reports, such as trip reports (using the BSA form), etc.