<?xml version="1.0" encoding="ISO-8859-15"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document> 
  <header> 
    <title>Welcome to DdlUtils</title> 
  </header> 
  <body> 
    <section id="What_is_DdlUtils">
      <title>What is DdlUtils</title>
      <p>
        <strong>DdlUtils</strong> is a small, easy-to-use component for working with Database Definition
        (DDL) files. These are XML files that contain the definition of a database schema, e.g. tables
        and columns. These files can be fed into DdlUtils via its Ant task or programmatically in order to
        create the corresponding database or alter it so that it corresponds to the DDL. Likewise, DdlUtils
        can generate a DDL file for an existing database.
      </p>
      <p>
        DdlUtils uses the <strong>Turbine</strong> XML format, which is shared by 
        <a href="ext:torque">Torque</a> and <a href="ext:ojb">OJB</a>. This format expresses
        the database schema in a database-independent way by using JDBC datatypes instead of raw SQL
        datatypes which are inherently database specific. An example of such a file is:
      </p>
      <source><![CDATA[
<?xml version="1.0"?>
<!DOCTYPE database SYSTEM "http://db.apache.org/torque/dtd/database.dtd">
<database name="testdb">
  <table name="author">
    <column name="author_id"
            type="INTEGER"
            primaryKey="true"
            required="true"/>
    <column name="name"
            type="VARCHAR"
            size="50"
            required="true"/>
    <column name="organisation"
            type="VARCHAR"
            size="50"
            required="false"/>
  </table>

  <table name="book">
    <column name="book_id"
            type="INTEGER"
            required="true"
            primaryKey="true"
            autoIncrement="true"/>
    <column name="isbn"
            type="VARCHAR"
            size="15"
            required="true"/>
    <column name="author_id"
            type="INTEGER"
            required="true"/>
    <column name="title"
            type="VARCHAR"
            size="255"
            defaultValue="N/A"
            required="true"/>

    <foreign-key foreignTable="author">
      <reference local="author_id" foreign="author_id"/>
    </foreign-key>  

    <index name="book_isbn">
      <index-column name="isbn"/>
    </index>
  </table>
</database>]]>
 </source>
    </section>
    <section id="Learning_more">
      <title>Learning more</title>
      <p>
        There are essentially two ways to use DdlUtils:
      </p>
      <ul>
        <li>
          In an <a href="ext:ant">Ant</a> build script via the task provided by DdlUtils.
          You can learn more about <a href="ext:ddlutils/antdoc/">here</a>.
        </li>
        <li>
          From within your Java program, about which you can learn more 
          <a href="site:documentation/api-usage">here</a>.
        </li>
      </ul>
      <p>
        You're also welcome to join DdlUtils' <a href="site:mail-lists">mailing lists</a>.
      </p>
    </section>
  </body>
</document>
