You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by sk...@apache.org on 2016/12/06 13:16:29 UTC
[2/5] cayenne git commit: Reverse Engineering Documentation
Reverse Engineering Documentation
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/320495e1
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/320495e1
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/320495e1
Branch: refs/heads/master
Commit: 320495e1e67a0347d8ce5bb99a5cc634b30b4843
Parents: ed2f6c0
Author: Savva Kolbachev <s....@gmail.com>
Authored: Fri Aug 19 16:10:52 2016 +0300
Committer: Savva Kolbachev <s....@gmail.com>
Committed: Fri Aug 19 16:10:52 2016 +0300
----------------------------------------------------------------------
docs/docbook/cayenne-guide/src/docbkx/index.xml | 1 +
docs/docbook/cayenne-guide/src/docbkx/part4.xml | 26 ++
.../cayenne-guide/src/docbkx/re-filtering.xml | 336 +++++++++++++++++++
.../src/docbkx/re-introduction.xml | 83 +++++
.../src/docbkx/re-name-generator.xml | 73 ++++
.../docbkx/re-relationships-loading-control.xml | 95 ++++++
.../cayenne-guide/src/docbkx/re-table-types.xml | 42 +++
.../src/docbkx/re-types-mapping.xml | 122 +++++++
.../src/docbkx/reverse-engineering-ch1.xml | 6 +-
9 files changed, 780 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/docs/docbook/cayenne-guide/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/index.xml b/docs/docbook/cayenne-guide/src/docbkx/index.xml
index a2ac46c..048bfca 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/index.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/index.xml
@@ -40,6 +40,7 @@
<xi:include href="part1.xml"/>
<xi:include href="part2.xml"/>
<xi:include href="part3.xml"/>
+ <xi:include href="part4.xml"/>
<xi:include href="appendix-a.xml"/>
<xi:include href="appendix-b.xml"/>
<xi:include href="appendix-c.xml"/>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/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
new file mode 100644
index 0000000..e6d2a45
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/part4.xml
@@ -0,0 +1,26 @@
+<?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.
+-->
+<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>
+ <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"/>
+</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/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
new file mode 100644
index 0000000..b36c7f2
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
@@ -0,0 +1,336 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0" xml:id="re-filtering">
+ <title>Filtering</title>
+ <para>
+ The first thing you usually want to control during reverse engineering is what exactly should be loaded from database and
+ what not. One of the most common cases is excluding system tables, as you usually don't want to map them.
+ </para>
+ <para>
+ Briefly, you are able to include/exclude tables, columns and procedures and do it at several levels: default, catalog, schema.
+ Although everything defined at the top level (default rules) will be applied for the nested elements, all rules from the most specific
+ areas will override general rules (i.e. rules from schemas override rules from catalogs and even more override default rules).
+ </para>
+ <para>
+ The following use-cases will provide you a better understanding of how filtering works and how you could use it.
+ </para>
+ <section xml:id="everything-schema-catalog">
+ <title>Process everything from schema/catalog</title>
+ <para>
+ 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">
+ <!-- Ant/Maven in case you only want to specify the schema to import -->
+ <schema>SCHEMA_NAME</schema>
+
+ <!-- Maven way in case you have nested elements in the schema -->
+ <schema>
+ <name>SCHEMA_NAME</name>
+ ...
+ </schema>
+
+ <!-- Ant way in case you have nested elements in the schema -->
+ <schema name="SCHEMA_NAME">
+ ...
+ </schema>
+ </programlisting>
+ <para>
+ The same options are available for catalogs:
+ </para>
+ <programlisting language="xml">
+ <!-- Ant/Maven in case you only want to specify the catalog to import -->
+ <catalog>CATALOG_NAME</catalog>
+
+ <!-- Maven way in case you have nested elements in the catalog -->
+ <catalog>
+ <name>CATALOG_NAME</name>
+ ...
+ </catalog>
+
+ <!-- Ant way in case you have nested elements in the catalog -->
+ <catalog name="CATALOG_NAME">
+ ...
+ </catalog>
+ </programlisting>
+ </section>
+ <section xml:id="combine-schema-catalog">
+ <title>Combine Schema and Catalog filters</title>
+ <para>
+ 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">
+ <schema name="schema-name-01"/>
+ <schema name="schema-name-02"/>
+ <schema name="schema-name-03"/>
+ </catalog>
+
+ <catalog name="shop_02">
+ <schema name="schema-name-01"/>
+ </catalog>
+
+ <catalog name="shop_03">
+ <schema name="schema-name-01"/>
+ <schema name="schema-name-02"/>
+ <schema name="schema-name-03"/>
+ </catalog>
+
+ </reverseEngineering>
+ ...
+ </configuration>
+ </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.
+ </para>
+ <para>
+ If you want to load everything from database, you could simply declare catalog specification alone.
+ </para>
+ <programlisting language="xml">
+ <configuration>
+ ...
+ <reverseEngineering>
+
+ <catalog name="shop_01"/>
+ <catalog name="shop_02"/>
+ <catalog name="shop_03"/>
+
+ </reverseEngineering>
+ ...
+ </configuration>
+ </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">
+ <schema name="schema-name-01"/>
+ <schema name="schema-name-03"/>
+ </catalog>
+
+ <catalog name="shop_02">
+ <schema name="schema-name-01"/>
+ </catalog>
+
+ <catalog name="shop_03">
+ <schema name="schema-name-01"/>
+ <schema name="schema-name-03"/>
+ </catalog>
+
+ </reverseEngineering>
+ ...
+ </configuration>
+ </programlisting>
+ </section>
+ <section xml:id="including-excluding-tables-columns-procedures">
+ <title>Including and Excluding tables, columns and procedures</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>1. Include tables with \u2018CRM_\u2019 prefix if you are working in that domain of application:</para>
+ <programlisting language="xml">
+ <includeTable>CRM_.*</includeTable>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>2. Include tables with \u2018_LOOKUP\u2019 suffix</para>
+ <programlisting language="xml">
+ <includeTable>
+ <pattern>.*_LOOKUP</pattern>
+ </includeTable>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>3. 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>
+ </listitem>
+ <listitem>
+ <para>4. Include only specific columns that follows specific naming convention:</para>
+ <programlisting language="xml">
+ <includeColumn>includeColumn01</includeColumn>
+ <includeColumn pattern="includeColumn03"/>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>5. Exclude system or obsolete columns:</para>
+ <programlisting language="xml">
+ <excludeColumn>excludeColumn01</excludeColumn>
+ <excludeColumn pattern="excludeColumn03"/>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>6. Include/Exclude columns for particular table or group of tables:</para>
+ <programlisting language="xml">
+ <includeTable pattern="table pattern">
+ <includeColumn pattern="includeColumn01"/>
+ <excludeColumn pattern="excludeColumn01"/>
+ </includeTable>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>7. Include stored procedures:</para>
+ <programlisting language="xml">
+ <includeProcedure>includeProcedure01</includeProcedure>
+ <includeProcedure pattern="includeProcedure03"/>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>8. Exclude stored procedures by pattern:</para>
+ <programlisting language="xml">
+ <excludeProcedure>excludeProcedure01</excludeProcedure>
+ <excludeProcedure pattern="excludeProcedure03"/>
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ All filtering tags includeTable, excludeTable, includeColumn, excludeColumn, includeProcedure and excludeProcedure have three ways
+ to pass filtering RegExp.
+ <itemizedlist>
+ <listitem>
+ <para>text inside tag</para>
+ <programlisting language="xml">
+ <includeTable>CRM_.*</includeTable>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>pattern attribute</para>
+ <programlisting language="xml">
+ <excludeProcedure pattern="excludeProcedure03"/>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>pattern inner tag</para>
+ <programlisting language="xml">
+ <includeTable>
+ <pattern>.*_LOOKUP</pattern>
+ </includeTable>
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ All filtering tags can be placed inside schema and catalog tags, but also inside <reverseEngineering> tag. It means that filtering rules
+ will be applied for all schemas and catalogs.
+ </para>
+ </section>
+ <section xml:id="complete-filtering-example">
+ <title>Complete filtering example</title>
+ <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>
+ <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">
+ <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.
+ </para>
+ <para>
+ Let\u2019s assume you have a lot of table prefixes with the same names. Cayenne allows you to mention a pattern as regular expression.
+ Using regular expressions is easier way to handle a big amount of database entities than writing filter config for each use-case.
+ 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>
+
+ <catalog>shop-01</catalog>
+
+ <catalog>
+ <name>shop-02</name>
+ </catalog>
+
+ <catalog name="shop-03">
+ <includeTable>includeTable-01</includeTable>
+
+ <includeTable>
+ <pattern>includeTable-02</pattern>
+ </includeTable>
+
+ <includeTable pattern="includeTable-03">
+ <includeColumn pattern="includeColumn-01"/>
+ <excludeColumn pattern="excludeColumn-01"/>
+ </includeTable>
+
+ <excludeTable>excludeTable-01</excludeTable>
+
+ <excludeTable>
+ <pattern>excludeTable-02</pattern>
+ </excludeTable>
+
+ <excludeTable pattern="excludeTable-03"/>
+
+ <includeColumn>includeColumn-01</includeColumn>
+
+ <includeColumn>
+ <pattern>includeColumn-02</pattern>
+ </includeColumn>
+
+ <includeColumn pattern="includeColumn-03"/>
+
+ <excludeColumn>excludeColumn-01</excludeColumn>
+
+ <excludeColumn>
+ <pattern>excludeColumn-02</pattern>
+ </excludeColumn>
+
+ <excludeColumn pattern="excludeColumn-03"/>
+
+ <includeProcedure>includeProcedure-01</includeProcedure>
+
+ <includeProcedure>
+ <pattern>includeProcedure-02</pattern>
+ </includeProcedure>
+
+ <includeProcedure pattern="includeProcedure-03"/>
+
+ <excludeProcedure>excludeProcedure-01</excludeProcedure>
+
+ <excludeProcedure>
+ <pattern>excludeProcedure-02</pattern>
+ </excludeProcedure>
+
+ <excludeProcedure pattern="excludeProcedure-03"/>
+
+ </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.
+ </para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/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
new file mode 100644
index 0000000..3125a7b
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
@@ -0,0 +1,83 @@
+<?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-introduction">
+ <title>Reverse Engineering 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 CGen Maven plugin,
+ which does class generation according to the Cayenne mapping file updates.
+ </para>
+ </section>
+ <section xml:id="re-configuration-file">
+ <title>Reverse Engineering configuration file</title>
+ <para>
+ Cayenne is designed to support database reverse engineering automation process via Maven and Ant build tools.
+ You could control and configure this process in the several ways:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Inside ANT/Maven build file</para>
+ </listitem>
+ <listitem>
+ <para>Externally in reverseEngineering.xml file, which will be used by Maven/Ant to perform cdbimport</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>
+ Note that the whole database structure will be loaded after execution reverse engineering with this stub.
+ </para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/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
new file mode 100644
index 0000000..e89ebfa
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-name-generator.xml
@@ -0,0 +1,73 @@
+<?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>
+ <tbody>
+ <tr>
+ <td>OneToMany</td>
+ <td>Implicit</td>
+ <td>Explicit</td>
+ </tr>
+ <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 ObjectNameGenerator interface.
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/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
new file mode 100644
index 0000000..bc0bc23
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-relationships-loading-control.xml
@@ -0,0 +1,95 @@
+<?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 (http://en.wikipedia.org/wiki/Junction_table).
+ 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 <skipRelationshipsLoading> 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 <skipPrimaryKeyLoading>. 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/320495e1/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
new file mode 100644
index 0000000..55403fe
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-table-types.xml
@@ -0,0 +1,42 @@
+<?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 SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS, SYNONYM, etc. Those things are specific for concrete databases and could be accepted
+ by the <tableType><tableType> element.
+ </para>
+ <para>
+ Import only tables
+ <programlisting language="xml">
+ <reverseEngineering>>
+ <tableType>TABLE</tableType>
+ </reverseEngineering>
+ </programlisting>
+ </para>
+ <para>
+ Tables and views (default option)
+ <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/320495e1/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
new file mode 100644
index 0000000..274c4ec
--- /dev/null
+++ b/docs/docbook/cayenne-guide/src/docbkx/re-types-mapping.xml
@@ -0,0 +1,122 @@
+<?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 java.sql.Types.
+ </para>
+ <para>
+ By default, java.sql.Types 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 <typeMapper> 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
+ org.apache.cayenne.access.types.ExtendedType 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>class</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>
+ <mapperClassName> - name of the fully qualified custom Java mapper class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <usePrimitives> - 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>
+ <java> - 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>
+ <jdbc> - 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>
+ <notNull> - 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>
+ <length>, <precision>, <scale> - 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 <type>, 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 <type> and the order of the <type> is important for types mapping.
+ If <typeMapper> and <type> specifications are found in <reverseEngineering>, then they will be applied for all
+ reverse engineering schemas and catalogs. Otherwise, Cayenne will automatically choose default behaviour for all schema and catalogs:
+ java.sql.Types will be mapped to java built in types or wrapper class types.
+ </para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/320495e1/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml b/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml
index 454e91b..13844b0 100644
--- a/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml
+++ b/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml
@@ -109,8 +109,6 @@
<listitem>
<para>Forward Engineering - Generating db schema according to the Java classes.</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>Reverse Engineering - Updating Java classes according to the database schema.</para>
</listitem>
@@ -122,10 +120,10 @@
<section xml:id="basic-usage">
<title>Basic Usage</title>
<para>
- CDBImport is a Maven plugin that helps you to do reverse engineering. In other words it helps you to synchronize
+ 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 CGen Maven plugin after CDBImport,
+ Most common practice to complete reverse engineering is to use CDBImport followed by CGen Maven plugin,
which does class generation according to the Cayenne mapping file updates.
</para>
<para>