You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2016/12/08 08:15:46 UTC
cayenne git commit: postrelease docs editing
Repository: cayenne
Updated Branches:
refs/heads/master 1e01dc871 -> 6caca2f61
postrelease docs editing
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/6caca2f6
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/6caca2f6
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/6caca2f6
Branch: refs/heads/master
Commit: 6caca2f61b4e3bc37703e37ff37d2cba4a388a70
Parents: 1e01dc8
Author: Andrus Adamchik <an...@objectstyle.com>
Authored: Thu Dec 8 10:31:10 2016 +0300
Committer: Andrus Adamchik <an...@objectstyle.com>
Committed: Thu Dec 8 11:14:23 2016 +0300
----------------------------------------------------------------------
.../src/docbkx/including-cayenne-in-project.xml | 54 ++-
docs/docbook/cayenne-guide/src/docbkx/part4.xml | 7 +-
.../cayenne-guide/src/docbkx/re-filtering.xml | 336 +++++++++----------
.../src/docbkx/re-introduction.xml | 149 +++-----
.../cayenne-guide/src/docbkx/re-modeler.xml | 10 +-
.../src/docbkx/re-name-generator.xml | 79 -----
.../src/docbkx/re-other-settings.xml | 65 ++++
.../docbkx/re-relationships-loading-control.xml | 93 -----
.../cayenne-guide/src/docbkx/re-table-types.xml | 40 ---
.../src/docbkx/re-types-mapping.xml | 120 -------
10 files changed, 293 insertions(+), 660 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
index 307a16c..aba358b 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
@@ -453,22 +453,20 @@
<tr>
<td><code>forceDataMapCatalog</code></td>
<td>boolean</td>
- <td>
- Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
- may some time be undesirable. If this is the case then setting <code>forceDataMapCatalog</code>
- to <code>true</code> will set DbEntity catalog to one in the DataMap.
- Default value <code>false</code>.
- </td>
+ <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
+ may sometimes be undesirable. If this is the case then setting
+ <code>forceDataMapCatalog</code> to <code>true</code> will set
+ DbEntity catalog to one in the DataMap. Default value is
+ <code>false</code>. </td>
</tr>
<tr>
<td><code>forceDataMapSchema</code></td>
<td>boolean</td>
- <td>
- Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
- may some time be undesirable. If this is the case then setting <code>forceDataMapSchema</code>
- to <code>true</code> will set DbEntity schema to one in the DataMap.
- Default value <code>false</code>.
- </td>
+ <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
+ may sometimes be undesirable. If this is the case then setting
+ <code>forceDataMapSchema</code> to <code>true</code> will set
+ DbEntity schema to one in the DataMap. Default value is
+ <code>false</code>. </td>
</tr>
<tr>
<td><code>meaningfulPkTables</code></td>
@@ -493,35 +491,30 @@
<tr xml:id="cdbimport-rr-parameter">
<td><code>reverseEngineering</code></td>
<td>XML</td>
- <td>
- An object that contains detailed reverse engineering rules about
- what DB objects should be processed.
- For full information about this parameter see
- <link linkend="re-introduction">reverse engineering</link> chapter.
- Here is some simple example:
- <programlisting language="xml"><reverseEngineering>
+ <td> An object that contains detailed reverse engineering rules about what DB objects should
+ be processed. For full information about this parameter see <link
+ linkend="re-introduction">"DB-First Flow</link> chapter. Here is
+ some simple example:
+ <programlisting language="xml"><reverseEngineering>
<skipRelationshipsLoading>false</skipRelationshipsLoading>
<skipPrimaryKeyLoading>false</skipPrimaryKeyLoading>
<catalog name="test_catalog">
<schema name="test_schema">
- <includeTable pattern=".*"/>
- <excludeTable>test_table</excludeTable>
+ <includeTable>".*"</includeTable>
+ <excludeTable>test_table</excludeTable>
</schema>
</catalog>
<includeProcedure pattern=".*"/>
</reverseEngineering></programlisting>
-
- </td>
+ </td>
</tr>
<tr>
<td><code>stripFromTableNames</code></td>
<td>String</td>
- <td>
- Regex that matches the part of the table name that needs to be stripped off.
- Here is some examples:
- <programlisting language="xml"><![CDATA[<!-- Strip prefix -->
+ <td>Regex that matches the part of the table name that needs to be stripped off when
+ generating ObjEntity name. Here are some examples: <programlisting language="xml"><![CDATA[<!-- Strip prefix -->
<stripFromTableNames>^myt_</stripFromTableNames>
<!-- Strip suffix -->
@@ -529,7 +522,7 @@
<!-- Strip multiple occurrences in the middle -->
<stripFromTableNames>_abc</stripFromTableNames>]]></programlisting>
- </td>
+ </td>
</tr>
<tr>
<td><code>username</code></td>
@@ -539,9 +532,8 @@
<tr>
<td><code>usePrimitives</code></td>
<td>boolean</td>
- <td>Whether numberic and boolean data types should be mapped as Java
- primitives or Java classes. Default is "true", i.e. primitives will
- be used.</td>
+ <td>Whether numeric and boolean data types should be mapped as Java primitives or Java
+ classes. Default is "true", i.e. primitives will be used.</td>
</tr>
</tbody>
</table>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/part4.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part4.xml b/docs/docbook/cayenne-guide/src/docbkx/part4.xml
index 9f15bbd..76ea83e 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/part4.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/part4.xml
@@ -16,12 +16,9 @@
-->
<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cayenne-guide-part4" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Cayenne Framework - Reverse Engineering </title>
+ <title>DB-First Flow</title>
<xi:include href="re-introduction.xml"/>
<xi:include href="re-filtering.xml"/>
- <xi:include href="re-relationships-loading-control.xml"/>
- <xi:include href="re-name-generator.xml"/>
- <xi:include href="re-table-types.xml"/>
- <xi:include href="re-types-mapping.xml"/>
+ <xi:include href="re-other-settings.xml"/>
<xi:include href="re-modeler.xml"/>
</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
index 00316c9..a4a53f3 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
@@ -35,7 +35,7 @@
The simplest example of reverse engineering is processing tables from one schema of catalog and there are several options to do this.
Basic syntax is described below:
</para>
- <programlisting language="xml">
+ <programlisting language="xml"><reverseEngineering>
<!-- Ant/Maven in case you only want to specify the schema to import -->
<schema>SCHEMA_NAME</schema>
@@ -49,11 +49,11 @@
<schema name="SCHEMA_NAME">
...
</schema>
- </programlisting>
+</reverseEngineering> </programlisting>
<para>
The same options are available for catalogs:
</para>
- <programlisting language="xml">
+ <programlisting language="xml"> <reverseEngineering>
<!-- Ant/Maven in case you only want to specify the catalog to import -->
<catalog>CATALOG_NAME</catalog>
@@ -66,7 +66,8 @@
<!-- Ant way in case you have nested elements in the catalog -->
<catalog name="CATALOG_NAME">
...
- </catalog></programlisting>
+ </catalog>
+</reverseEngineering></programlisting>
<note>
<para>Current version of reverse engineering doesn't support catalog filtering for Postgres database.</para>
</note>
@@ -77,32 +78,28 @@
Cayenne supports combination of different schemas and catalogs, and it filters data according to your requirements.
You could achieve this by the following example of reverse engineering configuration:
</para>
- <programlisting language="xml"><configuration>
- ...
- <reverseEngineering>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- </reverseEngineering>
- ...
-</configuration></programlisting>
+ <programlisting language="xml"><reverseEngineering>
+
+ <catalog>
+ <name>shop_01</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-02</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_02</name>
+ <schema>schema-name-01</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_03</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-02</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+</reverseEngineering></programlisting>
<para>
In the example above, Cayenne reverse engineering process contains three catalogs named as shop_01, shop_02 and shop_03,
each of wich has their own schemas. Cayenne will load all data only from the declared catalogs and schemas.
@@ -110,45 +107,37 @@
<para>
If you want to load everything from database, you could simply declare catalog specification alone.
</para>
- <programlisting language="xml"><configuration>
- ...
- <reverseEngineering>
+ <programlisting language="xml"><reverseEngineering>
- <catalog>shop_01</catalog>
- <catalog>shop_02</catalog>
- <catalog>shop_03</catalog>
+ <catalog>shop_01</catalog>
+ <catalog>shop_02</catalog>
+ <catalog>shop_03</catalog>
- </reverseEngineering>
- ...
-</configuration></programlisting>
+</reverseEngineering></programlisting>
<para>
If you want to do reverse engineering for specific schemas, just remove unwanted schemas from the catalog section.
For example, if you want to process schema-name-01 and schema-name-03 schemas only, then you should change reverse engineering section like this.
</para>
- <programlisting language="xml"><configuration>
- ...
- <reverseEngineering>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- </reverseEngineering>
- ...
-</configuration></programlisting>
+ <programlisting language="xml"><reverseEngineering>
+
+ <catalog>
+ <name>shop_01</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_02</name>
+ <schema>schema-name-01</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_03</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+</reverseEngineering></programlisting>
</section>
<section xml:id="including-excluding-tables-columns-procedures">
<title>Including and Excluding tables, columns and procedures</title>
@@ -161,65 +150,57 @@
<orderedlist numeration="arabic">
<listitem>
<para>Include tables with \u2018CRM_\u2019 prefix if you are working in that domain of application:</para>
- <programlisting language="xml">
- <includeTable>CRM_.*</includeTable></programlisting>
+ <programlisting language="xml"><includeTable>CRM_.*</includeTable></programlisting>
</listitem>
<listitem>
<para>Include tables with \u2018_LOOKUP\u2019 suffix</para>
- <programlisting language="xml">
- <includeTable>
- <pattern>.*_LOOKUP</pattern>
- </includeTable></programlisting>
+ <programlisting language="xml"><includeTable>
+ <pattern>.*_LOOKUP</pattern>
+</includeTable></programlisting>
</listitem>
<listitem>
<para>Exclude tables with \u2018CRM_\u2019 prefix if you are not working only in that domain of application:</para>
- <programlisting language="xml">
- <excludeTable>CRM_.*</excludeTable></programlisting>
+ <programlisting language="xml"><excludeTable>CRM_.*</excludeTable></programlisting>
</listitem>
<listitem>
<para>Include only specific columns that follows specific naming convention:</para>
- <programlisting language="xml">
- <includeColumn>includeColumn01</includeColumn>
- <includeColumn>includeColumn03</includeColumn></programlisting>
+ <programlisting language="xml"><includeColumn>includeColumn01</includeColumn>
+<includeColumn>includeColumn03</includeColumn></programlisting>
</listitem>
<listitem>
<para>Exclude system or obsolete columns:</para>
- <programlisting language="xml">
- <excludeColumn>excludeColumn01</excludeColumn>
- <excludeColumn>excludeColumn03</excludeColumn></programlisting>
+ <programlisting language="xml"><excludeColumn>excludeColumn01</excludeColumn>
+<excludeColumn>excludeColumn03</excludeColumn></programlisting>
</listitem>
<listitem>
<para>Include/Exclude columns for particular table or group of tables:</para>
- <programlisting language="xml">
- <includeTable>
- <pattern>table pattern</pattern>
- <includeColumn>includeColumn01</includeColumn>
- <excludeColumn>excludeColumn01</excludeColumn>
- </includeTable></programlisting>
+ <programlisting language="xml"><includeTable>
+ <pattern>table pattern</pattern>
+ <includeColumn>includeColumn01</includeColumn>
+ <excludeColumn>excludeColumn01</excludeColumn>
+</includeTable></programlisting>
</listitem>
<listitem>
<para>Include stored procedures:</para>
- <programlisting language="xml">
- <includeProcedure>includeProcedure01</includeProcedure>
- <includeProcedure>
- <pattern>includeProcedure03</pattern>
- </includeProcedure></programlisting>
+ <programlisting language="xml"><includeProcedure>includeProcedure01</includeProcedure>
+<includeProcedure>
+ <pattern>includeProcedure03</pattern>
+</includeProcedure></programlisting>
</listitem>
<listitem>
<para>Exclude stored procedures by pattern:</para>
- <programlisting language="xml">
- <excludeProcedure>excludeProcedure01</excludeProcedure>
- <excludeProcedure>
- <pattern>excludeProcedure03</pattern>
- </excludeProcedure></programlisting>
+ <programlisting language="xml"><excludeProcedure>excludeProcedure01</excludeProcedure>
+<excludeProcedure>
+ <pattern>excludeProcedure03</pattern>
+</excludeProcedure></programlisting>
</listitem>
</orderedlist>
</para>
- <para>
- All filtering tags <code><includeTable></code>, <code><excludeTable></code>, <code><includeColumn></code>, <code><excludeColumn></code>,
- <code><includeProcedure></code> and <code><excludeProcedure></code> have three ways
- to pass filtering RegExp.
- <orderedlist numeration="arabic">
+ <para> All filtering tags <code><includeTable></code>,
+ <code><excludeTable></code>, <code><includeColumn></code>,
+ <code><excludeColumn></code>, <code><includeProcedure></code> and
+ <code><excludeProcedure></code> have 2 ways to pass filtering RegExp.
+ <orderedlist numeration="arabic">
<listitem>
<para>text inside tag</para>
<programlisting language="xml">
@@ -232,11 +213,6 @@
<pattern>.*_LOOKUP</pattern>
</includeTable></programlisting>
</listitem>
- <listitem>
- <para>pattern attribute (only for Ant task)</para>
- <programlisting language="xml">
- <excludeProcedure pattern="excludeProcedure03"/></programlisting>
- </listitem>
</orderedlist>
</para>
<para>
@@ -249,22 +225,20 @@
<para>
Initially, let\u2019s make a small sample. Consider the following reverse engineering configuration.
</para>
- <programlisting language="xml">
- <reverseEngineering>
- <catalog>shop-01</catalog>
- </reverseEngineering></programlisting>
+ <programlisting language="xml"><reverseEngineering>
+ <catalog>shop-01</catalog>
+</reverseEngineering> </programlisting>
<para>
In this case reverse engineering will not filter anything from the shop-01 catalog. If you really want to filter database columns, tables,
stored procedures and relationships, you could do it in the following way.
</para>
- <programlisting language="xml">
- <reverseEngineering>
- <catalog>shop-01</catalog>
- <catalog>
- <name>shop-02</name>
- <includeTable>includeTable-01</includeTable>
- </catalog>
- </reverseEngineering></programlisting>
+ <programlisting language="xml"><reverseEngineering>
+ <catalog>shop-01</catalog>
+ <catalog>
+ <name>shop-02</name>
+ <includeTable>includeTable-01</includeTable>
+ </catalog>
+</reverseEngineering></programlisting>
<para>
Then Cayenne will do reverse engineering for both shop-01 and shop-02 catalogs. First catalog will not be processed for filtering,
but the second catalog will be processed with \u201cincludeTable-01\u201d filter.
@@ -275,66 +249,64 @@
They make your configuration more readable, understandable and straightforward. There is not complex.
Let\u2019s see how to use patterns in reverse engineering configuration with complete example.
</para>
- <programlisting language="xml">
- <reverseEngineering>
+ <programlisting language="xml"><reverseEngineering>
- <catalog>shop-01</catalog>
+ <catalog>shop-01</catalog>
- <catalog>
- <name>shop-02</name>
- </catalog>
+ <catalog>
+ <name>shop-02</name>
+ </catalog>
- <catalog>
- <name>shop-03</name>
- <includeTable>includeTable-01</includeTable>
+ <catalog>
+ <name>shop-03</name>
+ <includeTable>includeTable-01</includeTable>
- <includeTable>
- <pattern>includeTable-02</pattern>
- </includeTable>
+ <includeTable>
+ <pattern>includeTable-02</pattern>
+ </includeTable>
- <includeTable>
- <pattern>includeTable-03</pattern>
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
+ <includeTable>
+ <pattern>includeTable-03</pattern>
+ <includeColumn>includeColumn-01</includeColumn>
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ </includeTable>
- <excludeTable>excludeTable-01</excludeTable>
+ <excludeTable>excludeTable-01</excludeTable>
- <excludeTable>
- <pattern>excludeTable-02</pattern>
- </excludeTable>
+ <excludeTable>
+ <pattern>excludeTable-02</pattern>
+ </excludeTable>
- <includeColumn>includeColumn-01</includeColumn>
+ <includeColumn>includeColumn-01</includeColumn>
- <includeColumn>
- <pattern>includeColumn-02</pattern>
- </includeColumn>
+ <includeColumn>
+ <pattern>includeColumn-02</pattern>
+ </includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
+ <excludeColumn>excludeColumn-01</excludeColumn>
- <excludeColumn>
- <pattern>excludeColumn-02</pattern>
- </excludeColumn>
+ <excludeColumn>
+ <pattern>excludeColumn-02</pattern>
+ </excludeColumn>
- <includeProcedure>includeProcedure-01</includeProcedure>
+ <includeProcedure>includeProcedure-01</includeProcedure>
- <includeProcedure>
- <pattern>includeProcedure-02</pattern>
- </includeProcedure>
+ <includeProcedure>
+ <pattern>includeProcedure-02</pattern>
+ </includeProcedure>
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
+ <excludeProcedure>excludeProcedure-01</excludeProcedure>
- <excludeProcedure>
- <pattern>excludeProcedure-02</pattern>
- </excludeProcedure>
+ <excludeProcedure>
+ <pattern>excludeProcedure-02</pattern>
+ </excludeProcedure>
- </catalog>
- </reverseEngineering></programlisting>
- <para>
- The example above should provide you more idea about how to use filtering and patterns in Cayenne reverse engineering.
- You could notice that this example demonstrates you the "name" and "pattern" configurations. Yes, you could use these as separates xml element
- and xml attributes.
- </para>
+ </catalog>
+</reverseEngineering></programlisting>
+ <para>The example above should provide you more idea about how to use filtering and patterns
+ in Cayenne reverse engineering. You could notice that this example demonstrates you the
+ "name" and "pattern" configurations. Yes, you could use these as separates xml element
+ and xml attributes. </para>
<para>
The cdbimport will execute reverse engineering task for all entities from \u201cshop-01\u201d and \u201cshop-02\u201d, including tables, views, stored procedures
and table columns. As \u201cshop-03\u201d has variety filter tags, entities from this catalog will be filtered by cdbimport.
@@ -342,40 +314,38 @@
</section>
<section>
<title>Ant configuration example</title>
- <para>
- Here is config sample for <code>Ant</code> task:
- <programlisting language="xml">
-<!-- inside <cdbimport> tag -->
- <catalog>shop-01</catalog>
+ <para> Here is config sample for <code>Ant</code> task:
+ <programlisting language="xml"><!-- inside <cdbimport> tag -->
+<catalog>shop-01</catalog>
- <catalog name="shop-02"/>
+<catalog name="shop-02"/>
- <catalog name="shop-03">
+<catalog name="shop-03">
- <includeTable>includeTable-01</includeTable>
- <includeTable pattern="includeTable-02"/>
+ <includeTable>includeTable-01</includeTable>
+ <includeTable pattern="includeTable-02"/>
- <includeTable pattern="includeTable-03">
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
+ <includeTable pattern="includeTable-03">
+ <includeColumn>includeColumn-01</includeColumn>
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ </includeTable>
- <excludeTable>excludeTable-01</excludeTable>
- <excludeTable pattern="excludeTable-02"/>
+ <excludeTable>excludeTable-01</excludeTable>
+ <excludeTable pattern="excludeTable-02"/>
- <includeColumn>includeColumn-01</includeColumn>
- <includeColumn pattern="includeColumn-02"/>
+ <includeColumn>includeColumn-01</includeColumn>
+ <includeColumn pattern="includeColumn-02"/>
- <excludeColumn>excludeColumn-01</excludeColumn>
- <excludeColumn pattern="excludeColumn-02"/>
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ <excludeColumn pattern="excludeColumn-02"/>
- <includeProcedure>includeProcedure-01</includeProcedure>
- <includeProcedure pattern="includeProcedure-02"/>
+ <includeProcedure>includeProcedure-01</includeProcedure>
+ <includeProcedure pattern="includeProcedure-02"/>
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
- <excludeProcedure pattern="excludeProcedure-02"/>
+ <excludeProcedure>excludeProcedure-01</excludeProcedure>
+ <excludeProcedure pattern="excludeProcedure-02"/>
- </catalog></programlisting>
+</catalog></programlisting>
</para>
<note>
<para>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
index ca2a7fa..f65bc52 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
@@ -16,18 +16,46 @@
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0" xml:id="re-introduction">
- <title>Reverse Engineering Introduction</title>
+ <title>Introduction</title>
<section xml:id="what-is-cdbimport">
- <title>What is CDBImport</title>
- <para>
- CDBImport is a Maven/Ant plugin that helps you to do reverse engineering. In other words it helps you to synchronize
- database structure with your Cayenne mapping config. It does not update Java classes by itself, but it synchronizes db
- and data access layer representation in Cayenne mapping file with actual database state.
- Most common practice to complete reverse engineering is to use CDBImport followed by <link linkend="mvn-cgen">CGen Maven plugin</link>,
- which does class generation according to the Cayenne mapping file updates.
- </para>
+ <title>"DB-first" Flow</title>
+ <para>An ORM system consists of three parts: database, OR mapping and persistent Java classes.
+ These parts always need to be kept in sync with each other for the application to work.
+ "DB-first" flow is a common and practical approach to synchronization that assumes the
+ database to be the master source of the metadata, with other two parts synchronized from
+ the DB as the schema evolves. Cayenne provides a number of tools to automate and control
+ it. Here is how "DB-first" flow is typically implemented:<itemizedlist>
+ <listitem>
+ <para> A SQL migrations framework is used to bring a local DB to a certain
+ version. This is outside of the scope of Cayenne and is done with a
+ third-party tool, such as Liquibase or Flyway.</para>
+ </listitem>
+ <listitem>
+ <para>OR mapping model (Cayenne XML files) are synchronized with the state of the database
+ using <code>"cdbimport"</code> tool provdied by Cayenne.</para>
+ </listitem>
+ <listitem>
+ <para>Object layer of the OR mapping model is customized to the developer liking, usually via
+ CayenneModeler. Subsequent runs of <code>"cdbimport"</code> will not
+ override any customizations that you make.</para>
+ </listitem>
+ <listitem>
+ <para>Java classes are generated using <code>"cgen"</code> tool provided by Cayenne.</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>"cgen" and "cdbimport" tools can be invoked from Maven or Ant as discussed in the
+ "Including Cayenne in a Project" chapter or run from CayenneModeler. This chapter will
+ mostly focus on "cdbimport". </para>
<para>
Here is simple maven configuration to start with:
+
+
+ </para>
+ </section>
+ <section xml:id="re-configuration-file">
+ <title>Introduction to "cdbimport"</title>
+ <para>Here is a simple Maven configuration of "cdbimport" (for details see <link linkend="mvn-cdbimport">maven-cayenne-plugin</link> documentation)</para>
+ <para>
<programlisting language="xml">
<plugin>
<groupId>org.apache.cayenne.plugins</groupId>
@@ -35,109 +63,24 @@
<version><?eval ${project.version}?></version>
<configuration>
- <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
- <url><!-- jdbc url --></url>
- <driver><!-- jdbc driver class --></driver>
- <username>username</username>
+ <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
+ <url><!-- jdbc url --></url>
+ <driver><!-- jdbc driver class --></driver>
+ <username>username</username>
<password>password</password>
<defaultPackage>com.example.package</defaultPackage>
+ <reverseEngineering>
+ <includeTable>.*</includeTable>
+ </reverseEngineering>
</configuration>
-
- <executions>
- <execution>
- <goals>
- <goal>cdbimport</goal>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
-
<dependencies>
<!-- jdbc driver dependency -->
</dependencies>
</plugin>
</programlisting>
- For full list of <code>cdbimport</code> parameters see chapter <link linkend="mvn-cdbimport">Including Cayenne in a Project</link>
- </para>
- </section>
- <section xml:id="re-configuration-file">
- <title>Reverse Engineering configuration</title>
- <para>
- Cayenne is designed to support database reverse engineering automation process via Maven and Ant build tools.
- </para>
-
- <para>
- Here is a default template of reverse engineering settings, which should help you to get started:
- <programlisting language="xml">
- <plugin>
- ...
- <configuration>
- ...
- <reverseEngineering>
- <skipRelationshipsLoading>false</skipRelationshipsLoading>
- <skipPrimaryKeyLoading>false</skipPrimaryKeyLoading>
-
- <catalog>
- <schema>
- <includeTable>
- </includeTable>
- </schema>
- </catalog>
- <includeProcedure>.*</includeProcedure>
- </reverseEngineering>
- </configuration>
- ...
- </plugin>
- </programlisting>
- <caution><para>The whole database structure will be loaded after execution reverse engineering with this stub.</para></caution>
</para>
- <!--itemizedlist>
- <listitem>
- </listitem>
- <listitem>
- <para>
- Externally in reverseEngineering.xml file, which will be used by Maven/Ant to perform cdbimport
- <note><para>Configuration via file is not supported right now</para></note>
- </para>
-
- </listitem>
- </itemizedlist-->
- <!--para>
- Maven and Ant build files usually contain lots of configuration according to your project requirements. This is why reverseEngineering.xml
- is designed as a sum of configuration styles of Maven and Ant. It will be quite easy to use and move your configuration from build file
- definition into separate one. At practice you should be able to cut reverseEngineering section from Maven configuration and paste it into the
- external reverse engineering file without a problem. Then, put path to this file into config or it could be loaded from the datamap file.
- It should work for Ant at the same manner.
- </para>
- <para>
- Note that each datamap has its own reverse engineering file, which is described by the <reverse-engineering-config> datamap tag.
- <programlisting language="xml">
- <reverse-engineering-config name="reverseEngineering"/>
- </programlisting>
- </para>
- <para>
- Here is a default template of reverse engineering file, which should help you to get started:
- </para>
- <programlisting language="xml">
- <?xml version="1.0" encoding="utf-8"?>
- <reverseEngineering
- xmlns="http://cayenne.apache.org/schema/8/reverseEngineering"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://cayenne.apache.org/schema/8/reverseEngineering http://cayenne.apache.org/schema/8/reverseEngineering.xsd">
-
- <skipRelationshipsLoading>false</skipRelationshipsLoading>
- <skipPrimaryKeyLoading>false</skipPrimaryKeyLoading>
-
- <catalog>
- <schema>
- <includeTable>
- </includeTable>
- </schema>
- </catalog>
- <includeProcedure pattern=".*"/>
- </reverseEngineering>
- </programlisting-->
- <para>In the next chapter we will see more configuration details</para>
+ <para>In the next chapters we will discuss various filtering and other reverse-engineering
+ options.</para>
</section>
</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml b/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
index 017c455..b1c0eda 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
@@ -18,12 +18,10 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
<title>Reverse Engineering in Cayenne Modeler</title>
- <para>
- Alternative aproach to using <link linkend="what-is-cdbimport">cdbimport </link> is doing reverse engineering
- from <link linkend="running-cayennemodeler">Cayenne Modeler</link>. Currently modeler GUI doesn't support
- all features of ant/maven tasks but it suffice for general DB import.
- Especially it's a good place to quickly start working on your data model.
- </para>
+ <para>Alternative aproach to using <link linkend="what-is-cdbimport">cdbimport </link> is doing
+ reverse engineering from <link linkend="running-cayennemodeler">Cayenne Modeler</link>.
+ Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for
+ general DB import. Especially it's a good place to quickly start working on your data model. </para>
<para>
You can find reverse engineering tool in main modeler menu
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-name-generator.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-name-generator.xml b/docs/docbook/cayenne-guide/src/docbkx/re-name-generator.xml
deleted file mode 100644
index 34824b6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-name-generator.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<?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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-name-generator">
- <title>Name Generator</title>
- <para>
- Doing reverse engineering process, Cayenne have to translate database object names into names that follows Java naming convention.
- This page describes how Cayenne does this.
- </para>
- <section xml:id="default-name-generator">
- <title>Default Name Generator</title>
- <para>
- Usually, underscores are used for the word separations by db naming convention, while Java naming convention uses camelcase style.
- So, Cayenne uses this rule for almost all translations. The only exception is relationships naming, because they represented as foreign keys
- in the database and often have absent or auto-generated names. As a consequence those names are meaningless.
- In this case Cayenne tries to \u201cguess\u201d an appropriate name via the following rules:
- <itemizedlist>
- <listitem>
- <para>For explicit relationships (i.e PAINTING.ARTIST_ID), the column name is used. Cayenne cuts \u201cID\u201d and translates it into camelcase style,
- like ARTIST_ID -> artist</para>
- </listitem>
- <listitem>
- <para>For implicit relationships, it is usually a pluralized name of the target table in the camelcase</para>
- </listitem>
- </itemizedlist>
- </para>
- <table frame="void">
- <thead>
- <tr>
- <th>OneToMany</th>
- <th>Implicit</th>
- <th>Explicit</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>ARTIST.ARTIST_ID -- PAINTING.ARTIST_ID</td>
- <td>Artists.paintings</td>
- <td>Painting.artist</td>
- </tr>
- <tr>
- <td>PERSON.PERSON_ID -- PERSON.MOTHER_ID</td>
- <td>Person.people</td>
- <td>Person.mother</td>
- </tr>
- <tr>
- <td>PERSON.PERSON_ID -- ADDRESS.SHIPPING_ADDRESS_ID</td>
- <td>Person.addresses</td>
- <td>Address.shippingAddress</td>
- </tr>
- </tbody>
- </table>
- </section>
- <section xml:id="customizing-name-generator">
- <title>Cuztomizing Name Generator</title>
- <para>
- In case you want to customize the default naming strategy, you could set your own strategy through the namingStrategy option in the Maven or Ant
- configuration. Ensure that naming strategy class is in a class-path and implements <code>org.apache.cayenne.dbsync.naming.ObjectNameGenerator</code> interface.
- <programlisting language="xml">
- <reverseEngineering>
- <namingStrategy>YourCustomNameGenerator</namingStrategy>
- </reverseEngineering></programlisting>
- </para>
- </section>
-</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml b/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
new file mode 100644
index 0000000..3d70be4
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
@@ -0,0 +1,65 @@
+<?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.
+-->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0" xml:id="re-relationships-loading-control">
+ <title>Other Settings</title>
+ <para>
+ In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and
+ ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as
+ OneToMany, OneToOne and ManyToMany.
+ </para>
+ <section xml:id="skip-relationships-loading">
+ <title>Skip Relationships Loading</title>
+ <para>
+ You are able to skip relationships loading by the <code language="xml"><skipRelationshipsLoading></code> element.
+ </para>
+ <programlisting language="xml">
+ <reverseEngineering>
+ <skipRelationshipsLoading>true<skipRelationshipsLoading>
+ </reverseEngineering></programlisting>
+ </section>
+ <section xml:id="skip-pk-loading">
+ <title>Skip Primary Keys Loading</title>
+ <para>
+ Another useful Cayenne reverse engineering property is <code language="xml"><skipPrimaryKeyLoading></code>. If you decide to support all relationships at the application layer
+ and avoid their management in database, you\u2019ll find useful to turn off primary keys synchronization at all.
+ </para>
+ <programlisting language="xml">
+ <reverseEngineering>
+ <skipPrimaryKeyLoading>true<skipPrimaryKeyLoading>
+ </reverseEngineering></programlisting>
+ </section>
+ <section>
+ <title>Table Types</title>
+ <para>By default, cdbimport imports tables and views. Some databases may support other
+ table-like objects, e.g. <code>SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS,
+ SYNONYM</code>, etc. To control which types should be included <code language="xml"
+ ><tableType></tableType></code> element is used. Some examples:</para>
+ <para> Import tables only (skip views and others and other
+ types):<programlisting language="xml">
+ <reverseEngineering>
+ <tableType>TABLE</tableType>
+ </reverseEngineering></programlisting>
+ </para>
+ <para> Tables and views (<emphasis>the default
+ option</emphasis>):<programlisting language="xml">
+ <reverseEngineering>
+ <tableType>TABLE</tableType>
+ <tableType>VIEWS</tableType>
+ </reverseEngineering></programlisting></para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-relationships-loading-control.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-relationships-loading-control.xml b/docs/docbook/cayenne-guide/src/docbkx/re-relationships-loading-control.xml
deleted file mode 100644
index 9007cab..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-relationships-loading-control.xml
+++ /dev/null
@@ -1,93 +0,0 @@
-<?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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-relationships-loading-control">
- <title>Relationships Loading Control</title>
- <para>
- In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and
- ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as
- OneToMany, OneToOne and ManyToMany.
- </para>
- <section xml:id="one-to-many">
- <title>OneToMany relationships</title>
- <para>
- One to many is the simplest case of the database relationships:
- <itemizedlist>
- <listitem>
- <para>There is a table A with primary key A.ID</para>
- </listitem>
- <listitem>
- <para>There is a table B with primary key B.ID and foreign key B.A_ID (defined through db reference)</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- This is a way to model one-to-many relationship from table A to table B. Note that this is an implicit relationship, because table A don\u2019t have
- any evidence of data linkage with B. On the other hand, table B have explicit (column A_ID) link to the table A and it can have only one
- corresponding row from the table A. That\u2019s why for the table B it is many-to-one relationships.
- </para>
- <para>
- This pattern is the most common, easily recognisable and successfully handled by cdbimport.
- </para>
- </section>
- <section xml:id="one-to-one">
- <title>OneToOne relationships</title>
- <para>
- One-to-one relationships are very similar with one-to-many. The only difference is that foreign key at the second table should also be a primary key:
- <itemizedlist>
- <listitem>
- <para>There is a table A with primary key A.ID </para>
- </listitem>
- <listitem>
- <para>There is a table B with primary key B.A_ID and foreign key B.A_ID (defined through db reference)</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Overall, it means that there is one primary key for both tables. Only such structure will be treated as one-to-one relationship by cdbimport.
- </para>
- </section>
- <section xml:id="many-to-many">
- <title>ManyToMany</title>
- <para>
- This type of relationships usually modeled via join or junction table (<link xlink:href="http://en.wikipedia.org/wiki/Junction_table">http://en.wikipedia.org/wiki/Junction_table</link>).
- It is also successfully handled by cdbimport. Notice that join table should contain two and only two columns. Both of this columns
- should be included as primary keys.
- </para>
- </section>
- <section xml:id="skip-relationships-loading">
- <title>Skip Relationships Loading</title>
- <para>
- You are able to skip relationships loading by the <code language="xml"><skipRelationshipsLoading></code> element.
- </para>
- <programlisting language="xml">
- <reverseEngineering>
- <skipRelationshipsLoading>true<skipRelationshipsLoading>
- </reverseEngineering></programlisting>
- </section>
- <section xml:id="skip-pk-loading">
- <title>Skip Primary Keys Loading</title>
- <para>
- Another useful Cayenne reverse engineering property is <code language="xml"><skipPrimaryKeyLoading></code>. If you decide to support all relationships at the application layer
- and avoid their management in database, you\u2019ll find useful to turn off primary keys synchronization at all.
- </para>
- <programlisting language="xml">
- <reverseEngineering>
- <skipPrimaryKeyLoading>true<skipPrimaryKeyLoading>
- </reverseEngineering></programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-table-types.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-table-types.xml b/docs/docbook/cayenne-guide/src/docbkx/re-table-types.xml
deleted file mode 100644
index 6df6179..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-table-types.xml
+++ /dev/null
@@ -1,40 +0,0 @@
-<?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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-table-types">
- <title>Table Types</title>
- <para>
- By default, cdbimport processes only tables and views from schema, but there are a lot of other objects that could be loaded from database,
- such as <code>SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS, SYNONYM</code>, etc. Those things are specific for concrete databases and could be accepted
- by the <code language="xml"><tableType></tableType></code> element.
- </para>
- <para>
- Import only tables
- <programlisting language="xml">
- <reverseEngineering>
- <tableType>TABLE</tableType>
- </reverseEngineering></programlisting>
- </para>
- <para>
- Tables and views (<emphasis>default option</emphasis>)
- <programlisting language="xml">
- <reverseEngineering>
- <tableType>TABLE</tableType>
- <tableType>VIEWS</tableType>
- </reverseEngineering></programlisting>
- </para>
-</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/6caca2f6/docs/docbook/cayenne-guide/src/docbkx/re-types-mapping.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-types-mapping.xml b/docs/docbook/cayenne-guide/src/docbkx/re-types-mapping.xml
deleted file mode 100644
index e99146a..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-types-mapping.xml
+++ /dev/null
@@ -1,120 +0,0 @@
-<?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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-types-mapping">
- <title>Types Mapping</title>
- <para>
- Types mapping is a process of mapping between Database types and Java Classes through JDBC types that are represented by <code>java.sql.Types</code>.
- </para>
- <para>
- By default, <code>java.sql.Types</code> will be mapped to Java built in types or wrapper class types. Actually, Cayenne allows you to override the default mapping.
- You could use the <code><typeMapper></code> configuration section to customize how JDBC types should be identified in database and how they should be
- mapped to Java Classes during reverse engineering process.
- </para>
- <para>
- Sometimes you need to map database types to your custom Java Classes. If you really want to do this, then you should implement
- <code>org.apache.cayenne.access.types.ExtendedType</code> interface for your classes.
- </para>
- <section xml:id="basic-configuration">
- <title>Basic Configuration</title>
- <para>Here is an example of a basic typeMapper configuration:</para>
- <programlisting language="xml">
- <reverseEngineering>
- <typeMapper>
- <mapperClassName>CustomMapperClass</mapperClassName>
- <usePrimitives>false</usePrimitives>
- <type>
- <!-- Java type names-->
- <java>java.math.BigDecimal</java>
- <!-- JDBC tag is name for java.sql.Types -->
- <jdbc>DECIMAL</jdbc>
- <!-- Length, scale and precision can be used to specify the mapping precisely -->
- <precision>16</precision>
- <scale>2</scale>
- </type>
- <type>
- <java>java.lang.Long</java>
- <jdbc>NUMERIC</jdbc>
- </type>
- <type>
- <java>java.lang.String</java>
- <jdbc>VARCHAR</jdbc>
- <length>100</length>
- <notNull>true</notNull>
- </type>
- <type>
- <java>java.util.Date</java>
- <jdbc>TIMESTAMP</jdbc>
- </type>
- </typeMapper>
- </reverseEngineering>
- </programlisting>
- <itemizedlist>
- <listitem>
- <para>
- <code><mapperClassName></code> - name of the fully qualified custom Java mapper class.
- </para>
- </listitem>
- <listitem>
- <para>
- <code><usePrimitives></code> - allows you to make a decision whether to use primitives or not. It's quite useful, because primitives are faster than objects.
- If you want to use primitive type instead of wrapper type just set this option to true, otherwise false. It is more intuitive and has less overhead.
- If it is not possible because generics/autoboxing reasons, or if you want it to be nullable, then use the wrapper type. All the wrapper classes
- (Integer, Long, Byte, Double, Float, Short) are subclasses of the abstract class Number. The object of the wrapper class contains/wraps them respectively
- to the primitive data type. Converting primitive data types into objects is called boxing and compiler takes care about this. So, you don\u2019t need to use
- any special workarounds.
- </para>
- </listitem>
- <listitem>
- <para>
- <code><java></code> - name of the fully qualified Java class for mapping. If the class is a primitive wrapper class such as java.lang.Integer,
- the mapping also applies to the primitive type.
- </para>
- </listitem>
- <listitem>
- <para>
- <code><jdbc></code> - JDBC type which will be used by JDBC PreparedStatement, SQL Queries and for loading data from JDBC ResultSet.
- The valid types are defined in java.sql.Types.
- </para>
- </listitem>
- <listitem>
- <para>
- <code><notNull></code> - It's not a conditional constraint. Either your mapping are always required, in which case you should specify them as notNull="true",
- or not.
- </para>
- </listitem>
- <listitem>
- <para>
- <code><length>, <precision>, <scale></code> - length, scale and precision are used to specify the mapping precisely.
- </para>
- </listitem>
- </itemizedlist>
- <para>Note that you could write the elements above as attributes of <code><type></code>, for example:</para>
- <programlisting language="xml"> <type java="java built-in type"
- jdbc="java.sql.Types Name"
- length="Numeric value"
- precision="Numeric value"
- scale="Numeric value"
- notNull="true|false"/></programlisting>
- <para>
- The number of attributes specified in <code><type></code> and the order of the <code><type></code> is important for types mapping.
- If <code><typeMapper></code> and <code><type></code> specifications are found in <code><reverseEngineering></code>, then they will be applied for all
- reverse engineering schemas and catalogs. Otherwise, Cayenne will automatically choose default behaviour for all schema and catalogs:
- <code>java.sql.Types</code> will be mapped to java built in types or wrapper class types.
- </para>
- </section>
-</chapter>