cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From skolbac...@apache.org
Subject [1/5] cayenne git commit: Reverse Engineering Tutorial
Date Tue, 06 Dec 2016 13:16:28 GMT
Repository: cayenne
Updated Branches:
  refs/heads/master ca0ef2824 -> 71f994478


Reverse Engineering Tutorial


Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/ed2f6c03
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/ed2f6c03
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/ed2f6c03

Branch: refs/heads/master
Commit: ed2f6c038e540cec5dd47009a414a79d13caf2af
Parents: c614691
Author: Savva Kolbachev <s.kolbachev@gmail.com>
Authored: Wed Aug 17 11:31:01 2016 +0300
Committer: Savva Kolbachev <s.kolbachev@gmail.com>
Committed: Wed Aug 17 11:31:01 2016 +0300

----------------------------------------------------------------------
 .../getting-started-reverse-engineering/pom.xml |  41 +++
 .../src/docbkx/index.xml                        |  42 +++
 .../src/docbkx/reverse-engineering-ch1.xml      | 322 +++++++++++++++++++
 .../src/docbkx/reverse-engineering-ch2.xml      | 218 +++++++++++++
 .../images/customer-order-ordered_product.png   | Bin 0 -> 29330 bytes
 .../src/images/customer-order.png               | Bin 0 -> 16562 bytes
 .../src/images/customer1.png                    | Bin 0 -> 9652 bytes
 .../src/images/customer2.png                    | Bin 0 -> 11504 bytes
 docs/docbook/pom.xml                            |   1 +
 9 files changed, 624 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/pom.xml b/docs/docbook/getting-started-reverse-engineering/pom.xml
new file mode 100644
index 0000000..69209f4
--- /dev/null
+++ b/docs/docbook/getting-started-reverse-engineering/pom.xml
@@ -0,0 +1,41 @@
+<?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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>org.apache.cayenne.docs</groupId>
+        <artifactId>cayenne-docbook</artifactId>
+        <version>4.0.M4-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>getting-started-reverse-engineering</artifactId>
+
+    <packaging>jar</packaging>
+    <name>Docbook: Getting Started with Cayenne RE</name>
+
+    <build>
+        <resources>
+            <resource>
+                <directory>target/site</directory>
+            </resource>
+        </resources>
+    </build>
+</project>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/docbkx/index.xml b/docs/docbook/getting-started-reverse-engineering/src/docbkx/index.xml
new file mode 100644
index 0000000..38dafb0
--- /dev/null
+++ b/docs/docbook/getting-started-reverse-engineering/src/docbkx/index.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.
+-->
+<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
+    xml:id="getting-started-reverse-engineering" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <info>
+        <title>Getting Started with Cayenne Reverse Engineering</title>
+        <copyright>
+            <year>2011-2014</year>
+            <holder>Apache Software Foundation and individual authors</holder>
+        </copyright>
+        <legalnotice>
+            <title>License</title>
+            <para>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</para>
+            
+            <para>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.</para>
+        </legalnotice>
+    </info>
+    <xi:include href="reverse-engineering-ch1.xml"/>
+    <xi:include href="reverse-engineering-ch2.xml"/>
+</book>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/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
new file mode 100644
index 0000000..454e91b
--- /dev/null
+++ b/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch1.xml
@@ -0,0 +1,322 @@
+<?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">
+    <title>Introduction and Basic Usage</title>
+    <section xml:id="introduction">
+        <title>Introduction</title>
+        <para>In Java development there is a well known problem about synchronization
Java domain
+            model and relationship model in database. Let’s assume you are working on one
of
+            a shopping application, some of your domain model classes would be Product, Order,
+            Shopping Cart and Customer. Considering the above sentence, we have a Java class
and database
+            table name called “Customer”.</para>
+        <para>Java Class:</para>
+        <programlisting language="java">
+            public class Customer {
+
+                private int id;
+                private String name;
+
+                public Customer(){
+                    // to do your instance initialization stuff here
+                }
+
+                public  Customer(int id,String name){
+                    this.id = id;
+                    this.name = name;
+                }
+
+                // getter and setter method goes here
+
+            }
+        </programlisting>
+        <para>Database:</para>
+        <programlisting language="sql">
+            CREATE TABLE `customer` (
+            `id` INT(11) NOT NULL,
+            `name` VARCHAR(45) DEFAULT NULL,
+            PRIMARY KEY (`id`));
+        </programlisting>
+        <para>
+            <inlinemediaobject>
+                <imageobject>
+                    <imagedata fileref="images/customer1.png" scalefit="1" width="100%"/>
+                </imageobject>
+            </inlinemediaobject>
+        </para>
+
+        <para>Let’s assume you have to split Customer model “name” field as First
name and Last Name
+            due to the client requirement. In that case you have to update both Java class
and table model manually.
+        </para>
+        <para>Java Class:</para>
+        <programlisting language="java">
+            public class Customer {
+
+                private int id;
+                private String firstname;
+                private String lastname;
+                public Customer(){
+                    // to do your instance initialization stuff here
+                }
+
+                public  Customer(int id,String fname,String lname){
+                    this.id = id;
+                    this.firstname = fname;
+                    this.lastname = lname;
+                }
+
+                // getter and setter method goes here
+            }
+        </programlisting>
+        <para>Database:</para>
+        <programlisting language="sql">
+            CREATE TABLE `customer` (
+            `id` INT(11) NOT NULL,
+            `firstname` VARCHAR(45) DEFAULT NULL,
+            `lastname` VARCHAR(45) DEFAULT NULL,
+            PRIMARY KEY (`id`));
+        </programlisting>
+        <para>
+            <inlinemediaobject>
+                <imageobject>
+                    <imagedata fileref="images/customer2.png" scalefit="1" width="100%"/>
+                </imageobject>
+            </inlinemediaobject>
+        </para>
+        <para>
+            In the above example, synchronization of domain model and database relationship
model is manually
+            updated by Java developers. In this situation we have to keep both copies of
Java classes and
+            database tables up to date manually. If you change something in db, that changes
should be reflected
+            in Java classes. Likewise all Java classes changes should be reflected in database.
+            Although it can be automated manually, it will take some cost of time.
+        </para>
+        <para>
+            However, Cayenne automates this process with a minimum cost of time. It has two
options for this automation process:
+            <itemizedlist>
+                <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>
+            </itemizedlist>
+
+            The reverse engineering tool is called CDBImport.
+        </para>
+    </section>
+    <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
+            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,
+            which does class generation according to the Cayenne mapping file updates.
+        </para>
+        <para>
+            You could use CDBImport Maven plugin by declaring and configuring it in your
pom.xml.
+            See an example with comments below:
+        </para>
+        <programlisting language="xml">
+            &lt;profile&gt;
+                &lt;!-- Here we define a profile with cdbimport and cgen configurations.
+                For sure you could define all plugins in general build section, but it will
be time consuming
+                during each build to load database structure and check it for changes. Also,
you will probably want to
+                control when exactly reverse engineering happens in order to correct its
results if necessary. --&gt;
+                &lt;id>ormsync&lt;/id&gt;
+                &lt;build&gt;
+                    &lt;plugins&gt;
+                        &lt;plugin&gt;
+                            &lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+                            &lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+                            &lt;version&gt;4.0.M3&lt;/version&gt;
+                            &lt;executions&gt;
+                                &lt;execution&gt;
+                                    &lt;id&gt;ormsync&lt;/id&gt;
+                                    &lt;goals&gt;
+                                        &lt;!-- Again, cdbimport is a part of reverse
engineering process.
+                                        Next step is generating Java classes according to
their mapping by cgen. --&gt;
+                                        &lt;goal&gt;cdbimport&lt;/goal&gt;
+                                        &lt;goal&gt;cgen&lt;/goal&gt;
+                                    &lt;/goals&gt;
+                                    &lt;configuration&gt;
+                                        &lt;!-- At first, we have to define database
connection information
+                                        from which the structure will be loaded. --&gt;
+                                        &lt;driver&gt;com.mysql.jdbc.Driver&lt;/driver&gt;
+                                        &lt;url&gt;jdbc:mysql://127.0.0.1:3306/test&lt;/url&gt;
+                                        &lt;username&gt;root&lt;/username&gt;
+                                        &lt;!--&lt;password&gt;password&lt;/password&gt;--&gt;
+                                        &lt;!-- Next step is to define mapping file,
which we are going to use.
+                                        If it doesn't exist, it will be created automatically
after the first plugin execution.
+                                        Here you could also define some mapping properties.
It isn't necessary for cdbimport task, but it will be used by cgen. --&gt;
+                                        &lt;map&gt;${project.basedir}/src/main/resources/shopping.map.xml&lt;/map&gt;
+                                        &lt;defaultPackage&gt;org.apache.cayenne.shopping&lt;/defaultPackage&gt;
+                                        &lt;superPkg&gt;org.apache.cayenne.shopping.auto&lt;/superPkg&gt;
+                                        &lt;!-- Last part of configuration is reverse
engineering tuning.
+                                        Here we just define which catalogs we want to process
and which tables should be excluded.
+                                        You could find detailed description of possible configurations
in the documentation. --&gt;
+                                        &lt;catalog&gt;test&lt;/catalog&gt;
+                                        &lt;excludeTables&gt;system_patch,v_*,*_view&lt;/excludeTables&gt;
+                                    &lt;/configuration&gt;
+                                &lt;/execution&gt;
+                            &lt;/executions&gt;
+                            &lt;dependencies&gt;
+                                &lt;!-- Also, you have to add JDBC driver dependency.
--&gt;
+                                &lt;dependency&gt;
+                                    &lt;groupId&gt;mysql&lt;/groupId&gt;
+                                    &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
+                                    &lt;version&gt;5.1.28&lt;/version&gt;
+                                &lt;/dependency&gt;
+                            &lt;/dependencies&gt;
+                        &lt;/plugin&gt;
+                    &lt;/plugins&gt;
+                &lt;/build&gt;
+            &lt;/profile&gt;
+        </programlisting>
+        <para>
+            Let’s consider that shopping application consists of the following tables and
relationships in database.
+            Initially, we are going to take customer, order tables and one foreign key relationship
between them.
+        </para>
+        <para>SQL</para>
+        <programlisting language="sql">
+            CREATE TABLE `customer` (
+            `id` INT(11) NOT NULL,
+            `name` VARCHAR(50) DEFAULT NULL,
+            PRIMARY KEY (`id`));
+
+            CREATE TABLE `order` (
+            `id` INT(11) NOT NULL,
+            `amount` DECIMAL(6,2) DEFAULT NULL,
+            `customer_id` INT(11) DEFAULT NULL,
+            PRIMARY KEY (`id`),
+            KEY `fk_customers_id_idx` (`customer_id`),
+            CONSTRAINT `fk_customers_id_refference` FOREIGN KEY (`customer_id`) REFERENCES
`customer` (`id`)
+            ON DELETE CASCADE ON UPDATE CASCADE);
+        </programlisting>
+        <para>
+            <inlinemediaobject>
+                <imageobject>
+                    <imagedata fileref="images/customer-order.png" scalefit="1" width="100%"/>
+                </imageobject>
+            </inlinemediaobject>
+        </para>
+        <para>
+            Now, please arrange the profile above for your custom DB settings. That’s all
you need to do for reverse
+            engineering with Cayenne. Now you are able to run the reverse engineering task
as described below.
+        </para>
+        <programlisting>
+            mvn compile -Pormsync
+        </programlisting>
+        <para>The output should look like this:</para>
+        <programlisting>
+            [INFO] Scanning for projects...
+            [INFO]
+            [INFO] ------------------------------------------------------------------------
+            [INFO] Building MySQLTest 0.0.1-SNAPSHOT
+            [INFO] ------------------------------------------------------------------------
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cdbimport (ormsync) @ MySQLTest ---
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.access.DbLoader load
+            INFO: Schema loading...
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 3:36:41 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            [INFO]   Table: test.customer
+            [INFO]   Table: test.order
+            [INFO]     Db Relationship : toOne  (order.customer_id, customer.id)
+            [INFO]     Db Relationship : toMany (customer.id, order.customer_id)
+            [INFO]
+            [INFO] Map file does not exist. Loaded db model will be saved into '**/MySQLTest/src/main/resources/shopping.map.xml'
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cgen (ormsync) @ MySQLTest ---
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Customer.java
+            [INFO] Generating class file:**/MySQLTest/src/main/java/org/apache/cayenne/shopping/Customer.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Order.java
+            [INFO] Generating class file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/Order.java
+            [INFO]
+        </programlisting>
+        <para>
+            Above output demonstrates what was loaded from database (test.order, test.customer
tables and customer_id relationships)
+            by cdbimport task and which classes was generated by cgen task.
+        </para>
+        <para>
+            In the example we assume that you don't have a mapping file. But if you have,
it will contain the relationship between
+            Java class and database table. Note that if there is no mapping file, Cayenne
will generate it automatically and store it
+            under the resource folder specified by &lt;map&gt; property.
+        </para>
+
+        <para>
+            Notice that cdbimport updates only one file in your source code: mapping file
that you pointed in &lt;map&gt; maven option.
+            If you do reverse engineering again (mvn compile -Pormsync), plug-in will load
all information from database but say that
+            no changes are detected. On the other hand, cgen task will regenerate superclasses
(_Customer.java, _Order.java),
+            but not subclasses (Customer.java, Order.java).
+        </para>
+        <para>Console will provide the following output:</para>
+        <programlisting>
+            [INFO] Scanning for projects...
+            [INFO]
+            [INFO] ------------------------------------------------------------------------
+            [INFO] Building MySQLTest 0.0.1-SNAPSHOT
+            [INFO] ------------------------------------------------------------------------
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cdbimport (ormsync) @ MySQLTest ---
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.access.DbLoader load
+            INFO: Schema loading...
+            Aug 16, 2016 4:44:33 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 4:44:34 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 4:44:34 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            [INFO]   Table: test.customer
+            [INFO]   Table: test.order
+            [INFO]     Db Relationship : toOne  (order.customer_id, customer.id)
+            [INFO]     Db Relationship : toMany (customer.id, order.customer_id)
+            [INFO]
+            [INFO] Detected changes: No changes to import.
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cgen (ormsync) @ MySQLTest ---
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Customer.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Order.java
+            [INFO]
+        </programlisting>
+    </section>
+</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch2.xml
b/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch2.xml
new file mode 100644
index 0000000..2a48924
--- /dev/null
+++ b/docs/docbook/getting-started-reverse-engineering/src/docbkx/reverse-engineering-ch2.xml
@@ -0,0 +1,218 @@
+<?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">
+    <title>A few hands-on examples</title>
+    <section xml:id="renaming-table-column-example">
+        <title>Renaming table column example</title>
+        <para>
+            Let's rename "name" column from the Customer table to the "first_name".
+        </para>
+        <para>
+            SQL
+        </para>
+        <programlisting>
+            ALTER TABLE `customer` 
+            CHANGE COLUMN `name` `first_name` VARCHAR(50) NULL DEFAULT NULL ;
+        </programlisting>
+        <para>
+            Now we can do reverse engineering again by the command we already know:
+        </para>
+        <programlisting>
+            mvn compile -Pormsync
+        </programlisting>
+        <para>The output should look like this:</para>
+        <programlisting>
+            [INFO] Scanning for projects...
+            [INFO]
+            [INFO] ------------------------------------------------------------------------
+            [INFO] Building MySQLTest 0.0.1-SNAPSHOT
+            [INFO] ------------------------------------------------------------------------
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cdbimport (ormsync) @ MySQLTest ---
+            Aug 16, 2016 5:07:31 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.access.DbLoader load
+            INFO: Schema loading...
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:07:32 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            [INFO]   Table: test.customer
+            [INFO]   Table: test.order
+            [INFO]     Db Relationship : toOne  (order.customer_id, customer.id)
+            [INFO]     Db Relationship : toMany (customer.id, order.customer_id)
+            [INFO]
+            [INFO] Detected changes:
+            [INFO]     Add Column           customer.first_name
+            [INFO]     Drop Column          customer.name
+            [INFO]
+            [INFO] Migration Complete Successfully.
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cgen (ormsync) @ MySQLTest ---
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Customer.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Order.java
+            [INFO]
+        </programlisting>
+        <para>
+            As you could see, cdbimport task found and applied our changes to the model.
Then, superclasses was updated by 
+            cgen task to catch our changes. Notice that Cayenne treated a column renaming
change as dropping and adding 
+            a new column, because it can’t really track the renaming change.
+        </para>
+    </section>
+    <section xml:id="renaming-objattribute-example">
+        <title>Renaming ObjAttribute example</title>
+        <para>
+            Let’s rename an "amount" ObjAttribute name to "totalPrice" in Order ObjectEntity.
After running
+            reverse engineering task, the output will show you no changes to import:
+        </para>
+        <programlisting>
+            [INFO] Scanning for projects...
+            [INFO]
+            [INFO] ------------------------------------------------------------------------
+            [INFO] Building MySQLTest 0.0.1-SNAPSHOT
+            [INFO] ------------------------------------------------------------------------
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cdbimport (ormsync) @ MySQLTest ---
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.access.DbLoader load
+            INFO: Schema loading...
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:26:53 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            [INFO]   Table: test.customer
+            [INFO]   Table: test.order
+            [INFO]     Db Relationship : toOne  (order.customer_id, customer.id)
+            [INFO]     Db Relationship : toMany (customer.id, order.customer_id)
+            [INFO]
+            [INFO] Detected changes: No changes to import.
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cgen (ormsync) @ MySQLTest ---
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Customer.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Order.java
+            [INFO]
+        </programlisting>
+        <para>
+            As you could see, cdbimport task didn't detect any changes. Whenever you change
anything in “obj-attribute” xml element 
+            it will not reflect anything on the database side. But your changes will be reflected
in auto generated java classes
+            by cgen task.
+        </para>
+    </section>
+    <section xml:id="adding-table-relationships-example">
+        <title>Adding table and relationships example</title>
+        <para>
+            In this section we are going to add a new table "ordered_product" with foreign
key relationships between the existing tables.
+            So our schema will look as follows:
+        </para>
+        <para>
+            SQL
+        </para>
+        <programlisting language="sql">
+            CREATE TABLE `ordered_product` (
+            `customer_order_id` INT(11) NOT NULL,
+            `product_id` INT(11) DEFAULT NULL,
+            `quantity` SMALLINT(6) DEFAULT NULL,
+            PRIMARY KEY (`customer_order_id`),
+            KEY `fk_product_references_idx` (`product_id`),
+            CONSTRAINT `fk_order_references` FOREIGN KEY (`customer_order_id`) REFERENCES
`order` (`id`) 
+            ON DELETE CASCADE ON UPDATE CASCADE);
+        </programlisting>
+        <para>
+            <inlinemediaobject>
+                <imageobject>
+                    <imagedata fileref="images/customer-order-ordered_product.png" scalefit="1"
width="100%"/>
+                </imageobject>
+            </inlinemediaobject>
+        </para>
+        <para>
+            After running the reverse engineering task again as described in the previous
examples, the new output will 
+            show a few actual DB operations:
+        </para>
+        <programlisting>
+            [INFO] Scanning for projects...
+            [INFO]
+            [INFO] ------------------------------------------------------------------------
+            [INFO] Building MySQLTest 0.0.1-SNAPSHOT
+            [INFO] ------------------------------------------------------------------------
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cdbimport (ormsync) @ MySQLTest ---
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.access.DbLoader load
+            INFO: Schema loading...
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource logConnect
+            INFO: Connecting to 'jdbc:mysql://127.0.0.1:3306/test' as 'root'
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.datasource.DriverDataSource getConnection
+            INFO: +++ Connecting: SUCCESS.
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.log.CommonsJdbcEventLogger log
+            INFO: Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+            [INFO]   Table: test.customer
+            [INFO]   Table: test.order
+            [INFO]   Table: test.ordered_product
+            [INFO]     Db Relationship : toOne  (ordered_product.customer_order_id, order.id)
+            [INFO]     Db Relationship : toOne  (order.id, ordered_product.customer_order_id)
+            [INFO]     Db Relationship : toOne  (order.customer_id, customer.id)
+            [INFO]     Db Relationship : toMany (customer.id, order.customer_id)
+            [INFO]
+            [INFO] Detected changes:
+            [INFO]     Add Relationship     customerOrder order->ordered_product.customer_order_id
+            [INFO]     Create Table         ordered_product
+            [INFO]
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.util.EntityMergeSupport addMissingRelationships
+            WARNING: Can't find ObjEntity for ordered_product
+            Aug 16, 2016 5:43:52 PM org.apache.cayenne.util.EntityMergeSupport addMissingRelationships
+            WARNING: Db Relationship (Db Relationship : toOne  (order.id, ordered_product.customer_order_id))
will have GUESSED Obj Relationship reflection.
+            [INFO] Migration Complete Successfully.
+            [INFO]
+            [INFO] --- maven-cayenne-plugin:4.0.M3:cgen (ormsync) @ MySQLTest ---
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Customer.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_Order.java
+            [INFO] Generating superclass file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/auto/_OrderedProduct.java
+            [INFO] Generating class file: **/MySQLTest/src/main/java/org/apache/cayenne/shopping/OrderedProduct.java
+            [INFO]
+        </programlisting>
+    </section>
+</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/images/customer-order-ordered_product.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/images/customer-order-ordered_product.png
b/docs/docbook/getting-started-reverse-engineering/src/images/customer-order-ordered_product.png
new file mode 100644
index 0000000..d471065
Binary files /dev/null and b/docs/docbook/getting-started-reverse-engineering/src/images/customer-order-ordered_product.png
differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/images/customer-order.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/images/customer-order.png
b/docs/docbook/getting-started-reverse-engineering/src/images/customer-order.png
new file mode 100644
index 0000000..1aef34e
Binary files /dev/null and b/docs/docbook/getting-started-reverse-engineering/src/images/customer-order.png
differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/images/customer1.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/images/customer1.png b/docs/docbook/getting-started-reverse-engineering/src/images/customer1.png
new file mode 100644
index 0000000..777ef19
Binary files /dev/null and b/docs/docbook/getting-started-reverse-engineering/src/images/customer1.png
differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/getting-started-reverse-engineering/src/images/customer2.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-reverse-engineering/src/images/customer2.png b/docs/docbook/getting-started-reverse-engineering/src/images/customer2.png
new file mode 100644
index 0000000..5c535fb
Binary files /dev/null and b/docs/docbook/getting-started-reverse-engineering/src/images/customer2.png
differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/ed2f6c03/docs/docbook/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/pom.xml b/docs/docbook/pom.xml
index 5227396..6d3bf9e 100644
--- a/docs/docbook/pom.xml
+++ b/docs/docbook/pom.xml
@@ -34,6 +34,7 @@
 		<module>cayenne-guide</module>
 		<module>getting-started</module>
 		<module>getting-started-rop</module>
+        <module>getting-started-reverse-engineering</module>
 		<module>upgrade-guide</module>
     </modules>
 


Mime
View raw message