cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [07/13] cayenne git commit: CAY-2371 Switch documentation from Docbook to Asciidoctor format
Date Fri, 05 Jan 2018 13:10:34 GMT
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 3383e01..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
+++ /dev/null
@@ -1,473 +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 language="java">public class MyExtensionsModule implements Module {
-    public void configure(Binder binder) {
-        // customizations go here...
-    }
-}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule();
-ServerRuntime runtime = ServerRuntime.builder()
-        .addConfig("com/example/cayenne-mydomain.xml")
-        .addModule(extensions)
-        .build();</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.<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false ...</screen></para>
-            <para>A second one is to contribute a property to
-                    <code>org.apache.cayenne.configuration.DefaultRuntimeProperties.properties
-                </code>map (see the next section on how to do that). This map contains the default
-                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>
-        <title>Using custom data types</title>
-        <section>
-            <title>Value object type</title>
-            <para>
-                <code>ValueObjectType</code> is a new and lightweight alternative to the Extended Types API described in the following section.
-                In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when <code>ExtendedType</code> should be used:
-                when your value object can be mapped on different JDBC types.
-            </para>
-            <para>
-                In order to use your custom data type you should implement <code>ValueObjectType</code> describing it in terms of some type already known to Cayenne
-                (e.g. backed by system or user ExtendedType).
-            </para>
-            <para>
-                Let's assume we want to support some data type called <code>Money</code>:
-                <programlisting language="java"><![CDATA[public class Money {
-    private BigDecimal value;
-
-    public Money(BigDecimal value) {
-        this.value = value;
-    }
-
-    public BigDecimal getValue() {
-        return value;
-    }
-
-    // .. some other business logic ..
-}]]></programlisting>
-                Here is how <code>ValueObjectType</code> that will allow to store our <code>Money</code> class as <code>BigDecimal</code>
-                can be implemented:
-                <programlisting language="java"><![CDATA[public class MoneyValueObjectType implements ValueObjectType<Money, BigDecimal> {
-
-    @Override
-    public Class<BigDecimal> getTargetType() {
-        return BigDecimal.class;
-    }
-
-    @Override
-    public Class<Money> getValueType() {
-        return Money.class;
-    }
-
-    @Override
-    public Money toJavaObject(BigDecimal value) {
-        return new Money(value);
-    }
-
-    @Override
-    public BigDecimal fromJavaObject(Money object) {
-        return object.getValue();
-    }
-
-    @Override
-    public String toCacheKey(Money object) {
-        return object.getValue().toString();
-    }
-}]]></programlisting>
-            </para>
-            <para>
-                Last step is to register this new type in <code>ServerRuntime</code>:
-                <programlisting language="java"><![CDATA[ServerRuntime runtime = ServerRuntime.builder()
-    .addConfig("cayenne-project.xml")
-    .addModule(binder -> ServerModule.contributeValueObjectTypes(binder).add(MoneyValueObjectType.class))
-    .build();]]></programlisting>
-            </para>
-            <para>More examples of implementation you can find in
-                <link xlink:href="https://github.com/apache/cayenne/tree/STABLE-4.0/cayenne-java8/src/main/java/org/apache/cayenne/java8/access/types">cayenne-java8 module</link>
-            </para>
-        </section>
-        <section xml:id="extendedtypes">
-            <title>Extended Types</title>
-            <para>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class)
-                and a very specific mapping of these types to Java Object Types, such as java.lang.String,
-                java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and
-                Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from
-                a database "primitive" value, and conversely, how to transform an object of the custom type to
-                a JDBC-compatible object.</para>
-            <section xml:id="supporting-non-standard-types">
-                <title>Supporting Non-Standard Types</title>
-                <para>For supporting non-standard type you should define it via an interface <code>org.apache.cayenne.access.types.ExtendedType</code>.
-                    An implementation must provide <code>ExtendedType.getClassName()</code> method that returns
-                    a fully qualified Java class name for the supported custom type, and a number of methods
-                    that convert data between JDBC and custom type.
-                    The following example demonstrates how to add a custom DoubleArrayType
-                    to store <code>java.lang.Double[]</code> as a custom string in a database:</para>
-                <programlisting language="java">
-/**
-* Defines methods to read Java objects from JDBC ResultSets and write as parameters of
-* PreparedStatements.
-*/
-public class DoubleArrayType implements ExtendedType {
-
-    private final String SEPARATOR = ",";
-
-    /**
-    * Returns a full name of Java class that this ExtendedType supports.
-    */
-    @Override
-    public String getClassName() {
-        return Double[].class.getCanonicalName();
-    }
-
-    /**
-    * Initializes a single parameter of a PreparedStatement with object value.
-    */
-    @Override
-    public void setJdbcObject(PreparedStatement statement, Object value,
-            int pos, int type, int scale) throws Exception {
-
-        String str = StringUtils.join((Double[]) value, SEPARATOR);
-        statement.setString(pos, str);
-    }
-
-
-    /**
-    * Reads an object from JDBC ResultSet column, converting it to class returned by
-    * 'getClassName' method.
-    *
-    * @throws Exception if read error occurred, or an object can't be converted to a
-    *             target Java class.
-    */
-    @Override
-    public Object materializeObject(ResultSet rs, int index, int type) throws Exception {
-        String[] str = rs.getString(index).split(SEPARATOR);
-        Double[] res = new Double[str.length];
-
-        for (int i = 0; i &lt; str.length; i++) {
-            res[i] = Double.valueOf(str[i]);
-        }
-
-        return res;
-    }
-
-    /**
-    * Reads an object from a stored procedure OUT parameter, converting it to class
-    * returned by 'getClassName' method.
-    *
-    * @throws Exception if read error ocurred, or an object can't be converted to a
-    *             target Java class.
-    */
-    @Override
-    public Object materializeObject(CallableStatement rs, int index, int type) throws Exception {
-        String[] str = rs.getString(index).split(SEPARATOR);
-        Double[] res = new Double[str.length];
-
-        for (int i = 0; i &lt; str.length; i++) {
-            res[i] = Double.valueOf(str[i]);
-        }
-
-        return res;
-    }
-}
-                </programlisting>
-                <para>For Java7</para>
-                <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
-                .addConfig("cayenne-project.xml")
-                .addModule(new Module() {
-                    @Override
-                    public void configure(Binder binder) {
-                        ServerModule.contributeUserTypes(binder).add(new DoubleArrayType());
-                    }
-                })
-                .build();
-                </programlisting>
-                <para>For Java8</para>
-                <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
-                .addConfig("cayenne-project.xml")
-                .addModule(binder -> ServerModule.contributeUserTypes(binder).add(new DoubleArrayType()))
-                .build();
-                </programlisting>
-            </section>
-            <section xml:id="dbadapters-and-extended-types">
-                <title>DbAdapters and Extended Types</title>
-                <para>As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install
-                    their own extended types to address incompatibilities, incompleteness and differences between
-                    JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large
-                    character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc.
-                    Adapters provided with Cayenne override <code>configureExtendedTypes()</code> method to install their own types,
-                    possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</para>
-            </section>
-        </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.Slf4jJdbcEventLogger</code> that performs logging
-                via slf4j-api library. Cayenne library includes another potentially useful
-                logger - <code>org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger</code> that
-                produces formatted multiline SQL output that can be easier to read.</para>
-        </section>
-        <section xml:id="datasourcefactory">
-            <title>DataSourceFactory</title>
-            <para>Factory that returns <code>javax.sql.DataSource</code> object based on the configuration provided in the
-                "nodeDescriptor".
-            </para>
-        </section>
-        <section xml:id="datachannelfilter">
-            <title>DataChannelFilter</title>
-            <para> An interface of a filter that allows to intercept DataChannel operations. Filters allow
-                to implement chains of custom processors around a DataChannel, that can be used for
-                security, monitoring, business logic, providing context to lifecycle event listeners,
-                etc.
-            </para>
-        </section>
-        <section xml:id="querycache">
-            <title>QueryCache</title>
-            <para>Defines API of a cache that stores query results.</para>
-        </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 48e7462..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
+++ /dev/null
@@ -1,303 +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
-            to understand the semantics. A Cayenne expression can be represented as a String, which
-            can be converted to an expression object using <code>ExpressionFactory.exp</code> static
-            method. Here is an
-            example:<programlisting language="java">String expString = &quot;name like &apos;A%&apos; and price &lt; 1000&quot;;
-Expression exp = ExpressionFactory.exp(expString);</programlisting>This
-            particular expression may be used to match Paintings whose names that start with
-            &quot;A&quot; and whose price is 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 language="SQL">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 case
-            sensitive and are usually lowercase. Complex words follow the Java camel-case
-            style:<programlisting language="SQL">// 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 language="SQL">// 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 language="SQL">name like &apos;A%&apos;</programlisting>
-            <emphasis role="italic">Parameters.</emphasis> Expressions can contain named parameters
-            (names that start with &quot;$&quot;) that can be substituted with values either by name
-            or by position. 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 the examples of both positional and
-            named parameter
-            bindings:<programlisting language="java">Expression template = ExpressionFactory.exp(&quot;name = $name&quot;);
-...
-// name binding
-Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador Dali&quot;);
-Expression qualifier1 = template.params(p1);
-...
-// positional binding
-Expression qualifier2 = template.paramsArray(&quot;Monet&quot;);</programlisting></para>
-        <para>Positional binding is usually shorter. You can pass positional bindings to the
-                <code>"exp(..)"</code> factory method (its second argument is a params
-            vararg):<programlisting>Expression qualifier = ExpressionFactory.exp(&quot;name = $name&quot;, &quot;Monet&quot;);</programlisting></para>
-        <para>In parameterized expressions with LIKE clause, SQL wildcards must be part of the
-            values in the Map and not the expression string
-            itself:<programlisting language="java">Expression qualifier = ExpressionFactory.exp(&quot;name like $name&quot;, &quot;Salvador%&quot;);</programlisting>When
-            matching on a relationship, the value parameter must be either a Persistent object, an
-                <code>org.apache.cayenne.ObjectId</code>, or a numeric ID value (for single column
-            IDs).
-            E.g.:<programlisting language="java">Artist dali = ... // asume we fetched this one already
-Expression qualifier = ExpressionFactory.exp(&quot;artist = $artist&quot;, dali);</programlisting>When
-            using positional binding, Cayenne would expect values for <emphasis role="bold"
-                >all</emphasis> parameters to be present. Binding by name offers extra flexibility:
-            subexpressions with uninitialized parameters are automatically pruned from the
-            expression. So e.g. if certain parts of the expression criteria are not provided to the
-            application, you can still build a valid
-            expression:<programlisting language="java">Expression template = ExpressionFactory.exp(&quot;name like $name and dateOfBirth &gt; $date&quot;);
-...
-Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador%&quot;);
-Expression qualifier1 = template.params(p1);
-
-// "qualifier1" is now &quot;name like &apos;Salvador%&apos;&quot;.
-// &apos;dateOfBirth &gt; $date&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 are 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 the expression grammar is provided in Appendix C</para>
-            </note>
-        </para>
-    </section>
-    <section xml:id="expressions-with-expressionfactory">
-        <title>Creating Expressions via API</title>
-        <para>Creating expressions from Strings is a powerful and dynamic approach, however a safer
-            alternative is to use Java API. It provides compile-time checking of expressions
-            validity. The API in question is provided by <code>ExpressionFactory</code> class (that
-            we've seen already), <code>Property</code> class and <code>Expression</code> class
-            itself. <code>ExpressionFactory</code> contains a number of self-explanatory static
-            methods that can be used to build expressions. E.g.:</para>
-        <para>
-            <programlisting language="java">// String expression: name like &apos;A%&apos; and price &lt; 1000
-Expression e1 = ExpressionFactory.likeExp("name", &quot;A%&quot;);
-Expression e2 = ExpressionFactory.lessExp("price, 1000);
-Expression finalExp = e1.andExp(e2); </programlisting>
-            <note>
-                <para>The last line in the example above shows how to create a new expression by
-                    &quot;chaining&quot; two 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 language="java">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.
-                <code>"|exhibits.paintings"</code>, <code>"exhibits|paintings"</code>, etc.
-            Internally Cayenne would generate distinct aliases for each of the split expressions,
-            forcing separate joins.</para>
-        <para>While ExpressionFactory is pretty powerful, there's an even easier way to create
-            expression using static Property objects generated by Cayenne for each persistent class.
-            Some
-            examples:<programlisting>// Artist.NAME is generated by Cayenne and has a type of Property&lt;String>
-Expression e1 = Artist.NAME.eq("Pablo");
-
-// Chaining multiple properties into a path..
-// Painting.ARTIST is generated by Cayenne and has a type of Property&lt;Artist>
-Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");</programlisting></para>
-        <para>Property objects provide the API mostly analogius to ExpressionFactory, though it is
-            significantly shorter and is aware of the value types. It provides compile-time checks
-            of both property names and types of arguments in conditions. We will use Property-based
-            API in further examples.</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 language="java">Expression e = Artist.NAME.in(&quot;John&quot;, &quot;Bob&quot;);
-Artist artist = ...
-if(e.match(artist)) {
-   ...
-}</programlisting>Reading
-            property
-            value:<programlisting language="java">String name = Artist.NAME.path().evaluate(artist);</programlisting></para>
-        <para>Filtering a list of
-            objects:<programlisting language="java">Expression e = Artist.NAME.in(&quot;John&quot;, &quot;Bob&quot;);
-List&lt;Artist&gt; unfiltered = ...
-List&lt;Artist&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>
-
-    <section xml:id="expressions-to-ejbql">
-        <title>Translating Expressions to EJBQL</title>
-        <para>
-            <link linkend="ejbqlquery">EJBQL</link> is a textual query language that can be used
-            with Cayenne. In some situations, it is convenient to be able to convert Expression
-            instances into EJBQL. Expressions support this conversion. An example is shown below.
-            <programlisting language="java">String serial = ...
-Expression e = Pkg.SERIAL.eq(serial);
-List&lt;Object&gt; params = new ArrayList&lt;Object&gt;();
-EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,&quot;p&quot;);
-
-for(int i=0;i&lt;params.size();i++) {
-  query.setParameter(i+1, params.get(i));
-}</programlisting>
-            This would be equivalent to the following purely EJBQL querying logic;
-            <programlisting language="java">EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1");
-query.setParameter(1,serial);</programlisting>
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml
deleted file mode 100644
index f3e0a0d..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml
+++ /dev/null
@@ -1,91 +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="ext-cache-invalidation">
-    <title>Cache invalidation extension</title>
-    <section>
-        <title>Description</title>
-        <para>Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-cache-invalidation&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-cache-invalidation:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            Module supports autoloading mechanism, so no other actions required to enable it.
-            Just mark your entities with <code>@CacheGroups</code> annotation and you are ready to use it:
-            <programlisting language="java"><![CDATA[
-@CacheGroups("some-group")
-public class MyEntity extends _MyEntity {
-    // ...
-}]]></programlisting>
-            After any modification of <code>MyEntity</code> objects cache group <code>"some-group"</code>
-            will be dropped from cache automatically.
-            <note>
-                <para>You can read more about cache and cache groups in corresponding <link linkend="caching-and-fresh-data">chapter</link> of this documentation.</para>
-            </note>
-        </para>
-        <para>
-            In case you need some complex logic of cache invalidation you can disable default behaviour and provide your own.
-        </para>
-        <para>
-            To do so you need to implement <code>org.apache.cayenne.cache.invalidation.InvalidationHandler</code> interface and setup Cache Invalidation module to
-            use it.
-            Let's use implementation class called <code>CustomInvalidationHandler</code> that will simply match
-            all entities' types with <code>"custom-group"</code> cache group regardless of any annotations:
-            <programlisting language="java"><![CDATA[
-public class CustomInvalidationHandler implements InvalidationHandler {
-    @Override
-    public InvalidationFunction canHandle(Class<? extends Persistent> type) {
-        return p -> Collections.singleton(new CacheGroupDescriptor("custom-group"));
-    }
-}]]></programlisting>
-            Now we'll set up it's usage by <code>ServerRuntime</code>:
-            <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CacheInvalidationModule.extend()
-                // this will disable default handler based on @CacheGroups, and this is optional
-                .noCacheGroupsHandler()
-                .addHandler(CustomInvalidationHandler.class)
-                .module())
-]]></programlisting>
-            <note>
-                <para>You can combine as many invalidation handlers as you need.</para>
-            </note>
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml
deleted file mode 100644
index 20aec52..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml
+++ /dev/null
@@ -1,89 +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="ext-commit-log">
-    <title>Commit log extension</title>
-    <section>
-        <title>Description</title>
-        <para>The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-commitlog&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-commitlog:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            In order to use <code>commitlog</code> module you need to perform three steps:
-            <orderedlist>
-                <listitem>
-                    <para>Mark all entities which changes you are interested in with <code>@org.apache.cayenne.commitlog.CommitLog</code> annotation</para>
-                    <programlisting language="java"><![CDATA[
-@CommitLog(ignoredProperties = {"somePrivatePropertyToSkip"})
-public class MyEntity extends _MyEntity {
-    // ...
-}]]></programlisting>
-                </listitem>
-                <listitem>
-                    <para>
-                        Implement <code>CommitLogListener</code> interface.
-                        <programlisting language="java"><![CDATA[
-public class MyCommitLogListener implements CommitLogListener {
-    @Override
-    public void onPostCommit(ObjectContext originatingContext, ChangeMap changes) {
-        // ChangeMap will contain all information about changes happened in performed commit
-        // this particular example will print IDs of all inserted objects
-        changes.getUniqueChanges().stream()
-            .filter(change -> change.getType() == ObjectChangeType.INSERT)
-            .map(ObjectChange::getPostCommitId)
-            .forEach(id -> System.out.println("Inserted new entity with id: " + id));
-    }
-}]]></programlisting>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-                        Inject your listener into <code>ServerRuntime</code>
-                        <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CommitLogModule.extend()
-                .addListener(MyCommitLogListener.class)
-                .module())]]></programlisting>
-                    </para>
-                </listitem>
-            </orderedlist>
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml
deleted file mode 100644
index 8381bab..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml
+++ /dev/null
@@ -1,135 +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="ext-crypto">
-    <title>Crypto extension</title>
-    <section>
-        <title>Description</title>
-        <para>Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-crypto&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-crypto:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <section>
-            <title>Setup your model and DB</title>
-            <para>
-                To use crypto module you must prepare your database to allow <code>byte[]</code> storage and properly name
-                columns that will contain encrypted values.
-            </para>
-            <para>
-                Currently supported SQL types that can be used to store encrypted data are:
-                <orderedlist>
-                    <listitem>
-                        <para>
-                            Binary types: <code>BINARY, BLOB, VARBINARY, LONGVARBINARY</code>.
-                            These types are preferred.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>Character types, that will store <code>base64</code> encoded value:
-                            <code>CHAR, NCHAR, CLOB, NCLOB, LONGVARCHAR, LONGNVARCHAR, VARCHAR, NVARCHAR</code></para>
-                    </listitem>
-                </orderedlist>
-                <note>
-                    <para>Not all data types may be supported by your database.</para>
-                </note>
-            </para>
-            <para>
-                Default naming strategy that doesn't require additional setup suggests using <code>"CRYPTO_"</code> prefix.
-                You can change this default strategy by injecting you own implementation of
-                <code>org.apache.cayenne.crypto.map.ColumnMapper</code> interface.
-                <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CryptoModule.extend()
-                .columnMapper(MyColumnMapper.class)
-                .module())]]></programlisting>
-            </para>
-            <para>
-                Here is an example of how <code>ObjEntity</code> with two encrypted and two unencrypted properties
-                can look like:
-            </para>
-            <para><inlinemediaobject>
-                <imageobject>
-                    <imagedata fileref="images/ext-crypto-obj-entity.png" scalefit="1" width="100%"/>
-                </imageobject>
-            </inlinemediaobject></para>
-        </section>
-        <section>
-            <title>Setup keystore</title>
-            <para>
-                To perform encryption you must provide <code>KEYSTORE_URL</code> and <code>KEY_PASSWORD</code>.
-                Currently crypto module supports only Java "jceks" KeyStore.
-                <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CryptoModule.extend()
-                .keyStore(this.getClass().getResource("keystore.jcek"), "my-password".toCharArray(), "my-key-alias")
-                .module())]]></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Additional settings</title>
-            <para>
-                Additionally to <code>ColumnMapper</code> mentioned above you can customize other parts of
-                <code>crypto module</code>.
-                You can enable <code>gzip</code> compression and <code>HMAC</code> usage (later will ensure integrity of data).
-                <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CryptoModule.extend()
-                .compress()
-                .useHMAC()
-                .module())]]></programlisting>
-            </para>
-            <para>
-                Another useful extension point is support for custom Java value types. To add support for your
-                data type you need to implement <code>org.apache.cayenne.crypto.transformer.value.BytesConverter</code>
-                interface that will convert required type to and from <code>byte[]</code>.
-                <programlisting language="java"><![CDATA[
-ServerRuntime.builder()
-        .addModule(CryptoModule.extend()
-                .objectToBytesConverter(MyClass.class, new MyClassBytesConverter())
-                .module())]]></programlisting>
-            </para>
-            <note>
-                <para>In addition to Java primitive types (and their object counterparts), <code>crypto module</code>
-                    supports encryption only of <code>java.util.Date</code>, <code>java.math.BigInteger</code>
-                    and <code>java.math.BigDecimal</code> types.
-                </para>
-            </note>
-        </section>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml
deleted file mode 100644
index 715ebc6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml
+++ /dev/null
@@ -1,59 +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="ext-dbcp2">
-    <title>Apache Commons DBCP integration</title>
-    <section>
-        <title>Description</title>
-        <para>
-            This module enables usage of Apache Commons DBCP2 connection pool.
-        </para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-dbcp2&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-dbcp2:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            To use DBCP2 pool you need to setup it in <code>DataNode</code> settings in Cayenne Modeler:
-        </para>
-        <para><inlinemediaobject>
-            <imageobject>
-                <imagedata fileref="images/ext-dbcp-setup.png" scalefit="1" width="100%"/>
-            </imageobject>
-        </inlinemediaobject></para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml
deleted file mode 100644
index 9ee1e70..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml
+++ /dev/null
@@ -1,53 +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="ext-java8">
-    <title>Java 8 extension</title>
-    <section>
-        <title>Description</title>
-        <para>Java 8 module allows to use <code>java.time.LocalTime</code>, <code>java.time.LocalDate</code>
-        and <code>java.time.LocalDateTime</code> types for entity attributes</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-java8&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-java8:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            This module doesn't require any additional setup, you can just use new data types in your model.
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml
deleted file mode 100644
index 509d538..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml
+++ /dev/null
@@ -1,61 +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="ext-jcache">
-    <title>JCache integration</title>
-    <section>
-        <title>Description</title>
-        <para>This module allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-jcache&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-jcache:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            To use JCache provider in your app you need to include this module and caching provider libs (e.g. Ehcache).
-            You can provide own implementation of <code>org.apache.cayenne.jcache.JCacheConfigurationFactory</code>
-            to customize cache configuration if required.
-        </para>
-        <para>
-            For advanced configuration and management please use provider specific options and tools.
-        </para>
-        <note>
-            <para>You can read about using cache in Cayenne in <link linkend="caching-and-fresh-data">this</link> chapter.</para>
-            <para>You may else be interested in <link linkend="ext-cache-invalidation">cache invalidation</link> extension.</para>
-        </note>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml
deleted file mode 100644
index d777b68..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml
+++ /dev/null
@@ -1,53 +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="ext-joda">
-    <title>Joda time extension</title>
-    <section>
-        <title>Description</title>
-        <para>Joda time module allows to use <code>org.joda.time.LocalTime</code>, <code>org.joda.time.LocalDate</code>,
-            <code>org.joda.time.LocalDateTime</code> and <code>org.joda.time.DateTime</code> types for entity attributes</para>
-    </section>
-    <section>
-        <title>Including in a project</title>
-        <section>
-            <title>Maven</title>
-            <para>
-                <programlisting language="xml">&lt;dependency>
-    &lt;groupId>org.apache.cayenne&lt;/groupId>
-    &lt;artifactId>cayenne-joda&lt;/artifactId>
-    &lt;version><?eval ${project.version}?>&lt;/version>
-&lt;/dependency></programlisting>
-            </para>
-        </section>
-        <section>
-            <title>Gradle</title>
-            <para>
-                <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-joda:<?eval ${project.version}?>'</programlisting>
-            </para>
-        </section>
-    </section>
-    <section>
-        <title>Usage</title>
-        <para>
-            This module doesn't require any additional setup, you can just use new data types in your model.
-        </para>
-    </section>
-</chapter>

http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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/cde78f0b/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>


Mime
View raw message