You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2014/10/05 04:06:23 UTC
svn commit: r1629461 - in /db/torque/torque4/trunk/torque-site/src/site:
resources/images/schema-database.png resources/images/schema-table.png
resources/images/schema-view.png
xdoc/documentation/orm-reference/defining-the-schema.xml
Author: tfischer
Date: Sun Oct 5 02:06:23 2014
New Revision: 1629461
URL: http://svn.apache.org/r1629461
Log:
TORQUE-329 Started to create better schema documentation
Added:
db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-database.png (with props)
db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-table.png (with props)
db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-view.png (with props)
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/defining-the-schema.xml
Added: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-database.png
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-database.png?rev=1629461&view=auto
==============================================================================
Binary file - no diff available.
Propchange: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-database.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-table.png
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-table.png?rev=1629461&view=auto
==============================================================================
Binary file - no diff available.
Propchange: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-table.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-view.png
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-view.png?rev=1629461&view=auto
==============================================================================
Binary file - no diff available.
Propchange: db/torque/torque4/trunk/torque-site/src/site/resources/images/schema-view.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/defining-the-schema.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/defining-the-schema.xml?rev=1629461&r1=1629460&r2=1629461&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/defining-the-schema.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/defining-the-schema.xml Sun Oct 5 02:06:23 2014
@@ -45,7 +45,6 @@
between databases.
</p>
<p>
-
It is recommended to ensure schema compliance
by adding xsd information into the root database element, e.g.
</p>
@@ -68,6 +67,17 @@
http://db.apache.org/torque/torque-4.0/documentation/orm-reference/database-4-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">
@@ -108,9 +118,155 @@
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 <table>
+ 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.
@@ -121,44 +277,101 @@
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 attributes and possible values, see the xsd
+ For more information and possible value ranges, see also the xsd
<a href="database-4-0.xsd">database-4-0.xsd</a>.
</p>
<p>
- The database element can have the following child elements
+ 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>
- <ul>
- <li>option (currently not used by the torque templates)</li>
- <li>include-schema (see above)</li>
- <li>external-schema (see above)</li>
- <li>domain (definition of common data types, see below)</li>
- <li>table (see below)</li>
- <li>view (see below)</li>
- </ul>
</subsection>
- <subsection name="domains">
+
+ <subsection name="Tables">
<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.
+ <img src="../../images/schema-table.png"/>
</p>
- </subsection>
-
- <subsection name="tables">
<p>
- Tables are defined by the table element.
+ 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 below for reasons).
- Torque supports composite primary keys; to create one simply set
+ (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").
+ 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
@@ -171,10 +384,145 @@
"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.
@@ -213,6 +561,190 @@
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>
+ </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>default</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>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>
+ </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">
@@ -255,177 +787,371 @@
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 an additional primary key which
+ If you use a primary key which
has no meaning in real life, you do not run into that trouble.
</p>
</subsection>
- <subsection name="views">
+ <subsection name="Foreign keys">
<p>
- Views behave much as tables, except that they cannot be written to.
- and that they usually reference data from other tables.
+ 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 view definition must contain the column names and types.
+ A reference defines a link between local and foreign column
+ for a foreign-key element.
</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"".
- 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>
+ 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="example schema file">
+
+ <subsection name="Index">
<p>
- For an example schema file conaining most of the discussed features,
- look at the bookstore-schema.xml from the test project.
+ 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>
- </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">
+
+ <subsection name="Index Column">
<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.
+ 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="Databases with different structures">
+
+ <subsection name="Unique">
<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.
+ 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>
- 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.
+ 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>
- </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 <table>
- 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>
+ <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>
- <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>
+ <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>
- </section>
-
- <section name="Creating a schema from an existing database">
+ <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>
+ </subsection>
- <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>
+ <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>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org