cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [06/11] cayenne git commit: CAY-2371 Switch documentation from Docbook to Asciidoctor format
Date Fri, 05 Jan 2018 14:21:34 GMT
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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
deleted file mode 100644
index 6f3fb6c..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
+++ /dev/null
@@ -1,95 +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="cayenne-mapping-structure">
-    <title>Cayenne Mapping Structure</title>
-    <section xml:id="cayenne-project">
-        <title>Cayenne Project</title>
-        <para>A Cayenne project is an XML representation of a model connecting database schema with
-            Java classes. A project is normally created and manipulated via CayenneModeler GUI and
-            then used to initialize Cayenne runtime. A project is made of one or more files. There's
-            always a root project descriptor file in any valid project. It is normally called
-                <code>cayenne-xyz.xml</code>, where "xyz" is the name of the project.</para>
-        <para>Project descriptor can reference DataMap files, one per DataMap. DataMap files are
-            normally called <code>xyz.map.xml</code>, where "xyz" is the name of the DataMap. For
-            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
-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>
-        <para>DataMap are referenced by name in the root
-            descriptor:<programlisting>&lt;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>
-    </section>
-    <section xml:id="datamap">
-        <title>DataMap</title>
-        <para>DataMap is a container of persistent entities and other object-relational metadata.
-            DataMap provides developers with a scope to organize their entities, but it does not
-            provide a namespace for entities. In fact all DataMaps present in runtime are combined
-            in a single namespace. Each DataMap must be associated with a DataNode. This is how
-            Cayenne knows which database to use when running a query.</para>
-    </section>
-    <section xml:id="datanode">
-        <title>DataNode</title>
-        <para>DataNode is model of a database. It is actually pretty simple. It has an arbitrary
-            user-provided name and information needed to create or locate a JDBC DataSource. Most
-            projects only have one DataNode, though there may be any number of nodes if
-            needed.</para>
-    </section>
-    <section xml:id="dbentity">
-        <title>DbEntity</title>
-        <para>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes
-            that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships
-            are not strictly tied to FK constraints in DB, and should be mapped for all logical
-            "relationships" between the tables.</para>
-    </section>
-    <section xml:id="objentity">
-        <title>ObjEntity</title>
-        <para>ObjEntity is a model of a single persistent Java class. ObjEntity is made of
-            ObjAttributes and ObjRelationships. Both correspond to entity class properties. However
-            ObjAttributes represent "simple" properties (normally things like String, numbers,
-            dates, etc.), while ObjRelationships correspond to properties that have a type of
-            another entity. </para>
-        <para>ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each
-            ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped
-            DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from
-            another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called
-            "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a
-            chain of DbRelationships ("flattened" ObjRelationship).</para>
-        <para>ObjEntities may also contain mapping of their lifecycle callback methods.</para>
-    </section>
-    <section xml:id="embeddable">
-        <title>Embeddable</title>
-        <para>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity,
-            but maps to multiple columns in the database.</para>
-    </section>
-    <section xml:id="procedure">
-        <title>Procedure</title>
-        <para>A model of a stored procedure in the database.</para>
-    </section>
-    <section xml:id="query">
-        <title>Query</title>
-        <para>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created
-            in the code. Depending on the circumstances the users may take one or the other
-            approach.</para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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
deleted file mode 100644
index 4e41174..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ /dev/null
@@ -1,60 +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="cayennemodeler-application">
-    <title>CayenneModeler Application</title>
-    <section xml:id="working-with-mapping-projects">
-        <title>Working with Mapping Projects</title>
-    </section>
-    <section xml:id="reverse-engineering-database">
-        <title>Reverse Engineering Database</title>
-    </section>
-    <section xml:id="generating-database-schema">
-        <title>Generating Database Schema</title>
-    </section>
-    <section xml:id="migrations">
-        <title>Migrations</title>
-    </section>
-    <section xml:id="generating-java-classes">
-        <title>Generating Java Classes</title>
-    </section>
-    <section xml:id="modeling-inheritance">
-        <title>Modeling Inheritance</title>
-    </section>
-    <section xml:id="modeling-generic-persistence-classes">
-        <title>Modeling Generic Persistent Classes</title>
-        <para>Normally each ObjEntity is mapped to a specific Java class (such as Artist or
-            Painting) that explicitly declare all entity properties as pairs of getters and setters.
-            However Cayenne allows to map a completly generic class to any number of entities. The
-            only expectation is that a generic class implements
-                <emphasis>org.apache.cayenne.DataObject</emphasis>. So an ideal candidate for a
-            generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</para>
-        <para>If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic
-            mapping and uses the following implicit rules to determine a class of a generic object.
-            If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new
-            objects. If not, org.apache.cayenne.CayenneDataObject is used.</para>
-        <para>Class generation procedures (either done in the Modeler or with Ant or Maven) would
-            skip entities that are mapped to CayenneDataObject explicitly or have no class
-            mapping.</para>
-    </section>
-    <section xml:id="mapping-objattributes-to-custom-classes">
-        <title>Mapping ObjAttributes to Custom Classes</title>
-    </section>
-    <section xml:id="modeling-pk-generation-strategy">
-        <title>Modeling Primary Key Generation Strategy</title>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
deleted file mode 100644
index 4b69324..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
+++ /dev/null
@@ -1,20 +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="current-limitations">
-    <title>Current Limitations</title>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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
deleted file mode 100644
index d8155ee..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
+++ /dev/null
@@ -1,279 +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="customizing-cayenne-runtime">
-    <title>Customizing Cayenne Runtime</title>
-    <section xml:id="depdendency-injection-container">
-        <title>Dependency Injection Container</title>
-        <para>Cayenne runtime is built around a small powerful dependency injection (DI) container. Just
-            like other popular DI technologies, such as Spring or Guice, Cayenne DI container
-            manages sets of interdependent objects  and allows users to configure them. These
-            objects are regular Java objects. We are calling them "services" in this document to
-            distinguish from all other objects that are not configured in the container and are not
-            managed. DI container is responsible for service instantiation, injecting correct
-            dependencies, maintaining service instances scope, and dispatching scope events to
-            services. </para>
-        <para>The services are configured in special Java classes called "modules". Each module
-            defines binding of service interfaces to implementation instances, implementation types
-            or providers of implementation instances. There are no XML configuration files, and all
-            the bindings are type-safe. The container supports injection into instance variables and
-            constructor parameters based on the <code>@Inject</code> annotation. This mechanism is
-            very close to Google Guice.</para>
-        <para>The discussion later in this chapter demonstrates a standalone DI container. But keep in
-            mind that Cayenne already has a built-in Injector, and a set of default modules. A
-            Cayenne user would normally only use the API below to write custom extension modules
-            that will be loaded in that existing container when creating ServerRuntime. See
-            "Starting and Stopping ServerRuntime" chapter for an example of passing an extension
-            module to Cayenne.</para>
-        <para>Cayenne DI probably has ~80% of the features expected in a DI container and has no
-            dependency on the rest of Cayenne, so in theory can be used as an application-wide DI
-            engine. But it's primary purpose is still to serve Cayenne. Hence there are no plans to
-            expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere
-            with Spring, Guice or any other such framework present elsewhere in the
-            application.</para>
-        <section xml:id="di-bindings-api">
-            <title>DI Bindings API</title>
-            <para>To have a working DI container, we need three things: service interfaces and
-                classes, a module that describes service bindings, a container that loads the
-                module, and resolves the depedencies. Let's start with service interfaces and
-                classes:<programlisting language="java">public interface Service1 {
-    public String getString();
-}</programlisting><programlisting language="java">public interface Service2 {
-    public int getInt();
-}</programlisting></para>
-            <para>A service implementation using instance variable
-                injection:<programlisting language="java">public class Service1Impl implements Service1 {
-    @Inject
-    private Service2 service2;
-
-    public String getString() {
-        return service2.getInt() + "_Service1Impl";
-    }
-}</programlisting>Same
-                thing, but using constructor
-                injection:<programlisting language="java">public class Service1Impl implements Service1 {
-
-    private Service2 service2;
-
-    public Service1Impl(@Inject Service2 service2) {
-        this.service2 = service2;
-    }
-
-    public String getString() {
-        return service2.getInt() + "_Service1Impl";
-    }
-}
-</programlisting><programlisting language="java">public class Service2Impl implements Service2 {
-    private int i;
-
-    public int getInt() {
-        return i++;
-    }
-}</programlisting></para>
-            <para>Now let's create a module implementing
-                    <code>org.apache.cayenne.tutorial.di.Module</code> interface that will contain
-                DI configuration. A module binds service objects to keys that are reference. Binder
-                provided by container implements fluent API to connect the key to implementation,
-                and to configure various binding options (the options, such as scope, are
-                demonstrated later in this chapter). The simplest form of a key is a Java Class
-                object representing service interface. Here is a module that binds Service1 and
-                Service2 to corresponding default implementations:</para>
-            <para>
-                <programlisting language="java">public class Module1 implements Module {
-
-    public void configure(Binder binder) {
-        binder.bind(Service1.class).to(Service1Impl.class);
-        binder.bind(Service2.class).to(Service2Impl.class);
-    }
-}</programlisting>
-            </para>
-            <para>Once we have at least one module, we can create a DI container.
-                    <code>org.apache.cayenne.di.Injector</code> is the container class in
-                Cayenne:<programlisting language="java">Injector injector = DIBootstrap.createInjector(new Module1());</programlisting></para>
-            <para>Now that we have created the container, we can obtain services from it and call
-                their
-                methods:<programlisting language="java">Service1 s1 = injector.getInstance(Service1.class);
-for (int i = 0; i &lt; 5; i++) {
-    System.out.println("S1 String: " + s1.getString());
-}</programlisting></para>
-            <para>This outputs the following lines, demonstrating that s1 was Service1Impl and
-                Service2 injected into it was
-                Service2Impl:<programlisting language="java">0_Service1Impl
-1_Service1Impl
-2_Service1Impl
-3_Service1Impl
-4_Service1Impl</programlisting></para>
-            <para>There are more flavors of bindings:
-                <programlisting language="java">// binding to instance - allowing user to create and configure instance
-// inside the module class
-binder.bind(Service2.class).toInstance(new Service2Impl());
-
-// binding to provider - delegating instance creation to a special
-// provider class
-binder.bind(Service1.class).toProvider(Service1Provider.class);
-
-// binding to provider instance
-binder.bind(Service1.class).toProviderInstance(new Service1Provider());
-
-// multiple bindings of the same type using Key
-// injection can reference the key name in annotation:
-// @Inject("i1")
-// private Service2 service2;
-binder.bind(Key.get(Service2.class, "i1")).to(Service2Impl.class);
-binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisting></para>
-            <para>Another types of confiuguration that can be bound in the container are lists and
-                maps. They will be discussed in the following chapters. </para>
-        </section>
-        <section xml:id="managing-services-lifecycle">
-            <title>Service Lifecycle</title>
-            <para>An important feature of the Cayenne DI container is instance <emphasis role="italic"
-                    >scope</emphasis>. The default scope (implicitly used in all examples above) is
-                "singleton", meaning that a binding would result in creation of only one service
-                instance, that will be repeatedly returned from
-                    <code>Injector.getInstance(..)</code>, as well as injected into classes that
-                declare it as a dependency. </para>
-            <para>Singleton scope dispatches a "BeforeScopeEnd" event to interested services. This
-                event occurs before the scope is shutdown, i.e. when
-                    <code>Injector.shutdown()</code> is called. Note that the built-in Cayenne
-                injector is shutdown behind the scenes when <code>ServerRuntime.shutdown()</code>
-                is invoked. Services may register as listeners for this event by annotating a
-                no-argument method with <code>@BeforeScopeEnd</code> annotation. Such method should
-                be implemented if a service needs to clean up some resources, stop threads,
-                etc.</para>
-            <para>Another useful scope is "no scope", meaning that every time a container is asked to provide
-                a service instance for a given key, a new instance will be created and
-                returned:<programlisting language="java">binder.bind(Service2.class).to(Service2Impl.class).withoutScope();</programlisting>Users
-                can also create their own scopes, e.g. a web application request scope or a session
-                scope. Most often than not custom scopes can be created as instances of
-                    <code>org.apache.cayenne.di.spi.DefaultScope</code> with startup and shutdown
-                managed by the application (e.g. singleton scope is a DefaultScope managed by the
-                Injector) . </para>
-        </section>
-        <section xml:id="overriding-services">
-            <title>Overriding Services</title>
-            <para>Cayenne DI allows to override services already definied in the current module, or
-                more commonly - some other module in the the same container. Actually there's no
-                special API to override a service, you'd just bind the service key again with a new
-                implementation or provider. The last binding for a key takes precedence. This means
-                that the order of modules is important when configuring a container. The built-in
-                Cayenne injector ensures that Cayenne standard modules are loaded first, followed by
-                optional user extension modules. This way the application can override the standard
-                services in Cayenne.</para>
-        </section>
-    </section>
-    <section xml:id="ways-to-customize-runtime">
-        <title> Customization Strategies</title>
-        <para>The previous section discussed how Cayenne DI works in general terms. Since Cayenne users
-            will mostly be dealing with an existing Injector provided by ServerRuntime, it is
-            important to understand how to build custom extensions to a preconfigured container. As
-            shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by
-            writing an aplication DI module (or multiple modules) that configures service overrides.
-            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 {
-    public void configure(Binder binder) {
-        // customizations go here...
-    }
-}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule();
-ServerRuntime runtime = 
-    new ServerRuntime("com/example/cayenne-mydomain.xml", extensions);</programlisting>
-        <section xml:id="changing-properties-of-existing-services">
-            <title>Changing Properties of Existing Services</title>
-            <para>Many built-in Cayenne services change their behavior based on a value of some
-                environment property. A user may change Cayenne behavior without even knowing which
-                services are responsible for it, but setting a specific value of a known property.
-                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>
-            <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
-                property values and can accept application-specific values, overrding the defaults. </para>
-            <para>Note that if a property value is a name of a Java class, when this Java class is
-                instantiated by Cayenne, the container performs injection of instance variables. So
-                even the dynamically specified Java classes can use @Inject annotation to get a hold
-                of other Cayenne services.</para>
-            <para>If the same property is specified both in the command line and in the properties
-                map, the command-line value takes precedence. The map value will be ignored. This
-                way Cayenne runtime can be reconfigured during deployment.</para>
-        </section>
-        <section xml:id="contributing-to-service-lists-maps">
-            <title>Contributing to Service Collections</title>
-            <para>Cayenne can be extended by adding custom objects to named maps or lists bound in
-                DI. We are calling these lists/maps "service collections". A service collection
-                allows things like appending a custom strategy to a list of built-in strategies.
-                E.g. an application that needs to install a custom DbAdapter for some database type
-                may contribute an instance of custom DbAdapterDetector to a
-                    <code>org.apache.cayenne.configuration.server.DefaultDbAdapterFactory.detectors</code>
-                list:</para>
-            <programlisting language="java">public class MyDbAdapterDetector implements DbAdapterDetector {
-    public DbAdapter createAdapter(DatabaseMetaData md) throws SQLException {
-        // check if we support this database and retun custom adapter
-        ...
-    }
-}</programlisting>
-            <programlisting language="java">// since build-in list for this key is a singleton, repeated
-// calls to 'bindList' will return the same instance 
-binder.bindList(DefaultDbAdapterFactory.DETECTORS_LIST)
-       .add(MyDbAdapterDetector.class);</programlisting>
-            <para>Maps are customized using a similar "<code>bindMap</code>" method.</para>
-            <para>The names of built-in collections are listed in "Appendix B".</para>
-        </section>
-        <section xml:id="alternative-service-implementations">
-            <title>Alternative Service Implementations</title>
-            <para>As mentioned above, custom modules are loaded by ServerRuntime after the built-in
-                modules. So it is easy to redefine a built-in service in Cayenne by rebinding
-                desired implementations or providers. To do that, first we need to know what those
-                services to redefine are. While we describe some of them in the following sections,
-                the best way to get a full list is to check the source code of the Cayenne version
-                you are using and namely look in
-                    <code>org.apache.cayenne.configuration.server.ServerModule</code> - the main
-                built-in module in Cayenne. </para>
-            <para>Now an example of overriding <code>QueryCache</code> service. The default
-                implementation of this service is provided by <code>MapQueryCacheProvider</code>.
-                But if we want to use <code>EhCacheQueryCache</code> (a Cayenne wrapper for the
-                EhCache framework), we can define it like
-                this:<programlisting language="java">binder.bind(QueryCache.class).to(EhCacheQueryCache.class);</programlisting></para>
-        </section>
-    </section>
-    <section xml:id="noteworthy-runtime-components">
-        <title>Noteworthy Built-in Services</title>
-        <section xml:id="jdbceventlogger">
-            <title>JdbcEventLogger</title>
-            <para><code>org.apache.cayenne.log.JdbcEventLogger</code> is the service that defines
-                logging API for Cayenne internals. It provides facilities for logging queries,
-                commits, transactions, etc. The default implementation is
-                    <code>org.apache.cayenne.log.CommonsJdbcEventLogger</code> that performs logging
-                via commons-logging library. Cayenne library includes another potentially useful
-                logger - <code>org.apache.cayenne.log.FormattedCommonsJdbcEventLogger</code> that
-                produces formatted multiline SQL output that can be easier to read.</para>
-        </section>
-        <section xml:id="datasourcefactory">
-            <title>DataSourceFactory</title>
-        </section>
-        <section xml:id="datachannelfilter">
-            <title>DataChannelFilter</title>
-        </section>
-        <section xml:id="querycache">
-            <title>QueryCache</title>
-        </section>
-        <section xml:id="extendedtypes">
-            <title>ExtendedTypes</title>
-        </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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
deleted file mode 100644
index 34257f3..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
+++ /dev/null
@@ -1,265 +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="expressions">
-    <title>Expressions</title>
-    <section xml:id="expressions-overview">
-        <title>Expressions Overview</title>
-        <para>Cayenne provides a simple yet powerful object-based expression language. The most common
-            usese of expressions are to build qualifiers and orderings of queries that are later
-            converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
-            access certain values in the object graph or to perform in-memory object filtering and
-            sorting). Cayenne provides API to build expressions in the code and a parser to create
-            expressions from strings.</para>
-    </section>
-    <section xml:id="path-expressions">
-        <title>Path Expressions</title>
-        <para>Before discussing how to build expressions, it is important to understand one group of
-            expressions widely used in Cayenne - path expressions. There are two types of path
-            expressions - object and database, used for navigating graphs of connected objects or
-            joined DB tables respectively. Object paths are much more commonly used, as after all
-            Cayenne is supposed to provide a degree of isolation of the object model from the
-            database. However database paths are helpful in certain situations. General structure of
-            path expressions is the following:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
-                <listitem>
-                    <para>&quot;db:&quot; is an optional prefix indicating that the following path is a DB
-                        path. Otherwise it is an object path.</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;segment&quot; is a name of a property (relationship or attribute in Cayenne
-                        terms) in the path. Path must have at least one segment; segments are
-                        separated by dot (&quot;.&quot;).</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;+&quot; An &quot;OUTER JOIN&quot; path component. Currently &quot;+&quot; only has effect when
-                        translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
-                        is ignored.</para>
-                </listitem>
-            </itemizedlist></para>
-        <para>An object path expression represents a chain of property names rooted in a certain
-            (unspecified during expression creation) object and &quot;navigating&quot; to its related value.
-            E.g. a path expression &quot;artist.name&quot; might be a property path starting from a Painting
-            object, pointing to the related Artist object, and then to its name attribute. A few
-            more examples:</para>
-        <para>
-            <itemizedlist>
-                <listitem>
-                    <para>&quot;name&quot; - can be used to navigate (read) the &quot;name&quot; property of a Person
-                        (or any other type of object that has a &quot;name&quot; property).</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;artist.exhibits.closingDate&quot; - can be used to navigate to a closing date
-                        of any of the exhibits of a Painting&apos;s Artist object.</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;artist.exhibits+.closingDate&quot; - same as the previous example, but when
-                        translated into SQL, an OUTER JOIN will be used for &quot;exhibits&quot;.</para>
-                </listitem>
-            </itemizedlist>
-        </para>
-        <para>Similarly a database path expression is a dot-separated path through DB table joins
-            and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
-            (the closest concept to DbRelationship name in the DB world is a named foreign key
-            constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
-            constraints naming or even constraints presence). A database path therefore might look
-            like this -  &quot;db:dbrelationshipX.dbrelationshipY.COLUMN_Z&quot;. More specific examples:<itemizedlist>
-                <listitem>
-                    <para>&quot;db:NAME&quot; - can be used to navigate to the value of &quot;NAME&quot; column of some
-                        unspecified table.</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;db:artist.artistExhibits.exhibit.CLOSING_DATE&quot; - can be used to match a
-                        closing date of any of the exhibits of a related artist record.</para>
-                </listitem>
-            </itemizedlist></para>
-        <para>Cayenne supports &quot;aliases&quot; in path Expressions. E.g. the same expression can be
-            written using explicit path or an alias:<itemizedlist>
-                <listitem>
-                    <para>&quot;artist.exhibits.closingDate&quot; - full path</para>
-                </listitem>
-                <listitem>
-                    <para>&quot;e.closingDate&quot; - alias &quot;e&quot; is used for &quot;artist.exhibits&quot;.</para>
-                </listitem>
-            </itemizedlist>SelectQuery using the second form of the path expression must be made
-            aware of the alias via <emphasis role="italic">
-                &quot;SelectQuery.aliasPathSplits(..)&quot;</emphasis>, otherwise an Exception will be
-            thrown. The main use of aliases is to allow users to control how SQL joins are generated
-            if the same path is encountered more than once in any given Expression. Each alias for
-            any given path would result in a separate join. Without aliases, a single join will be
-            used for a group of matching paths.</para>
-    </section>
-    <section xml:id="expressions-from-strings">
-        <title>Creating Expressions from Strings </title>
-        <para>While in most cases users are likely to rely on API from the following section for
-            expression creation, we&apos;ll start by showing String expressions, as this will help
-            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 = &quot;name like &apos;A%&apos; and price &lt; 1000&quot;;
-Expression exp = Expression.fromString(expString);</programlisting>This
-            particular expression may be used to match Paintings with names that start with &quot;A&quot; and
-            a price less than $1000. While this example is pretty self-explanatory, there are a few
-            points worth mentioning. &quot;name&quot; and &quot;price&quot; here are object paths discussed earlier. As
-            always, paths themselves are not attached to a specific root entity and can be applied
-            to any entity that has similarly named attributes or relationships. So when we are
-            saying that this expression &quot;may be used to match Paintings&quot;, we are implying that there
-            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 = &apos;ABC&apos;
-
-// double quotes are escaped inside Java Strings of course
-name = \&quot;ABC\&quot;</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
-name likeIgnoreCase &apos;A%&apos;
-
-// invalid - will throw a parse exception
-name LIKEIGNORECASE &apos;A%&apos;</programlisting></para>
-        <para><emphasis role="italic">Grouping with parenthesis:</emphasis>
-            <programlisting>value = (price + 250.00) * 3</programlisting>
-        </para>
-        <para><emphasis role="italic">Path prefixes.</emphasis> Object expressions are unquoted strings,
-            optionally prefixed by &quot;obj:&quot; (usually they are not prefixed at all actually). Database
-            expressions are always prefixed with &quot;db:&quot;. A special kind of prefix, not discussed yet
-            is &quot;enum:&quot; that prefixes an enumeration
-            constant:<programlisting>// object path
-name = &apos;Salvador Dali&apos;
-
-// same object path - a rarely used form
-obj:name = &apos;Salvador Dali&apos;
-
-// multi-segment object path
-artist.name = &apos;Salvador Dali&apos;
-
-// db path
-db:NAME = &apos;Salvador Dali&apos;
-
-// enumeration constant
-name = enum:org.foo.EnumClass.VALUE1</programlisting></para>
-        <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 &apos;A%&apos;</programlisting>
-            <emphasis role="italic">Named parameters.</emphasis> Expressions can have named parameters (names that
-            start with &quot;$&quot;). Parameterized expressions allow to create reusable expression
-            templates. Also if an Expression contains a complex object that doesn&apos;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(&quot;name = $name&quot;);
-...
-Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador Dali&quot;);
-Expression qualifier1 = template.expWithParameters(p1);
-...
-Map p2 = Collections.singletonMap(&quot;name&quot;, &quot;Monet&quot;);
-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(&quot;name like $name&quot;);
-...
-Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador%&quot;);
-Expression qualifier1 = template.expWithParameters(p1);</programlisting>When
-            matching on a relationship, parameters can be Persistent objects or
-            ObjectIds:<programlisting>Expression template = Expression.fromString(&quot;artist = $artist&quot;);
-...
-Artist dali = // asume we fetched this one already
-Map p1 = Collections.singletonMap(&quot;artist&quot;, 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(&quot;name like $name and dateOfBirth &gt; $date&quot;);
-...
-Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador%&quot;);
-Expression qualifier1 = template.expWithParameters(p1);
-
-// qualifier1 is now equals to &quot;name like &apos;Salvador%&apos;&quot;, the &apos;dateOfBirth&apos; condition was
-// pruned, as no value was specified for the $date parameter</programlisting></para>
-        <para><emphasis role="italic">Null handling.</emphasis> Handling of Java nulls as operands
-            is no different from normal values. Instead of using special conditional operators, like
-            SQL does (IS NULL, IS NOT NULL), &quot;=&quot; and &quot;!=&quot; expressions can be used directly with null
-            values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</para>
-        <para>
-            <note>
-                <para>A formal definition of all possible valid expressions in a form of JavaCC
-                    grammar is provided in Appendix C</para>
-            </note>
-        </para>
-    </section>
-    <section xml:id="expressions-with-expressionfactory">
-        <title>Creating Expressions with API</title>
-        <para>Creating expressions from Strings is a powerful and dynamic approach, however a safer
-            alternative is to use Java API. It provides some degree of compile-time checking of
-            expressions validity. The API is cenetred around ExpressionFactory class, and the
-            Expression class. ExpressionFactory contains a number of rather self-explanatory factory
-            methods. We won&apos;t be going over all of them in detail, but will rather show a few
-            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 &apos;A%&apos; and price &lt; 1000
-Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, &quot;A%&quot;);
-Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000);
-Expression finalExp = e1.andExp(e2); </programlisting>This
-            is more verbose than creating it from String, but it is also more resilient to the
-            entity properties renaming and precludes semantic errors in the expression String.<note>
-                <para>The last line in the example above shows how to create a new expression by
-                    &quot;chaining&quot; 2 other epxressions. A common error when chaining expressions is to
-                    assume that &quot;andExp&quot; and &quot;orExp&quot; append another expression to the current
-                    expression. In fact a new expression is created. I.e. Expression API treats
-                    existing expressions as immutable.</para>
-            </note></para>
-        <para>As discussed earlier, Cayenne supports aliases in path Expressions, allowing to
-            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 &quot;split&quot; match paths into individual joins if
-            needed:<programlisting>Expression matchAllExp(String path, Collection values)
-Expression matchAllExp(String path, Object... values)</programlisting></para>
-        <para>&quot;Path&quot; argument to both of these methods can use a split character (a pipe symbol &apos;|&apos;)
-            instead of dot to indicate that relationship following a path should be split into a
-            separate set of joins, one per collection value. There can only be one split at most in
-            any given path. Split must always precede a relationship. E.g. &quot;|exhibits.paintings&quot;,
-            &quot;exhibits|paintings&quot;, etc. Internally Cayenne would generate distinct aliases for each
-            of the split expressions, forcing separate joins.</para>
-    </section>
-    <section xml:id="expressions-in-memory">
-        <title>Evaluating Expressions in Memory</title>
-        <para>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
-            clause) by Cayenne during query execution. Thus the actual evaluation against the data
-            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, &quot;John&quot;, &quot;Bob&quot;);
-User user = ...
-if(e.match(user)) {
-   ...
-}</programlisting>Reading
-            property
-            value:<programlisting>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, &quot;John&quot;, &quot;Bob&quot;);
-List&lt;User&gt; unfiltered = ...
-List&lt;User&gt; filtered = e.filterObjects(unfiltered);</programlisting></para>
-        <para>
-            <note>
-                <para>Current limitation of in-memory expressions is that no collections are
-                    permitted in the property path.</para>
-            </note>
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
deleted file mode 100644
index a95a0fd..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
+++ /dev/null
@@ -1,20 +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="implementing-rop-client">
-    <title>Implementing ROP Client</title>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
deleted file mode 100644
index 3032fd1..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
+++ /dev/null
@@ -1,20 +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="implementing-rop-server">
-    <title>Implementing ROP Server</title>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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 359bef9..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
+++ /dev/null
@@ -1,546 +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 and Dependencies</title>
-        <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
-                        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
-                        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
-            included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
-                <listitem>
-                    <para><link xlink:href="http://velocity.apache.org/">Apache Velocity
-                            Template Engine</link>, version 1.6.x (and all its dependencies bundled
-                        with velocity-dep)</para>
-                </listitem>
-                <listitem>
-                    <para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
-                            Collections</link>, version 3.2.1</para>
-                </listitem>
-                <listitem>
-                    <para><link xlink:href="http://commons.apache.org/logging/">Apache
-                            Commons Logging</link>, version 1.1</para>
-                </listitem>
-            </itemizedlist></para>
-        <para>Cayenne integrates with various caching, clustering and other frameworks. These
-            optional integrations will require other third-party jars that the users will need to
-            obtain on their own.</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>&lt;dependency>
-   &lt;groupId>org.apache.cayenne&lt;/groupId>
-   &lt;artifactId>cayenne-server&lt;/artifactId>
-   &lt;version>X.Y.Z&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:maven-cayenne-plugin</code>.</para>
-        <section xml:id="mvn-cgen">
-            <title>cgen</title>
-            <para><code>cgen</code> is a <code>maven-cayenne-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">
-                    <caption>cgen required parameters</caption>
-                    <col width="14%"/>
-                    <col width="6%"/>
-                    <col width="80%"/>
-                    <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>
-                        <tr>
-                            <td><code>destDir</code></td>
-                            <td>File</td>
-                            <td>Root destination directory for Java classes (ignoring their package
-                                names).</td>
-                        </tr>
-                    </tbody>
-                </table>
-                <table frame="void">
-                    <caption>cgen optional parameters</caption>
-                    <col width="33%"/>
-                    <col width="8%"/>
-                    <col width="59%"/>
-                    <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>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"
-                                os "true", will overwrite older versions of generated classes.</td>
-                        </tr>
-                        <tr>
-                            <td><code>superPkg</code></td>
-                            <td>String</td>
-                            <td>Java package name of generated superclasses. Only has effect if
-                                "makepairs" and "usePkgPath" are set to "true" (both are true by
-                                default). Defines a common package for all generated Java classes.
-                                If omitted, each superclass will be placed in the same package as
-                                subclass.</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>
-                    </tbody>
-                </table>
-                Example - a typical class generation scenario, where pairs of classes are
-                generated, and superclasses are placed in a separate package:
-                <programlisting>&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-    &lt;version>X.Y.Z&lt;/version>
-
-    &lt;!--
-    There's an intermittent problem when using Maven/cgen in Eclipse with  m2eclipse plugin that
-    requires placing "configuration" section at the plugin level, instead of execution
-    level.
-    -->
-    &lt;configuration>
-        &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-        &lt;destDir>${project.basedir}/src/main/java&lt;/destDir>
-        &lt;superPkg>org.example.model.auto&lt;/superPkg>
-    &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>maven-cayenne-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">
-                    <caption>cdbgen required parameters</caption>
-                    <col width="14%"/>
-                    <col width="10%"/>
-                    <col width="76%"/>
-                    <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>driver</code></td>
-                            <td>String</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>JDBC connection URL of a target database.</td>
-                        </tr>
-                    </tbody>
-                </table></para>
-            <para>
-                <table frame="void">
-                    <caption>cdbgen optional parameters</caption>
-                    <col width="18%"/>
-                    <col width="11%"/>
-                    <col width="75%"/>
-                    <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>
-                        <tr>
-                            <td><code>password</code></td>
-                            <td>String</td>
-                            <td>Database user password.</td>
-                        </tr>
-                        <tr>
-                            <td><code>username</code></td>
-                            <td>String</td>
-                            <td>Database user name.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </para>
-            <para>Example - creating a DB schema on a local HSQLDB
-                database:<programlisting>&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-    &lt;version>X.Y.Z&lt;/version>
-
-    &lt;executions>
-        &lt;execution>
-            &lt;configuration>
-                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-                &lt;url>jdbc:hsqldb:hsql://localhost/testdb&lt;/url>
-                &lt;adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter>
-                &lt;driver>org.hsqldb.jdbcDriver&lt;/driver>
-                &lt;username>sa&lt;/username>
-            &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>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, which may be necessary if you are also using the cgen task.<table
-                    frame="void">
-                    <caption>cdbimport required parameters</caption>
-                    <col width="14%"/>
-                    <col width="10%"/>
-                    <col width="76%"/>
-                    <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 is the destination of the schema import.
-                                Maybe 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></td>
-                        </tr>
-                        <tr>
-                            <td><code>driver</code></td>
-                            <td>String</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>JDBC connection URL of a target database.</td>
-                        </tr>
-                    </tbody>
-                </table></para>
-            <para>
-                <table frame="void">
-                    <caption>cdbimport optional parameters</caption>
-                    <col width="25%"/>
-                    <col width="10%"/>
-                    <col width="65%"/>
-                    <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>importProcedures</code></td>
-                            <td>boolean</td>
-                            <td>Indicates whether stored procedures should be imported from the
-                                database. Default is false. </td>
-                        </tr>
-                        <tr>
-                            <td><code>meaningfulPk</code></td>
-                            <td>boolean</td>
-                            <td>Indicates whether primary keys should be mapped as attributes of the
-                                ObjEntity. Default is false. </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.map.naming.SmartNamingStrategy</code>.
-                            </td>
-                        </tr>
-                        <tr>
-                            <td><code>overwriteExisting</code></td>
-                            <td>boolean</td>
-                            <td>Indicates whether existing DB and object entities should be
-                                overwritten. This is an all-or-nothing setting. If you need finer
-                                granularity, use the CayenneModeler. Default is "true". </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>schemaName</code></td>
-                            <td>String</td>
-                            <td>Database schema to import tables/stored procedures from. </td>
-                        </tr>
-                        <tr>
-                            <td><code>tablePattern</code></td>
-                            <td>String</td>
-                            <td>Pattern to match table names against for import. Default is to match
-                                all tables. </td>
-                        </tr>
-                        <tr>
-                            <td><code>username</code></td>
-                            <td>String</td>
-                            <td>Database user name.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </para>
-            <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
-                compared to the cdbgen example above)
-                :<programlisting>&lt;plugin>
-    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-    &lt;version>X.Y.Z&lt;/version>
-
-    &lt;executions>
-        &lt;execution>
-            &lt;configuration>
-                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-                &lt;url>jdbc:mysql://127.0.0.1/mydb&lt;/url>
-                &lt;adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter>
-                &lt;driver>com.mysql.jdbc.Driver&lt;/driver>
-                &lt;username>sa&lt;/username>
-            &lt;/configuration>
-            &lt;goals>
-                &lt;goal>cdbimport&lt;/goal>
-            &lt;/goals>
-        &lt;/execution>
-    &lt;/executions>
-&lt;/plugin></programlisting></para>
-        </section>
-    </section>
-    <section xml:id="ant-projects">
-        <title>Ant Projects</title>
-        <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 maven-cayenne-plugin described
-                above. It has exactly the same properties. Here is a usage
-                example:<programlisting> &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"/> </programlisting>
-            </para>
-        </section>
-        <section xml:id="ant-cdataport">
-            <title>cdataport</title>
-        </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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 0e850e8..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/index.xml
+++ /dev/null
@@ -1,46 +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"
-    xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
-    <info>
-        <title>Cayenne Guide</title>
-        <copyright>
-            <year>2011-2017</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="appendix-a.xml"/>
-    <xi:include href="appendix-b.xml"/>
-    <xi:include href="appendix-c.xml"/>
-</book>


Mime
View raw message