You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/04 16:01:21 UTC
[07/14] cayenne git commit: Switch documentation from Docbook to
Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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>"db:" is an optional prefix indicating that the following path is a DB
- path. Otherwise it is an object path.</para>
- </listitem>
- <listitem>
- <para>"segment" 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 (".").</para>
- </listitem>
- <listitem>
- <para>"+" An "OUTER JOIN" path component. Currently "+" 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 "navigating" to its related value.
- E.g. a path expression "artist.name" 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>"name" - can be used to navigate (read) the "name" property of a Person
- (or any other type of object that has a "name" property).</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
- of any of the exhibits of a Painting's Artist object.</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits+.closingDate" - same as the previous example, but when
- translated into SQL, an OUTER JOIN will be used for "exhibits".</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 - "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:<itemizedlist>
- <listitem>
- <para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
- unspecified table.</para>
- </listitem>
- <listitem>
- <para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - 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 "aliases" in path Expressions. E.g. the same expression can be
- written using explicit path or an alias:<itemizedlist>
- <listitem>
- <para>"artist.exhibits.closingDate" - full path</para>
- </listitem>
- <listitem>
- <para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
- </listitem>
- </itemizedlist>SelectQuery using the second form of the path expression must be made
- aware of the alias via <emphasis role="italic">
- "SelectQuery.aliasPathSplits(..)"</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'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 = "name like 'A%' and price < 1000";
-Expression exp = ExpressionFactory.exp(expString);</programlisting>This
- particular expression may be used to match Paintings whose names that start with
- "A" and whose price is less than $1000. While this example is pretty
- self-explanatory, there are a few points worth mentioning. "name" and
- "price" 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
- "may be used to match Paintings", 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 = 'ABC'
-
-// double quotes are escaped inside Java Strings of course
-name = \"ABC\"</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 'A%'
-
-// invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</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 "obj:" (usually they are not prefixed at all actually). Database
- expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
- is "enum:" that prefixes an enumeration
- constant:<programlisting language="SQL">// object path
-name = 'Salvador Dali'
-
-// same object path - a rarely used form
-obj:name = 'Salvador Dali'
-
-// multi-segment object path
-artist.name = 'Salvador Dali'
-
-// db path
-db:NAME = 'Salvador Dali'
-
-// 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 'A%'</programlisting>
- <emphasis role="italic">Parameters.</emphasis> Expressions can contain named parameters
- (names that start with "$") 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'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("name = $name");
-...
-// name binding
-Map p1 = Collections.singletonMap("name", "Salvador Dali");
-Expression qualifier1 = template.params(p1);
-...
-// positional binding
-Expression qualifier2 = template.paramsArray("Monet");</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("name = $name", "Monet");</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("name like $name", "Salvador%");</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("artist = $artist", 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("name like $name and dateOfBirth > $date");
-...
-Map p1 = Collections.singletonMap("name", "Salvador%");
-Expression qualifier1 = template.params(p1);
-
-// "qualifier1" is now "name like 'Salvador%'".
-// 'dateOfBirth > $date' 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), "=" and "!=" 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 'A%' and price < 1000
-Expression e1 = ExpressionFactory.likeExp("name", "A%");
-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
- "chaining" two other epxressions. A common error when chaining
- expressions is to assume that "andExp" and "orExp" 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 "split" 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>"Path" argument to both of these methods can use a split character (a pipe
- symbol '|') instead of dot to indicate that relationship following a path
- should be split into a 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<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<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("John", "Bob");
-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("John", "Bob");
-List<Artist> unfiltered = ...
-List<Artist> 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<Object> params = new ArrayList<Object>();
-EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p");
-
-for(int i=0;i<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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-cache-invalidation</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-commitlog</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-crypto</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-dbcp2</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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 aa58d8a..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml
+++ /dev/null
@@ -1,56 +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><emphasis>Since Cayenne 4.1 this extension is deprecated, and is present for backwards
- compatibility purposes only. cayenne-server module now incorporates all Cayenne Java
- 8 functionality.</emphasis> 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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-java8</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-jcache</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/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"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-joda</artifactId>
- <version><?eval ${project.version}?></version>
-</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/df1324e4/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml
deleted file mode 100644
index d645098..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.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-project-compatibility">
- <title>Project compatibility extension</title>
- <section>
- <title>Description</title>
- <para>Since version <emphasis>4.1</emphasis> Cayenne doesn't allow to load project XML files
- from previous versions as this can lead to unexpected errors in runtime. This module allows to
- use project files from older versions performing their upgrade on the fly (without modifying files).
- This can be useful when using Cayenne models from third-party libraries in your app.
- <note>
- <para>You should prefer explicit project upgrade via Cayenne Modeler.</para>
- </note>
- </para>
- </section>
- <section>
- <title>Including in a project</title>
- <section>
- <title>Maven</title>
- <para>
- <programlisting language="xml"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-project-compatibility</artifactId>
- <version><?eval ${project.version}?></version>
-</dependency></programlisting>
- </para>
- </section>
- <section>
- <title>Gradle</title>
- <para>
- <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-project-compatibility:<?eval ${project.version}?>'</programlisting>
- </para>
- </section>
- </section>
- <section>
- <title>Usage</title>
- <para>
- This module doesn't require any additional setup.
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml
deleted file mode 100644
index 4086bdf..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml
+++ /dev/null
@@ -1,79 +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-velocity">
- <title>Apache Velocity extension</title>
- <section>
- <title>Description</title>
- <para>This module enables usage of full featured Apache Velocity templates in <code>org.apache.cayenne.query.SQLTemplate</code>
- queries.</para>
- </section>
- <section>
- <title>Including in a project</title>
- <section>
- <title>Maven</title>
- <para>
- <programlisting language="xml"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-velocity</artifactId>
- <version><?eval ${project.version}?></version>
-</dependency></programlisting>
- </para>
- </section>
- <section>
- <title>Gradle</title>
- <para>
- <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-velocity:<?eval ${project.version}?>'</programlisting>
- </para>
- </section>
- </section>
- <section>
- <title>Usage</title>
- <para>
- This module doesn't require any additional setup.
- </para>
- <para>
- In addition of directives mentioned in <link linkend="sqltemplate-bind-directive">this</link> chapter, this module enables <code>#chain</code> and <code>#chunk</code>
- directives.
- </para>
- <para><code>#chain</code> and <code>#chunk</code> directives are used for
- conditional inclusion of SQL code. They are used together with
- <code>#chain</code> wrapping multiple <code>#chunks</code>. A chunk
- evaluates its parameter expression and if it is NULL suppresses rendering of the
- enclosed SQL block. A chain renders its prefix and its chunks joined by the
- operator. If all the chunks are suppressed, the chain itself is suppressed. This
- allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause
- can contain multiple conditions joined with AND or OR. Application code would
- like to exclude a condition if its right-hand parameter is not present (similar
- to Expression pruning discussed above). If all conditions are excluded, the
- entire WHERE clause should be excluded. chain/chunk allows to do that.</para>
- <para>
- <emphasis role="italic"
- >Semantics</emphasis>:<programlisting language="java">#chain(operator) ... #end
-#chain(operator prefix) ... #end
-#chunk() ... #end
-#chunk(param) ... #end </programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="java">#chain('OR' 'WHERE')
- #chunk($name) NAME LIKE #bind($name) #end
- #chunk($id) ARTIST_ID > #bind($id) #end
-#end" </programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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/df1324e4/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>