<?xml version="1.0"?>
<!--
 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.
-->

<document>
 <properties>
  <title>Torque ORM Reference - Defining the Schema</title>
 </properties>

 <body>
 
  <section name="Creating a database schema">
    <subsection name="Introduction">
      <p>
        A Torque database schema consists of one or more XML files
        describing the structure of the databases.
        The files which are considered by the generator can be configured
        by the sourceIncludes and sourceExcludes settings of the
        maven plugin or ant task. By default, all files are considered
        ending with the suffix <code>schema.xml</code>.
      </p>
      <p>
        All schema files should comply either to
        <a href="database-5-0-strict.xsd">database-5-0-strict.xsd</a>
        or to <a href="database-5-0.xsd">database-5-0.xsd</a>.
        The difference between the strict schema
        and the normal schema is that in the strict schema, additional
        naming restrictions are made which are aimed at better interoperability
        between databases.
      </p>
      <p>
        It is recommended to ensure schema compliance
        by adding xsd information into the root database element, e.g.
      </p>
      <source><![CDATA[
<database 
    xmlns="http://db.apache.org/torque/5.0/templates/database"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://db.apache.org/torque/5.0/templates/database 
        http://db.apache.org/torque/torque-5.0/documentation/orm-reference/database-5-0-strict.xsd"
   ...
      ]]></source>
      <p>
        or
      </p>
      <source><![CDATA[
<database 
    xmlns="http://db.apache.org/torque/5.0/templates/database"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://db.apache.org/torque/5.0/templates/database 
        http://db.apache.org/torque/torque-5.0/documentation/orm-reference/database-5-0.xsd"
   ...
      ]]></source>
      <p>
        A <a href="#Schema_Reference">reference of the Torque schema</a>
        can be found below.
      </p>
    </subsection>

    <subsection name="Example schema file">
      <p>
        For an example schema file containing most of the discussed features,
        look at the bookstore-schema.xml from the test project.
      </p>
    </subsection>

    <subsection name="Organisation of the schema files">
      <p>
        A single database can consist of one or more schema files.
        For small database definitions, it is best to use one schema file
        per database.
        For complicated database definitions, it can be better to use
        more than one schema files.
        To have foreign key references between tables in different files,
        other schema files can either be included using the
        <code>include-schema</code> element, 
        or they can be referenced using the <code>external-schema</code>
        element.
        The difference between included and referenced schemata is that 
        included schema are considered under torque's control, whereas
        tables and views defined in an external schema file can be
        referenced, but are not under torque's control.
        In practice that means that an included schema can have
        foreign key relations between all tables in all files,
        and the ddl generation generates create (and possibly drop)
        commands for all tables.
        With referenced schema files, relations from the
        referenced schema to the main schema are forbidden,
        and the ddl generation only generates create (and/or drop)
        commands for tables in the main schema, not the external schema.
        With both included and referenced schema files, 
        care should be taken that the imported/included files 
        are not read on their own by the  maven plugin or ant tasks.
      </p>
      <p>
        For example, in the test project, the files included-schema.xml and 
        ext-schema.xml are included respectively referenced 
        by the test-schema.xml.
        In the configuration of the torque-maven-plugin in the pom, these
        files are excluded as source files in order to read them only via the
        include-schema/external-schema element and not as schema files of
        their own.
      </p>
    </subsection>
  </section>
  
    <section name="More than one database">
    <p>
      Torque can access multiple databases with different structure and even
      different database vendors from within one Torque instance.
      Basically this means that Torque's inbuilt connection handling can handle
      more than one database connection pool.
    </p>
    <p>
      There are three different scenarios for multiple databases,
      with different levels of support from Torque:
    </p>
    <ul>
      <li>
        Each table has a unique name; different tables belong to different
        databases. This situation is fully supported by the Torque runtime.
        If the generated peer classes (generated by the torque generator 
        using the torque templates) are used, the different databases are
        handled automatically in the standard cases because each table has
        a default database to which it belongs.
      </li>
      <li>
        Some or all table names are not unique (there are tables with the
        same name in different databases), and the tables with the same
        name have the same structure (same column names and data types etc).
        This situation is also fully supported by the Torque runtime.
        However, the generated peer classes are not generated for this
        situation; meaning that by default, a connection for querying and
        saving is always opened to the default database for the given table
        name.
        This means you will either need to pass the correct database handle name
        for querying and saving, or not use the connection handling
        provided by the peer classes.
      </li>
      <li>
        Some or all table names are not unique (there are tables with the
        same name in different databases), and some of the tables with the same
        name have a different structure than other tables with the same name.
        This situation is not recommended, it is unclear to which extent it is
        supported.
      </li>
    </ul>
    
    <subsection name="Databases with the same structure">
      <p>
        If your databases have the same structure, define the schema and 
        generate the classes as if it were only one database.
        Accessing different databases using the generated classes is covered 
        <a href="read-from-db.html#Accessing_Multiple_Databases">later</a>
        in this documentation.
      </p>
    </subsection>
    
    <subsection name="Databases with different structures">
      <p>
        On schema creation time, make sure that the different databases
        are defined in different schema files. Also make sure that the different
        databases have different name attributes in the database element.
        Then, define different database handles using the database names
        from the schema files. Torque will then use the database handle with
        the key equal to the database element's name attribute for each table.
      </p>
      <p>
        It is recommended to generate the classes for the different databases
        into different packages to keep them apart.
        To achieve this, the corresponding classes must be generated
        in different generator runs with different package settings.
      </p>
    </subsection>
  </section>

  <section name="Using database Schema names">

    <p>
      It is possible to qualify table names with schema names
      (as in ${schema}.${table}) at generate time. To do this, use the
      fully qualified table name as name attribute in the &lt;table&gt;
      element of your schema.xml.
      For example, to use the schema "bookstore" for the table "book",
      use the following table definition:
    </p>

    <source><![CDATA[
...
<table name="bookstore.book" description="Book table">
...
]]>
    </source>

    <p>
      If the standard options are used, the resulting
      java class name will ignore the leading database name
      (e.g. the class will be named Book for the example above). 
      If you want to retain the schema names in the java names,
      (i.e. the resulting java class should be named "BookstoreBook"),
      you can either use the javaName attribute of the table definition:
    </p>

    <source><![CDATA[
...
<table name="bookstore.book" javaName="BookstoreBook" description="Book table">
...
]]>
    </source>

    <p>
      or you can set the generation option 
      <code>torque.om.retainSchemaNamesInJavaName</code> to <code>true</code>.
    </p>

    <p>
      If you use a sequence to autogenerate ids, 
      the sequence will be generated in the same schema as the table.
    </p>

    <p>
      In some databases (hsqldb, postgresql, mssql), a schema exists independly
      of other database objects (user or database). In these databases,
      a "create schema" (but no "drop schema") command(s) are created
      automatically in the ddl-sql script if qualified names are used
      as table names.
    </p>

  </section>
  
  <section name="Creating a schema from an existing database">

    <p>
      Torque can create a starting point for a schema file from an existing
      database. For doing this, Torque uses the JDBC metainformation
      provided by the database driver. Not all information about the 
      schema can be collected from JDBC metainformation, so this can only
      serve as a starting point.
    </p>
  
    <p>
      See the information about
      <a href="running-the-generator.html#Generation_of_XML_schema_from_an_existing_database">running the Torque generator</a>
      on how to generate a schema file from an existing database.
    </p>
  </section>
  
  <section name="Schema Reference">
    <subsection name="The database element">
      <p>
        <img src="../../images/schema-database.png"/>
      </p>
      <p>
        Each schema file contains one database element as root element.
        The database element must have a <code>name</code> attribute,
        which defines the default handle by which the database can be accessed.
        For example, in the test project, most databases have the name
        <code>bookstore</code>, so by default they are accessed by the 
        bookstore configuration settings.
        A database can also define whether by default primitive or object types
        are used (via the <code>defaultJavaType</code> attribute),
        or which is the default id method to use to generate primary keys
        (via the <code>defaultIdMethod</code> attribute).
        For more information and possible value ranges, see also the xsd
        <a href="database-5-0.xsd">database-5-0.xsd</a>.
      </p>
      <p>
        The database element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>include-schema</td>
            <td>see <a href="#Organisation_of_the_schema_files">Organisation of the schema files</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>external-schema</td>
            <td>see <a href="#Organisation_of_the_schema_files">Organisation of the schema files</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>table</td>
            <td>see <a href="#Tables">Tables</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>view</td>
            <td>see <a href="#Views">Views</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>domain</td>
            <td>definition of common data types, see <a href="#Domains">Domains</a></td>
            <td>0 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The database element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The default handle by which the database can be accessed</td>
            <td></td>
          </tr>
          <tr>
            <td>defaultJavaType</td>
            <td>
              Whether by default primitive or object types are used. 
              Permitted values are object or primitive
            </td>
            <td>primitive</td>
          </tr>
          <tr>
            <td>defaultIdMethod</td>
            <td>
              The default id method to use to generate primary keys.
              Permitted values are native, idbroker and none.
            </td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Tables">
      <p>
        <img src="../../images/schema-table.png"/>
      </p>
      <p>
        Tables are defined by the table element and have the tableType
        XSD type depicted in the image above.
        All tables must have a name and should have at least some columns. 
        It is recommended that each table has a primary key
        (see <a href="#Primary_Keys">below</a> for reasons).
        Torque supports composite primary keys; to create one, simply set
        the primary-key attribute to true in more than one column
        of the same table.
      </p>
      <p>
        Torque can auto-generate numeric primary keys using either
        the native database mechanism (idMethod="native", recommended)
        or a method involving an extra table (idMethod="idbroker").
        For defining primary keys manually, use idMethod="none".
      </p>
      <p>
        Foreign key relations between tables can be defined using the 
        foreign-key element. Foreign keys can consist of one or more columns,
        simply add a reference elements for each column in the foreign key.
      </p>
      <p>
        Indexes on the table can be set using the index element.
        Indexes can also consist of one or more columns. 
        "Normal" indexes are not unique, use the unique element for 
        defining unique constraints.
      </p>
      <p>
        The table element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>
              Currently used only for MySQL. See 
              <a href="supported-databases.html#Table_create_options">the supported database page</a>
              for details.
            </td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>column</td>
            <td>see <a href="#Columns">Columns</a></td>
            <td>1 or more times</td>
          </tr>
          <tr>
            <td>foreign-key</td>
            <td>see <a href="#Foreign_keys">Foreign Keys</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>index</td>
            <td>see <a href="#Index">Index</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>unique</td>
            <td>see <a href="#Unique">Unique</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>id-method-parameter</td>
            <td>
              The name of the sequence, if a sequence is used 
              to generate the primary key. 
              See <a href="#Id_method_parameters">ID Method Parameters</a>
            </td>
            <td>0 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The table element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the table</td>
            <td></td>
          </tr>
          <tr>
            <td>description</td>
            <td>A description of the table.</td>
            <td></td>
          </tr>
          <tr>
            <td>idMethod</td>
            <td>
              The id method to use to generate primary keys for this table.
              Permitted values are native, idbroker and none.
            </td>
            <td>
              The value of the defaultIdMethod attribute 
              in the database element
            </td>
          </tr>
          <tr>
            <td>skipSql</td>
            <td>
              Whether to skip generation of DDL SQL(CREATE TABLE...) 
              for this table.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>javaName</td>
            <td>The base name of the java classes representing the table</td>
            <td>autogenerated from the name attribute</td>
          </tr>
          <tr>
            <td>interface</td>
            <td>
              The interface which the generated data object class
              for this table should implement</td>
            <td></td>
          </tr>
          <tr>
            <td>peerInterface</td>
            <td>
              The interface which the generated peer class
              for this table should implement
            </td>
            <td></td>
          </tr>
          <tr>
            <td>baseClass</td>
            <td>
              The class from which the generated data object class
              for this table should inherit
            </td>
            <td></td>
          </tr>
          <tr>
            <td>basePeer</td>
            <td>
              The class from which the generated peer class
              for this table should inherit
            </td>
            <td></td>
          </tr>
          <tr>
            <td>abstract</td>
            <td>
              Whether the generated data object class should be
              an abstract class
            </td>
            <td>false</td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Columns">
      <p>
        The column element defines a column in a table. 
        Each column must have a name and a type. 
      </p>
      <p>
       There are some column names which you can not use in Torque although
       your database would support them. These are any column name that contains
       characters that are not in Java's variable identifier character set.  
       The reason is that column names are used as variable names in the OM Peer
       classes and these columns will cause the Torque generated code to not 
       compile.  
       </p>
       
       <p>
       Note however, that SQL92 standard and up uses the same identifier
       characters as Java for non-delimited columns. So this should only apply 
       to columns defined by the SQL standard as delimited columns, i.e. 
       columns referred to surrounded by double quotes.  Delimited column 
       are considered to be case sensitive and/or contain non-standard 
       characters.  However, most good cross DB server designs should avoid 
       these special types of column since some servers don't support delimited 
       columns.
       </p>
       
       <p>
       In addition, there are two column names that are handled slighly 
       differently in the OM Peer classes.  This is so they will not produce 
       constants twice in the generated code. The following column names (case is 
       ignored) will have an &quot;_&quot; prefixed in front of them in the Peer
       classes:
       <ul>
        <li>TABLE_NAME => _TABLE_NAME</li>
        <li>DATABASE_NAME => _DATABASE_NAME</li>
       </ul>
      </p>
      
      <p>
       Furthermore, it is recommended that you do not use words which have
       a defined meaning in SQL as column names. Even if you can trick your
       database into using them, it is not sure whether Torque can do the same.
       And besides, even if it works for one database, if you ever decide
       to use another database, you may run into trouble then.
      </p>
      <p>
        The column element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>inheritance</td>
            <td>see <a href="#Inheritance">Inheritance</a></td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>enum-value</td>
            <td>see <a href="#EnumValue">EnumValue</a></td>
            <td>0 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The column element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the column. Required.</td>
            <td></td>
          </tr>
          <tr>
            <td>type</td>
            <td>
              The SQL type of the column, also determines the java type.
              Required unless the domain attribute is set.
              Note that not every type is supported by every database.
              Also note that for most (but not all) data types, the javaType
              of the column can be automatically determined from the SQL type.
              Possible values are BIT, TINYINT, SMALLINT, INTEGER, BIGINT, 
              FLOAT, REAL, NUMERIC, DECIMAL, CHAR, VARCHAR, LONGVARCHAR, 
              DATE, TIME, TIMESTAMP, BINARY, VARBINARY, LONGVARBINARY, 
              NULL, OTHER, JAVA_OBJECT, DISTINCT, STRUCT, ARRAY, BLOB, CLOB, 
              REF, BOOLEANINT, BOOLEANCHAR and DOUBLE.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>description</td>
            <td>A description of the column.</td>
            <td></td>
          </tr>
          <tr>
            <td>size</td>
            <td>
              The SQL size of the column. Must be an integer.
              Does only make sense for some SQL Types.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>scale</td>
            <td>
              The SQL scale of the column (number of digits after the comma).
              Must be an integer. Does only make sense for some SQL Types.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>default</td>
            <td>
              The default value of the column. 
            </td>
            <td></td>
          </tr>
          <tr>
            <td>useDatabaseDefaultValue</td>
            <td>
              Whether to use the database default value 
              if a new object is saved
              and the attribute value is equal to the java default value. 
              Has no effect on primitive boolean columns.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>primaryKey</td>
            <td>
              Whether this column is part of the primary key of the column.
              Allowed values are true and false.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>required</td>
            <td>
              Whether this column is required, i. e. it must be not-null
              Allowed values are true and false.
            </td>
            <td>
              true for columns which are part of the primary key,
              false otherwise
            </td>
          </tr>
          <tr>
            <td>autoIncrement</td>
            <td>
              Whether the value for this column should be autogenerated.
              Has only effect for primary key columns.
              Allowed values are true and false.
            </td>
            <td>
              true for columns which are part of the primary key,
              false otherwise
            </td>
          </tr>
          <tr>
            <td>javaName</td>
            <td>
              The base name for the column for generating 
              java methods and fields.
            </td>
            <td>
              Determined from the name attribute.
            </td>
          </tr>
          <tr>
            <td>javaType</td>
            <td>
              The java type for the java representation of the column.
            </td>
            <td>
              For most types, determined from the type attribute.
            </td>
          </tr>
          <tr>
            <td>domain</td>
            <td>
              The <a href="#Domains">domain</a> to use for this column.
            </td>
            <td>
            </td>
          </tr>
          <tr>
            <td>inheritance</td>
            <td>
              The inheritance type defined by this column, 
              see <a href="inheritance.html">the inheritance guide</a>.
              Allowed values are single and false.
            </td>
            <td>
            </td>
          </tr>
          <tr>
            <td>enumType</td>
            <td>
              If set, declares this column as an enum.
              The attribute value defines the enum class name and can either be unqualified, 
              in which case the enum will be generated using the enum-value child elements,
              or the content can be fully qualified, in which case the enum
              must be hand-written, and needs to contain the methods
              getValue(), which returns the SQL value of the enum instance,
              and the static method getByValue(${javaType} sqlValue),
              which returns the enum instance corresponding to the sqlValue.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>protected</td>
            <td>
              If true, the generated java setters and getters for this property 
              will be protected rather than public.
              Allowed values are true and false.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>version</td>
            <td>
              If true, this column is used as a version number 
              for optimistic locking.
              I.e. for updates, Torque will check that the version 
              number in the database is equal to the version number
              of the supplied object and it will automatically increase
              the version number of the updated row.
              Setting version to true will only work
              for numeric columns and will produce code that does not compile
              if applied to other column types.
              Allowed values are true and false.
            </td>
            <td>
            </td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Primary keys">
      <p>
       For every table, you should create a primary key which has no meaning
       in real life. The reasons for this are:
      </p>
  
      <p>
       You should use a primary key at all because it creates a well-defined
       link between the objects in the database and the objects in memory.
       Often, one has to decide whether a java object in memory describes
       &quot;the same&quot; object as a certain row in the database.
       For example if you read an object from a database, 
       change a field value and write it again to the database,
       you would usually want to update the row you read from.
       This is only possible if Torque can find the row
       in the database from which the object originated. For this, the
       primary key is used in relational databases. If two java objects have
       the same primary key, they describe &quot;the same thing&quot; and refer
       to the same row in the database. If you do not have
       a primary key, there is no well-defined way to decide if two java
       objects describe &quot;the same thing&quot;. You might run into not
       being able to update an object.
      </p>
  
      <p>
       Now that we know why we want to have a primary key at all, why should
       it have no meaning in real life ? This can be explained best by an
       example. Consider a table which holds manufactured parts. Each part
       has an unique serial number. So it is tempting to use the serial number
       as a primary key. But now imagine that we have registered the wrong
       serial number for a certain part in the database. Remember that
       the primary key is used to decide &quot;is it the same object?&quot;
       So we cannot change the serial number of a specified object without
       making it another object.
      </p>
  
      <p>
       In Torque, this problem manifests itself in that there is no easy way
       to change the primary key of an object; you must trick Torque into it
       by using Torque's internals. This should be avoided if possible.
       If you use a primary key which
       has no meaning in real life, you do not run into that trouble.
      </p>
    </subsection>

    <subsection name="Foreign keys">
      <p>
        A foreign-key element defines a SQL foreign-key relation between
        two tables. The columns which constitute the foreign key relation
        are added as reference elements.
      </p>
      <p>
        The foreign-key element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>reference</td>
            <td>see <a href="#Reference">Reference</a></td>
            <td>1 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The foreign-key element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the foreign key relation.</td>
            <td></td>
          </tr>
          <tr>
            <td>foreignTable</td>
            <td>
              The name of the foreign table. 
              Must be a table name known in this schema.
              Required.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>onDelete</td>
            <td>
              The action to be executed by the database when the referenced
              entry is deleted.
              Allowed values are cascade, setnull or restrict.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>onUpdate</td>
            <td>
              The action to be executed by the database when the referenced
              entry is updated. 
              Allowed values are cascade, setnull or restrict.
            </td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Reference">
      <p>
        A reference defines a link between local and foreign column
        for a foreign-key element.
      </p>
     <p>
       The reference element can contain 
       no child elements. It can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>foreign</td>
            <td>
              The SQL name of the column in the foreign table.
              The column name must be known in the Torque schema.
              Required.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>local</td>
            <td>
              The SQL name of the column in the local table.
              The column name must be known in the Torque schema.
              Required.
            </td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="EnumValue">
      <p>
        An enum-value element defines one possible value of a column. 
      </p>
      <p>
        The enum-value element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>value</td>
            <td>The SQL value of the enum.</td>
            <td></td>
          </tr>
          <tr>
            <td>javaName</td>
            <td>The name of the enum key.</td>
            <td>computed from the value attribute</td>
          </tr>
          <tr>
            <td>description</td>
            <td>A description of the enum value</td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>
    <subsection name="Index">
      <p>
        An index element defines a SQL index on a table. 
        The columns which constitute the index
        are added as index-column elements.
      </p>
      <p>
        The index element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>index-column</td>
            <td>see <a href="#Index_Column">Index column</a></td>
            <td>1 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The index element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the index.</td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Index Column">
      <p>
        A index-column defines a column which is part of an index.
      </p>
     <p>
       The index-column element can contain 
       no child elements. It can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>
              The SQL name of the column which is part of the index.
              The column name must be known in the Torque schema.
              Required.
            </td>
            <td></td>
          </tr>
       </table>
      </p>
    </subsection>

    <subsection name="Unique">
      <p>
        An unique element defines a SQL unique index on a table. 
        The columns which constitute the unique index
        are added as unique-column elements.
      </p>
      <p>
        The unique element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>unique-column</td>
            <td>see <a href="#Unique_Column">Unique column</a></td>
            <td>1 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The unique element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the unique index.</td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Unique Column">
      <p>
        A unique-column defines a column which is part of an unique index.
      </p>
     <p>
       The unique-column element can contain 
       no child elements. It can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>
              The SQL name of the column which is part of the unique index.
              The column name must be known in the Torque schema.
              Required.
            </td>
            <td></td>
          </tr>
       </table>
      </p>
    </subsection>

    <subsection name="Id method parameters">
      <p>
        A id-method-parameter is currently only used to define the
        name of a sequence if th database uses a sequence for generating
        primary keys for a table.
      </p>
     <p>
       The id-method-parameter element can contain 
       no child elements. It can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>
              Currently not used by Torque.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>value</td>
            <td>
              The SQL name of the sequence.
            </td>
            <td></td>
          </tr>
       </table>
      </p>
    </subsection>

    <subsection name="Inheritance">
      <p>
        A inheritance element defines the usage of a column with respect
        to inheritance. See <a href="inheritance.html">the inheritance guide</a>
        for details.
      </p>
     <p>
       The id-method-parameter element can contain 
       no child elements. It can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>key</td>
            <td>
              A value found in the column marked as the inheritance key column.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>class</td>
            <td>
              The class name for the object that will inherit the record values
            </td>
            <td></td>
          </tr>
          <tr>
            <td>extends</td>
            <td>
              The class that the inheritor class will extend
            </td>
            <td></td>
          </tr>
       </table>
      </p>
    </subsection>

    <subsection name="Views">
      <p>
        <img src="../../images/schema-view.png"/>
      </p>
      <p>
        Views behave much as tables, except that they cannot be written to.
        and that they usually reference data from other tables.
      </p>
      <p>
        A view definition must contain the column names and types.
      </p>
      <p>
        To let Torque create the sql for the view, you can specify 
        a sql suffix for the view, e.g. 
        "from book join author on book.author_id=author.author_id", and the
        select snippet for each column using the select attribute, e.g. 
        "author.author_id". E.g.
      </p>
      <source><![CDATA[
<view name="BOOK_AUTHORS" sqlSuffix="from book join author on book.author_id=author.author_id">
  <column name="book_id" type="INTEGER" select="book.book_id"/>
  <column name="author_id" type="INTEGER" select="author.author_id"/>
  <column name="book_title" type="VARCHAR" select="book.title"/>
  <column name="author_name" type="VARCHAR" select="author.name"/>
</view>
      ]]></source>
      <p>
        This will usually work only for simple views, but is easy to read
        in the schema.
        If you cannot create the sql like this, you can also fill the attribute
        createSql with the sql needed to create the sql.
      </p>
      <p>
        The view element can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>column</td>
            <td>see <a href="#View_Columns">View columns</a></td>
            <td>1 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The view element can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the view</td>
            <td></td>
          </tr>
          <tr>
            <td>baseClass</td>
            <td>
              The fully qualified name of class 
              which the generated data object class extends
            </td>
            <td></td>
          </tr>
          <tr>
            <td>basePeer</td>
            <td>
              The fully qualified name of class 
              which the generated peer class extends
            </td>
            <td></td>
          </tr>
          <tr>
            <td>abstract</td>
            <td>
              Whether the generated data object class should be abstract
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>javaName</td>
            <td>
              The base name of the generated java classes
            </td>
            <td>generated from the SQL name</td>
          </tr>
          <tr>
            <td>sqlSuffix</td>
            <td>
              The suffix after the select column for the view creation SQL.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>createSql</td>
            <td>
              The SQL to create the view.
            </td>
            <td>
              computed from the select attributes of the columns 
              and the sqlSuffix attribute of the view
            </td>
          </tr>
          <tr>
            <td>skipSql</td>
            <td>
              Whether to skip the create statement 
              when generating the schema creation sql
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>description</td>
            <td>A description of the view</td>
            <td></td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="View Columns">
      <p>
        View columns are similar for table columns, but have a different
        set of attributes because views are read-only and have a different
        creation SQL than tables.
      </p>
      <p>
        The column element in a view can contain the following elements:
        <table>
          <tr>
            <th>element</th>
            <th>description / reference</th>
            <th></th>
          </tr>
          <tr>
            <td>option</td>
            <td>currently not used by the torque templates</td>
            <td>0 or more times</td>
          </tr>
          <tr>
            <td>inheritance</td>
            <td>see <a href="#Inheritance">Inheritance</a></td>
            <td>0 or more times</td>
          </tr>
        </table>
      </p>
      <p>
        The column element in a view can contain the following attributes:
        <table>
          <tr>
            <th>attribute</th>
            <th>description / reference</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>name</td>
            <td>The SQL name of the column</td>
            <td></td>
          </tr>
          <tr>
            <td>type</td>
            <td>
              The SQL type of the column, also determines the java type.
              Required unless the domain attribute is set.
              Note that not every type is supported by every database.
              Also note that for most (but not all) data types, the javaType
              of the column can be automatically determined from the SQL type.
              Possible values are BIT, TINYINT, SMALLINT, INTEGER, BIGINT, 
              FLOAT, REAL, NUMERIC, DECIMAL, CHAR, VARCHAR, LONGVARCHAR, 
              DATE, TIME, TIMESTAMP, BINARY, VARBINARY, LONGVARBINARY, 
              NULL, OTHER, JAVA_OBJECT, DISTINCT, STRUCT, ARRAY, BLOB, CLOB, 
              REF, BOOLEANINT, BOOLEANCHAR and DOUBLE.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>description</td>
            <td>A description of the column.</td>
            <td></td>
          </tr>
          <tr>
            <td>size</td>
            <td>
              The SQL size of the column. Must be an integer.
              Does only make sense for some SQL Types.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>scale</td>
            <td>
              The SQL scale of the column (number of digits after the comma).
              Must be an integer. Does only make sense for some SQL Types.
            </td>
            <td></td>
          </tr>
          <tr>
            <td>javaName</td>
            <td>
              The base name for the column for generating 
              java methods and fields.
            </td>
            <td>
              Determined from the name attribute.
            </td>
          </tr>
          <tr>
            <td>javaType</td>
            <td>
              The java type for the java representation of the column.
            </td>
            <td>
              For most types, determined from the type attribute.
            </td>
          </tr>
          <tr>
            <td>domain</td>
            <td>
              The <a href="#Domains">domain</a> to use for this column.
            </td>
            <td>
            </td>
          </tr>
          <tr>
            <td>protected</td>
            <td>
              If true, the generated java setters and getters for this property 
              will be protected rather than public.
              Allowed values are true and false.
            </td>
            <td>false</td>
          </tr>
          <tr>
            <td>select</td>
            <td>
              The SQL snippet which reads the view column value.
            </td>
            <td>
            </td>
          </tr>
        </table>
      </p>
    </subsection>

    <subsection name="Domains">
      <p>
        A domain is used to create a common type definition.
        A domain must have a name and a data type
        and can have a size, scale and default value.
        Once the domain is defined, it can be used as any other data type
        in columns. 
      </p>
    </subsection>
  </section>
 </body>
</document>
