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.kolbac...@gmail.com> Authored: Wed Aug 17 11:31:01 2016 +0300 Committer: Savva Kolbachev <s.kolbac...@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"> + <profile> + <!-- 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. --> + <id>ormsync</id> + <build> + <plugins> + <plugin> + <groupId>org.apache.cayenne.plugins</groupId> + <artifactId>maven-cayenne-plugin</artifactId> + <version>4.0.M3</version> + <executions> + <execution> + <id>ormsync</id> + <goals> + <!-- Again, cdbimport is a part of reverse engineering process. + Next step is generating Java classes according to their mapping by cgen. --> + <goal>cdbimport</goal> + <goal>cgen</goal> + </goals> + <configuration> + <!-- At first, we have to define database connection information + from which the structure will be loaded. --> + <driver>com.mysql.jdbc.Driver</driver> + <url>jdbc:mysql://127.0.0.1:3306/test</url> + <username>root</username> + <!--<password>password</password>--> + <!-- 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. --> + <map>${project.basedir}/src/main/resources/shopping.map.xml</map> + <defaultPackage>org.apache.cayenne.shopping</defaultPackage> + <superPkg>org.apache.cayenne.shopping.auto</superPkg> + <!-- 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. --> + <catalog>test</catalog> + <excludeTables>system_patch,v_*,*_view</excludeTables> + </configuration> + </execution> + </executions> + <dependencies> + <!-- Also, you have to add JDBC driver dependency. --> + <dependency> + <groupId>mysql</groupId> + <artifactId>mysql-connector-java</artifactId> + <version>5.1.28</version> + </dependency> + </dependencies> + </plugin> + </plugins> + </build> + </profile> + </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 <map> property. + </para> + + <para> + Notice that cdbimport updates only one file in your source code: mapping file that you pointed in <map> 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>
