You should start by unzipping the Dovetail distribution to an appropriate place on your computer. You can find all Dovetail distributions on our 'Files' page at SourceForge
The Dovetail distribution uses Jakarta Ant to set up and run the sample programs. Using Ant is an easy way to run Java makes and scripts in a 100% cross-platform way.
The design of Dovetail does not tie it to any specific database (relational or otherwise), but it currently best supports MySQL. MySQL also has the advantage of being very lightweight and easy to administer, which makes it a good choice for doing a lot of experimentation and learning about Dovetail.
MySQL is available for lots of common platforms including Win32, Linux and Solaris.
After you get and install MySQL, make sure you start up the MySQL server. The Dovetail Survey Site example will need to connect to it in order to run successfully.
The MySQL 'test' database
The MySQL installation creates a database called 'test', which doesn't require a user name or password to access. That makes it convenient for experimentation. For that reason, the Dovetail examples will use the MySQL 'test' database. You shouldn't ever use it in a live site though since there's no security on it.
There are several aspects of Dovetail that must be customized for the specific database that you are using. Just to give you a general idea of what the issues are:
Dovetail is designed to build web sites with Java Servlet & Java Server Pages (JSP). As such, it requires a servlet runner such as Jakarta Tomcat 3.x. Other JSP engines such as GNUJSP, iPlanet, and IBM WebSphere should work as well, but for the sake of brevity this install guide is going to require Tomcat.
- Different databases have different SQL syntax, especially for modifying the schema. This has several effects on Dovetail:
- SQL queries in the site document must be correct for the database being used.
- Generated SQL to create and drop tables must be different for each database. Dovetail handles this by using an XSL stylesheet to generate this SQL. A different stylesheet is used for each database.
- Different databases report errors such as constraint violations in different ways. If you want to implement support for a new database, Dovetail's SQLDatabase class will need to be extended to understand these idiosynchrasies in order for all of its features to work correctly (such as converting SQLException instances into more specific types such as DuplicateKeyException).
- Not all databases implement transactions (the standard MySQL distribution doesn't). Dovetail mostly leaves implementing the database interaction up to you, so understanding how to deal with this issue is up to you. However, it does provide plenty of help in the form of database metadata and convenient classes for creating, updating, and modifying records.
This step is currently optional since the Sample Site documentation doesn't describe how to get the JSP pages running.