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/11 12:08:17 UTC
cayenne git commit: Improve cayenne-guide (4.0) navigation to match
old version
Repository: cayenne
Updated Branches:
refs/heads/STABLE-4.0 b07201b63 -> 7ecf0d337
Improve cayenne-guide (4.0) navigation to match old version
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/7ecf0d33
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/7ecf0d33
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/7ecf0d33
Branch: refs/heads/STABLE-4.0
Commit: 7ecf0d337ad1656080b2ae5525d68d563e47c8d3
Parents: b07201b
Author: Nikita Timofeev <st...@gmail.com>
Authored: Thu Jan 11 15:08:09 2018 +0300
Committer: Nikita Timofeev <st...@gmail.com>
Committed: Thu Jan 11 15:08:09 2018 +0300
----------------------------------------------------------------------
.../asciidoc/_cayenne-guide/expressionsBNF.adoc | 1 +
.../asciidoc/_cayenne-guide/part1/modeler.adoc | 4 +-
.../asciidoc/_cayenne-guide/part1/setup.adoc | 2 +-
.../_cayenne-guide/part2/customize.adoc | 1 -
.../_cayenne-guide/part2/expressions.adoc | 6 +-
.../_cayenne-guide/part2/including.adoc | 12 +-
.../_cayenne-guide/part2/objectContext.adoc | 1 +
.../asciidoc/_cayenne-guide/part2/queries.adoc | 4 +-
.../asciidoc/_cayenne-guide/part2/starting.adoc | 2 +-
.../asciidoc/_cayenne-guide/part2/tuning.adoc | 135 ++++++++++++++-----
.../docs/asciidoc/_cayenne-guide/part3/rop.adoc | 2 +-
.../_cayenne-guide/part4/filtering.adoc | 1 +
.../_cayenne-guide/part4/introduction.adoc | 3 +-
.../_cayenne-guide/part4/otherSettings.adoc | 1 +
.../_cayenne-guide/part4/revEngineering.adoc | 6 +-
.../_cayenne-guide/part5/cacheInvalidation.adoc | 2 +-
.../_cayenne-guide/part5/commitLog.adoc | 1 +
.../asciidoc/_cayenne-guide/part5/crypto.adoc | 1 +
.../asciidoc/_cayenne-guide/part5/jCache.adoc | 3 +-
.../asciidoc/_cayenne-guide/part5/java8.adoc | 1 +
.../asciidoc/_cayenne-guide/part5/jodaTime.adoc | 1 +
21 files changed, 132 insertions(+), 58 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
index ee3726a..1c4f2ac 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
@@ -12,6 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
+[[appendixC]]
== Appendix C. Expressions BNF
[source]
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
index 56cf7f1..decd253 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
@@ -18,7 +18,7 @@
==== Reverse Engineering Database
-See chapter xref:reverse[Reverse Engineering in Cayenne Modeler]
+See chapter <<Reverse Engineering in Cayenne Modeler>>
==== Generating Database Schema
@@ -30,7 +30,7 @@ You can select what database parts should be generated and what tables you want
==== Generating Java Classes
-Before using Cayenne in you code you need to generate java source code for persistent objects. This can be done with Modeler GUI or via xref:cgen[cgen] maven/ant plugin.
+Before using Cayenne in you code you need to generate java source code for persistent objects. This can be done with Modeler GUI or via <<cgen>> maven/ant plugin.
To generate classes in the modeler use *Tools > Generate Classes*
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
index 61431af..5b8e28b 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
@@ -53,7 +53,7 @@ include::../var.adoc[]
- JDBC Driver: An appropriate DB-specific JDBC driver is needed to access the database. It can be included in the application or used in web container DataSource configuration.
-- Third-party Libraries: Cayenne runtime framework has a minimal set of required and a few more optional dependencies on third-party open source packages. See xref:include["Including Cayenne in a Project"]. chapter for details.
+- Third-party Libraries: Cayenne runtime framework has a minimal set of required and a few more optional dependencies on third-party open source packages. See <<Including Cayenne in a Project>> chapter for details.
[[runModeler]]
==== Running CayenneModeler
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
index 42504d2..aa78d0d 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
@@ -12,7 +12,6 @@
// the specific language governing permissions and limitations under the
// License.
-[[customize]]
=== Customizing Cayenne Runtime
==== Dependency Injection Container
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
index 4d41f1d..3d1bbd5 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
@@ -11,7 +11,7 @@
// CONDITIONS OF ANY KIND, either express or implied. See the License for
// the specific language governing permissions and limitations under the
// License.
-[[expressions]]
+
=== Expressions
==== Expressions Overview
@@ -177,7 +177,7 @@ Expression qualifier1 = template.params(p1);
Null handling. 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.
-NOTE: A formal definition of the expression grammar is provided in Appendix C
+NOTE: A formal definition of the expression grammar is provided in <<appendixC, Appendix C>>
==== Creating Expressions via API
@@ -191,7 +191,7 @@ Expression e2 = ExpressionFactory.lessExp("price", 1000);
Expression finalExp = e1.andExp(e2);
----
-NOTE: 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.
+NOTE: The last line in the example above shows how to create a new expression by "chaining" two other expressions. 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.
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:
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
index b60cc2e..7c74f37 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
@@ -14,7 +14,7 @@
include::../var.adoc[]
-[[include]]
+[[including-cayenne-in-project]]
=== Including Cayenne in a Project
==== Jar Files
@@ -25,7 +25,7 @@ This is an overview of Cayenne jars that is agnostic of the build tool used. The
- `cayenne-server-{version}.jar` - contains main Cayenne runtime (adapters, DB access classes, etc.). Most applications will require this file.
-- `cayenne-client-{version}.jar` - a client-side runtime for xref:rop[ROP applications].
+- `cayenne-client-{version}.jar` - a client-side runtime for <<introduction-to-rop, ROP applications>>
- Other cayenne-* jars - various Cayenne tools extensions.
@@ -278,7 +278,7 @@ Example - creating a DB schema on a local HSQLDB database:
[[mavenCdbimort]]
===== cdbimport
-`cdbimport` is a `cayenne-maven-plugin` goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter xref:dbFirstFlow["DB-First Flow"]
+`cdbimport` is a `cayenne-maven-plugin` goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter <<DB-First Flow>>
[#cdbimportTable.table.table-bordered]
.cdbimport parameters
[cols="2,1,2,5"]
@@ -303,7 +303,7 @@ Example - creating a DB schema on a local HSQLDB database:
.^|dbimport
.^|XML
.^|No
-.^|An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see xref:dbFirstFlow["DB-First Flow"] chapter.
+.^|An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <<DB-First Flow>> chapter.
|===
[#cdbimportDataSource.table.table-bordered]
@@ -355,7 +355,7 @@ Example - creating a DB schema on a local HSQLDB database:
.^|String
.^|A comma-separated list of Perl5 patterns that defines which imported tables should have their primary key columns mapped as ObjAttributes. "*" would indicate all tables.
-.^|namingStrategy
+.^|[[namingStrategy]]namingStrategy
.^|String
.^|The naming strategy used for mapping database names to object entity names. Default is `org.apache.cayenne.dbsync.naming.DefaultObjectNameGenerator`.
@@ -392,7 +392,7 @@ a|Regex that matches the part of the table name that needs to be stripped off wh
.^|filters configuration
.^|XML
-a|Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see xref:dbFirstFlow["DB-First Flow"] chapter. Here is some simple example:
+a|Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <<DB-First Flow>> chapter. Here is some simple example:
[source,XML]
----
<dbimport>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
index de13e70..888be47 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
@@ -12,6 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
+[[persistent-objects-objectcontext]]
=== Persistent Objects and ObjectContext
==== ObjectContext
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
index e69ca41..abe2db9 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
@@ -244,7 +244,7 @@ Artist artistWithId1 = SelectById.query(Artist.class, 1)
===== SQLSelect and SQLExec
-`SQLSelect` and `SQLExec` are essentially a "fluent" versions of older `SQLTemplate` query. `SQLSelect` can be used (as name suggests) to select custom data in form of entities, separate columns or collection of `DataRow. SQLExec` is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.) This queries support all directives described in xref:sqltemplate[SQLTemplate] section.
+`SQLSelect` and `SQLExec` are essentially a "fluent" versions of older `SQLTemplate` query. `SQLSelect` can be used (as name suggests) to select custom data in form of entities, separate columns or collection of `DataRow`. `SQLExec` is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.) This queries support all directives described in xref:sqltemplate[SQLTemplate] section.
Here is example of how to use SQLSelect:
@@ -638,7 +638,7 @@ Arguments:
- `column` - the name of the column to render in SQL SELECT clause.
-- `javaType` - a fully-qualified Java class name for a given result column. For simplicity most common Java types used in JDBC can be specified without a package. These include all numeric types, primitives, String, SQL dates, BigDecimal and BigInteger. So "_#result('A' 'String')_", "_#result('B' 'java.lang.String')_" and "_#result('C' 'int')_" are all valid
+- `javaType` - a fully-qualified Java class name for a given result column. For simplicity most common Java types used in JDBC can be specified without a package. These include all numeric types, primitives, String, SQL dates, BigDecimal and BigInteger. So `"#result('A' 'String')"`, `"#result('B' 'java.lang.String')"` and `"#result('C' 'int')"` are all valid
- `alias` - specifies both the SQL alias of the column and the value key in the DataRow. If omitted, "column" value is used.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
index b556536..c136abc 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
@@ -27,7 +27,7 @@ ServerRuntime runtime = ServerRuntime.builder()
The parameter you pass to the builder is a location of the main project file. Location is a '/'-separated path (same path separator is used on UNIX and Windows) that is resolved relative to the application classpath. The project file can be placed in the root package or in a subpackage (e.g. in the code above it is in "com/example" subpackage).
-ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the container are discussed in xref:customize["Customizing Cayenne Runtime"] chapter. Here we'll just show an example of how an application might turn on external transactions:
+ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the container are discussed in <<Customizing Cayenne Runtime>> chapter. Here we'll just show an example of how an application might turn on external transactions:
[source, java]
----
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
index aa90e0e..fb5bb3f 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
@@ -16,7 +16,10 @@
==== Prefetching
-Prefetching is a technique that allows to bring back in one query not only the queried objects, but also objects related to them. In other words it is a controlled eager relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning" chapter, as it is a powerful performance optimization method. However another common application of prefetching is to refresh stale object relationships, so more generally it can be viewed as a technique for managing subsets of the object graph.
+Prefetching is a technique that allows to bring back in one query not only the queried objects, but also objects related to them.
+In other words it is a controlled eager relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning" chapter,
+as it is a powerful performance optimization method. However another common application of prefetching is to refresh stale
+object relationships, so more generally it can be viewed as a technique for managing subsets of the object graph.
Prefetching example:
@@ -50,11 +53,14 @@ query.prefetch(Artist.PAINTINGS.disjoint());
query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());
----
-If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint" prefetches are executed (see prefetching semantics discussion below for what disjoint and joint prefetches mean).
+If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint" prefetches are executed
+(see prefetching semantics discussion below for what disjoint and joint prefetches mean).
===== Prefetching Semantics
-Prefetching semantics defines a strategy to prefetch relationships. Depending on it, Cayenne would generate different types of queries. The end result is the same - query root objects with related objects fully resolved. However semantics can affect preformance, in some cases significantly. There are 3 types of prefetch semantics, all defined as constants in `org.apache.cayenne.query.PrefetchTreeNode`:
+Prefetching semantics defines a strategy to prefetch relationships. Depending on it, Cayenne would generate different types of queries.
+The end result is the same - query root objects with related objects fully resolved. However semantics can affect performance,
+in some cases significantly. There are 3 types of prefetch semantics, all defined as constants in `org.apache.cayenne.query.PrefetchTreeNode`:
[source]
----
@@ -63,44 +69,68 @@ PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS
PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS
----
-There's no limitation on mixing different types of semantics in the same query. Each prefetch can have its own semantics. `SelectQuery` uses `DISJOINT_PREFETCH_SEMANTICS` by default. `ObjectSelect` requires explicit semantics as we've seen above. `SQLTemplate_ and _ProcedureQuery` are both using `JOINT_PREFETCH_SEMANTICS` and it can not be changed due to the nature of those two queries.
+There's no limitation on mixing different types of semantics in the same query. Each prefetch can have its own semantics.
+`SelectQuery` uses `DISJOINT_PREFETCH_SEMANTICS` by default. `ObjectSelect` requires explicit semantics as we've seen above.
+ `SQLTemplate` and `ProcedureQuery` are both using `JOINT_PREFETCH_SEMANTICS` and it can not be changed due to the nature of those two queries.
===== Disjoint Prefetching Semantics
-This semantics results in Cayenne generatiing one SQL statement for the main objects, and a separate statement for each prefetch path (hence "disjoint" - related objects are not fetched with the main query). Each additional SQL statement uses a qualifier of the main query plus a set of joins traversing the preftech path between the main and related entity.
+This semantics results in Cayenne generatiing one SQL statement for the main objects, and a separate statement for
+each prefetch path (hence "disjoint" - related objects are not fetched with the main query).
+Each additional SQL statement uses a qualifier of the main query plus a set of joins traversing the
+prefetch path between the main and related entity.
-This strategy has an advantage of efficient JVM memory use, and faster overall result processing by Cayenne, but it requires (1+N) SQL statements to be executed, where N is the number of prefetched relationships.
+This strategy has an advantage of efficient JVM memory use, and faster overall result processing by Cayenne,
+but it requires (1+N) SQL statements to be executed, where N is the number of prefetched relationships.
===== Disjoint-by-ID Prefetching Semantics
-This is a variation of disjoint prefetch where related objects are matched against a set of IDs derived from the fetched main objects (or intermediate objects in a multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller queries. The size of is controlled by the DI property Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL statements for each query using disjoint-by-ID prefetches, where N is the number of relationships to prefetch, and M is the number of queries for a given prefetch that is dependent on the number of objects in the result (ideally M = 1).
+This is a variation of disjoint prefetch where related objects are matched against a set of IDs derived from the fetched
+main objects (or intermediate objects in a multi-step prefetch). Cayenne limits the size of the generated WHERE clause,
+as most DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller queries.
+The size of is controlled by the DI property `Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY`
+(the default number of conditions in the generated WHERE clause is 10000).
+Cayenne will generate (1 + N * M) SQL statements for each query using disjoint-by-ID prefetches,
+where N is the number of relationships to prefetch, and M is the number of queries for a given prefetch
+that is dependent on the number of objects in the result (ideally M = 1).
-The advantage of this type of prefetch is that matching database rows by ID may be much faster than matching the qualifier of the original query. Moreover this is *the only type of prefetch* that can handle SelectQueries with *fetch* limit. Both joint and regular disjoint prefetches may produce invalid results or generate inefficient fetch-the-entire table SQL when fetch limit is in effect.
+The advantage of this type of prefetch is that matching database rows by ID may be much faster than matching
+the qualifier of the original query. Moreover this is *the only type of prefetch* that can handle SelectQueries with *fetch* limit.
+Both joint and regular disjoint prefetches may produce invalid results or generate inefficient fetch-the-entire table SQL when fetch limit is in effect.
The disadvantage is that query SQL can get unwieldy for large result sets, as each object will have to have its own condition in the WHERE clause of the generated SQL.
===== Joint Prefetching Semantics
-Joint semantics results in a single SQL statement for root objects and any number of jointly prefetched paths. Cayenne processes in memory a cartesian product of the entities involved, converting it to an object tree. It uses OUTER joins to connect prefetched entities.
+Joint semantics results in a single SQL statement for root objects and any number of jointly prefetched paths.
+Cayenne processes in memory a cartesian product of the entities involved, converting it to an object tree.
+It uses OUTER joins to connect prefetched entities.
-Joint is the most efficient prefetch type of the three as far as generated SQL goes. There's always just 1 SQL query generated. Its downsides are the potentially increased amount of data that needs to get across the network between the application server and the database, and more data processing that needs to be done on the Cayenne side.
+Joint is the most efficient prefetch type of the three as far as generated SQL goes. There's always just 1 SQL query generated.
+Its downsides are the potentially increased amount of data that needs to get across the network between the application server and the database,
+and more data processing that needs to be done on the Cayenne side.
===== Similar Behaviours Using EJBQL
-It is possible to achieve similar behaviours with xref:ejbql[EJBQLQuery] queries by employing the "FETCH" keyword.
+It is possible to achieve similar behaviours with <<EJBQLQuery>> queries by employing the "FETCH" keyword.
[source, SQL]
----
SELECT a FROM Artist a LEFT JOIN FETCH a.paintings
----
-In this case, the Paintings that exist for the Artist will be obtained at the same time as the Artists are fetched. Refer to third-party query language documentation for further detail on this mechanism.
+In this case, the Paintings that exist for the Artist will be obtained at the same time as the Artists are fetched.
+Refer to third-party query language documentation for further detail on this mechanism.
==== Data Rows
-Converting result set data to Persistent objects and registering these objects in the ObjectContext can be an expensive operation compareable to the time spent running the query (and frequently exceeding it). Internally Cayenne builds the result as a list of DataRows, that are later converted to objects. Skipping the last step and using data in the form of DataRows can significantly increase performance.
+Converting result set data to Persistent objects and registering these objects in the ObjectContext can be an expensive
+ operation comparable to the time spent running the query (and frequently exceeding it). Internally Cayenne builds the result as a list of DataRows,
+ that are later converted to objects. Skipping the last step and using data in the form of DataRows can significantly increase performance.
-DataRow is a simply a map of values keyed by their DB column name. It is a ubiqutous representation of DB data used internally by Cayenne. And it can be quite usable as is in the application in many cases. So performance sensitive selects should consider DataRows - it saves memory and CPU cycles. All selecting queries support DataRows option, e.g.:
+DataRow is a simply a map of values keyed by their DB column name. It is a ubiqutous representation of DB data used internally by Cayenne.
+And it can be quite usable as is in the application in many cases. So performance sensitive selects should consider
+DataRows - it saves memory and CPU cycles. All selecting queries support DataRows option, e.g.:
[source, Java]
----
@@ -134,7 +164,7 @@ for(DataRow row : rows) {
==== Specific Attributes and Relationships with EJBQL
-It is possible to fetch specific attributes and relationships from a model using xref:ejbqlquery[EJBQLQuery]. The following example would return a java.util.List of String objects;
+It is possible to fetch specific attributes and relationships from a model using <<EJBQLQuery>>. The following example would return a java.util.List of String objects;
[source, SQL]
----
@@ -152,13 +182,20 @@ Refer to third-party query language documentation for further detail on this mec
==== Iterated Queries
-While contemporary hardware may easily allow applications to fetch hundreds of thousands or even millions of objects into memory, it doesn't mean this is always a good idea to do so. You can optimize processing of very large result sets with two techniques discussed in this and the following chapter - iterated and paginated queries.
+While contemporary hardware may easily allow applications to fetch hundreds of thousands or even millions of objects into memory,
+it doesn't mean this is always a good idea to do so. You can optimize processing of very large result sets with two techniques discussed in this and the following chapter - iterated and paginated queries.
-Iterated query is not actually a special query. Any selecting query can be executed in iterated mode by an ObjectContext. ObjectContext creates an object called `ResultIterator` that is backed by an open ResultSet. Iterator provides constant memory performance for arbitrarily large ResultSets. This is true at least on the Cayenne end, as JDBC driver may still decide to bring the entire ResultSet into the JVM memory.
+Iterated query is not actually a special query. Any selecting query can be executed in iterated mode by an ObjectContext.
+ObjectContext creates an object called `ResultIterator` that is backed by an open ResultSet.
+Iterator provides constant memory performance for arbitrarily large ResultSets. This is true at least on the Cayenne end,
+as JDBC driver may still decide to bring the entire ResultSet into the JVM memory.
-Data is read from ResultIterator one row/object at a time until it is exhausted. There are two styles of accessing ResultIterator - direct access which requires explicit closing to avoid JDBC resources leak, or a callback that lets Cayenne handle resource management. In both cases iteration can be performed using "for" loop, as ResultIterator is "Iterable".
+Data is read from ResultIterator one row/object at a time until it is exhausted. There are two styles of accessing
+ResultIterator - direct access which requires explicit closing to avoid JDBC resources leak, or a callback that lets
+Cayenne handle resource management. In both cases iteration can be performed using "for" loop, as ResultIterator is "Iterable".
-Direct access. Here common sense tells us that ResultIterators instances should be processed and closed as soon as possible to release the DB connection. E.g. storing open iterators between HTTP requests for unpredictable length of time would quickly exhaust the connection pool.
+Direct access. Here common sense tells us that ResultIterators instances should be processed and closed as soon as possible to release the DB connection.
+E.g. storing open iterators between HTTP requests for unpredictable length of time would quickly exhaust the connection pool.
[source, Java]
----
@@ -180,7 +217,9 @@ ObjectSelect.query(Artist.class).iterate(context, (Artist a) -> {
});
----
-Another example is a batch iterator that allows to process more than one object in each iteration. This is a common scenario in various data processing jobs - read a batch of objects, process them, commit the results, and then repeat. This allows to further optimize processing (e.g. by avoiding frequent commits).
+Another example is a batch iterator that allows to process more than one object in each iteration.
+This is a common scenario in various data processing jobs - read a batch of objects, process them, commit the results,
+and then repeat. This allows to further optimize processing (e.g. by avoiding frequent commits).
[source, Java]
----
@@ -196,7 +235,9 @@ try(ResultBatchIterator<Artist> it = ObjectSelect.query(Artist.class).batchItera
==== Paginated Queries
-Enabling query pagination allows to load very large result sets in a Java app with very little memory overhead (much smaller than even the DataRows option discussed above). Moreover it is completely transparent to the application - a user gets what appears to be a list of Persistent objects - there's no iterator to close or DataRows to convert to objects:
+Enabling query pagination allows to load very large result sets in a Java app with very little memory overhead
+(much smaller than even the DataRows option discussed above). Moreover it is completely transparent to the application -
+a user gets what appears to be a list of Persistent objects - there's no iterator to close or DataRows to convert to objects:
[source, Java]
----
@@ -214,9 +255,15 @@ List<DataRow> rows =
ObjectSelect.dataRowQuery(Artist.class).pageSize(50).select(context);
----
-The way pagination works internally, it first fetches a list of IDs for the root entity of the query. This is very fast and initially takes very little memory. Then when an object is requested at an arbitrary index in the list, this object and adjacent objects (a "page" of objects that is determined by the query pageSize parameter) are fetched together by ID. Subsequent requests to the objects of this "page" are served from memory.
+The way pagination works internally, it first fetches a list of IDs for the root entity of the query. This is very
+fast and initially takes very little memory. Then when an object is requested at an arbitrary index in the list,
+this object and adjacent objects (a "page" of objects that is determined by the query pageSize parameter) are
+fetched together by ID. Subsequent requests to the objects of this "page" are served from memory.
-An obvious limitation of pagination is that if you eventually access all objects in the list, the memory use will end up being the same as with no pagination. However it is still a very useful approach. With some lists (e.g. multi-page search results) only a few top objects are normally accessed. At the same time pagination allows to estimate the full list size without fetching all the objects. And again - it is completely transparent and looks like a normal query.
+An obvious limitation of pagination is that if you eventually access all objects in the list, the memory use will end up
+being the same as with no pagination. However it is still a very useful approach. With some lists (e.g. multi-page search results)
+only a few top objects are normally accessed. At the same time pagination allows to estimate the full list size without
+fetching all the objects. And again - it is completely transparent and looks like a normal query.
[[caching]]
==== Caching and Fresh Data
@@ -225,18 +272,26 @@ An obvious limitation of pagination is that if you eventually access all objects
===== Query Result Caching
-Cayenne supports mostly transparent caching of the query results. There are two levels of the cache: local (i.e. results cached by the ObjectContext) and shared (i.e. the results cached at the stack level and shared between all contexts). Local cache is much faster then the shared one, but is limited to a single context. It is often used with a shared read-only ObjectContext.
+Cayenne supports mostly transparent caching of the query results. There are two levels of the cache: local
+(i.e. results cached by the ObjectContext) and shared (i.e. the results cached at the stack level and shared between all contexts).
+Local cache is much faster then the shared one, but is limited to a single context. It is often used with a shared read-only ObjectContext.
-To take advantage of query result caching, the first step is to mark your queries appropriately. Here is an example for ObjectSelect query. Other types of queries have similar API:
+To take advantage of query result caching, the first step is to mark your queries appropriately.
+Here is an example for ObjectSelect query. Other types of queries have similar API:
[source, Java]
----
ObjectSelect.query(Artist.class).localCache("artists");
----
-This tells Cayenne that the query created here would like to use local cache of the context it is executed against. A vararg parameter to `localCache()` (or `sharedCache()`) method contains so called "cache groups". Those are arbitrary names that allow to categorize queries for the purpose of setting cache policies or explicit invalidation of the cache. More on that below.
+This tells Cayenne that the query created here would like to use local cache of the context it is executed against.
+A vararg parameter to `localCache()` (or `sharedCache()`) method contains so called "cache groups".
+Those are arbitrary names that allow to categorize queries for the purpose of setting cache policies or explicit invalidation of the cache. More on that below.
-The above API is enough for the caching to work, but by default your cache is an unmanaged LRU map. You can't control its size, expiration policies, etc. For the managed cache, you will need to explicitly use one of the more advanced cache providers. One such provider available in Cayenne is a provider for http://www.ehcache.org[EhCache]. It can be enabled on ServerRuntime startup in a custom Module:
+The above API is enough for the caching to work, but by default your cache is an unmanaged LRU map. You can't control its size,
+expiration policies, etc. For the managed cache, you will need to explicitly use one of the more advanced cache providers.
+One such provider available in Cayenne is a provider for http://www.ehcache.org[EhCache].
+It can be enabled on ServerRuntime startup in a custom Module:
[source, Java]
----
@@ -264,9 +319,11 @@ By default EhCache reads a file called "ehcache.xml" located on classpath. You c
</ehcache>
----
-The example shows how to configure default cache settings ("defaultCache") as well as settings for a named cache group ("artists"). For many other things you can put in "ehcache.xml" refer to EhCache docs.
+The example shows how to configure default cache settings ("defaultCache") as well as settings for a named cache group ("artists").
+For many other things you can put in "ehcache.xml" refer to EhCache docs.
-Often "passive" cache expiration policies similar to shown above are not sufficient, and the users want real-time cache invalidation when the data changes. So in addition to those policies, the app can invalidate individual cache groups explicitly with `RefreshQuery`:
+Often "passive" cache expiration policies similar to shown above are not sufficient, and the users want real-time cache invalidation when the data changes.
+So in addition to those policies, the app can invalidate individual cache groups explicitly with `RefreshQuery`:
[source, Java]
----
@@ -274,7 +331,9 @@ RefreshQuery refresh = new RefreshQuery("artist");
context.performGenericQuery(refresh);
----
-The above can be used e.g. to build UI for manual cache invalidation. It is also possible to automate cache refresh when certain entities are committed. This requires including `cayenne-lifecycle.jar` deoendency. From that library you will need two things: `@CacheGroups` annotation to mark entities that generate cache invalidation events and `CacheInvalidationFilter` that catches the updates to the annotated objects and generates appropriate invalidation events:
+The above can be used e.g. to build UI for manual cache invalidation. It is also possible to automate cache refresh when certain entities are committed.
+This requires including `cayenne-lifecycle.jar` deoendency. From that library you will need two things: `@CacheGroups` annotation
+to mark entities that generate cache invalidation events and `CacheInvalidationFilter` that catches the updates to the annotated objects and generates appropriate invalidation events:
[source, Java]
----
@@ -297,14 +356,21 @@ public class Artist extends _Artist {
}
----
-Finally you may cluster cache group events. They are very small and can be efficiently sent over the wire to other JVMs running Cayenne. An example of Cayenne setup with event clustering is https://github.com/andrus/wowodc13/tree/master/services/src/main/java/demo/services/cayenne[available on GitHub].
+Finally you may cluster cache group events. They are very small and can be efficiently sent over the wire to other JVMs running Cayenne.
+An example of Cayenne setup with event clustering is https://github.com/andrus/wowodc13/tree/master/services/src/main/java/demo/services/cayenne[available on GitHub].
==== Turning off Synchronization of ObjectContexts
-By default when a single ObjectContext commits its changes, all other contexts in the same runtime receive an event that contains all the committed changes. This allows them to update their cached object state to match the latest committed data. There are however many problems with this ostensibly helpful feature. In short - it works well in environments with few contexts and in unclustered scenarios, such as single user desktop applications, or simple webapps with only a few users. More specifically:
+By default when a single ObjectContext commits its changes, all other contexts in the same runtime receive an event that contains all the committed changes.
+This allows them to update their cached object state to match the latest committed data. There are however many problems with this ostensibly helpful feature.
+In short - it works well in environments with few contexts and in unclustered scenarios, such as single user desktop applications,
+or simple webapps with only a few users. More specifically:
-- The performance of synchronization is (probably worse than) O(N) where N is the number of peer ObjectContexts in the system. In a typical webapp N can be quite large. Besides for any given context, due to locking on synchronization, context own performance will depend not only on the queries that it runs, but also on external events that it does not control. This is unacceptable in most situations.
+- The performance of synchronization is (probably worse than) O(N) where N is the number of peer ObjectContexts in the system.
+In a typical webapp N can be quite large. Besides for any given context, due to locking on synchronization,
+context own performance will depend not only on the queries that it runs, but also on external events that it does not control.
+This is unacceptable in most situations.
- Commit events are untargeted - even contexts that do not hold a given updated object will receive the full event that they will have to process.
@@ -314,7 +380,8 @@ By default when a single ObjectContext commits its changes, all other contexts i
- Synchronization will interfere with optimistic locking.
-So we've made a good case for disabling synchronization in most webapps. To do that, set to "false" the following DI property - `Constants.SERVER_CONTEXTS_SYNC_PROPERTY`, using one of the standard Cayenne DI approaches. E.g. from command line:
+So we've made a good case for disabling synchronization in most webapps. To do that, set to "false" the following DI property -
+`Constants.SERVER_CONTEXTS_SYNC_PROPERTY`, using one of the standard Cayenne DI approaches. E.g. from command line:
----
$ java -Dcayenne.server.contexts_sync_strategy=false
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
index f69f98a..a9932a8 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
@@ -12,7 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
-[[rop]]
+[[introduction-to-rop]]
=== Introduction to ROP
==== What is ROP
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
index 12d1484..0c1dae3 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
@@ -12,6 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
+[[re-filtering]]
=== Filtering
The first thing you usually want to control during reverse engineering is what exactly should be loaded from database and what not. One of the most common cases is excluding system tables, as you usually don't want to map them.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
index 9fbd3a2..262f562 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
@@ -14,10 +14,9 @@
include::../var.adoc[]
-[[dbFirstFlow]]
+[[re-introduction]]
=== Introduction
-[[cImp]]
==== "DB-first" Flow
An ORM system consists of three parts: database, OR mapping and persistent Java classes. These parts always need to be kept in sync with each other for the application to work. "DB-first" flow is a common and practical approach to synchronization that assumes the database to be the master source of the metadata, with other two parts synchronized from the DB as the schema evolves. Cayenne provides a number of tools to automate and control it. Here is how "DB-first" flow is typically implemented:
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
index 2315ba3..c22de49 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
@@ -12,6 +12,7 @@
// the specific language governing permissions and limitations under the
// License.
+[[re-relationships-loading-control]]
=== Other Settings
In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as OneToMany, OneToOne and ManyToMany.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
index 0dafaac..cdd71a7 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
@@ -12,10 +12,10 @@
// the specific language governing permissions and limitations under the
// License.
-[[reverse]]
+[[re-modeler]]
=== Reverse Engineering in Cayenne Modeler
-Alternative aproach to using xref:cImp[cdbimport] is doing reverse engineering from xref:runModeler[Cayenne Modeler]. Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for general DB import. Especially it's a good place to quickly start working on your data model.
+Alternative aproach to using <<cdbimport>> is doing reverse engineering from <<CayenneModeler Application, CayenneModeler>>. Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for general DB import. Especially it's a good place to quickly start working on your data model.
You can find reverse engineering tool in main modeler menu *Tools > Reengineer Database Schema*
@@ -45,7 +45,7 @@ NOTE: You can only select one catalog. If you need to import multiple catalogs y
- *Procedure Name Pattern*: RegExp to filter procedures. Default pattern .* includes all stored procedures.
-- *Naming Strategy*: Currently there is only one naming strategy available. See ant/maven tools xref:reverse[documentation] for details about naming strategy.
+- *Naming Strategy*: Currently there is only one naming strategy available. See ant/maven tools <<namingStrategy, documentation>> for details about naming strategy.
- *Tables with Meaningful PK Pattern*: Comma separated list of RegExp's for tables that you want to have meaningful primary keys. By default no meaningful PKs are created.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
index 7577238..246162f 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
@@ -14,7 +14,7 @@
include::../var.adoc[]
-[[cacheInvalidation]]
+[[ext-cache-invalidation]]
=== Cache invalidation extension
==== Description
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
index 7501a42..5f43f66 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
@@ -14,6 +14,7 @@
include::../var.adoc[]
+[[ext-commit-log]]
=== Commit log extension
==== Description
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
index a2f91ca..86efada 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
@@ -14,6 +14,7 @@
include::../var.adoc[]
+[[ext-crypto]]
=== Crypto extension
==== Description
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
index 04c09d0..5a3daac 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
@@ -14,6 +14,7 @@
include::../var.adoc[]
+[[ext-jcache]]
=== JCache integration
==== Description
@@ -48,4 +49,4 @@ For advanced configuration and management please use provider specific options a
NOTE: You can read about using cache in Cayenne in xref:caching[this] chapter.
-You may else be interested in xref:cacheInvalidation[cache invalidation] extension.
\ No newline at end of file
+You may else be interested in <<Cache invalidation extension>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
index be7e9a7..a98357f 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
@@ -14,6 +14,7 @@
include::../var.adoc[]
+[[ext-java8]]
=== Java 8 extension
==== Description
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7ecf0d33/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
index 5510f77..5edabde 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
@@ -14,6 +14,7 @@
include::../var.adoc[]
+[[ext-joda]]
=== Joda time extension
==== Description