isis-sql-objectstore.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<book>
  <bookinfo>
    <title><?eval ${docbkxGuideTitle}?></title>

    <subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>

    <releaseinfo><?eval ${project.version}?></releaseinfo>

    <authorgroup>
      <author>
        <firstname>Kevin</firstname>

        <surname>Meyer</surname>
      </author>

      <author>
        <firstname>Robert</firstname>

        <surname>Matthews</surname>
      </author>
    </authorgroup>

    <legalnotice>
      <para>Permission is granted to make and distribute verbatim copies of
      this manual provided that the copyright notice and this permission
      notice are preserved on all copies.</para>
    </legalnotice>
  </bookinfo>

  <!-- front matter -->

  <toc></toc>

  <preface id="preface">
    <title>Preface</title>

    <para><emphasis>Apache Isis</emphasis> is designed to allow programmers
    rapidly develop domain-driven applications following the <ulink
    url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
    pattern. It is made up of a core framework plus a number of alternate
    implementations, and supports various viewers and object stores. Apache
    Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
    Foundation</ulink>, and is licensed under <ulink
    url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
    License v2</ulink>.</para>

    <para>This guide is written for programmers who want to use the
    <emphasis>SQL Object Store</emphasis> to persist domain objects running
    within the <emphasis>Apache Isis</emphasis> framework. Specifically, it
    covers how to write repository implementations, how to configure the
    object store, and how to deploy your applications using the object
    store.</para>
  </preface>

  <!--main content -->

  <chapter id="chp.Intro">
    <title>Operation</title>

    <abstract>
      <para>What's it all about?</para>
    </abstract>

    <sect1>
      <title>Background</title>

      <para>The SQL objectstore provides a fully-automatic object store that
      uses a jdbc SQL-compatible database server.</para>

      <para>All domain objects (entities) are introspected during
      initialisation, and have a 1-to-1 mapping onto a database table. All
      properties (values) are mapped onto one or more columns with each
      database table.</para>

      <para>Domain object classes are introspected and all properties
      recursively introspected to value types. Thus, if a property stores a
      reference to a class, that class's properties are introspected,
      etc.</para>
    </sect1>

    <sect1>
      <title>Setup</title>

      <sect2>
        <title>Properties</title>

        <para>The SQL objectstore is setup via the
        <code>isis.properties</code> file. The required variables are given
        below:</para>

        <blockquote>
          <para><property>isis.persistor.sql.jdbc.driver=org.hsqldb.jdbcDriver</property></para>

          <para><property>isis.persistor.sql.jdbc.connection=jdbc:hsqldb:file:hsql-db/tests</property></para>

          <para><property>isis.persistor.sql.jdbc.user=sa</property></para>

          <para><property>isis.persistor.sql.jdbc.password=</property></para>
        </blockquote>

        <para>The driver property must contain the name of the jdbc driver
        class that provides access to your SQL server. Known examples are
        given below in <xref linkend="sec.servers.tested" />.</para>
      </sect2>

      <sect2>
        <title>Table Creation</title>

        <para>Missing database tables are automatically created when the SQL
        objectstore is initialised.</para>

        <para>Please note that changes to domain classes such as renaming
        fields (properties) or the classes themselves, are
        <emphasis>not</emphasis> automatically detected. If you rename a
        property after a table has been created, you should use the
        appropriate database administration tool to rename the column in the
        containing table.</para>

        <para>If you rename a domain class (entity), you must also rename the
        appropriate table.</para>
      </sect2>
    </sect1>

    <sect1>
      <title>Mappers</title>

      <para>The mappers take care of mapping a value type onto a SQL data
      type. Default mappers are provided by
      JdbcFieldMappingFactoryInstaller.</para>

      <sect2>
        <title id="sec.mappers.modifiable-values">Modifiable values</title>

        <para>The following SQL datatypes can be overridden, if specified in
        the properties file (the default value is given in parenthesis), [the
        mapped value classes are given in square brackets]:<simplelist>
            <member>isis.persistor.sql.datatypes.timestamp (DATETIME)
            [TimeStamp, java.sql.Timestamp]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.datetime (DATETIME)
            [DateTime]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.date (DATE) [Date,
            java.sql.Date, java.util.Date]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.time (TIME) [Time]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.double (FLOAT)
            [double]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.float (FLOAT)
            [float]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.short (INT) [short]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.long (INT) [long,
            Color]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.int (INT) [int]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.boolean (CHAR(1))
            [boolean]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.string (VARCHAR(65))
            [String]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.longstring (VARCHAR(128))
            [String]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.password (VARCHAR(120))
            [Password]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.default (VARCHAR(65))
            [Everything else, e.g. Image]</member>
          </simplelist></para>

        <para><simplelist>
            <member>isis.persistor.sql.datatypes.primarykey (INTEGER)
            [IdMappingAbstract -&gt; JdbcObjectReferenceMapping -&gt;
            JdbcObjectReferenceFieldMapping]</member>
          </simplelist></para>

        <para>The final value, primarykey, is a special value.</para>

        <para>In general, be very careful about changing the SQL data type, as
        the default value mappers are written assuming the default values.
        Data parsing uses prepared statements and reads/writes values as
        objects.</para>

        <para>The datatype longstring is used to store classnames, required
        for polymorphism.</para>
      </sect2>

      <sect2>
        <title>Floating Point Value Limits</title>

        <para><emphasis>Caution:</emphasis> Testing on certain database
        servers (MySQL and PostgreSQL) has shown that <code>float</code>s and
        <code>double</code>s (stored as <code>FLOAT</code> or <code>DOUBLE
        PRECISION</code> respectively) are not stored to the same resolution
        as supported by Java. The tested range of float is 1E-37 to 1E38, and
        the tested range of double is 1E-307 to 1E308.</para>
      </sect2>

      <sect2>
        <title>Fixed values</title>

        <para>The following classes are not modifiable:</para>

        <para>[char] is set to CHAR(1)</para>

        <para>[Money] value is FLOAT, currency is VARCHAR(3)</para>

        <para>[Percentage] is FLOAT</para>
      </sect2>

      <sect2>
        <title>Modifying individual property types</title>

        <para>By default, all property types will use the SQL datatype, as
        determined above (see <xref
        linkend="sec.mappers.modifiable-values" />), but it is possible to
        override these values for individual object properties, by specifying
        the following override in the properties file:</para>

        <para><property>isis.persistor.sql.automapper.type.&lt;object&gt;.&lt;property&gt;=&lt;SQL
        data type&gt;</property></para>

        <para>where</para>

        <itemizedlist>
          <listitem>
            <para>object is the final part of the domain object name (e.g. in
            my.domain.Member, it'll be Member)</para>
          </listitem>

          <listitem>
            <para>property is the lower case property name (e.g. in getName(),
            it'll be name)</para>
          </listitem>

          <listitem>
            <para>SQL data type is an acceptable datatype (e.g. VARCHAR(255)
            )</para>
          </listitem>
        </itemizedlist>

        <para>Again, please be very careful about changing the defaults as the
        value mappers make assumptions about the underlying data type.</para>

        <para>It is safe to change the size of VARCHAR() types, e.g. when you
        know only a partcular field requires more that 65 characters, the
        default String length.</para>
      </sect2>
    </sect1>

    <sect1>
      <title>Naming Conventions</title>

      <para>While case is determined by the capabilities of the database
      driver, all SQL names will be written in UPPER CASE, below.</para>

      <sect2>
        <title>Tables</title>

        <para>By default, all Isis tables are preceded with "ISIS_". This
        behaviour can be altered by specifying a replacement table prefix. See
        <xref linkend="sec.defaults.tableprefix" />.</para>

        <sect3>
          <title>Internal Tables</title>

          <para>ISIS_ADMIN_SERIAL_ID ISIS_ADMIN_SERVICES</para>
        </sect3>

        <sect3>
          <title>Domain Tables</title>

          <para>Only the "class" part of the package name is used. Thus a
          domain class called "some.package.Client", will be mapped onto a
          table "ISIS_CLIENT" (assuming that the default table prefix has not
          been changed).</para>
        </sect3>
      </sect2>

      <sect2>
        <title>Columns</title>

        <sect3>
          <title>Internal column: pk_id</title>

          <para>ID column: PK_ID</para>

          <para>VERSION BIGINT,</para>

          <para>MODIFIED_BY VARCHAR(32),</para>

          <para>MODIFIED_ON TIMESTAMP</para>

          <para>The default ID column name is "PK_ID", but this can be
          over-ridden by specifying the new name in the properties
          file:</para>

          <para><property>isis.persistor.sql.pk_id=id</property></para>

          <para><property>ID column: ID</property></para>

          <para><property>Used internally by Isis to record services, in the
          table "ISIS_ADMIN_SERVICES".</property></para>
        </sect3>

        <sect3>
          <title>Properties</title>

          <para>Most properties are named as per the class property. This
          means you must take care not to use SQL reserved labels are property
          names. The exceptions are collections and multi-field values (e.g.
          Money).</para>
        </sect3>

        <sect3>
          <title>Collections</title>

          <para>Collections are mapped onto the child class:</para>

          <para>If a parent class (some.package.Parent) has a collection of
          (some.other.package.Child) named "children", the child table
          (ISIS_CHILD) gets a column labeled "FK_PARENT_CHILDREN" of type
          primarykey. The child property is assigned the ID of the parent
          class.</para>

          <para>This means that a given child can only appear in one parent's
          collection of the same name.</para>
        </sect3>

        <sect3>
          <title>Multi-field values</title>

          <para>Some value types need more than 1 field to store their values,
          e.g. Money - some.package.class#price.</para>

          <para>In this case, the SQL objectstore creates 2 fields, price1 and
          price2.</para>

          <para>See "<code>JdbcMoneyValueMapper</code>", which extends
          "<code>AbstractJdbcMultiFieldMapping</code>".</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1>
      <title>Number of instances returned by queries</title>

      <para>By default, only up to 100 object instances are returned by
      queries. This value can be changed by specifying:</para>

      <para><property>isis.persistor.sql.maxinstances=100</property></para>
    </sect1>

    <sect1>
      <title>Versioning</title>

      <para>Isis uses a version number to assist in detecting concurrency
      conflicts.</para>

      <para>However, if you need to turn off versioning completely, or for a
      particular table, you can control it with:</para>

      <para><property>isis.persistor.sql.default.versioning=false</property></para>

      <para>for global control, or by table:</para>

      <para><property>isis.persistor.sql.default.versioning.members=false</property></para>
    </sect1>

    <sect1>
      <title>Password values</title>

      <para>The <code>JdbcPasswordValueMapper</code> value mapper has the
      ability to (weakly) encode the password value strings stored in the
      database tables.</para>

      <para>By adding the following property values:</para>

      <blockquote>
        <para><property>isis.persistor.sql.default.password.seed=&lt;random
        string&gt;</property></para>

        <para><property>isis.persistor.sql.default.password.length=&lt;integer
        length&gt;</property></para>
      </blockquote>

      <para>You can enable a weak password encoding/decoding scheme that will
      obscure password values from casual browsers of your database
      tables.</para>

      <para>The length of all stored passwords is the same, and determined by
      the <property>isis.persistor.sql.default.password.length</property>
      property. This length must not exceed the SQL storage, as defined in
      <xref linkend="sec.mappers.modifiable-values" />.</para>

      <para>The passwords are convolved with the value of the string given by
      the <property>isis.persistor.sql.default.password.seed</property>
      property, and the resulting string is stored in the database
      table.</para>

      <para>If <property>isis.persistor.sql.default.password.seed</property>
      is undefined (null), the passwords are stored as plain text.</para>
    </sect1>
  </chapter>

  <chapter id="ch.supported.dbs">
    <title>Supported Database Servers</title>

    <abstract>
      <para>Which SQL database servers have been used?</para>
    </abstract>

    <sect1>
      <!--content: List of database servers tested.-->

      <title id="sec.servers.tested">Tested</title>

      <para>The following database servers are tested in the object store
      integration tests:<itemizedlist>
          <listitem>
            <para>HSQLDB (tested against 1.8.0.10)</para>
          </listitem>

          <listitem>
            <para>Postgresql (tested on 8.3.12-ubuntu9.04)</para>
          </listitem>

          <listitem>
            <para>MySQL (tested on 5.1.31-1ubuntu2)</para>
          </listitem>

          <listitem>
            <para>Microsoft SQL Server 2008 (Only from 2008 is DATE and TIME
            supported)</para>
          </listitem>
        </itemizedlist></para>

      <sect2>
        <title>HSQLDB</title>

        <para></para>
      </sect2>

      <sect2>
        <title>Postgresql</title>

        <para><blockquote>
            <para><property>isis.persistor.sql.jdbc.driver=org.hsqldb.jdbcDriver</property></para>

            <para><property>isis.persistor.sql.jdbc.connection=jdbc:hsqldb:file:hsql-db/tests</property></para>

            <para><property>isis.persistor.sql.jdbc.user=sa</property></para>

            <para><property>isis.persistor.sql.jdbc.password=</property></para>
          </blockquote>The default <classname>TimeStamp</classname> and
        <classname>DateTime</classname> SQL data class is DATETIME, which does
        not work on Postgresql. Here, the default must be replaced with the
        following properties file entries:</para>

        <blockquote>
          <para>isis.persistor.sql.datatypes.timestamp=TIMESTAMP</para>

          <para>isis.persistor.sql.datatypes.datetme=TIMESTAMP</para>

          <para>isis.persistor.sql.datatypes.double=DOUBLE PRECISION</para>
        </blockquote>

        <para></para>
      </sect2>

      <sect2>
        <title>MySQL</title>

        <para>There was an issue with storing and correctly retrieving date
        (time) values - a special "try .. catch" has been used to ensure that
        UTC temporal values are correctly retrieved.</para>

        <para>The following data type overrides may be required:</para>

        <blockquote>
          <para>isis.persistor.sql.datatypes.double=DOUBLE PRECISION</para>
        </blockquote>

        <para></para>
      </sect2>

      <sect2>
        <title>Microsoft SQL Server 2008</title>

        <para>The sourceforge driver seemed to work well enough for
        testing.</para>

        <para>The tested connection parameters were:</para>

        <para><blockquote>
            <para># SQL Server </para>

            <para>#isis.persistence.sql.jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver</para>

            <para>isis.persistence.sql.jdbc.driver=net.sourceforge.jtds.jdbc.Driver</para>

            <para>isis.persistence.sql.jdbc.connection=jdbc:jtds:sqlserver://&lt;server&gt;;databaseName=&lt;database&gt;</para>

            <para>isis.persistence.sql.jdbc.user=&lt;user&gt;</para>

            <para>isis.persistence.sql.jdbc.password=&lt;password&gt;</para>
          </blockquote></para>

        <para></para>
      </sect2>

      <sect2>
        <title>IBM DB2 (v8)</title>

        <para>Beware! This version of DB2 has a very small limit on table and
        column names. You will have to keep your domain class and property
        names short to suit, especially collections!</para>

        <para>The tested connection parameters were:</para>

        <blockquote>
          <para># DB2 test</para>

          <para>
          isis.persistence.sql.jdbc.driver=com.ibm.db2.jcc.DB2Driver</para>

          <para>
          isis.persistence.sql.jdbc.connection=jdbc:db2://&lt;host&gt;:50000/&lt;database&gt;</para>

          <para> isis.persistence.sql.jdbc.user=&lt;user&gt;</para>

          <para> isis.persistence.sql.jdbc.password=&lt;password&gt;</para>
        </blockquote>
      </sect2>
    </sect1>

    <sect1>
      <title>Tested values</title>

      <para>The following value types have been tested (stored and
      retrieved):</para>

      <itemizedlist>
        <listitem>
          <para>standard values: integer, short, long (INT), float, double
          (FLOAT), char (CHAR(2)).</para>
        </listitem>

        <listitem>
          <para>standard classes: Money (FLOAT and VARCHAR(3)), Percentage
          (FLOAT), Password (VARCHAR(12)), Color (INT), String (VARCHAR
          (65)).</para>
        </listitem>

        <listitem>
          <para>Special value mappers:</para>

          <itemizedlist>
            <listitem>
              <para><code>org.apache.isis.applib.value.date</code> and
              <code>java.sql.date</code> (DATE, via
              <code>org.apache.isis.alternatives.objectstore.sql.jdbc.JdbcDateMapper</code>)</para>
            </listitem>

            <listitem>
              <para>Time, DateTime (DATETIME), java.sql.Time, java.util.Date,
              java.sql.Timestamp (DATETIME), TimeStamp (DATETIME) blah</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para></para>
        </listitem>
      </itemizedlist>

      <para>Default automapper is installed by
      <code>org.apache.isis.alternatives.objectstore.sql.FieldMappingFactoryInstaller</code>
      ..</para>

      <para>Default automapper is
      <code>org.apache.isis.objectstore.sql.jdbc.installer.JdbcFieldMappingFactoryInstaller</code></para>

      <para></para>
    </sect1>
  </chapter>

  <chapter>
    <title id="sec.defaults">Defaults</title>

    <para>The SQL objectstore exposes several defaults that can be replaced
    either in configuration or at runtime.</para>

    <para>The class
    <code>org.apache.isis.objectstore.sql.Defaults</code>
    contains the following:</para>

    <para>Programmatic, at runtime:</para>

    <itemizedlist>
      <listitem>
        <para>TimeZone: <code>setTimeZone(DateTimeZone.UTC)</code></para>
      </listitem>
    </itemizedlist>

    <para>Configuration, e.g. in isis.properties:</para>

    <para><itemizedlist>
        <listitem>
          <para>Primary key column:</para>

          <para><property>isis.persistor.sql.default.pk_id=pk_id</property></para>
        </listitem>

        <listitem>
          <para>Service ID column:</para>

          <para><property>isis.persistor.sql.default.id=id</property></para>
        </listitem>

        <listitem>
          <para>Maximum records returned by objectstore methods that return a
          list/collection, such as <code>allMatches()</code>, etc:</para>

          <para><property><property>isis.persistor.sql.default.maxinstances=100</property></property></para>
        </listitem>

        <listitem>
          <para id="sec.defaults.tableprefix" xreflabel="Table Prefix">Table
          prefix. The default prefix "isis_" is added to all table created by
          the object store. This prefix can be replaced, or left off entirely
          by specifying an empty value, e.g.:</para>

          <para><property>isis.persistor.sql.default.tableprefix=</property></para>
        </listitem>

        <listitem>
          <para>See "Modifiable values", <link
          linkend="sec.mappers.modifiable-values">above</link>.</para>
        </listitem>
      </itemizedlist></para>
  </chapter>

  <chapter>
    <title>Polymorphism</title>

    <para>The SQL Objectstore supports polymorphic classes. Both properties
    and collections are supported.</para>

    <sect1>
      <title>Properties</title>

      <para>Polymorphic properties are handled with
      <classname>JdbcPolymorphicObjectReferenceMapping</classname>.</para>

      <para>Two columns are created in the class table: The actual instance
      class type, and the instance ID.</para>
    </sect1>

    <sect1>
      <title>Collections</title>

      <para>There are two implementations currently selectable by editting
      <classname>AbstractAutoMapper</classname>.</para>

      <para>The default implementation is
      <classname>PolymorphicForeignKeyInChildCollectionBaseMapper</classname>.</para>

      <sect2>
        <title>PolymorphicForeignKeyInChildCollectionBaseMapper</title>

        <para>Creates two columns in the child class table, to contain the
        child class type and child class ID.</para>

        <para>Used to map 1-to-many collections by creating, in the collection
        child table (which may be an interface or abstract class), 2 columns
        per parent collection.</para>

        <para>The first column is the class type, the second is the entity
        ID.</para>

        <para>The columns are named by combining the final part of the parent
        class name and the collection variable name.</para>

        <para>Collection loading is a case of iterating through all collection
        entries and adding the named class instance of the stored ID.</para>
      </sect2>

      <sect2>
        <title>PolymorphicForeignKeyInChildCollectionMapper</title>

        <para>Used to map 1-to-many collections by creating, in the child
        table, 1 column per parent collection.</para>

        <para>The column is named by combining the final part of the parent
        class name and the collection variable name.</para>

        <para>Collection loading is a case of iterating through all subclasses
        of the collection type and adding class instances of the stored ID.
        This could be problematic if different subclasses have the same
        ID.</para>
      </sect2>
    </sect1>
  </chapter>

  <appendix>
    <title>Example</title>

    <para></para>

    <para><property>isis.persistor.sql.jdbc.driver=com.mysql.jdbc.Driver</property></para>

    <para><property>isis.persistor.sql.jdbc.connection=jdbc:mysql://localhost/isis_data</property></para>

    <para><property>isis.persistor.sql.jdbc.user=isis</property></para>

    <para><property>isis.persistor.sql.jdbc.password=noneofyourbusiness</property></para>

    <para><property></property></para>

    <para><property>isis.persistor.sql.default.versioning.Member=false
    </property></para>

    <para><property>isis.persistor.sql.automapper.type.Member.address=VARCHAR(255)
    </property></para>

    <para><property>isis.persistor.sql.automapper.type.Member.comments=VARCHAR(255)
    </property></para>
  </appendix>

  <appendix>
    <title>Correspondence</title>

    <abstract>
      <para>Who said what, when?</para>
    </abstract>

    <sect1 id="sec.module-ui">
      <title>Email</title>

      <para></para>

      <sect2>
        <title>2011/02/01, Response by Dan Haywood</title>

        <para><remark>At the moment I'm just putting down whatever comes into
        my head, with a view of later editting it into a coherent document,
        but obviously there are questions of level of detail, etc. For
        example, should I really bother with describing what persistance is,
        and how the domain classes are introspected?! </remark></para>

        <para>I don't think so, no.</para>

        <para>That said, if you do find yourself writing "introductory"
        material like this, we can always move it. The place for such stuff
        should probably be the "core" documentation
        (core/src/docbkx/guide/isis-core.xml), which is what I'm chipping away
        at myself.</para>

        <para><remark>Yes to: what SQL data types are used by default, yes to:
        how to override the automappers and provide your own mapper, yes to:
        how collections and parent/child relatonships are handled, etc.
        </remark></para>

        <para>It'd be worth showing examples of all the different types of
        mappings supported, as well as those that are not supported.</para>

        <para>For example:</para>

        <itemizedlist>
          <listitem>
            <para>Id generation - how is that supported?</para>
          </listitem>

          <listitem>
            <para>optimistic locking - how supported?</para>
          </listitem>

          <listitem>
            <para>one&lt;-&gt;many</para>
          </listitem>

          <listitem>
            <para>one&lt;-many</para>
          </listitem>

          <listitem>
            <para>one-&gt;many</para>
          </listitem>

          <listitem>
            <para>two one&lt;-&gt;many relationships between same types A and
            B (if I recall, this isn't supported?)</para>
          </listitem>

          <listitem>
            <para>many&lt;-&gt;many</para>
          </listitem>

          <listitem>
            <para>many-&gt;many - subtype relationships (roll-up, roll-down,
            table per subtype)</para>
          </listitem>

          <listitem>
            <para>polymorphic relationships to interfaces</para>
          </listitem>
        </itemizedlist>

        <para>You could also peruse some of the Hibernate ORM docs for
        examples of mappings there; that might prompt you to consider some
        additional scenarios.</para>

        <para><remark>What else?</remark></para>

        <para>Obviously, any additional entries required in isis.properties to
        enable the SQL object store. In addition, as background it'd be worth
        explaining about the different subcomponents used by the object store:
        the OidGenerator, PersistAlgorithm, TransactionManager Also, I know
        that the JPA object store has to configure a different
        ClassSubstitutor/ObjectFactory, because it leaves the ORM to perform
        cglib proxying. I don't think you have any similar restrictions, but
        it might be worth saying so.</para>
      </sect2>
    </sect1>

    <sect1>
      <title>Edit History</title>

      <para>Last editted: Kevin, 17/10/2011.<!--dd/mm/yyyy--></para>
    </sect1>
  </appendix>
</book>