cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [06/13] cayenne git commit: CAY-2371 Switch documentation from Docbook to Asciidoctor format
Date Fri, 05 Jan 2018 13:10:33 GMT
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 6cc7050..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
+++ /dev/null
@@ -1,893 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements. See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to you under the Apache License, Version
-    2.0 (the "License"); you may not use this file except in compliance
-    with the License. You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-    applicable law or agreed to in writing, software distributed under the
-    License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-    CONDITIONS OF ANY KIND, either express or implied. See the License for
-    the specific language governing permissions and limitations under the
-    License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-    version="5.0" xml:id="including-cayenne-in-project">
-    <title>Including Cayenne in a Project</title>
-    <section xml:id="jar-files-and-depdendencies">
-        <title>Jar Files</title>
-        <para>This is an overview of Cayenne jars that is agnostic of the build tool used. The
-            following are the important libraries:</para>
-        <para>
-            <itemizedlist>
-                <listitem>
-                    <para><emphasis role="italic"
-                            >cayenne-di-<?eval ${project.version}?>.jar</emphasis> -  Cayenne
-                        dependency injection (DI) container library. All applications will require
-                        this file.</para>
-                </listitem>
-                <listitem>
-                    <para><emphasis role="italic"
-                            >cayenne-server-<?eval ${project.version}?>.jar</emphasis> - contains
-                        main Cayenne runtime (adapters, DB access classes, etc.). Most applications
-                        will require this file.</para>
-                </listitem>
-                <listitem>
-                    <para><emphasis>cayenne-client-<?eval ${project.version}?>.jar</emphasis> - a
-                        client-side runtime for <link linkend="introduction-to-rop">ROP
-                            applications</link>.</para>
-                </listitem>
-                <listitem>
-                    <para>Other cayenne-* jars - various Cayenne tools extensions.</para>
-                </listitem>
-            </itemizedlist>
-        </para>
-    </section>
-    <section>
-        <title>Dependencies</title>
-        <para>With modern build tools like Maven and Gradle, you should not worry about tracking
-            dependencies. If you have one of those, you can skip this section and go straight to the
-            Maven section below. However if your environment requires manual dependency resolution
-            (like Ant), the distribution provides all of Cayenne jars plus a minimal set of
-            third-party dependencies to get you started in a default configuration. Check
-                <code>lib</code> and <code>lib/third-party</code> folders for those.</para>
-        <para>Dependencies for non-standard configurations will need to be figured out by the users
-            on their own. Check <code>pom.xml</code> files of the corresponding Cayenne modules in
-            one of the searchable Maven archives out there to get an idea of those dependencies
-            (e.g. <link xlink:href="http://search.maven.org">http://search.maven.org</link>).</para>
-    </section>
-    <section xml:id="maven-projects">
-        <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 language="xml">&lt;dependency>
-   &lt;groupId>org.apache.cayenne&lt;/groupId>
-   &lt;artifactId>cayenne-server&lt;/artifactId>
-   &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/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
-            following subsection. The full plugin name is
-                <code>org.apache.cayenne.plugins:cayenne-maven-plugin</code>.</para>
-        <section xml:id="mvn-cgen">
-            <title>cgen</title>
-            <para><code>cgen</code> is a <code>cayenne-maven-plugin</code> goal that generates and maintains
-                source (.java) files of persistent objects based on a DataMap. By default, it is
-                bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
-                recommended default), this task will generate a pair of classes
-                (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
-                changed manually, since they are always overwritten. Subclasses are never
-                overwritten and may be later customized by the user. If "makePairs" is set to
-                "false", a single class will be generated for each ObjEntity. </para>
-            <para>By creating custom templates, you can use cgen to generate other output (such as
-                web pages, reports, specialized code templates) based on DataMap information.</para>
-            <para>
-                <table frame="void" xml:id="cgen_params_table">
-                    <caption>cgen required parameters</caption>
-                    <col width="14%"/>
-                    <col width="7%"/>
-                    <col width="79%"/>
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>Type</th>
-                            <th>Description</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><code>map</code>
-                            </td>
-                            <td>File</td>
-                            <td>DataMap XML file which serves as a source of metadata for class
-                                generation. E.g.
-                                    <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
-                        </tr>
-                    </tbody>
-                </table>
-                <table frame="void">
-                    <caption>cgen optional parameters</caption>
-                    <col width="14%"/>
-                    <col width="7%"/>
-                    <col width="79%"/>
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>Type</th>
-                            <th>Description</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><code>additionalMaps</code>
-                            </td>
-                            <td>File</td>
-                            <td>A directory that contains additional DataMap XML files that may be
-                                needed to resolve cross-DataMap relationships for the the main
-                                DataMap, for which class generation occurs.</td>
-                        </tr>
-                        <tr>
-                            <td><code>client</code></td>
-                            <td>boolean</td>
-                            <td>Whether we are generating classes for the client tier in a Remote
-                                Object Persistence application. "False" by default.</td>
-                        </tr>
-                        <tr>
-                            <td><code>destDir</code></td>
-                            <td>File</td>
-                            <td>Root destination directory for Java classes (ignoring their package
-                                names). The default is "src/main/java".</td>
-                        </tr>
-                        <tr>
-                            <td><code>embeddableTemplate</code></td>
-                            <td>String</td>
-                            <td>Location of a custom Velocity template file for Embeddable class
-                                generation. If omitted, default template is used.</td>
-                        </tr>
-                        <tr>
-                            <td><code>embeddableSuperTemplate</code></td>
-                            <td>String</td>
-                            <td>Location of a custom Velocity template file for Embeddable
-                                superclass generation. Ignored unless "makepairs" set to "true". If
-                                omitted, default template is used.</td>
-                        </tr>
-                        <tr>
-                            <td><code>encoding</code></td>
-                            <td>String</td>
-                            <td>Generated files encoding if different from the default on current
-                                platform. Target encoding must be supported by the JVM running the
-                                build. Standard encodings supported by Java on all platforms are
-                                US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
-                                javadocs for java.nio.charset.Charset for more information.</td>
-                        </tr>
-                        <tr>
-                            <td><code>excludeEntities</code></td>
-                            <td>String</td>
-                            <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
-                                regex) to exclude from template generation. By default none of the
-                                DataMap entities are excluded.</td>
-                        </tr>
-                        <tr>
-                            <td><code>includeEntities</code></td>
-                            <td>String</td>
-                            <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
-                                regex) to include from template generation. By default all DataMap
-                                entities are included.</td>
-                        </tr>
-                        <tr>
-                            <td><code>makePairs</code></td>
-                            <td>boolean</td>
-                            <td>If "true" (a recommended default), will generate subclass/superclass
-                                pairs, with all generated code placed in superclass.</td>
-                        </tr>
-                        <tr>
-                            <td><code>mode</code></td>
-                            <td>String</td>
-                            <td>Specifies class generator iteration target. There are three possible
-                                values: "entity" (default), "datamap", "all". "entity" performs one
-                                generator iteration for each included ObjEntity, applying either
-                                standard to custom entity templates. "datamap" performs a single
-                                iteration, applying DataMap templates. "All" is a combination of
-                                entity and datamap.</td>
-                        </tr>
-                        <tr>
-                            <td><code>overwrite</code></td>
-                            <td>boolean</td>
-                            <td>Only has effect when "makePairs" is set to "false". If "overwrite"
-                                is "true", will overwrite older versions of generated classes.</td>
-                        </tr>
-                        <tr>
-                            <td><code>superPkg</code></td>
-                            <td>String</td>
-                            <td>Java package name of all generated superclasses. If omitted, each
-                                superclass will be placed in the subpackage of its subclass called
-                                "auto". Doesn't have any effect if either "makepairs" or
-                                "usePkgPath" are false (both are true by default). </td>
-                        </tr>
-                        <tr>
-                            <td><code>superTemplate</code></td>
-                            <td>String</td>
-                            <td>Location of a custom Velocity template file for ObjEntity superclass
-                                generation. Only has effect if "makepairs" set to "true". If
-                                omitted, default template is used.</td>
-                        </tr>
-                        <tr>
-                            <td><code>template</code></td>
-                            <td>String</td>
-                            <td>Location of a custom Velocity template file for ObjEntity class
-                                generation. If omitted, default template is used.</td>
-                        </tr>
-                        <tr>
-                            <td><code>usePkgPath</code></td>
-                            <td>boolean</td>
-                            <td>If set to "true" (default), a directory tree will be generated in
-                                "destDir" corresponding to the class package structure, if set to
-                                "false", classes will be generated in "destDir" ignoring their
-                                package.</td>
-                        </tr>
-                        <tr>
-                            <td><code>createPropertyNames</code></td>
-                            <td>boolean</td>
-                            <td>If set to "true", will generate String Property names.
-                                Default is "false"</td>
-                        </tr>
-                    </tbody>
-                </table> Example - a typical class generation scenario, where pairs of classes are
-                generated with default Maven source destination and superclass
-                package:<programlisting language="xml">&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>cayenne-maven-plugin&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-
-    &lt;configuration>
-        &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-    &lt;/configuration>
-
-    &lt;executions>
-        &lt;execution>
-            &lt;goals>
-                &lt;goal>cgen&lt;/goal>
-            &lt;/goals>
-        &lt;/execution>
-    &lt;/executions>
-&lt;/plugin></programlisting></para>
-		</section>
-		<section xml:id="mvn-cdbgen">
-			<title>cdbgen</title>
-			<para><code>cdbgen</code> is a <code>cayenne-maven-plugin</code> goal that drops and/or generates
-				tables in a database on Cayenne DataMap. By default, it is bound to the
-				pre-integration-test phase.
-				<table frame="void" xml:id="cdbgen_parameters">
-					<caption>cdbgen required parameters</caption>
-					<col width="14%"/>
-					<col width="7%"/>
-					<col width="79%"/>
-					<thead>
-						<tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr>
-					</thead>
-					<tbody>
-						<tr>
-							<td><code>map</code>
-							</td>
-							<td>File</td>
-							<td>DataMap XML file which serves as a source of metadata for DB schema
-								generation. E.g.
-									<code>${project.basedir}/src/main/resources/my.map.xml</code></td>
-						</tr>
-                        <tr>
-                            <td><code>dataSource</code>
-                            </td>
-                            <td>XML</td>
-                            <td>An object that contains Data Source parameters</td>
-                        </tr>
-					</tbody>
-				</table>
-            </para>
-            <para>
-                <table frame="void">
-                    <caption>&lt;dataSource> parameters</caption>
-                    <col width="14%"/>
-                    <col width="7%"/>
-                    <col width="7%"/>
-                    <col width="72%"/>
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>Type</th>
-                            <th>Required</th>
-                            <th>Description</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><code>driver</code></td>
-                            <td>String</td>
-                            <td>Yes</td>
-                            <td>A class of JDBC driver to use for the target database.</td>
-                        </tr>
-                        <tr>
-                            <td><code>url</code></td>
-                            <td>String</td>
-                            <td>Yes</td>
-                            <td>JDBC URL of a target database.</td>
-                        </tr>
-                        <tr>
-                            <td><code>username</code></td>
-                            <td>String</td>
-                            <td>No</td>
-                            <td>Database user name.</td>
-                        </tr>
-                        <tr>
-                            <td><code>password</code></td>
-                            <td>String</td>
-                            <td>No</td>
-                            <td>Database user password.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </para>
-			<para>
-				<table frame="void">
-					<caption>cdbgen optional parameters</caption>
-					<col width="14%"/>
-					<col width="7%"/>
-					<col width="79%"/>
-					<thead>
-						<tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr>
-					</thead>
-					<tbody>
-						<tr>
-							<td><code>adapter</code>
-							</td>
-							<td>String</td>
-							<td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
-								this attribute is optional (a generic JdbcAdapter is used if not
-								set), it is highly recommended to specify correct target
-								adapter.</td>
-						</tr>
-						<tr>
-							<td><code>createFK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
-						</tr>
-						<tr>
-							<td><code>createPK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
-								"true".</td>
-						</tr>
-						<tr>
-							<td><code>createTables</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create new tables. Default is "true".</td>
-						</tr>
-						<tr>
-							<td><code>dropPK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
-								"false".</td>
-						</tr>
-						<tr>
-							<td><code>dropTables</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
-								Default is "false".</td>
-						</tr>
-					</tbody>
-				</table>
-			</para>
-			<para>Example - creating a DB schema on a local HSQLDB
-				database:<programlisting language="xml">&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>cayenne-maven-plugin&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-    &lt;executions>
-        &lt;execution>
-            &lt;configuration>
-                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-                &lt;adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter>
-                &lt;dataSource>
-                    &lt;url>jdbc:hsqldb:hsql://localhost/testdb&lt;/url>
-                    &lt;driver>org.hsqldb.jdbcDriver&lt;/driver>
-                    &lt;username>sa&lt;/username>
-                &lt;/dataSource>
-            &lt;/configuration>
-            &lt;goals>
-                &lt;goal>cdbgen&lt;/goal>
-            &lt;/goals>
-        &lt;/execution>
-    &lt;/executions>
-&lt;/plugin></programlisting></para>
-		</section>
-		<section xml:id="mvn-cdbimport">
-			<title>cdbimport</title>
-			<para><code>cdbimport</code> is a <code>cayenne-maven-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.
-				CDBImport plugin described in details in chapter <link linkend="re-introduction">"DB-First Flow"</link>
-				<table frame="void" xml:id="cdbimport_parameters">
-					<caption>cdbimport parameters</caption>
-					<col width="14%"/>
-					<col width="7%"/>
-                    <col width="7%"/>
-					<col width="72%"/>
-					<thead>
-						<tr>
-							<th>Name</th>
-							<th>Type</th>
-                            <th>Required</th>
-							<th>Description</th>
-						</tr>
-					</thead>
-					<tbody>
-						<tr>
-							<td><code>map</code>
-							</td>
-							<td>File</td>
-                            <td>Yes</td>
-							<td>DataMap XML file which is the destination of the schema import. Can
-								be an existing file. If this file does not exist, it is created when
-								cdbimport is executed. E.g.
-									<code>${project.basedir}/src/main/resources/my.map.xml</code>.
-								If "overwrite" is true (the default), an existing DataMap will be
-								used as a template for the new imported DataMap, i.e. all its
-								entities will be cleared and recreated, but its common settings,
-								such as default Java package, will be preserved (unless changed
-								explicitly in the plugin configuration).</td>
-						</tr>
-                        <tr>
-                            <td><code>adapter</code>
-                            </td>
-                            <td>String</td>
-                            <td>No</td>
-                            <td>A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is
-                                optional. If not specified, AutoAdapter is used, which will attempt
-                                to guess the DB type.</td>
-                        </tr>
-                        <tr>
-                            <td><code>dataSource</code>
-                            </td>
-                            <td>XML</td>
-                            <td>Yes</td>
-                            <td>An object that contains Data Source parameters</td>
-                        </tr>
-                        <tr>
-                            <td><code>dbimport</code>
-                            </td>
-                            <td>XML</td>
-                            <td>No</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">"DB-First Flow"</link> chapter.</td>
-                        </tr>
-					</tbody>
-				</table>
-            </para>
-            <para>
-                <table frame="void">
-                    <caption>&lt;dataSource> parameters</caption>
-                    <col width="14%"/>
-                    <col width="7%"/>
-                    <col width="7%"/>
-                    <col width="72%"/>
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>Type</th>
-                            <th>Required</th>
-                            <th>Description</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><code>driver</code></td>
-                            <td>String</td>
-                            <td>Yes</td>
-                            <td>A class of JDBC driver to use for the target database.</td>
-                        </tr>
-                        <tr>
-                            <td><code>url</code></td>
-                            <td>String</td>
-                            <td>Yes</td>
-                            <td>JDBC URL of a target database.</td>
-                        </tr>
-                        <tr>
-                            <td><code>username</code></td>
-                            <td>String</td>
-                            <td>No</td>
-                            <td>Database user name.</td>
-                        </tr>
-                        <tr>
-                            <td><code>password</code></td>
-                            <td>String</td>
-                            <td>No</td>
-                            <td>Database user password.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </para>
-			<para>
-				<table frame="void">
-					<caption>&lt;dbimport> parameters</caption>
-					<col width="14%"/>
-					<col width="7%"/>
-					<col width="79%"/>
-					<thead>
-						<tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr>
-					</thead>
-					<tbody>
-						<tr>
-							<td><code>defaultPackage</code></td>
-							<td>String</td>
-							<td>A Java package that will be set as the imported DataMap default and
-								a package of all the persistent Java classes. This is a required
-								attribute if the "map" itself does not already contain a default
-								package, as otherwise all the persistent classes will be mapped with
-								no package, and will not compile.</td>
-						</tr>
-						<tr>
-							<td><code>forceDataMapCatalog</code></td>
-							<td>boolean</td>
-							<td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
-                                may sometimes 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 is
-                                    <code>false</code>. </td>
-						</tr>
-						<tr>
-							<td><code>forceDataMapSchema</code></td>
-							<td>boolean</td>
-							<td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
-                                may sometimes 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 is
-                                    <code>false</code>. </td>
-						</tr>
-						<tr>
-							<td><code>meaningfulPkTables</code></td>
-							<td>String</td>
-							<td>A comma-separated list of Perl5 patterns that defines which imported tables should have
-								their primary key columns mapped as ObjAttributes. "*" would
-								indicate all tables.</td>
-						</tr>
-						<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.dbsync.naming.DefaultObjectNameGenerator</code>.
-							</td>
-						</tr>
-                        <tr>
-                            <td><code>skipPrimaryKeyLoading</code></td>
-                            <td>boolean</td>
-                            <td>Whether to load primary keys. Default "false".</td>
-                        </tr>
-                        <tr>
-                            <td><code>skipRelationshipsLoading</code></td>
-                            <td>boolean</td>
-                            <td>Whether to load relationships. Default "false".</td>
-                        </tr>
-                        <tr>
-                            <td><code>stripFromTableNames</code></td>
-                            <td>String</td>
-                            <td>Regex that matches the part of the table name that needs to be stripped off when
-                                generating ObjEntity name. Here are 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>usePrimitives</code></td>
-                            <td>boolean</td>
-                            <td>Whether numeric and boolean data types should be mapped as Java primitives or Java
-                                classes. Default is "true", i.e. primitives will be used.</td>
-                        </tr>
-                        <tr>
-                            <td><code>useJava7Types</code></td>
-                            <td>boolean</td>
-                            <td>Whether <code>DATE</code>, <code>TIME</code> and <code>TIMESTAMP</code> data types should be mapped
-                                as <code>java.util.Date</code> or <code>java.time.*</code> classes.
-                                Default is "false", i.e. <code>java.time.*</code> will be used.</td>
-                        </tr>
-						<tr xml:id="cdbimport-rr-parameter">
-							<td>filters configuration</td>
-							<td>XML</td>
-							<td>Detailed reverse engineering rules about what DB objects should be processed.
-                                For full information about this parameter see <link linkend="re-introduction">"DB-First Flow"</link> chapter.
-                                Here is some simple example:
-                                <programlisting language="xml">&lt;dbimport&gt;
-	&lt;catalog name="test_catalog"&gt;
-		&lt;schema name="test_schema"&gt;
-			&lt;includeTable>.*&lt;/includeTable>
-			&lt;excludeTable>test_table&lt;/excludeTable>
-		&lt;/schema&gt;
-	&lt;/catalog&gt;
-
-	&lt;includeProcedure pattern=".*"/&gt;
-&lt;/dbimport&gt;</programlisting>
-                            </td>
-						</tr>
-					</tbody>
-				</table>
-			</para>
-			<para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
-                compared to the <code>cdbgen</code> example above)
-				:<programlisting language="xml">&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>cayenne-maven-plugin&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-
-    &lt;executions>
-        &lt;execution>
-            &lt;configuration>
-                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-                &lt;dataSource>
-                    &lt;url>jdbc:mysql://127.0.0.1/mydb&lt;/url>
-                    &lt;driver>com.mysql.jdbc.Driver&lt;/driver>
-                    &lt;username>sa&lt;/username>
-                &lt;/dataSource>
-                &lt;dbimport>
-                    &lt;defaultPackage>com.example.cayenne&lt;/defaultPackage>
-                &lt;/dbimport>
-            &lt;/configuration>
-            &lt;goals>
-                &lt;goal>cdbimport&lt;/goal>
-            &lt;/goals>
-        &lt;/execution>
-    &lt;/executions>
-&lt;/plugin></programlisting></para>
-        </section>
-    </section>
-    <section xml:id="gradle-projects">
-        <title>Gradle Projects</title>
-        <para>
-            To include Cayenne into your Gradle project you have two options:
-            <itemizedlist>
-                <listitem><para>
-                    Simply add Cayenne as a dependency:
-                    <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-server:<?eval ${project.version}?>'</programlisting>
-                </para></listitem>
-                <listitem>
-                    <para>Or you can use Cayenne Gradle plugin</para>
-                </listitem>
-            </itemizedlist>
-        </para>
-        <section xml:id="gradle-plugin">
-            <title>Gradle Plugin</title>
-            <para>
-                Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping
-                or synching mapping with the database. Plugin aslo provides <code>cayenne</code> extension that have some
-                useful utility methods.
-                Here is example of how to include Cayenne plugin into your project:
-                <programlisting language="groovy">
-buildscript {
-    // add Maven Central repository
-    repositories {
-        mavenCentral()
-    }
-    // add Cayenne Gradle Plugin
-    dependencies {
-        classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '<?eval ${project.version}?>'
-    }
-}
-
-// apply plugin
-apply plugin: 'org.apache.cayenne'
-
-// set default DataMap
-cayenne.defaultDataMap 'datamap.map.xml'
-
-// add Cayenne dependencies to your project
-dependencies {
-    // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
-    compile cayenne.dependency('server')
-    compile cayenne.dependency('java8')
-}</programlisting>
-            </para>
-            <para>
-                <warning>
-                    Cayenne Gradle plugin is experimental and it's API can change later.
-                </warning>
-            </para>
-            <section>
-                <title>cgen</title>
-                <para>
-                    Cgen task generates Java classes based on your DataMap,
-                    it has same configuration parameters as in Maven Plugin version, described in
-                    <xref linkend="cgen_params_table"/>.
-                    If you provided default DataMap via <code>cayenne.defaultDataMap</code>,
-                    you can skip <code>cgen</code> configuration as default settings will suffice in common case.
-                </para>
-                <para>
-                    Here is how you can change settings of the default <code>cgen</code> task:
-                    <programlisting language="groovy">
-cgen {
-    client = false
-    mode = 'all'
-    overwrite = true
-    createPropertiesNames = true
-}</programlisting>
-
-                    And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
-                    <programlisting language="groovy">
-task clientCgen(type: cayenne.cgen) {
-    client = true
-}</programlisting>
-                </para>
-            </section>
-            <section>
-                <title>cdbimport</title>
-                <para>
-                    This task is for creating and synchronizing your Cayenne model from database schema.
-                    Full list of parameters are same as in Maven Plugin version, described in
-                    <xref linkend="cdbimport_parameters"/>, with exception that Gradle version will use Groovy instead
-                    of XML.
-                </para>
-                <para>
-                    Here is example of configuration for cdbimport task:
-                    <programlisting language="groovy">
-cdbimport {
-    // map can be skipped if it is defined in cayenne.defaultDataMap
-    map 'datamap.map.xml'
-
-    dataSource {
-        driver 'com.mysql.cj.jdbc.Driver'
-        url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
-        username 'root'
-        password ''
-    }
-
-    dbImport
-        // additional settings
-        usePrimitives false
-        defaultPackage 'org.apache.cayenne.test'
-
-        // DB filter configuration
-        catalog 'catalog-1'
-        schema 'schema-1'
-
-        catalog {
-            name 'catalog-2'
-
-            includeTable 'table0', {
-                excludeColumns '_column_'
-            }
-
-            includeTables 'table1', 'table2', 'table3'
-
-            includeTable 'table4', {
-                includeColumns 'id', 'type', 'data'
-            }
-
-            excludeTable '^GENERATED_.*'
-        }
-
-        catalog {
-            name 'catalog-3'
-            schema {
-                name 'schema-2'
-                includeTable 'test_table'
-                includeTable 'test_table2', {
-                    excludeColumn '__excluded'
-                }
-            }
-        }
-
-        includeProcedure 'procedure_test_1'
-
-        includeColumns 'id', 'version'
-
-        tableTypes 'TABLE', 'VIEW'
-    }
-}</programlisting>
-                </para>
-            </section>
-            <section>
-                <title>cdbgen</title>
-                <para>
-                    Cdbgen task drops and/or generates tables in a database on Cayenne DataMap.
-                    Full list of parameters are same as in Maven Plugin version, described in
-                    <xref linkend="cdbgen_parameters"/>
-                </para>
-                <para>
-                    Here is example of how to configure default <code>cdbgen</code> task:
-                    <programlisting language="groovy">
-cdbgen {
-
-    adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
-
-    dataSource {
-        driver 'org.apache.derby.jdbc.EmbeddedDriver'
-        url 'jdbc:derby:build/testdb;create=true'
-        username 'sa'
-        password ''
-    }
-
-    dropTables true
-    dropPk true
-
-    createTables true
-    createPk true
-    createFk true
-}</programlisting>
-                </para>
-            </section>
-            <section>
-                <title>Link tasks to Gradle build lifecycle</title>
-                <para>
-                    With gradle you can easily connect Cayenne tasks to default build lifecycle.
-                    Here is short example of how to connect defaut <code>cgen</code> and <code>cdbimport</code> tasks
-                    with <code>compileJava</code> task:
-                    <programlisting language="groovy">cgen.dependsOn cdbimport
-compileJava.dependsOn cgen</programlisting>
-                    <note>
-                        Running <code>cdbimport</code> automatically with build not always a good choice,
-                        e.g. in case of complex model that you need to alter in the Cayenne Modeler after import.
-                    </note>
-                </para>
-            </section>
-        </section>
-    </section>
-    <section xml:id="ant-projects">
-        <title>Ant Projects</title>
-        <para>Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen",
-            "cdbimport". Configuration parameters are also similar (except Maven can guess many
-            defaults that Ant can't). To include Ant tasks in the project, use the following
-            Antlib:<programlisting language="xml">&lt;typedef resource="org/apache/cayenne/tools/antlib.xml"> 
-   &lt;classpath>
-   		&lt;fileset dir="lib" >
-			&lt;include name="cayenne-ant-*.jar" />
-			&lt;include name="cayenne-cgen-*.jar" />
-			&lt;include name="cayenne-dbsync-*.jar" />
-			&lt;include name="cayenne-di-*.jar" />
-			&lt;include name="cayenne-project-*.jar" />
-			&lt;include name="cayenne-server-*.jar" />
-			&lt;include name="commons-collections-*.jar" />
-			&lt;include name="commons-lang-*.jar" />
-			&lt;include name="slf4j-api-*.jar" />
-			&lt;include name="velocity-*.jar" />
-			&lt;include name="vpp-2.2.1.jar" />
-		&lt;/fileset>
-   &lt;/classpath> 
-&lt;/typedef></programlisting></para>
-        <section xml:id="ant-cgen">
-            <title>cgen</title>
-        </section>
-        <section xml:id="ant-cdbgen">
-            <title>cdbgen</title>
-        </section>
-        <section xml:id="ant-cdbimport">
-            <title>cdbimport</title>
-            <para>This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described
-                above. It has exactly the same properties. Here is a usage
-                example:<programlisting language="xml"> &lt;cdbimport map="${context.dir}/WEB-INF/my.map.xml"
-    driver="com.mysql.jdbc.Driver" 
-    url="jdbc:mysql://127.0.0.1/mydb" 
-    username="sa"
-    defaultPackage="com.example.cayenne"/> </programlisting>
-			</para>
-		</section>
-	</section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 8ac6c61..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/index.xml
+++ /dev/null
@@ -1,49 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements. See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to you under the Apache License, Version
-    2.0 (the "License"); you may not use this file except in compliance
-    with the License. You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-    applicable law or agreed to in writing, software distributed under the
-    License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-    CONDITIONS OF ANY KIND, either express or implied. See the License for
-    the specific language governing permissions and limitations under the
-    License.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-      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-<?dbtimestamp format="Y"?></year>
-            <holder>Apache Software Foundation and individual authors</holder>
-        </copyright>
-        <legalnotice>
-            <title>License</title>
-            <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
-                license agreements. See the NOTICE file distributed with this work for additional
-                information regarding copyright ownership. The ASF licenses this file to you under
-                the Apache License, Version 2.0 (the "License"); you may not use this file except in
-                compliance with the License. You may obtain a copy of the License at
-                http://www.apache.org/licenses/LICENSE-2.0</para>
-
-            <para>Unless required by applicable law or agreed to in writing, software distributed
-                under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-                CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
-                language governing permissions and limitations under the License.</para>
-        </legalnotice>
-    </info>
-    <xi:include href="part1.xml"/>
-    <xi:include href="part2.xml"/>
-    <xi:include href="part3.xml"/>
-    <xi:include href="part4.xml"/>
-    <xi:include href="part5.xml"/>
-    <xi:include href="appendix-a.xml"/>
-    <xi:include href="appendix-b.xml"/>
-    <xi:include href="appendix-c.xml"/>
-</book>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml b/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
deleted file mode 100644
index 09eefd6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
+++ /dev/null
@@ -1,314 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements. See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to you under the Apache License, Version
-    2.0 (the "License"); you may not use this file except in compliance
-    with the License. You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-    applicable law or agreed to in writing, software distributed under the
-    License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-    CONDITIONS OF ANY KIND, either express or implied. See the License for
-    the specific language governing permissions and limitations under the
-    License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-    version="5.0" xml:id="lifecycle-events">
-    <title>Lifecycle Events</title>
-    <para>An application might be interested in getting notified when a Persistent object moves
-        through its lifecycle (i.e. fetched from DB, created, modified, committed). E.g. when a new
-        object is created, the application may want to initialize its default properties (this can't
-        be done in constructor, as constructor is also called when an object is fetched from DB).
-        Before save, the application may perform validation and/or set some properties (e.g.
-        "updatedTimestamp"). After save it may want to create an audit record for each saved object,
-        etc., etc. </para>
-    <para>All this can be achieved by declaring callback methods either in Persistent objects or in
-        non-persistent listener classes defined by the application (further simply called
-        "listeners"). There are eight types of lifecycle events supported by Cayenne, listed later
-        in this chapter. When any such event occurs (e.g. an object is committed), Cayenne would
-        invoke all appropriate callbacks. Persistent objects would receive their own events, while
-        listeners would receive events from any objects. </para>
-    <para>Cayenne allows to build rather powerful and complex "workflows" or "processors" tied to
-        objects lifecycle, especially with listeners, as they have full access to the application
-        evnironment outside Cayenne. This power comes from such features as filtering which entity
-        events are sent to a given listener and the ability to create a common operation context for
-        multiple callback invocations. All of these are discussed later in this chapter.</para>
-    <section xml:id="types-of-lifecycle-events">
-        <title>Types of Lifecycle Events</title>
-        <para>Cayenne defines the following 8 types of lifecycle events for which callbacks can be
-                regsitered:<table frame="void">
-                <caption>Lifecycle Event Types</caption>
-                <col width="16%"/>
-                <col width="84%"/>
-                <thead>
-                    <tr>
-                        <th>Event</th>
-                        <th>Occurs...</th>
-                    </tr>
-                </thead>
-                <tbody>
-                    <tr>
-                        <td>PostAdd</td>
-                        <td>right after a new object is created inside
-                                <code>ObjectContext.newObject()</code>. When this event is fired the
-                            object is already registered with its ObjectContext and has its ObjectId
-                            and ObjectContext properties set.</td>
-                    </tr>
-                    <tr>
-                        <td>PrePersist</td>
-                        <td>right before a new object is committed, inside
-                                <code>ObjectContext.commitChanges()</code> and
-                                <code>ObjectContext.commitChangesToParent()</code> (and after
-                                "<code>validateForInsert()</code>").</td>
-                    </tr>
-                    <tr>
-                        <td>PreUpdate</td>
-                        <td>right before a modified object is committed, inside
-                                <code>ObjectContext.commitChanges()</code> and
-                                <code>ObjectContext.commitChangesToParent()</code> (and after
-                                "<code>validateForUpdate()</code>").</td>
-                    </tr>
-                    <tr>
-                        <td>PreRemove</td>
-                        <td>right before an object is deleted, inside
-                                <code>ObjectContext.deleteObjects()</code>. The event is also
-                            generated for each object indirectly deleted as a result of CASCADE
-                            delete rule.</td>
-                    </tr>
-                    <tr>
-                        <td>PostPersist</td>
-                        <td>right after a commit of a new object is done, inside
-                                <code>ObjectContext.commitChanges()</code>.</td>
-                    </tr>
-                    <tr>
-                        <td>PostUpdate</td>
-                        <td>right after a commit of a modified object is done, inside
-                                <code>ObjectContext.commitChanges()</code>.</td>
-                    </tr>
-                    <tr>
-                        <td>PostRemove</td>
-                        <td>right after a commit of a deleted object is done, inside
-                                <code>ObjectContext.commitChanges()</code>.</td>
-                    </tr>
-                    <tr>
-                        <td>PostLoad</td>
-                        <td>
-                            <itemizedlist>
-                                <listitem>
-                                    <para>After an object is fetched inside
-                                            <code>ObjectContext.performQuery()</code>.</para>
-                                </listitem>
-                                <listitem>
-                                    <para>After an object is reverted inside
-                                            <code>ObjectContext.rollbackChanges()</code>.</para>
-                                </listitem>
-                                <listitem>
-                                    <para>Anytime a faulted object is resolved (i.e. if a
-                                        relationship is fetched).</para>
-                                </listitem>
-                            </itemizedlist>
-                        </td>
-                    </tr>
-                </tbody>
-            </table></para>
-    </section>
-    <section xml:id="callback-persistent">
-        <title>Callbacks on Persistent Objects</title>
-        <para>Callback methods on Persistent classes are mapped in CayenneModeler for each
-            ObjEntity. Empty callback methods are automatically created as a part of class
-            generation (either with Maven, Ant or the Modeler) and are later filled with appropriate
-            logic by the programmer. E.g. assuming we mapped a 'post-add' callback called
-            'onNewOrder' in ObjEntity 'Order', the following code will be
-            generated:<programlisting language="java">public abstract class _Order extends CayenneDataObject {
-    protected abstract void onNewOrder();
-}
-
-public class Order extends _Order {
-
-    @Override
-    protected void onNewOrder() {
-        //TODO: implement onNewOrder
-    }
-}</programlisting></para>
-        <para>As <code>onNewOrder()</code> is already declared in the mapping, it does not need to
-            be registered explicitly. Implementing the method in subclass to do something meaningful
-            is all that is required at this point. </para>
-        <para>As a rule callback methods do not have any knowledge of the outside application, and
-            can only access the state of the object itself and possibly the state of other
-            persistent objects via object's own ObjectContext.</para>
-        <para>
-            <note>
-                <para><emphasis role="italic">Validation and callbacks:</emphasis> There is a clear
-                    overlap in functionality between object callbacks and
-                        <code>DataObject.validateForX()</code> methods. In the future validation may
-                    be completely superceeded by callbacks. It is a good idea to use "validateForX"
-                    strictly for validation (or not use it at all). Updating the state before commit
-                    should be done via callbacks.</para>
-            </note>
-        </para>
-    </section>
-    <section xml:id="callback-non-persistent">
-        <title>Callbacks on Non-Persistent Listeners</title>
-            <para>A listener is simply some application class that has one or more annotated
-            callback methods. A callback method signature should be <code>void
-                someMethod(SomePersistentType object)</code>. It can be public, private, protected
-            or use default access:</para>
-            <para>
-                <programlisting language="java"> public class OrderListener { 
-  
-   @PostAdd(Order.class)
-   public void setDefaultsForNewOrder(Order o) {
-      o.setCreatedOn(new Date());
-   }
-}</programlisting>
-            </para>
-        <para>Notice that the example above contains an annotation on the callback method that
-            defines the type of the event this method should be called for. Before we go into
-            annotation details, we'll show how to create and register a listener with Cayenne. It is
-            always a user responsibility to register desired application listeners, usually right
-            after ServerRuntime is started. Here is an example:</para>
-        <para>First let's define 2 simple
-            listeners.<programlisting language="java">public class Listener1 {
-
-    @PostAdd(MyEntity.class)
-    void postAdd(Persistent object) {
-        // do something
-    }
-}
-
-public class Listener2 {
-
-    @PostRemove({ MyEntity1.class, MyEntity2.class })
-    void postRemove(Persistent object) {
-        // do something
-    }
-
-    @PostUpdate({ MyEntity1.class, MyEntity2.class })
-    void postUpdate(Persistent object) {
-        // do something
-    }
-}</programlisting></para>
-        <para>Ignore the annotations for a minute. The important point here is that the listeners
-            are arbitrary classes unmapped and unknown to Cayenne, that contain some callback
-            methods. Now let's register them with
-            runtime:<programlisting language="java">ServerRuntime runtime = ...
-
-runtime.getDataDomain().addListener(new Listener1());
-runtime.getDataDomain().addListener(new Listener2());</programlisting></para>
-        <para>Listeners in this example are very simple. However they don't have to be. Unlike
-            Persistent objects, normally listeners initialization is managed by the application
-            code, not Cayenne, so listeners may have knowledge of various application services,
-            operation transactional context, etc. Besides a single listener can apply to multiple
-            entities. As a consequence their callbacks can do more than just access a single
-            ObjectContext. </para>
-        <para>Now let's discuss the annotations. There are eight annotations exactly matching the
-            names of eight lifecycle events. A callback method in a listener should be annotated
-            with at least one, but possibly with more than one of them. Annotation itself defines
-            what event the callback should react to. Annotation parameters are essentially an entity
-            filter, defining a subset of ObjEntities whose events we are interested
-            in:<programlisting language="java">// this callback will be invoked on PostRemove event of any object 
-// belonging to MyEntity1, MyEntity2 or their subclasses
-@PostRemove({ MyEntity1.class, MyEntity2.class })
-void postRemove(Persistent object) {
-    ...
-}</programlisting><programlisting language="java">// similar example with multipe annotations on a single method
-// each matching just one entity
-@PostPersist(MyEntity1.class)
-@PostRemove(MyEntity1.class)
-@PostUpdate(MyEntity1.class)
-void postCommit(MyEntity1 object) {
-    ...
-}</programlisting></para>
-        <para>As shown above, "value" (the implicit annotation parameter) can contain one or more
-            entity classes. Only these entities' events will result in callback invocation. There's
-            also another way to match entities - via custom annotations. This allows to match any
-            number of entities without even knowing what they are. Here is an example. We'll first
-            define a custom
-            annotation:<programlisting language="java">@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.RUNTIME)
-public @interface Tag {
-
-}</programlisting></para>
-        <para>Now we can define a listener that will react to events from ObjEntities annotated with
-            this
-            annotation:<programlisting language="java">public class Listener3 {
-
-    @PostAdd(entityAnnotations = Tag.class)
-    void postAdd(Persistent object) {
-        // do something
-    }
-}</programlisting></para>
-        <para>As you see we don't have any entities yet, still we can define a listener that does
-            something useful. Now let's annotate some
-            entities:<programlisting language="java">@Tag
-public class MyEntity1 extends _MyEntity1 {
-
-}
-
-@Tag
-public class MyEntity2 extends _MyEntity2 {
-
-}</programlisting></para>
-        </section>
-
-    <section xml:id="comining-listeners-with-datachannelfilters">
-        <title>Combining Listeners with DataChannelFilters</title>
-        <para>A final touch in the listeners design is preserving the state of the listener within a
-            single select or commit, so that events generated by multiple objects can be collected
-            and processed all together. To do that you will need to implement a
-                <code>DataChannelFilter</code>, and add some callback methods to it. They will store
-            their state in a ThreadLocal variable of the filter. Here is an example filter that does
-            something pretty meaningless - counts how many total objects were committed. However it
-            demonstrates the important pattern of aggregating multiple events and presenting a
-            combined
-            result:<programlisting language="java">public class CommittedObjectCounter implements DataChannelFilter {
-
-    private ThreadLocal&lt;int[]> counter;
-
-    @Override
-    public void init(DataChannel channel) {
-        counter = new ThreadLocal&lt;int[]>();
-    }
-
-    @Override
-    public QueryResponse onQuery(ObjectContext originatingContext, Query query, DataChannelFilterChain filterChain) {
-        return filterChain.onQuery(originatingContext, query);
-    }
-
-    @Override
-    public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType,
-            DataChannelFilterChain filterChain) {
-        
-        // init the counter for the current commit
-        counter.set(new int[1]);
-
-        try {
-            return filterChain.onSync(originatingContext, changes, syncType);
-        } finally {
-
-            // process aggregated result and release the counter
-            System.out.println("Committed " + counter.get()[0] + " object(s)");
-            counter.set(null);
-        }
-    }
-
-    @PostPersist(entityAnnotations = Tag.class)
-    @PostUpdate(entityAnnotations = Tag.class)
-    @PostRemove(entityAnnotations = Tag.class)
-    void afterCommit(Persistent object) {
-        counter.get()[0]++;
-    }
-}</programlisting></para>
-        <para>Now since this is both a filter and a listener, it needs to be registered as
-            such:<programlisting language="java">CommittedObjectCounter counter = new CommittedObjectCounter();
-
-ServerRuntime runtime = ...
-DataDomain domain = runtime.getDataDomain();
-
-// register filter
-// this will also add it as a listener (since 3.2)
-domain.addFilter(counter);</programlisting></para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/orderings.xml b/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
deleted file mode 100644
index a3a6bde..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements. See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to you under the Apache License, Version
-    2.0 (the "License"); you may not use this file except in compliance
-    with the License. You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-    applicable law or agreed to in writing, software distributed under the
-    License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-    CONDITIONS OF ANY KIND, either express or implied. See the License for
-    the specific language governing permissions and limitations under the
-    License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-    version="5.0" xml:id="orderings">
-    <title>Orderings</title>
-        <para>An Ordering object defines how a list of objects should be ordered. Orderings are
-            essentially path expressions combined with a sorting strategy. Creating an Ordering:
-            <programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING);</programlisting></para>
-        <para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
-        occurs in the database). Also like expressions, orderings can be used in memory, naturally -
-        to sort
-        objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
-List&lt;Painting> list = ...
-o.orderList(list);</programlisting>Note
-        that unlike filtering with Expressions, ordering is performed in-place. This list object is
-        reordered and no new list is created.</para>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part1.xml b/docs/docbook/cayenne-guide/src/docbkx/part1.xml
deleted file mode 100644
index ac79499..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part1.xml
+++ /dev/null
@@ -1,23 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-	Licensed to the Apache Software Foundation (ASF) under one or more
-	contributor license agreements. See the NOTICE file distributed with
-	this work for additional information regarding copyright ownership.
-	The ASF licenses this file to you under the Apache License, Version
-	2.0 (the "License"); you may not use this file except in compliance
-	with the License. You may obtain a copy of the License at
-
-	http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-	applicable law or agreed to in writing, software distributed under the
-	License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-	CONDITIONS OF ANY KIND, either express or implied. See the License for
-	the specific language governing permissions and limitations under the
-	License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-        xml:id="cayenne-guide-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
-        <title>Object Relational Mapping with Cayenne</title>
-        <xi:include href="setup.xml"/>
-        <xi:include href="cayenne-mapping-structure.xml"/>
-        <xi:include href="cayennemodeler-application.xml"/>
-</part>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part2.xml b/docs/docbook/cayenne-guide/src/docbkx/part2.xml
deleted file mode 100644
index c5f8201..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part2.xml
+++ /dev/null
@@ -1,29 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements. See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to you under the Apache License, Version
-    2.0 (the "License"); you may not use this file except in compliance
-    with the License. You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-    applicable law or agreed to in writing, software distributed under the
-    License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-    CONDITIONS OF ANY KIND, either express or implied. See the License for
-    the specific language governing permissions and limitations under the
-    License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-    xml:id="cayenne-guide-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <title>Cayenne Framework</title>
-    <xi:include href="including-cayenne-in-project.xml"/>
-    <xi:include href="starting-cayenne.xml"/>
-    <xi:include href="persistent-objects-objectcontext.xml"/>
-    <xi:include href="expressions.xml"/>
-    <xi:include href="orderings.xml"/>
-    <xi:include href="queries.xml"/>
-    <xi:include href="lifecycle-events.xml"/>
-    <xi:include href="performance-tuning.xml"/>
-    <xi:include href="customizing-cayenne-runtime.xml"/>
-</part>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part3.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part3.xml b/docs/docbook/cayenne-guide/src/docbkx/part3.xml
deleted file mode 100644
index 75c60b3..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part3.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-	Licensed to the Apache Software Foundation (ASF) under one or more
-	contributor license agreements. See the NOTICE file distributed with
-	this work for additional information regarding copyright ownership.
-	The ASF licenses this file to you under the Apache License, Version
-	2.0 (the "License"); you may not use this file except in compliance
-	with the License. You may obtain a copy of the License at
-
-	http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-	applicable law or agreed to in writing, software distributed under the
-	License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-	CONDITIONS OF ANY KIND, either express or implied. See the License for
-	the specific language governing permissions and limitations under the
-	License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-    xml:id="cayenne-guide-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <title>Cayenne Framework - Remote Object Persistence </title>
-    <xi:include href="rop-introduction.xml"/>
-    <xi:include href="rop-setup.xml"/>
-    <xi:include href="implementing-rop-server.xml"/>
-    <xi:include href="implementing-rop-client.xml"/>
-    <xi:include href="rop-deployment.xml"/>
-    <xi:include href="current-limitations.xml"/>
-</part>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 76ea83e..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part4.xml
+++ /dev/null
@@ -1,24 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-	Licensed to the Apache Software Foundation (ASF) under one or more
-	contributor license agreements. See the NOTICE file distributed with
-	this work for additional information regarding copyright ownership.
-	The ASF licenses this file to you under the Apache License, Version
-	2.0 (the "License"); you may not use this file except in compliance
-	with the License. You may obtain a copy of the License at
-	
-	http://www.apache.org/licenses/LICENSE-2.0 Unless required by
-	applicable law or agreed to in writing, software distributed under the
-	License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-	CONDITIONS OF ANY KIND, either express or implied. See the License for
-	the specific language governing permissions and limitations under the
-	License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-    xml:id="cayenne-guide-part4" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <title>DB-First Flow</title>
-    <xi:include href="re-introduction.xml"/>
-	<xi:include href="re-filtering.xml"/>
-	<xi:include href="re-other-settings.xml"/>
-	<xi:include href="re-modeler.xml"/>
-</part>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part5.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part5.xml b/docs/docbook/cayenne-guide/src/docbkx/part5.xml
deleted file mode 100644
index 347f6ce..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part5.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  ~   Licensed to the Apache Software Foundation (ASF) under one
-  ~  or more contributor license agreements.  See the NOTICE file
-  ~  distributed with this work for additional information
-  ~  regarding copyright ownership.  The ASF licenses this file
-  ~  to you under the Apache License, Version 2.0 (the
-  ~  "License"); you may not use this file except in compliance
-  ~  with the License.  You may obtain a copy of the License at
-  ~
-  ~    http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~  Unless required by applicable law or agreed to in writing,
-  ~  software distributed under the License is distributed on an
-  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  ~  KIND, either express or implied.  See the License for the
-  ~  specific language governing permissions and limitations
-  ~  under the License.
-  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-      xml:id="cayenne-guide-part5" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <title>Cayenne Additional Modules</title>
-    <xi:include href="ext-cache-invalidation.xml"/>
-    <xi:include href="ext-commit-log.xml"/>
-    <xi:include href="ext-crypto.xml"/>
-    <xi:include href="ext-dbcp2.xml"/>
-    <xi:include href="ext-java8.xml"/>
-    <xi:include href="ext-jcache.xml"/>
-    <xi:include href="ext-joda.xml"/>
-</part>


Mime
View raw message