Dovetail Database Schema Document Reference

Kevin Gilpin
Last Updated...



Dovetail uses 2 primary XML documents to represent a web site: the database schema document, which must conform to schema.dtd, and the site document, which must conform to site.dtd.

This page describes the database schema DTD. In actuality, the master document for the database schema schema (DTD is just one way of defining an XML schema) is schema.qjml, which is a Quick 3 document. But for the purposes of writing a database schema XML document, that detail is not important.

Generating DDL (SQL)

Dovetail can use the database schema document to generate the DDL (SQL) statements to create or drop the tables in the database. SQL generation is done by applying an XSLT stylesheet to the DB schema document. Differences in database syntax make it necessary to use a different stylesheet for each database. A MySQL stylesheet is provided with the Dovetail distribution. To use it, run:
prompt % java org.apache.xalan.xslt.Process -IN <DB schema XML document> -XSL generate-schema-mysql.xsl 
			  -OUT makedatabase.sql
To run this command, or any other Dovetail command, you should have all the JAR files in the Dovetail lib directory in your CLASSPATH.

You can also use a stylesheet to drop the database schema. You can generate the SQL statements to drop the database by running:
prompt % java org.apache.xalan.xslt.Process -IN <DB schema XML document> -XSL generate-drop-schema-mysql.xsl 
			  -OUT dropdatabase.sql

Generating DB Schema Java Code

Running DoveTail2Java

The Site and Schema Java classes are generated by running the agonism.dovetail.util.DoveTail2Java utility. Here is an example:
c:\myproject> java agonism.dovetail.util.DoveTail2Java my-site.xml c:\java\dovetail\schema\site.qjml
	               my-schema.xml c:\java\dovetail\schema\schema.qjml c:\java\dovetail\xsl output
You can run DoveTail2Java with no arguments to get simple usage information.

Schema Metadata Classes

The schema metadata classes are generated Java classes that provide a statically compiled API to the database schema. Dovetail generates a single class called [package].[schema]Schema, where the [package] and [schema] strings are provided by the DB schema XML document. This Schema class provides a method to get a Java object for each table in the schema. Each of these table objects (located in the same package as the Schema class), has an accessor method for each Column which is defined on that Table.

Instance Classes

The metadata classes are immutable objects that describe the schema. What about creating and updating records? Dovetail includes several mechanisms for creating, updating, and deleting records in the database. One of those mechanisms is the generated Java instance classes. For each table, a class named [package].instance.[table]Instance will be generated.

Each of these instance classes has methods for accomplishing the following:


Suppose that the DB schema includes the following (portions of this XML document have been removed to make the example more clear. The full document is survey-schema.xml
<schema name="survey" package="dovetail.example.survey.schema">
  <table name="RegisteredUser">	... </table>
  <table name="Survey">	... </table>
  <table name="SurveyResponse">	... </table>
The following metadata classes will be generated: The following instance classes will be generated: See the Survey Site example to see examples of these classes being generated and used.

Index of Elements


Element schema

The schema element is the root of any Dovetail database schema document (hereafter referred to as the 'schema document').

schema attributes
NameDescriptionRequiredDefault Value
name A short, simple name for the schema. Typically the site and schema documents will have the same name, which would be related in some way to the name of the web site that they are part of. The Java code generator will append 'Schema' to the name. true
description Informational description of the schema false
package This attribute is used when generating the Java classes that represent the schema. It should be in the form of a Java package name : name tokens separated by '.' characters. For example, agonism.dovetail.example.survey. The Java code generator will append '.schema' to the package attribute. true

schema child elements
table Each table element describes a database table in the schema 0*

Element table

Each table element represents a database table.

table attributes
NameDescriptionRequiredDefault Value
name The name of the table true

table child elements
column Each column element is a column in the table 0*
constraint Can be used to create column constraints, specifically UNIQUE constraints on multiple columns. This feature is not as well used and tested as the index element. 0*
index Can be used to create single or multi-column indices, with or without UNIQUE-ness 0*

Element column

Describes how the column should be created

column attributes
NameDescriptionRequiredDefault Value
name The name of the column false
isPassword Whether the column is storing a password. This attribute is used when rendering forms so that password form inputs render with 'type="PASSWORD"'. It is also used to prevent the server from un-necessarily sending password values out to the browser. falsefalse
isPrimaryKey Whether the column is the primary key for the record. Only one column may be the primary key. This attribute is primarily used for generating the DDL to create the schema falsefalse
isAutoIncrement Most databases support the notion of an auto-incrementing column. An auto-incrementing column is typically an INTEGER column whose value is automatically assigned from a SEQUENCE each time a new record is inserted. The combination of 'isPrimaryKey' with 'isAutoIncrement' gives the column an automatically generated primary key. falsefalse
allowNull Whether a SQL NULL value is allowed in this column. falsetrue

column child elements
type Data type of the column 1, unless the column is a reference1, unless the column is a reference
defaultValue Default value that will be written into the column. defaultValue is only valid if the 'type' is also specified and the column is not a reference 01
reference A column may be defined as a reference to another column. This has several effects.
  1. The data type of the column is determined by the column to which this column is a reference. Thus, the type of this column should not be specified
  2. The SQL for this table should include a REFERENCES( otherColumn )
1, unless the type is specified1
displayText A more user-friendly name for this column. 01
comment A description of this column. Due to a bug in the XML parser, this column should be considered REQUIRED, even though it is not technically necessary in order for the schema to be created. 11

Element type

Data type stored in the column. The data type of the type element is determined by whether its child element is 'int', 'float', 'date', 'boolean', 'fixed-string', 'string', 'enum', or 'blob'.

type attributes
NameDescriptionRequiredDefault Value
size For string values, this attribute specifies the length of the string. For the 'fixed-string' data type, the generated SQL data type should be CHAR([size]). For the 'string' type it shoul be VARCHAR([size]). In SQL, the string stored in CHAR fields are always exactly [size] characters in length, whereas strings stored in VARCHAR can be any length up to and including [size] false-1

type child elements
int SQL INTEGER, Java int 01
float SQL FLOAT, Java double 01
date SQL DATETIME, Java java.util.Date 01
boolean SQL CHAR(1) whose value is either 't' or 'f', Java boolean. A single character is used to store boolean values in the database because there isn't any consistent implementation of boolean in SQL. Some databases use a BIT data type, others have BOOLEAN, others require CHAR(1). 01
fixed-string SQL CHAR([size]), Java String. The values stored in this column will always have exactly [size] characters. 01
string SQL VARCHAR([size]), Java String. The values stored in this column will have up to [size] characters, inclusive. 01
enum SQL ENUM ( value1, value2, ... ), Java String. For each ENUM column that you create, you should write a corresponding Java class which can convert the String values returned from the database into constant (static final) Java objects. 01
blob SQL MEDIUMBLOB (for MySQL), Java byte[]. Handling of binary data is another area that is not consistently implemented across databases, but all databases do have some mechanism for doing it, and the JDBC API provides a standard way to put and access the data. The only real trick with 'blob' columns is generating the write DDL to create them. of course, if you're using Dovetail you don't have to worry about that (if you do, it's a Dovetail bug). 01

Element enum

Enumerated type. The possible values for the enum are specified by the 'value' child elements. The values of the enum column will be returned via JDBC (and Dovetail) as Strings.

enum child elements
value A string which is a legal value for the column. One value element should be listed for each possible value of the enumerated type. 1*

Element reference

This element is used to declare that one column is a reference (foreign key) to another column. Typically this is implemented with using the SQL feature 'REFERENCES <table name>(<column name>)' within the CREATE TABLE statement.

reference attributes
NameDescriptionRequiredDefault Value
table-name Name of the table to which this column is a reference. true
column-name Name of the column to which this column is a reference. true

Element constraint

A database CONSTRAINT on one or more columns, with optional UNIQUE-ness

constraint attributes
NameDescriptionRequiredDefault Value
isUnique A UNIQUE CONSTRAINT enforces that each combination of column values in the database is unique. For example, suppose there is a table with two columns, firstName and lastName. The UNIQUE CONSTRAINT will allow the table to contain the following data:
firstName lastName
--------- --------
Ed        Wood
Phil      Woods
Woody     Allen
Paul      Allen
But it would prevent the addition of Woody Allen (or any of the other existing firstName/lastName combinations) to the table.

constraint child elements
column-ref A reference to another column in the table 1*

Element index

A database INDEX on one or more columns, with optional UNIQUE-ness. An INDEX builds a fast-access data structure of all the values of one or more columns so that they can be quickly queried. A full discussion of indexing is (far) outside the scope of this reference. Just be aware that you can use this element to specify indices on tables.

index attributes
NameDescriptionRequiredDefault Value
isUnique Whether the INDEX is a UNIQUE index. UNIQUE-ness implies bascially the same things as having a UNIQUE CONSTRAINT. true

index child elements
column-ref A reference to another column in the table 1*