Dovetail Database Schema Document Reference

Kevin Gilpin
Last Updated...

About
Generating DDL (SQL)
Generating DB Schema Java Code

Running DoveTail2Java
Schema Metadata Classes
Instance Classes
Example

Index of Elements

About

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:

Constructing a new Instance using values for all the NOT NULL columns
Constructing an Instance for an already existing record, using its PRIMARY KEY
Setting the value of each column
Creating a new record in the database using the column values
Updating the record in the database using the column values
Deleting the record

Example

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>
</schema>

The following metadata classes will be generated:

dovetail.example.survey.schema.SurveySchema
dovetail.example.survey.schema.RegisteredUserTable
dovetail.example.survey.schema.SurveyResponseTable
dovetail.example.survey.schema.SurveyTable

The following instance classes will be generated:

dovetail.example.survey.schema.instance.RegisteredUserInstance
dovetail.example.survey.schema.instance.SurveyInstance
dovetail.example.survey.schema.instance.SurveyResponseInstance

See the Survey Site example to see examples of these classes being generated and used.

Index of Elements

schema
table
column
type
enum
reference
constraint
index

Element `schema`

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

**`schema` attributes**
Name	Description	Required
`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**
Name	Description	MinOccurs	MaxOccurs
`table`	Each table element describes a database table in the schema	0	*

Element `table`

Each table element represents a database table.

**`table` attributes**
Name	Description	Required	Default Value
`name`	The name of the table	true

**`table` child elements**
Name	Description	MaxOccurs
`column`	Each column element is a column in the table	*
`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.	*
`index`	Can be used to create single or multi-column indices, with or without UNIQUE-ness	*

Element `column`

Describes how the column should be created

**`column` attributes**
Name	Description	Required	Default 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.	false	false
`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	false	false
`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.	false	false
`allowNull`	Whether a SQL NULL value is allowed in this column.	false	true

**`column` child elements**
Name	Description	MinOccurs	MaxOccurs
`type`	Data type of the column	1, unless the column is a reference	1, 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	0	1
`reference`	A column may be defined as a reference to another column. This has several effects. 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 The SQL for this table should include a REFERENCES( otherColumn )	1, unless the type is specified	1
`displayText`	A more user-friendly name for this column.	0	1
`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.	1	1

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**
Name	Description	Required	Default 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**
Name	Description	MaxOccurs
`int`	SQL INTEGER, Java int	1
`float`	SQL FLOAT, Java double	1
`date`	SQL DATETIME, Java java.util.Date	1
`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).	1
`fixed-string`	SQL CHAR([size]), Java String. The values stored in this column will always have exactly [size] characters.	1
`string`	SQL VARCHAR([size]), Java String. The values stored in this column will have up to [size] characters, inclusive.	1
`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.	1
`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).	1

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**
Name	Description	MinOccurs	MaxOccurs
`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**
Name	Description	Required	Default 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**
Name	Description	Required	Default 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.	true

**`constraint` child elements**
Name	Description	MinOccurs	MaxOccurs
`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**
Name	Description	Required	Default 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**
Name	Description	MinOccurs	MaxOccurs
`column-ref`	A reference to another column in the table	1	*

Home

Dovetail Database Schema Document Reference

Contents

About

Generating DDL (SQL)

Generating DB Schema Java Code

Running DoveTail2Java

Schema Metadata Classes

Instance Classes

Example

Index of Elements

Element schema

Element table

Element column

Element type

Element enum

Element reference

Element constraint

Element index