Cayenne documentation update - added Modeler reverse engineering tool description - docbook maven plugin updated - all docs updated to proper syntax highlight - css style added for console input/output elements (<screen> tag) - added links - updated cdbimport parameters - added some info about modeler - auto insert of the year and cayenne version
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/34be65a0 Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/34be65a0 Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/34be65a0 Branch: refs/heads/master Commit: 34be65a0175ddd4919d681b19a52c3d8490f4ec8 Parents: 320495e Author: Nikita Timofeev <stari...@gmail.com> Authored: Mon Dec 5 17:52:20 2016 +0300 Committer: Nikita Timofeev <stari...@gmail.com> Committed: Mon Dec 5 17:52:20 2016 +0300 ---------------------------------------------------------------------- .../src/docbkx/cayenne-mapping-structure.xml | 8 +- .../src/docbkx/cayennemodeler-application.xml | 56 +++ .../src/docbkx/customizing-cayenne-runtime.xml | 4 +- .../cayenne-guide/src/docbkx/expressions.xml | 32 +- .../src/docbkx/including-cayenne-in-project.xml | 134 +++--- docs/docbook/cayenne-guide/src/docbkx/index.xml | 5 +- docs/docbook/cayenne-guide/src/docbkx/part4.xml | 1 + .../src/docbkx/performance-tuning.xml | 24 +- .../docbkx/persistent-objects-objectcontext.xml | 4 +- .../cayenne-guide/src/docbkx/queries.xml | 40 +- .../cayenne-guide/src/docbkx/re-filtering.xml | 457 ++++++++++--------- .../src/docbkx/re-introduction.xml | 116 +++-- .../cayenne-guide/src/docbkx/re-modeler.xml | 113 +++++ .../src/docbkx/re-name-generator.xml | 18 +- .../docbkx/re-relationships-loading-control.xml | 20 +- .../cayenne-guide/src/docbkx/re-table-types.xml | 22 +- .../src/docbkx/re-types-mapping.xml | 104 +++-- .../cayenne-guide/src/docbkx/rop-deployment.xml | 2 +- docs/docbook/cayenne-guide/src/docbkx/setup.xml | 64 ++- .../src/docbkx/starting-cayenne.xml | 2 +- .../src/images/re-modeler-datasource-select.png | Bin 0 -> 32658 bytes .../re-modeler-reverseengineering-dialog.png | Bin 0 -> 29936 bytes .../src/main/resources/css/cayenne-doc.css | 8 + .../src/docbkx/index.xml | 2 +- .../src/docbkx/reverse-engineering-ch1.xml | 378 ++++++++------- .../src/docbkx/reverse-engineering-ch2.xml | 286 ++++++------ .../getting-started-rop/src/docbkx/index.xml | 2 +- .../getting-started/src/docbkx/index.xml | 2 +- docs/docbook/pom.xml | 7 +- docs/docbook/upgrade-guide/src/docbkx/index.xml | 2 +- 30 files changed, 1095 insertions(+), 818 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml index 6f3fb6c..6d76ef2 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml @@ -29,13 +29,13 @@ legacy reasons this naming convention is different from the convention for the root project descriptor above, and we may align it in the future versions. Here is how a typical project might look on the file - system:<programlisting>~: ls -l + system:<screen><prompt>$</prompt> <userinput>ls -l</userinput> total 24 -rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml --rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</programlisting></para> +-rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</screen></para> <para>DataMap are referenced by name in the root - descriptor:<programlisting><map name="datamap"/></programlisting></para> - <para>Map files are resolved by Cayenne by appending <code>.map.xml</code>" extension to the + descriptor:<programlisting language="xml"><map name="datamap"/></programlisting></para> + <para>Map files are resolved by Cayenne by appending "<code>.map.xml</code>" extension to the map name, and resolving the resulting string relative to the root descriptor URI. The following sections discuss varios ORM model objects, without regards to their XML representation. XML format details are really unimportant to the Cayenne users.</para> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml index 4e41174..4c6b9ae 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml @@ -19,21 +19,75 @@ <title>CayenneModeler Application</title> <section xml:id="working-with-mapping-projects"> <title>Working with Mapping Projects</title> + <para></para> </section> <section xml:id="reverse-engineering-database"> <title>Reverse Engineering Database</title> + <para> + See chapter <link linkend="re-modeler">Reverse Engineering in Cayenne Modeler</link> + </para> </section> <section xml:id="generating-database-schema"> <title>Generating Database Schema</title> + <para> + With Cayenne Modeler you can create simple database schemas without any additional database tools. + This is a good option for initial database setup if you completely created you model with the Modeler. + You can start SQL schema generation by selecting menu + <emphasis role="strong"> + <guimenu>Tools</guimenu> > <guimenuitem>Generate Database Schema</guimenuitem> + </emphasis> + </para> + <para> + You can select what database parts should be generated and what tables you want + </para> </section> <section xml:id="migrations"> <title>Migrations</title> + <para> </para> </section> <section xml:id="generating-java-classes"> <title>Generating Java Classes</title> + <para> + Before using Cayenne in you code you need to generate java source code for persistent objects. + This can be done with Modeler GUI or via <link linkend="mvn-cgen">cgen</link> maven/ant plugin. + </para> + <para> + To generate classes in the modeler use + <emphasis role="strong"> + <guimenu>Tools</guimenu> > <guimenuitem>Generate Classes</guimenuitem> + </emphasis> + </para> + <para> + There is three default types of code generation + <itemizedlist> + <listitem> + <para><emphasis role="strong">Standard Persistent Objects</emphasis></para> + <para> + Default type of generation suitable for almost all cases. + Use this type unless you now what exactly you need to customize. + </para> + </listitem> + <listitem> + <para><emphasis role="strong">Client Persistent Objects</emphasis></para> + <para> + + </para> + </listitem> + <listitem> + <para><emphasis role="strong">Advanced.</emphasis></para> + <para> + In advanced mode you can control almost all aspects of code generation including custom templates for java code. + See default Cayenne templates on + <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-tools/src/main/resources/templates/v1_2";>GitHub</link> + as an example + </para> + </listitem> + </itemizedlist> + </para> </section> <section xml:id="modeling-inheritance"> <title>Modeling Inheritance</title> + <para> </para> </section> <section xml:id="modeling-generic-persistence-classes"> <title>Modeling Generic Persistent Classes</title> @@ -53,8 +107,10 @@ </section> <section xml:id="mapping-objattributes-to-custom-classes"> <title>Mapping ObjAttributes to Custom Classes</title> + <para> </para> </section> <section xml:id="modeling-pk-generation-strategy"> <title>Modeling Primary Key Generation Strategy</title> + <para> </para> </section> </chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml index 097d7d9..21719ce 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml @@ -184,7 +184,7 @@ binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisti This section shows all the configuration possibilities in detail, including changing properties of the existing services, contributing services to standard service lists and maps, and overriding service implementations. All the code examples later in this - section are assumed to be placed in an application module "configure" method:</para><programlisting>public class MyExtensionsModule implements Module { + section are assumed to be placed in an application module "configure" method:</para><programlisting language="java">public class MyExtensionsModule implements Module { public void configure(Binder binder) { // customizations go here... } @@ -199,7 +199,7 @@ ServerRuntime runtime = Supported property names are listed in "Appendix A".</para> <para>There are two ways to set service properties. The most obvious one is to pass it to the JVM with -D flag on startup. - E.g.<programlisting>java -Dcayenne.server.contexts_sync_strategy=false ...</programlisting></para> + E.g.<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false ...</screen></para> <para>A second one is to contribute a property to <code>org.apache.cayenne.configuration.DefaultRuntimeProperties.properties </code>map (see the next section on how to do that). This map contains the default http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/expressions.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml index 7e34f71..01deb9c 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml @@ -109,7 +109,7 @@ understanding the semantics. A Cayenne expression can be represented as a String, which can be later converted to an expression object using <code>Expression.fromString</code> static method. Here is an - example:<programlisting>String expString = "name like 'A%' and price < 1000"; + example:<programlisting language="java">String expString = "name like 'A%' and price < 1000"; Expression exp = Expression.fromString(expString);</programlisting>This particular expression may be used to match Paintings with names that start with "A" and a price less than $1000. While this example is pretty self-explanatory, there are a few @@ -120,13 +120,13 @@ Expression exp = Expression.fromString(expString);</programlisting>This may be other entities, for which this expression is valid. Now the expression details... </para> <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values should be enclosed in single or double quotes. Two of the expressions below are - equivalent:<programlisting>name = 'ABC' + equivalent:<programlisting language="SQL">name = 'ABC' // double quotes are escaped inside Java Strings of course name = \"ABC\"</programlisting></para> <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case sensitive and are usually lowercase. Complex words follow the java camel-case - style:<programlisting>// valid + style:<programlisting language="SQL">// valid name likeIgnoreCase 'A%' // invalid - will throw a parse exception @@ -138,7 +138,7 @@ name LIKEIGNORECASE 'A%'</programlisting></para> optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database expressions are always prefixed with "db:". A special kind of prefix, not discussed yet is "enum:" that prefixes an enumeration - constant:<programlisting>// object path + constant:<programlisting language="SQL">// object path name = 'Salvador Dali' // same object path - a rarely used form @@ -156,13 +156,13 @@ name = enum:org.foo.EnumClass.VALUE1</programlisting></para> <emphasis role="italic">Binary conditions</emphasis> are expressions that contain a path on the left, a value on the right, and some operation between them, such as equals, like, etc. They can be used as qualifiers in - SelectQueries:<programlisting>name like 'A%'</programlisting> + SelectQueries:<programlisting language="SQL">name like 'A%'</programlisting> <emphasis role="italic">Named parameters.</emphasis> Expressions can have named parameters (names that start with "$"). Parameterized expressions allow to create reusable expression templates. Also if an Expression contains a complex object that doesn't have a simple String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such expression is the only way to represent it as String. Here are some - examples:<programlisting>Expression template = Expression.fromString("name = $name"); + examples:<programlisting language="java">Expression template = Expression.fromString("name = $name"); ... Map p1 = Collections.singletonMap("name", "Salvador Dali"); Expression qualifier1 = template.expWithParameters(p1); @@ -171,19 +171,19 @@ Map p2 = Collections.singletonMap("name", "Monet"); Expression qualifier2 = template.expWithParameters(p2);</programlisting>To create a named parameterized expression with a LIKE clause, SQL wildcards must be part of the values in the Map and not the expression string - itself:<programlisting>Expression template = Expression.fromString("name like $name"); + itself:<programlisting language="java">Expression template = Expression.fromString("name like $name"); ... Map p1 = Collections.singletonMap("name", "Salvador%"); Expression qualifier1 = template.expWithParameters(p1);</programlisting>When matching on a relationship, parameters can be Persistent objects or - ObjectIds:<programlisting>Expression template = Expression.fromString("artist = $artist"); + ObjectIds:<programlisting language="java">Expression template = Expression.fromString("artist = $artist"); ... Artist dali = // asume we fetched this one already Map p1 = Collections.singletonMap("artist", dali); Expression qualifier1 = template.expWithParameters(p1);</programlisting>Uninitialized parameters will be automatically pruned from expressions, so a user can omit some parameters when creating an expression from a parameterized - template:<programlisting>Expression template = Expression.fromString("name like $name and dateOfBirth > $date"); + template:<programlisting language="java">Expression template = Expression.fromString("name like $name and dateOfBirth > $date"); ... Map p1 = Collections.singletonMap("name", "Salvador%"); Expression qualifier1 = template.expWithParameters(p1); @@ -211,7 +211,7 @@ Expression qualifier1 = template.expWithParameters(p1); general examples and some gotchas. </para> <para>The following code recreates the expression from the previous chapter, but now using expression - API:<programlisting>// String expression: name like 'A%' and price < 1000 + API:<programlisting language="java">// String expression: name like 'A%' and price < 1000 Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%"); Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000); Expression finalExp = e1.andExp(e2); </programlisting>This @@ -227,7 +227,7 @@ Expression finalExp = e1.andExp(e2); </programlisting>This control how SQL joins are generated if the same path is encountered more than once in the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases to "split" match paths into individual joins if - needed:<programlisting>Expression matchAllExp(String path, Collection values) + needed:<programlisting language="java">Expression matchAllExp(String path, Collection values) Expression matchAllExp(String path, Object... values)</programlisting></para> <para>"Path" argument to both of these methods can use a split character (a pipe symbol '|') instead of dot to indicate that relationship following a path should be split into a @@ -243,16 +243,16 @@ Expression matchAllExp(String path, Object... values)</programlisting></para> is done by the database engine. However the same expressions can also be used for accessing object properties, calculating values, in-memory filtering. </para> <para>Checking whether an object satisfies an - expression:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob"); + expression:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob"); User user = ... if(e.match(user)) { ... }</programlisting>Reading property - value:<programlisting>Expression e = Expression.fromString(User.NAME_PROPERTY); + value:<programlisting language="java">Expression e = Expression.fromString(User.NAME_PROPERTY); String name = e.evaluate(user);</programlisting></para> <para>Filtering a list of - objects:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob"); + objects:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob"); List<User> unfiltered = ... List<User> filtered = e.filterObjects(unfiltered);</programlisting></para> <para> @@ -270,7 +270,7 @@ List<User> filtered = e.filterObjects(unfiltered);</programlisting></para> In some situations, it is convenient to be able to convert Expression instances into EJBQL. Expressions support this conversion. An example is shown below. - <programlisting>String serial = ... + <programlisting language="java">String serial = ... Expression e = ExpressionFactory.matchExp(Pkg.SERIAL_PROPERTY, serial); List<Object> params = new ArrayList<Object>(); EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p"); @@ -281,7 +281,7 @@ for(int i=0;i<params.size();i++) { This would be equivalent to the following purely EJBQL querying logic; - <programlisting>EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1"); + <programlisting language="java">EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1"); query.setParameter(1,serial);</programlisting> </para> </section> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml index ae7f81a..307a16c 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml @@ -22,19 +22,19 @@ <para>Cayenne distribution contains the following core runtime jars in the distribution <code>lib</code> directory: <itemizedlist> <listitem> - <para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full + <para><emphasis role="italic">cayenne-server-<?eval ${project.version}?>.jar</emphasis> - contains full Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications will use only this file.</para> </listitem> <listitem> - <para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on + <para>cayenne-client-<?eval ${project.version}?>.jar - a subset of cayenne-server.jar trimmed for use on the client in an ROP application.</para> </listitem> <listitem> <para>Other cayenne-* jars - various Cayenne extensions.</para> </listitem> </itemizedlist></para> - <para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all + <para>When using <code>cayenne-server-<?eval ${project.version}?>.jar</code> you'll need a few third party jars (all included in <code>lib/third-party</code> directory of the distribution): <itemizedlist> <listitem> <para><link xlink:href="http://velocity.apache.org/";>Apache Velocity @@ -58,10 +58,10 @@ <title>Maven Projects</title> <para>If you are using Maven, you won't have to deal with figuring out the dependencies. You can simply include cayenne-server artifact in your - POM:<programlisting><dependency> + POM:<programlisting language="xml"><dependency> <groupId>org.apache.cayenne</groupId> <artifactId>cayenne-server</artifactId> - <version>X.Y.Z</version> + <version><?eval ${project.version}?></version> </dependency></programlisting></para> <para>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project tasks, such as synching generated Java classes with the mapping, described in the @@ -232,10 +232,10 @@ </tbody> </table> Example - a typical class generation scenario, where pairs of classes are generated with default Maven source destination and superclass - package:<programlisting><plugin> + package:<programlisting language="xml"><plugin> <groupId>org.apache.cayenne.plugins</groupId> <artifactId>maven-cayenne-plugin</artifactId> - <version>X.Y.Z</version> + <version><?eval ${project.version}?></version> <configuration> <map>${project.basedir}/src/main/resources/my.map.xml</map> @@ -353,10 +353,10 @@ </table> </para> <para>Example - creating a DB schema on a local HSQLDB - database:<programlisting><plugin> + database:<programlisting language="xml"><plugin> <groupId>org.apache.cayenne.plugins</groupId> <artifactId>maven-cayenne-plugin</artifactId> - <version>X.Y.Z</version> + <version><?eval ${project.version}?></version> <executions> <execution> <configuration> @@ -378,8 +378,9 @@ <para><code>cdbimport</code> is a <code>maven-cayenne-plugin</code> goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building - your project, possibly followed by "cgen" execution to generate the classes.<table - frame="void"> + your project, possibly followed by "cgen" execution to generate the classes. + CDBImport plugin described in details in chapter <link linkend="re-introduction">Reverse Engineering</link> + <table frame="void"> <caption>cdbimport required parameters</caption> <col width="14%"/> <col width="7%"/> @@ -441,13 +442,6 @@ to guess the DB type.</td> </tr> <tr> - <td><code>catalog</code></td> - <td>String</td> - <td>A database catalog to import tables/stored procedures from. This can - be a pattern in the format supported by - DatabaseMetadata.getTables(). I.e. it can contain '%' wildcard.</td> - </tr> - <tr> <td><code>defaultPackage</code></td> <td>String</td> <td>A Java package that will be set as the imported DataMap default and @@ -457,29 +451,24 @@ no package, and will not compile.</td> </tr> <tr> - <td><code>excludeTables</code></td> - <td>boolean</td> - <td>A comma-separated list of Perl5 patterns that defines which table names should be skipped - during the import. This (together with 'includeTables') is the most - flexible way to filter the table list. Another way to filter it is - via "tablePattern" that is limited to filtering with a single - wildcard pattern as defined in DatabaseMetadata.getTables().</td> - </tr> - <tr> - <td><code>includeTables</code></td> + <td><code>forceDataMapCatalog</code></td> <td>boolean</td> - <td>A comma-separated list of Perl5 patterns that defines which table names should be - included during the import. Additionally matching tables will be - compared with "excludeTables" pattern. If they match include and - exclude, they will be skipped. Another way to filter it is via - "tablePattern" that is limited to filtering with a single wildcard - pattern as defined in DatabaseMetadata.getTables().</td> + <td> + Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) + may some time be undesirable. If this is the case then setting <code>forceDataMapCatalog</code> + to <code>true</code> will set DbEntity catalog to one in the DataMap. + Default value <code>false</code>. + </td> </tr> <tr> - <td><code>importProcedures</code></td> + <td><code>forceDataMapSchema</code></td> <td>boolean</td> - <td>Indicates whether stored procedures should be imported from the - database. Default is false. </td> + <td> + Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) + may some time be undesirable. If this is the case then setting <code>forceDataMapSchema</code> + to <code>true</code> will set DbEntity schema to one in the DataMap. + Default value <code>false</code>. + </td> </tr> <tr> <td><code>meaningfulPkTables</code></td> @@ -491,41 +480,56 @@ <tr> <td><code>namingStrategy</code></td> <td>String</td> - <td>The naming strategy used for mapping database names to object entity - names. Default is - <code>org.apache.cayenne.map.naming.SmartNameGenerator</code>. + <td> + The naming strategy used for mapping database names to object entity + names. Default is <code>org.apache.cayenne.dbsync.naming.DefaultObjectNameGenerator</code>. </td> </tr> <tr> - <td><code>overwrite</code></td> - <td>boolean</td> - <td>If true (default), deletes all existing mappings before starting scheman import. If - false, already existing entities are preserved.</td> - </tr> - <tr> <td><code>password</code></td> <td>String</td> <td>Database user password.</td> </tr> - <tr> - <td><code>procedurePattern</code></td> - <td>String</td> - <td>Pattern to match stored procedure names against for import. Default - is to match all stored procedures. This value is only meaningful if - importProcedures is true. </td> - </tr> - <tr> - <td><code>schema</code></td> - <td>String</td> - <td>A database schema to import tables/stored procedures from. This can - be a pattern in the format supported by - DatabaseMetadata.getTables(). I.e. it can contain '%' wildcard.</td> + <tr xml:id="cdbimport-rr-parameter"> + <td><code>reverseEngineering</code></td> + <td>XML</td> + <td> + An object that contains detailed reverse engineering rules about + what DB objects should be processed. + For full information about this parameter see + <link linkend="re-introduction">reverse engineering</link> chapter. + Here is some simple example: + <programlisting language="xml"><reverseEngineering> + <skipRelationshipsLoading>false</skipRelationshipsLoading> + <skipPrimaryKeyLoading>false</skipPrimaryKeyLoading> + + <catalog name="test_catalog"> + <schema name="test_schema"> + <includeTable pattern=".*"/> + <excludeTable>test_table</excludeTable> + </schema> + </catalog> + + <includeProcedure pattern=".*"/> +</reverseEngineering></programlisting> + + </td> </tr> <tr> - <td><code>tablePattern</code></td> + <td><code>stripFromTableNames</code></td> <td>String</td> - <td>Pattern to match table names against for import. Default is to match - all tables. </td> + <td> + Regex that matches the part of the table name that needs to be stripped off. + Here is some examples: + <programlisting language="xml"><![CDATA[<!-- Strip prefix --> +<stripFromTableNames>^myt_</stripFromTableNames> + +<!-- Strip suffix --> +<stripFromTableNames>_s$</stripFromTableNames> + +<!-- Strip multiple occurrences in the middle --> +<stripFromTableNames>_abc</stripFromTableNames>]]></programlisting> + </td> </tr> <tr> <td><code>username</code></td> @@ -544,10 +548,10 @@ </para> <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) - :<programlisting><plugin> + :<programlisting language="xml"><plugin> <groupId>org.apache.cayenne.plugins</groupId> <artifactId>maven-cayenne-plugin</artifactId> - <version>X.Y.Z</version> + <version><?eval ${project.version}?></version> <executions> <execution> @@ -578,7 +582,7 @@ <title>cdbimport</title> <para>This is an Ant counterpart of "cdbimport" goal of maven-cayenne-plugin described above. It has exactly the same properties. Here is a usage - example:<programlisting> <cdbimport map="${context.dir}/WEB-INF/my.map.xml" + example:<programlisting language="xml"> <cdbimport map="${context.dir}/WEB-INF/my.map.xml" driver="com.mysql.jdbc.Driver" url="jdbc:mysql://127.0.0.1/mydb" username="sa" http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/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 048bfca..b3dc9f2 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/index.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/index.xml @@ -15,11 +15,12 @@ License. --> <book xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0" - xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude";> + xmlns:xi="http://www.w3.org/2001/XInclude"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://docbook.org/xml/5.0/xsd/docbook.xsd"; xml:id="cayenne-guide"> <info> <title>Cayenne Guide</title> <copyright> - <year>2011-2014</year> + <year>2011-<?dbtimestamp format="Y"?></year> <holder>Apache Software Foundation and individual authors</holder> </copyright> <legalnotice> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/part4.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/part4.xml b/docs/docbook/cayenne-guide/src/docbkx/part4.xml index e6d2a45..9f15bbd 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/part4.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/part4.xml @@ -23,4 +23,5 @@ <xi:include href="re-name-generator.xml"/> <xi:include href="re-table-types.xml"/> <xi:include href="re-types-mapping.xml"/> + <xi:include href="re-modeler.xml"/> </part> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml index 41f2d98..d7a12c5 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml @@ -116,7 +116,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</programlisting></para> <link linkend="ejbqlquery">EJBQLQuery</link> queries by employing the "FETCH" keyword.</para> - <screen>SELECT a FROM Artist a LEFT JOIN FETCH a.paintings</screen> + <programlisting language="sql">SELECT a FROM Artist a LEFT JOIN FETCH a.paintings</programlisting> <para> In this case, the Paintings that exist for the Artist will be obtained at the same time @@ -165,12 +165,12 @@ for(DataRow row : rows) { The following example would return a java.util.List of String objects; </para> - <screen>SELECT a.name FROM Artist a</screen> + <programlisting language="sql">SELECT a.name FROM Artist a</programlisting> <para>The following will yield a java.util.List containing Object[] instances, each of which would contain the name followed by the dateOfBirth value.</para> - <screen>SELECT a.name, a.dateOfBirth FROM Artist a</screen> + <programlisting language="sql">SELECT a.name, a.dateOfBirth FROM Artist a</programlisting> <para>Refer to third-party query language documentation for further detail on this mechanism.</para> @@ -204,7 +204,7 @@ for(DataRow row : rows) { } }</programlisting></para> <para>Same thing with a - callback:<programlisting>ObjectSelect.query(Artist.class).iterate(context, (Artist a) -> { + callback:<programlisting language="java">ObjectSelect.query(Artist.class).iterate(context, (Artist a) -> { // do something with the object... ... });</programlisting></para> @@ -212,7 +212,7 @@ for(DataRow row : rows) { each iteration. This is a common scenario in various data processing jobs - read a batch of objects, process them, commit the results, and then repeat. This allows to further optimize processing (e.g. by avoiding frequent - commits).<programlisting>try(ResultBatchIterator<Artist> it = ObjectSelect.query(Artist.class).iterator(context)) { + commits).<programlisting language="java">try(ResultBatchIterator<Artist> it = ObjectSelect.query(Artist.class).iterator(context)) { for(List<Artist> list : it) { // do something with each list ... @@ -265,7 +265,7 @@ List<Artist> artists = <para>To take advantage of query result caching, the first step is to mark your queries appropriately. Here is an example for ObjectSelect query. Other types of queries have similar - API:<programlisting>ObjectSelect.query(Artist.class).localCache("artists");</programlisting></para> + API:<programlisting language="java">ObjectSelect.query(Artist.class).localCache("artists");</programlisting></para> <para>This tells Cayenne that the query created here would like to use local cache of the context it is executed against. A vararg parameter to <code>localCache()</code> (or <code>sharedCache()</code>) method contains so called "cache groups". Those are @@ -277,7 +277,7 @@ List<Artist> artists = providers. One such provider available in Cayenne is a provider for <link xlink:href="http://www.ehcache.org/";>EhCache</link>. It can be enabled on ServerRuntime startup in a custom - Module:<programlisting>ServerRuntimeBuilder + Module:<programlisting language="java">ServerRuntimeBuilder .builder() .addModule((binder) -> binder.bind(QueryCache.class).to(EhCacheQueryCache.class) @@ -285,7 +285,7 @@ List<Artist> artists = .build();</programlisting></para> <para>By default EhCache reads a file called "ehcache.xml" located on classpath. You can put your cache configuration in that file. - E.g.:<programlisting><ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + E.g.:<programlisting language="xml"><ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="false" monitoring="off" dynamicConfig="false"> @@ -302,7 +302,7 @@ List<Artist> artists = sufficient, and the users want real-time cache invalidation when the data changes. So in addition to those policies, the app can invalidate individual cache groups explicitly with - <code>RefreshQuery</code>:<programlisting>RefreshQuery refresh = new RefreshQuery("artist"); + <code>RefreshQuery</code>:<programlisting language="java">RefreshQuery refresh = new RefreshQuery("artist"); context.performGenericQuery(refresh);</programlisting></para> <para>The above can be used e.g. to build UI for manual cache invalidation. It is also possible to automate cache refresh when certain entities are committed. This @@ -310,7 +310,7 @@ context.performGenericQuery(refresh);</programlisting></para> you will need two things: <code>@CacheGroups</code> annotation to mark entities that generate cache invalidation events and  <code>CacheInvalidationFilter</code> that catches the updates to the annotated objects and generates appropriate invalidation - events:<programlisting>// configure filter on startup + events:<programlisting language="java">// configure filter on startup ServerRuntimeBuilder .builder() .addModule((binder) -> @@ -319,7 +319,7 @@ ServerRuntimeBuilder .build();</programlisting></para> <para>Now you can associate entities with cache groups, so that commits to those entities would atomatically invalidate the - groups:<programlisting>@CacheGroups("artists") + groups:<programlisting language="java">@CacheGroups("artists") public class Artist extends _Artist { }</programlisting></para> <para>Finally you may cluster cache group events. They are very small and can be @@ -366,7 +366,7 @@ public class Artist extends _Artist { To do that, set to "false" the following DI property - <code>Constants.SERVER_CONTEXTS_SYNC_PROPERTY</code>, using one of the standard Cayenne DI approaches. E.g. from command - line:<programlisting language="java">java -Dcayenne.server.contexts_sync_strategy=false</programlisting>Or + line:<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false</screen>Or by changing the standard properties Map in a custom extensions module:<programlisting language="java">public class MyModule implements Module { http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml b/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml index 404cab1..6305c9a 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml @@ -267,7 +267,7 @@ generic.writeProperty("name", "New Name");</programlisting>This that spans more than one Cayenne operation. E.g. two sequential commits that need to be rolled back together in case of failure. This can be done via <code>ServerRuntime.performInTransaction</code> - method:<programlisting>Integer result = runtime.performInTransaction(() -> { + method:<programlisting language="java">Integer result = runtime.performInTransaction(() -> { // commit one or more contexts context1.commitChanges(); context2.commitChanges(); @@ -282,7 +282,7 @@ generic.writeProperty("name", "New Name");</programlisting>This <para>When inside the transaction, current thread Transaction object can be accessed via a static method. E.g. here is an example that initializes transaction JDBC connection with a custom connection object - :<programlisting>Transaction tx = BaseTransaction.getThreadTransaction(); + :<programlisting language="java">Transaction tx = BaseTransaction.getThreadTransaction(); tx.addConnection("mydatanode", myConnection); </programlisting></para> </section> </chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/queries.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries.xml b/docs/docbook/cayenne-guide/src/docbkx/queries.xml index 2b3b580..37254d4 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/queries.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/queries.xml @@ -50,8 +50,8 @@ query:<programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class).select(context);</programlisting>This returned all rows in the "ARTIST" table. If the logs were turned on, you might see the following SQL - printed:<programlisting language="java">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 -INFO: === returned 5 row. - took 5 ms.</programlisting></para> + printed:<screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 +INFO: === returned 5 row. - took 5 ms.</screen></para> <para>This SQL was generated by Cayenne from the ObjectSelect above. ObjectSelect can have a qualifier to select only the data matching specific criteria. Qualifier is simply an Expression (Expressions where discussed in the previous chapter), appended to the query @@ -61,9 +61,9 @@ INFO: === returned 5 row. - took 5 ms.</programlisting></para> .where(Artist.NAME.like("Pablo%")) .select(context);</programlisting>The SQL will look different this - time:<programlisting language="java">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ? + time:<screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ? [bind: 1->NAME:'Pablo%'] -INFO: === returned 1 row. - took 6 ms.</programlisting></para> +INFO: === returned 1 row. - took 6 ms.</screen></para> <para>ObjectSelect allows to assemble qualifier from parts, using "and" and "or" method to chain then together:<programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class) @@ -120,28 +120,26 @@ List<String> names = context.performQuery(query);</programlisting> example would require three individual positional parameters (named parameters could also have been used) to be supplied. - <screen>select p from Painting p where p.paintingTitle in (?1,?2,?3)</screen> + <programlisting language="sql">select p from Painting p where p.paintingTitle in (?1,?2,?3)</programlisting> The following example requires a single positional parameter to be supplied. The parameter can be any concrete implementation of the java.util.Collection interface such as java.util.List or java.util.Set. - <screen>select p from Painting p where p.paintingTitle in ?1</screen> + <programlisting language="sql">select p from Painting p where p.paintingTitle in ?1</programlisting> The following example is functionally identical to the one prior. - <screen>select p from Painting p where p.paintingTitle in (?1)</screen> + <programlisting language="sql">select p from Painting p where p.paintingTitle in (?1)</programlisting> + </para> <para> - It is - <link linkend="expressions-to-ejbql">possible to convert</link> - an - <link linkend="expressions">Expression</link> - object used with a - <link linkend="selectquery">SelectQuery</link> + It is <link linkend="expressions-to-ejbql">possible to convert</link> + an <link linkend="expressions">Expression</link> + object used with a <link linkend="selectquery">SelectQuery</link> to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose. </para> - + <para> While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few noteable differences: @@ -278,7 +276,7 @@ query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING")); #bind($xyz 'VARCHAR') #bind($xyz 'DECIMAL' 2)</programlisting></para> <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">update ARTIST set NAME = #bind($name) where ID = #bind($id)</programlisting></para> + example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID = #bind($id)</programlisting></para> </section> <section> <title>#bindEqual</title> @@ -303,7 +301,7 @@ query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING")); #bindEqual($xyz 'VARCHAR') #bindEqual($xyz 'DECIMAL' 2)</programlisting></para> <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para> + example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para> </section> <section> <title>#bindNotEqual</title> @@ -321,7 +319,7 @@ query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING")); #bindNotEqual($xyz 'VARCHAR') #bindNotEqual($xyz 'DECIMAL' 2)</programlisting></para> <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para> + example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para> </section> <section> <title>#bindObjectEqual</title> @@ -427,7 +425,7 @@ select.setParameters(Collections.singletonMap("a", a)); </programlisting></para> #result('DOB' 'java.util.Date' '' 'artist.DATE_OF_BIRTH') #result('SALARY' 'float') </programlisting></para> <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">SELECT #result('ID' 'int'), #result('NAME' 'String'), #result('DATE_OF_BIRTH' 'java.util.Date') FROM ARTIST</programlisting></para> + example:</emphasis><programlisting language="sql">SELECT #result('ID' 'int'), #result('NAME' 'String'), #result('DATE_OF_BIRTH' 'java.util.Date') FROM ARTIST</programlisting></para> </section> <section> <title>#chain and #chunk</title> @@ -451,8 +449,8 @@ select.setParameters(Collections.singletonMap("a", a)); </programlisting></para> #chunk(param) ... #end </programlisting></para> <para><emphasis role="italic">Full example:</emphasis><programlisting language="java">#chain('OR' 'WHERE') - #chunk($name) NAME LIKE #bind($name) #end" - #chunk($id) ARTIST_ID > #bind($id) #end" + #chunk($name) NAME LIKE #bind($name) #end + #chunk($id) ARTIST_ID > #bind($id) #end #end" </programlisting></para> </section> @@ -474,7 +472,7 @@ List<Artist> artists = context.performQuery(query);</programlisting>Just useful with SQLTemplate, as the result type most often than not does not represent a Cayenne entity, but instead may be some aggregated report or any other data whose object structure is opaque to - Cayenne:<programlisting language="java">String sql = SELECT t0.NAME, COUNT(1) FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) " + Cayenne:<programlisting language="java">String sql = "SELECT t0.NAME, COUNT(1) FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) " + "GROUP BY t0.NAME ORDER BY COUNT(1)"; SQLTemplate query = new SQLTemplate(Artist.class, sql); http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml index b36c7f2..930448b 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml @@ -21,38 +21,40 @@ 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> + <!-- 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> + <!-- 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> + <note> + <para>Current version of reverse engineering doesn't support catalog filtering for Postgres database.</para> + </note> </section> <section xml:id="combine-schema-catalog"> <title>Combine Schema and Catalog filters</title> @@ -60,31 +62,32 @@ 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> + <programlisting language="xml"><configuration> + ... + <reverseEngineering> + + <catalog> + <name>shop_01</name> + <schema>schema-name-01</schema> + <schema>schema-name-02</schema> + <schema>schema-name-03</schema> + </catalog> + + <catalog> + <name>shop_02</name> + <schema>schema-name-01</schema> + </catalog> + + <catalog> + <name>shop_03</name> + <schema>schema-name-01</schema> + <schema>schema-name-02</schema> + <schema>schema-name-03</schema> + </catalog> + + </reverseEngineering> + ... +</configuration></programlisting> <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. @@ -92,138 +95,137 @@ <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> + <programlisting language="xml"><configuration> + ... + <reverseEngineering> + + <catalog>shop_01</catalog> + <catalog>shop_02</catalog> + <catalog>shop_03</catalog> + + </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> + <programlisting language="xml"><configuration> + ... + <reverseEngineering> + + <catalog> + <name>shop_01</name> + <schema>schema-name-01</schema> + <schema>schema-name-03</schema> + </catalog> + + <catalog> + <name>shop_02</name> + <schema>schema-name-01</schema> + </catalog> + + <catalog> + <name>shop_03</name> + <schema>schema-name-01</schema> + <schema>schema-name-03</schema> + </catalog> + + </reverseEngineering> + ... +</configuration></programlisting> </section> <section xml:id="including-excluding-tables-columns-procedures"> <title>Including and Excluding tables, columns and procedures</title> <para> - <itemizedlist> + Cayenne reverse engineering let you fine tune table, columns and stored procedures names that you need to import + to your model file. In every filter you can use regexp syntax. Here is some examples of configuration + for common tasks. + </para> + <para> + <orderedlist numeration="arabic"> <listitem> - <para>1. Include tables with âCRM_â prefix if you are working in that domain of application:</para> + <para>Include tables with âCRM_â prefix if you are working in that domain of application:</para> <programlisting language="xml"> - <includeTable>CRM_.*</includeTable> - </programlisting> + <includeTable>CRM_.*</includeTable></programlisting> </listitem> <listitem> - <para>2. Include tables with â_LOOKUPâ suffix</para> + <para>Include tables with â_LOOKUPâ suffix</para> <programlisting language="xml"> - <includeTable> - <pattern>.*_LOOKUP</pattern> - </includeTable> - </programlisting> + <includeTable> + <pattern>.*_LOOKUP</pattern> + </includeTable></programlisting> </listitem> <listitem> - <para>3. Exclude tables with âCRM_â prefix if you are not working only in that domain of application:</para> + <para>Exclude tables with âCRM_â prefix if you are not working only in that domain of application:</para> <programlisting language="xml"> - <excludeTable>CRM_.*</excludeTable> - </programlisting> + <excludeTable>CRM_.*</excludeTable></programlisting> </listitem> <listitem> - <para>4. Include only specific columns that follows specific naming convention:</para> + <para>Include only specific columns that follows specific naming convention:</para> <programlisting language="xml"> - <includeColumn>includeColumn01</includeColumn> - <includeColumn pattern="includeColumn03"/> - </programlisting> + <includeColumn>includeColumn01</includeColumn> + <includeColumn>includeColumn03</includeColumn></programlisting> </listitem> <listitem> - <para>5. Exclude system or obsolete columns:</para> + <para>Exclude system or obsolete columns:</para> <programlisting language="xml"> - <excludeColumn>excludeColumn01</excludeColumn> - <excludeColumn pattern="excludeColumn03"/> - </programlisting> + <excludeColumn>excludeColumn01</excludeColumn> + <excludeColumn>excludeColumn03</excludeColumn></programlisting> </listitem> <listitem> - <para>6. Include/Exclude columns for particular table or group of tables:</para> + <para>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> + <includeTable> + <pattern>table pattern</pattern> + <includeColumn>includeColumn01</includeColumn> + <excludeColumn>excludeColumn01</excludeColumn> + </includeTable></programlisting> </listitem> <listitem> - <para>7. Include stored procedures:</para> + <para>Include stored procedures:</para> <programlisting language="xml"> - <includeProcedure>includeProcedure01</includeProcedure> - <includeProcedure pattern="includeProcedure03"/> - </programlisting> + <includeProcedure>includeProcedure01</includeProcedure> + <includeProcedure> + <pattern>includeProcedure03</pattern> + </includeProcedure></programlisting> </listitem> <listitem> - <para>8. Exclude stored procedures by pattern:</para> + <para>Exclude stored procedures by pattern:</para> <programlisting language="xml"> - <excludeProcedure>excludeProcedure01</excludeProcedure> - <excludeProcedure pattern="excludeProcedure03"/> - </programlisting> + <excludeProcedure>excludeProcedure01</excludeProcedure> + <excludeProcedure> + <pattern>excludeProcedure03</pattern> + </excludeProcedure></programlisting> </listitem> - </itemizedlist> + </orderedlist> </para> <para> - All filtering tags includeTable, excludeTable, includeColumn, excludeColumn, includeProcedure and excludeProcedure have three ways + All filtering tags <code><includeTable></code>, <code><excludeTable></code>, <code><includeColumn></code>, <code><excludeColumn></code>, + <code><includeProcedure></code> and <code><excludeProcedure></code> have three ways to pass filtering RegExp. - <itemizedlist> + <orderedlist numeration="arabic"> <listitem> <para>text inside tag</para> <programlisting language="xml"> - <includeTable>CRM_.*</includeTable> - </programlisting> + <includeTable>CRM_.*</includeTable></programlisting> </listitem> <listitem> - <para>pattern attribute</para> + <para>pattern inner tag</para> <programlisting language="xml"> - <excludeProcedure pattern="excludeProcedure03"/> - </programlisting> + <includeTable> + <pattern>.*_LOOKUP</pattern> + </includeTable></programlisting> </listitem> <listitem> - <para>pattern inner tag</para> + <para>pattern attribute (only for Ant task)</para> <programlisting language="xml"> - <includeTable> - <pattern>.*_LOOKUP</pattern> - </includeTable> - </programlisting> + <excludeProcedure pattern="excludeProcedure03"/></programlisting> </listitem> - </itemizedlist> + </orderedlist> </para> <para> - All filtering tags can be placed inside schema and catalog tags, but also inside <reverseEngineering> tag. It means that filtering rules + All filtering tags can be placed inside schema and catalog tags, but also inside <code><reverseEngineering></code> tag. It means that filtering rules will be applied for all schemas and catalogs. </para> </section> @@ -233,22 +235,21 @@ Initially, letâs make a small sample. Consider the following reverse engineering configuration. </para> <programlisting language="xml"> - <reverseEngineering> - <catalog>shop-01</catalog> - </reverseEngineering> - </programlisting> + <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> + <reverseEngineering> + <catalog>shop-01</catalog> + <catalog> + <name>shop-02</name> + <includeTable>includeTable-01</includeTable> + </catalog> + </reverseEngineering></programlisting> <para> Then Cayenne will do reverse engineering for both shop-01 and shop-02 catalogs. First catalog will not be processed for filtering, but the second catalog will be processed with âincludeTable-01â filter. @@ -260,69 +261,60 @@ Letâs 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> + <reverseEngineering> + + <catalog>shop-01</catalog> + + <catalog> + <name>shop-02</name> + </catalog> + + <catalog> + <name>shop-03</name> + <includeTable>includeTable-01</includeTable> + + <includeTable> + <pattern>includeTable-02</pattern> + </includeTable> + + <includeTable> + <pattern>includeTable-03</pattern> + <includeColumn>includeColumn-01</includeColumn> + <excludeColumn>excludeColumn-01</excludeColumn> + </includeTable> + + <excludeTable>excludeTable-01</excludeTable> + + <excludeTable> + <pattern>excludeTable-02</pattern> + </excludeTable> + + <includeColumn>includeColumn-01</includeColumn> + + <includeColumn> + <pattern>includeColumn-02</pattern> + </includeColumn> + + <excludeColumn>excludeColumn-01</excludeColumn> + + <excludeColumn> + <pattern>excludeColumn-02</pattern> + </excludeColumn> + + <includeProcedure>includeProcedure-01</includeProcedure> + + <includeProcedure> + <pattern>includeProcedure-02</pattern> + </includeProcedure> + + <excludeProcedure>excludeProcedure-01</excludeProcedure> + + <excludeProcedure> + <pattern>excludeProcedure-02</pattern> + </excludeProcedure> + + </catalog> + </reverseEngineering></programlisting> <para> The example above should provide you more idea about how to use filtering and patterns in Cayenne reverse engineering. You could notice that this example demonstrates you the "name" and "pattern" configurations. Yes, you could use these as separates xml element @@ -333,4 +325,47 @@ and table columns. As âshop-03â has variety filter tags, entities from this catalog will be filtered by cdbimport. </para> </section> + <section> + <title>Ant configuration example</title> + <para> + Here is config sample for <code>Ant</code> task: + <programlisting language="xml"> +<!-- inside <cdbimport> tag --> + <catalog>shop-01</catalog> + + <catalog name="shop-02"/> + + <catalog name="shop-03"> + + <includeTable>includeTable-01</includeTable> + <includeTable pattern="includeTable-02"/> + + <includeTable pattern="includeTable-03"> + <includeColumn>includeColumn-01</includeColumn> + <excludeColumn>excludeColumn-01</excludeColumn> + </includeTable> + + <excludeTable>excludeTable-01</excludeTable> + <excludeTable pattern="excludeTable-02"/> + + <includeColumn>includeColumn-01</includeColumn> + <includeColumn pattern="includeColumn-02"/> + + <excludeColumn>excludeColumn-01</excludeColumn> + <excludeColumn pattern="excludeColumn-02"/> + + <includeProcedure>includeProcedure-01</includeProcedure> + <includeProcedure pattern="includeProcedure-02"/> + + <excludeProcedure>excludeProcedure-01</excludeProcedure> + <excludeProcedure pattern="excludeProcedure-02"/> + + </catalog></programlisting> + </para> + <note> + <para> + In Ant task configuration all filter tags located inside root tag <code><cdbimport></code> as there is no <code><reverseEngineering></code> tag. + </para> + </note> + </section> </chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/34be65a0/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml index 3125a7b..ca2a7fa 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml @@ -23,25 +23,87 @@ 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, + Most common practice to complete reverse engineering is to use CDBImport followed by <link linkend="mvn-cgen">CGen Maven plugin</link>, which does class generation according to the Cayenne mapping file updates. </para> + <para> + Here is simple maven configuration to start with: + <programlisting language="xml"> + <plugin> + <groupId>org.apache.cayenne.plugins</groupId> + <artifactId>maven-cayenne-plugin</artifactId> + <version><?eval ${project.version}?></version> + + <configuration> + <map>${project.basedir}/src/main/resources/datamap.map.xml</map> + <url><!-- jdbc url --></url> + <driver><!-- jdbc driver class --></driver> + <username>username</username> + <password>password</password> + <defaultPackage>com.example.package</defaultPackage> + </configuration> + + <executions> + <execution> + <goals> + <goal>cdbimport</goal> + <goal>cgen</goal> + </goals> + </execution> + </executions> + + <dependencies> + <!-- jdbc driver dependency --> + </dependencies> + </plugin> + </programlisting> + For full list of <code>cdbimport</code> parameters see chapter <link linkend="mvn-cdbimport">Including Cayenne in a Project</link> + </para> </section> <section xml:id="re-configuration-file"> - <title>Reverse Engineering configuration file</title> + <title>Reverse Engineering configuration</title> + <para> + Cayenne is designed to support database reverse engineering automation process via Maven and Ant build tools. + </para> + <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: + Here is a default template of reverse engineering settings, which should help you to get started: + <programlisting language="xml"> + <plugin> + ... + <configuration> + ... + <reverseEngineering> + <skipRelationshipsLoading>false</skipRelationshipsLoading> + <skipPrimaryKeyLoading>false</skipPrimaryKeyLoading> + + <catalog> + <schema> + <includeTable> + </includeTable> + </schema> + </catalog> + <includeProcedure>.*</includeProcedure> + </reverseEngineering> + </configuration> + ... + </plugin> + </programlisting> + <caution><para>The whole database structure will be loaded after execution reverse engineering with this stub.</para></caution> </para> - <itemizedlist> + + <!--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> + <para> + Externally in reverseEngineering.xml file, which will be used by Maven/Ant to perform cdbimport + <note><para>Configuration via file is not supported right now</para></note> + </para> + </listitem> - </itemizedlist> - <para> + </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 @@ -58,26 +120,24 @@ 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"> + <?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> + <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> + <catalog> + <schema> + <includeTable> + </includeTable> + </schema> + </catalog> + <includeProcedure pattern=".*"/> + </reverseEngineering> + </programlisting--> + <para>In the next chapter we will see more configuration details</para> </section> </chapter>
