Resource Code

Reusable Code

Many parts of the project have been designed for component reusability, so any place something like this is done in this project, you should use these. These are also designed for reuse into other projects. Here's a short list of them, some explanations, and links to the javadocs. Feel free to use these in other projects, and as you're developing, add features that will be useful to this project and other projects (of course, that's true in general).

Most re-usable components are stored in the org.browsecode.helpers package, completely separate from anything else and intended to be used for many different applications. (Everything in org.browsecode.helpers is application-independent).

Object Oriented Database Storage
DatabaseStorageFactory, DatabaseStorage, TableStorage, TableFormat, DataTableModel, ForwardOnlyData

A database-independent way of accessing data. Built to layer on top of SQL, since so many SQL databases don't use the standard SQL code for everything (e.g. MySQL table creation and alteration is not compatible with other systems, and Microsoft Access has a very wierd way of saving numbers). Using this will make your database access swappable between multiple types of databases (for any databases which have an interface implemented -- currently just MySQL).

This means you can do database access with a programmatic interface which has many different useful features for creating tables, deleting tables, modifying tables, and more.

When you would have wanted to use a forward-only ResultSet, you can get your data from DataTableModel as ForwardOnlyData, instead of using the table directly -- using ForwardOnlyData will greatly reduce the amount of data that the database server needs to load and keep access to.

If you use TableFormat, your tables will be automatically upgraded and modified as needed. The tables will be created when you need them, and if you add a new column, etc, the database structure (using ForwardOnlyData only) will automaticaly create your columns the first time it's needed. Read through the documentation for TableFormat and ForwardOnlyData to see how to use this better.

DataTableModel works neatly with JTable, and creates a mutable, editable, table that has some undo/redo support, ability to add/delete columns and rows. You can use the TablePanel GUI to add a simple GUI that takes advantage of all these features -- and adds find/replace (including RegExp), row numbers on the left, a pop-up editor that lets you see more text and change whether a cell is null, a calendar editor, and more.

Also, a benefit of using this over a ResultSet or any raw SQL connection is that it automatically refreshes the database if the connection is lost, etc. (on most operations -- this isn't implemented perfectly). You can even set a GUI operation to fire while it tries to re-connect to the database -- see SearchingForConnectionListener (example). Note that in MySQL, the delay is quite long for the database to timeout its connection, while reconnection is very quick -- so this might not show up in practice for short network disconnects -- this is a todo, but it would be a high overhead to check how long it takes to run each SQL call.

Automatic Bug Reporting & Aggregation
Maintenance,MaintenanceGUI, MaintenanceListener

Bug reports can automatically be sent, filed, and aggregated in a database. Users can be automatically asked whether they'd like to send the bug report or not.

Logging
The Maintenance class is used for debugging output and sending error reports. Never use "System.out.println()" or "System.err.println()" when they are printing debugging-related output -- always print it out with Maintenance.debugOutput() and Maintenance.debugOutputError() which will always print to a logging file if one has been registered.

File Unexpected Exceptions
Never drop an unexpected exception or error -- pass it to Maintenance.sendBug(...), and it'll get sent to either a website database or to an email address. Call Maintenance.catchUncaughtExceptions() to fire messages even for uncaught exceptions.

Users Can Check For Sensitive Information
When an email is sent from a webapp (or any non-gui application) it'll be emailed to the registered user, so that they can check to make sure there's no sensitive information in it, and then forward it to the developers. If it's a GUI-based application, you can have Maintenance optionally ask the user whether to send the bug (in all of our applications, it asks the user before sending, for privacy issues -- showing the user all the information that will be sent). The application will automatically guess SMTP servers for sending, and this works fine in most conditions.

It's also possible to filter out bugs to avoid sending (i.e. there is a list of bugs that don't get sent), etc., but this is not yet done in a program-independent way -- it's on the to-do list.

A* Search
AStar, AISearchDomain, Solution

This is a Java implementation of A*. Implementation of A* is fairly simple, however, there are a variety of potential pitfalls that you can avoid with this example.

This implementation of A* fully supports multiple threads searching the same domain. This is great if you have multiple processors on your computer. During our tests under linux it looks like Intel's hyperthreading in Java under Red Hat Linux does not offer any performance enhancements, under a variety of tests (not just A*).

GUI Tools
These pieces may be useful when you are implementing a GUI -- some, like the Wizard, are GUIs, others are simply backend tools you'll only need when making a GUI, like UndoHandler.

MenuBarHandler
MenuBarHelper

A menu bar system that supports multi-part application development better than the Java system. Instead of being oriented around menus, forcing developers to add each menu item individually to the right spot, this works around

UndoHandler
UndoHandler, UndoableEdit2, CompoundUndoableEdit2

A enhanced undo manager.
Primary Features: Out-of-order undo, support for data-oriented undo (vs. Java's default of GUI-object based undo)

The default Java has a strange implementation which requires you to make the manager do the merging (i.e. if you type "hi" they merge together into one undo, not two). This has support such that the undos themselves (subclasses of UndoableEdit2) decide whether they can merge with another undo.

Out-of-order undo is implemented in a beta GUI. This means that you can go to the "undo manager", and see a list of all the recent changes that have happened. Then, you can undo or redo any actions which do not conflict with the current state. In other words, if you change the text on one object, and move it to a new place, you can undo either action in the undo manager. If you change the text twice, the undos conflict so you can't undo the first edit before the second edit -- those ones have to be done in order. We hope to improve this GUI and the code interface (not yet finalized) and make this Undo Manager a resource for other projects.

This can be added to menus that use MenuBarHelper automatically.

Dialogs
Dialogs

A bunch of utility dialogs that are easy to call for showing simple alert dialogs, single questions, etc.

Wizard
Wizard, WizardCard

A Wizard GUI.
Primary Features: Resizable, Changeable background and good default images. Depending upon return values for the implementations of WizardCard, automatically decides what "cards" are available and unavailable, etc. Launch the TAWC example.

Full Tools
These are fully implemented tools that may be useful for other projects or for things outside the surveys, whether or not you want to write code to use them.

Database Editor
DatabaseEditor

A decent database editor application that is easier to use than any other interface to SQL that we've seen (if you see one that's easier to use in Java and open-source, let us know). Run it now.

Text Analysis and Word Counts
TAWC

A word counting application for analyzing text. [more]