Currently, a DTD is not available for the Tornado configuration files. Until one is created, the following examples are intentded to illustrate how to configure mappings for common usages.

Defining a database

<database name="xplanner" engine="mysql">
	<driver class-name="org.gjt.mm.mysql.Driver"
			url="jdbc:mysql://myhost.com/xplanner?autoReconnect=true">
		<param name="user" value="me" />
		<param name="password" value="mypassword" />
	</driver>
	<mapping href="mappings/FirstObjectMapping.xml" />
	<mapping href="mappings/SecondObjectMapping.xml" />
</database>

Defining a simple object mapping

This mapping defines a Note object consisting of several simple fields. The object is mapped to the "note" table and the object identity is defined by the "id" column in that table. When the object is deleted, the "is_deleted" column will be set to "1". If a "deleted-column" element is not specified, objects will be deleted from the database instead of marked for deletion. Upon insert and subsequent updates of a Note instance, the last update column will be immediately updated with the current time. The optional identity generator is specified as an attribute of the class element.

<mapping>
  <class name="com.company.Note" identity="id"
	     identity-generator="com.company.IdentityGenerator">
    <description>Note</description>
    <map-to table="note" />
    <deleted-column name="is_deleted"/> <!-- optional -->
    <last-update-column name="last_update"/> <!-- optional -->
    <field name="id" type="integer">
      <sql name="id" type="integer"/>
    </field>
    <field name="title" type="string">
      <sql name="title" type="char"/>
    </field>
    <field name="text" type="string">
      <sql name="text" type="char"/>
    </field>
    <field name="authorId" type="integer">
      <sql name="author_id" type="integer"/>
    </field>
    <field name="submissionTime" type="date">
      <sql name="submission_time" type="timestamp"/>
    </field>
    <field name="attachedToId" type="integer">
      <sql name="attachedTo_id" type="integer"/>
    </field>
  </class>
</mapping>

Defining an object mapping with a one-to-many relationship.

This mapping defines a Task object consisting of several simple fields and a relationship. The object is mapped to the "task" table and the object identity is defined by the "id" column in that table. A Task has a one-to-many association with Notes. The foreign key in the Note table is "attachedTo_id". This relationship is also specified with a cascading delete, so that when a Task is deleted all it's related Notes are deleted (or marked for delete is a deleted column is specified).

<mapping>
  <class name="com.company.Task" identity="id">
    <description>Story Task</description>
    <map-to table="task" />
    <field name="id" type="integer">
      <sql name="id" type="integer"/>
    </field>
    <field name="name" type="string">
      <sql name="name" type="char"/>
    </field>
    <field name="type" type="string">
      <sql name="type" type="char"/>
    </field>
    <!-- ... other fields -->
    <field name="notes" type="com.company.Note">
       <sql related-by="attachedTo_id" delete="cascade" />
     </field>
  </class>
</mapping>

Defining an object mapping with a many-to-many relationship.

This mapping defines an ElectronicResource object containing a many-to-many relationship. The many-to-many relationship uses an intermediate table to define the association. In this example, the table is called "assoc". The "from_column" and "to_column" attributes define the columns that hold the identifiers for the ElectronicResource and Category objects (note: currently many-to-many relationships are not supported for compound keys). Furthermore, this mapping is sharing it's association table with other associations. To distinguish this association from others that exist in the table, the "where" attribute specifies how to select the entries for this type of association. The intent behind this feature is to allow dynamic associations to be created at runtime. Of course, these associations would probably not be represented in the Java class definition but they can be accessed programatically. Sharing association tables is an optional feature. Each association can have it's own table if that's desired.

<mapping>
  <class name="com.company.ElectronicResource"
	 extends="com.company.Resource"
	 identity="id">
    <description>Electronic resource information</description>
    <map-to table="electronicresource" />
    <field name="id" type="integer">
      <sql name="id" type="integer"/>
    </field>
    <field name="uri" type="string">
      <sql name="uri" type="char"/>
    </field>
    <field name="format" type="string">
      <sql name="format" type="char"/>
    </field>
	<field name="categories" type="com.company.Category">
	  <sql many-table="assoc" from-column="to_id" to-column="from_id" 
           where="assoc.type = 3"/>
	</field>
  </class>
</mapping>