You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by sk...@apache.org on 2016/12/06 13:16:31 UTC
[4/5] cayenne git commit: 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 ( tag
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 <st...@gmail.com>
Authored: Mon Dec 5 17:52:20 2016 +0300
Committer: Nikita Timofeev <st...@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 \u2018CRM_\u2019 prefix if you are working in that domain of application:</para>
+ <para>Include tables with \u2018CRM_\u2019 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 \u2018_LOOKUP\u2019 suffix</para>
+ <para>Include tables with \u2018_LOOKUP\u2019 suffix</para>
<programlisting language="xml">
- <includeTable>
- <pattern>.*_LOOKUP</pattern>
- </includeTable>
- </programlisting>
+ <includeTable>
+ <pattern>.*_LOOKUP</pattern>
+ </includeTable></programlisting>
</listitem>
<listitem>
- <para>3. Exclude tables with \u2018CRM_\u2019 prefix if you are not working only in that domain of application:</para>
+ <para>Exclude tables with \u2018CRM_\u2019 prefix if you are not working only in that domain of application:</para>
<programlisting language="xml">
- <excludeTable>CRM_.*</excludeTable>
- </programlisting>
+ <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\u2019s 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 \u201cincludeTable-01\u201d filter.
@@ -260,69 +261,60 @@
Let\u2019s see how to use patterns in reverse engineering configuration with complete example.
</para>
<programlisting language="xml">
- <reverseEngineering>
-
- <catalog>shop-01</catalog>
-
- <catalog>
- <name>shop-02</name>
- </catalog>
-
- <catalog name="shop-03">
- <includeTable>includeTable-01</includeTable>
-
- <includeTable>
- <pattern>includeTable-02</pattern>
- </includeTable>
-
- <includeTable pattern="includeTable-03">
- <includeColumn pattern="includeColumn-01"/>
- <excludeColumn pattern="excludeColumn-01"/>
- </includeTable>
-
- <excludeTable>excludeTable-01</excludeTable>
-
- <excludeTable>
- <pattern>excludeTable-02</pattern>
- </excludeTable>
-
- <excludeTable pattern="excludeTable-03"/>
-
- <includeColumn>includeColumn-01</includeColumn>
-
- <includeColumn>
- <pattern>includeColumn-02</pattern>
- </includeColumn>
-
- <includeColumn pattern="includeColumn-03"/>
-
- <excludeColumn>excludeColumn-01</excludeColumn>
-
- <excludeColumn>
- <pattern>excludeColumn-02</pattern>
- </excludeColumn>
-
- <excludeColumn pattern="excludeColumn-03"/>
-
- <includeProcedure>includeProcedure-01</includeProcedure>
-
- <includeProcedure>
- <pattern>includeProcedure-02</pattern>
- </includeProcedure>
-
- <includeProcedure pattern="includeProcedure-03"/>
-
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
-
- <excludeProcedure>
- <pattern>excludeProcedure-02</pattern>
- </excludeProcedure>
-
- <excludeProcedure pattern="excludeProcedure-03"/>
-
- </catalog>
- </reverseEngineering>
- </programlisting>
+ <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 \u201cshop-03\u201d 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>