<?xml version="1.0"?>
<document url="http://castor.org/srcgen-properties.xml">

  <properties>
    <title>Castor DDL Generator -- Properties</title>
    <author email="ralf DOT joachim AT syscon DOT eu">Ralf Joachim</author>
    <abstract>
       Describes properties of the Castor DDL Generator.
    </abstract>
    <status>Draft</status>
  </properties>

  <body>

    <title>Castor DDL Generator - Properties</title>

    <section title="Overview">

      <p>
        At startup, the DDL Generator first evaluates the command line options.
        Next it loads the global properties on the command line if specified,
        otherwise the default properties included with the DDL Generator.
        There are two important properties loaded at startup:
      </p>
      <dl>
        <dt><tt>org.castor.ddlgen.Generators</tt></dt>
        <dd>tells the DDL Generator about the supported database engines.</dd>
        <dt><tt>org.castor.ddlgen.DefaultEngine</tt></dt>
        <dd>
          The database engine for which to generate a SQL script.  Can be
          overridden on the command line.
        </dd>
      </dl>
      <p>
        The last step at startup is to read the specific configuration of the
        database engine being used.  A custom configuration can be provided on
        the command line to override the default.
      </p>

    </section>

    <section title="Global properties">

      <p>
        Below you can find a list of global properties to control various advanced
        options of the DDL Generator.
      </p>

      <ctable>
        <cheader>
          <th align="center">Option</th>
          <th>Description</th>
          <th>Values</th>
          <th>Default</th>
          <th>Since</th>
        </cheader>
        <crow>
          <td>org.castor.ddlgen.Generators</td>
          <td>Generator classes of supported database engines.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.DefaultEngine</td>
          <td>Name of default database engine. Will be overwritten by engine specified
              on commandline.</td>
          <td><i>db2</i>, <i>derby</i>, <i>hsql</i>, <i>mssql</i>, <i>mysql</i>,
              <i>oracle</i>, <i>pointbase</i>, <i>postgresql</i>, <i>sapdb</i> or
              <i>sybase</i></td>
          <td><i>mysql</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.SchemaName</td>
          <td>Name of the database schema.</td>
          <td><br/></td>
          <td><i>test</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GroupStatements</td>
          <td>How to group generated DDL statements?</td>
          <td><i>TABLE</i> or <i>DDLTYPE</i></td>
          <td><i>TABLE</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.CharFormat</td>
          <td>How to format characters of generated DDL statements?</td>
          <td><i>SENSITIVE</i>, <i>UPPER</i> or <i></i>LOWER</td>
          <td><i>SENSITIVE</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.Newline</td>
          <td>Character sequence to write for newline.</td>
          <td><br/></td>
          <td><i>\n</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.Indention</td>
          <td>Character sequence to write for indented lines.</td>
          <td><br/></td>
          <td><i>\t</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateSchema</td>
          <td>Generate SCHEMA statements.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateDrop</td>
          <td>Generate DROP statements.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateCreate</td>
          <td>Generate CREATE statements.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GeneratePrimaryKey</td>
          <td>Generate PRIMARYKEY statement.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateForeignKey</td>
          <td>Generate FOREIGNKEY statement.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateIndex</td>
          <td>Generate INDEX statements (Not supported yet).</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>false</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>org.castor.ddlgen.GenerateKeyGenerator</td>
          <td>Generate KEYGENERATOR statements.</td>
          <td><i>true</i> or <i>false</i></td>
          <td><i>true</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_tinyint_precision</td>
          <td>Default precision of tinyint values.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_smallint_precision</td>
          <td>Default precision of smallint values.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_integer_precision</td>
          <td>Default precision of integer values.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_bigint_precision</td>
          <td>Default precision of bigint values.</td>
          <td><br/></td>
          <td><i>19</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_bigint_decimals</td>
          <td>Default decimals of bigint values.</td>
          <td><br/></td>
          <td><i>0</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_float_precision</td>
          <td>Default precision of float values.</td>
          <td><br/></td>
          <td><i>38</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td></td>
          <td>Default precision of tinyint values.</td>
          <td><br/></td>
          <td><i></i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_float_decimals</td>
          <td>Default decimals of float values.</td>
          <td><br/></td>
          <td><i>7</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_double_precision</td>
          <td>Default precision of double values.</td>
          <td><br/></td>
          <td><i>53</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_double_decimals</td>
          <td>Default decimals of double values.</td>
          <td><br/></td>
          <td><i>15</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_real_precision</td>
          <td>Default precision of real values.</td>
          <td><br/></td>
          <td><i>38</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_real_decimals</td>
          <td>Default decimals of real values.</td>
          <td><br/></td>
          <td><i>7</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_numeric_precision</td>
          <td>Default precision of numeric values.</td>
          <td><br/></td>
          <td><i>65</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_numeric_decimals</td>
          <td>Default decimals of numeric values.</td>
          <td><br/></td>
          <td><i>30</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_decimal_precision</td>
          <td>Default precision of decimal values.</td>
          <td><br/></td>
          <td><i>65</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_decimal_decimals</td>
          <td>Default decimals of decimal values.</td>
          <td><br/></td>
          <td><i>30</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_char_length</td>
          <td>Default length of char values.</td>
          <td><br/></td>
          <td><i>256</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_varchar_length</td>
          <td>Default length of varchar values.</td>
          <td><br/></td>
          <td><i>256</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_longvarchar_length</td>
          <td>Default length of longvarchar values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_date_precision</td>
          <td>Default precision of date values.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_time_precision</td>
          <td>Default precision of time values.</td>
          <td><br/></td>
          <td><br/></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_timestamp_precision</td>
          <td>Default precision of timestamp values.</td>
          <td><br/></td>
          <td><i>19</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_binary_length</td>
          <td>Default length of binary values.</td>
          <td><br/></td>
          <td><i>256</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_varbinary_length</td>
          <td>Default length of varbinary values.</td>
          <td><br/></td>
          <td><i>256</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_longvarbinary_length</td>
          <td>Default length of longvarbinary values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_other_length</td>
          <td>Default length of other values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_javaobject_length</td>
          <td>Default length of javaobject values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_blob_length</td>
          <td>Default length of blob values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
        <crow>
          <td>default_clob_length</td>
          <td>Default length of clob values.</td>
          <td><br/></td>
          <td><i>1024</i></td>
          <td>1.1</td>
        </crow>
      </ctable>

      <section title="Supported database engines">

        <p>
          The supported database engines are defined as follows:
        </p>

        <code-panel><![CDATA[
#
# generator classes of supported database engines
#
org.castor.ddlgen.Generators=\
  org.castor.ddlgen.engine.db2.Db2Generator,\
  org.castor.ddlgen.engine.derby.DerbyGenerator,\
  org.castor.ddlgen.engine.hsql.HsqlGenerator,\
  org.castor.ddlgen.engine.mssql.MssqlGenerator,\
  org.castor.ddlgen.engine.mysql.MysqlGenerator,\
  org.castor.ddlgen.engine.oracle.OracleGenerator,\
  org.castor.ddlgen.engine.pointbase.PointBaseGenerator,\
  org.castor.ddlgen.engine.postgresql.PostgresqlGenerator,\
  org.castor.ddlgen.engine.sapdb.SapdbGenerator,\
  org.castor.ddlgen.engine.sybase.SybaseGenerator]]></code-panel>

      </section>

      <section title="Grouping of DDL statements">

        <p>
          There are 2 supported modes to group DDL statements. For a simple example, the
          output of both modes is:
        </p>

        <code-panel top-caption="org.castor.ddlgen.GroupStatements=TABLE"><![CDATA[
drop A if exist
create A(IDA int);
alter table A add primary key (IDA)

drop B if exist
create B(IDB int);
alter table B add primary key (IDB)]]></code-panel>

        <code-panel top-caption="org.castor.ddlgen.GroupStatements=DDLTYPE"><![CDATA[
drop A if exist
drop B if exist

create A(IDA int);
create B(IDB int);

alter table A add primary key (IDA)
alter table B add primary key (IDB)]]></code-panel>

      </section>

    </section>

    <section title="Specific properties">

      <p>
        Below you can find a list of specific properties to control various advanced
        options of the DDL Generator.
      </p>

      <section title="Properties common for all database engines">

        <ctable>
          <cheader>
            <th align="center">Option</th>
            <th>Description</th>
            <th>Values</th>
            <th>Default</th>
            <th>Since</th>
          </cheader>
          <crow>
            <td>org.castor.ddlgen.KeyGeneratorFactories</td>
            <td>Key generator factory classes supported by DB/2.</td>
            <td><br/></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
          <crow>
            <td>org.castor.ddlgen.HeaderComment</td>
            <td>Comment to add to head of generated script.</td>
            <td><br/></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
        </ctable>

        <section title="Key generators">

          <p>
            The key generators supported by a database engine are defined as follows
            (example taken from Oracle):
          </p>

          <code-panel><![CDATA[
#
# key generator factory classes of supported database engines
#
org.castor.ddlgen.KeyGeneratorFactories=\
  org.castor.ddlgen.keygenerator.HighLowKeyGeneratorFactory,\
  org.castor.ddlgen.keygenerator.MaxKeyGeneratorFactory,\
  org.castor.ddlgen.keygenerator.UUIDKeyGeneratorFactory,\
  org.castor.ddlgen.engine.oracle.OracleSequenceKeyGeneratorFactory]]></code-panel>

        </section>

      </section>

      <section title="Properties for db2, hsql, Oracle, Postgresql and sapdb">

        <ctable>
          <cheader>
            <th align="center">Option</th>
            <th>Description</th>
            <th>Values</th>
            <th>Default</th>
            <th>Since</th>
          </cheader>
          <crow>
            <td>org.castor.ddlgen.TriggerTemplate</td>
            <td>Template to create TRIGGER statements.</td>
            <td><br/></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
        </ctable>

        <section title="Trigger template">

          <p>
            Below you can take a look at the default trigger template defined for Oracle.
            The DDL Generator will replace the parameters in brackets with appropriate
            values (e.g. &lt;table_name&gt;).
          </p>

          <code-panel><![CDATA[
#
# trigger template
#
org.castor.ddlgen.TriggerTemplate=\
CREATE TRIGGER <trigger_name>\n\t\
  BEFORE INSERT OR UPDATE ON <table_name>\n\t\
  FOR EACH ROW\n\t\
  DECLARE\n\t\t\
    iCounter <table_name>.<pk_name>%TYPE;\n\t\t\
    cannot_change_counter EXCEPTION;\n\t\
  BEGIN\n\t\t\
    IF INSERTING THEN\n\t\t\t\
      Select <sequence_name>.NEXTVAL INTO iCounter FROM Dual;\n\t\t\t\
      :new.<pk_name> := iCounter;\n\t\t\
    END IF;\n\t\
\n\t\t\
    IF UPDATING THEN\n\t\t\t\
      IF NOT (:new.<pk_name> = :old.<pk_name>) THEN\n\t\t\t\t\
        RAISE cannot_change_counter;\n\t\t\t\
      END IF;\n\t\t\
    END IF;\n\t\
\n\t\
EXCEPTION\n\t\t\
  WHEN cannot_change_counter THEN\n\t\t\t\
    raise_application_error(-20000, 'Cannot Change Counter Value');\n\t\
END;]]></code-panel>

        </section>

      </section>

      <section title="Properties for MySQL only">

        <ctable>
          <cheader>
            <th align="center">Option</th>
            <th>Description</th>
            <th>Values</th>
            <th>Default</th>
            <th>Since</th>
          </cheader>
          <crow>
            <td>org.castor.ddlgen.engine.mysql.StorageEngine</td>
            <td>Storage engine to be used. If left empty the default configured at the
                database server will be used.</td>
            <td><i>MYISAM</i>, <i>InnoDB</i>, <i>MERGE</i>, <i>MEMORY</i>, <i>BDB</i> or
                <i>ISAM</i></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
          <crow>
            <td>org.castor.ddlgen.engine.mysql.ForeignKeyOnDeleteStrategy</td>
            <td>Delete strategy for foreign keys. If not specified <i>NO ACTION</i>
                will be used by default.</td>
            <td><i>CASCADE</i>, <i>RESTRICT</i>, <i>SET NULL</i>, <i>NO ACTION</i></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
          <crow>
            <td>org.castor.ddlgen.engine.mysql.ForeignKeyOnUpdateStrategy</td>
            <td>Update strategy for foreign keys. If not specified <i>NO ACTION</i>
                will be used by default.</td>
            <td><i>CASCADE</i>, <i>RESTRICT</i>, <i>SET NULL</i>, <i>NO ACTION</i></td>
            <td><br/></td>
            <td>1.1</td>
          </crow>
        </ctable>

      </section>

    </section>

  </body>

</document>
