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 2019/11/14 08:46:57 UTC
[cayenne-website] branch asf-site updated: update documentation
This is an automated email from the ASF dual-hosted git repository.
ntimofeev pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/cayenne-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 470bc28 update documentation
470bc28 is described below
commit 470bc2812f28da03a87eec61078a82d8d153fc0d
Author: Nikita Timofeev <st...@gmail.com>
AuthorDate: Thu Nov 14 11:46:53 2019 +0300
update documentation
---
docs/4.1/cayenne-guide.toc/index.html | 14 +-
docs/4.1/cayenne-guide/index.html | 601 ++++++++++++---------------
docs/4.1/getting-started-db-first/index.html | 32 +-
docs/4.1/getting-started-guide/index.html | 38 +-
docs/4.1/getting-started-rop/index.html | 20 +-
5 files changed, 324 insertions(+), 381 deletions(-)
diff --git a/docs/4.1/cayenne-guide.toc/index.html b/docs/4.1/cayenne-guide.toc/index.html
index 3489bb1..55da58f 100644
--- a/docs/4.1/cayenne-guide.toc/index.html
+++ b/docs/4.1/cayenne-guide.toc/index.html
@@ -21,7 +21,7 @@
<li><a href="#performance-tuning" class="nav-link">2.8. Performance Tuning</a></li>
<li><a href="#customizing-cayenne-runtime" class="nav-link">2.9. Customizing Cayenne Runtime</a></li>
</ul> </li>
- <li><a href="#cayenne-framework-remote-object-persistence" class="nav-link">3. Cayenne Framework - Remote Object Persistence</a>
+ <li><a href="#rop" class="nav-link">3. Cayenne Framework - Remote Object Persistence</a>
<ul class="sectlevel2 nav">
<li><a href="#introduction-to-rop" class="nav-link">3.1. Introduction to ROP</a></li>
<li><a href="#rop-deployment" class="nav-link">3.2. ROP Deployment</a></li>
@@ -33,17 +33,17 @@
<li><a href="#re-relationships-loading-control" class="nav-link">4.3. Other Settings</a></li>
<li><a href="#re-modeler" class="nav-link">4.4. Reverse Engineering in Cayenne Modeler</a></li>
</ul> </li>
- <li><a href="#cayenne-additional-modules" class="nav-link">5. Cayenne Additional Modules</a>
+ <li><a href="#additional-modules" class="nav-link">5. Additional Modules</a>
<ul class="sectlevel2 nav">
- <li><a href="#ext-cache-invalidation" class="nav-link">5.1. Cache invalidation extension</a></li>
+ <li><a href="#ext-cache-invalidation" class="nav-link">5.1. Cache Invalidation Extension</a></li>
<li><a href="#ext-commit-log" class="nav-link">5.2. Commit log extension</a></li>
<li><a href="#ext-crypto" class="nav-link">5.3. Crypto extension</a></li>
<li><a href="#ext-jcache" class="nav-link">5.4. JCache integration</a></li>
<li><a href="#ext-project-compatibility" class="nav-link">5.5. Project compatibility extension</a></li>
- <li><a href="#ext-velocity" class="nav-link">5.6. Apache Velocity extension</a></li>
- <li><a href="#cayenne-web-extension" class="nav-link">5.7. Cayenne Web extension</a></li>
- <li><a href="#cayenne-osgi-extension" class="nav-link">5.8. Cayenne OSGI extension</a></li>
- <li><a href="#cayenne-rop-server-extension" class="nav-link">5.9. Cayenne Rop Server extension</a></li>
+ <li><a href="#ext-velocity" class="nav-link">5.6. Apache Velocity Extension</a></li>
+ <li><a href="#ext-web" class="nav-link">5.7. Cayenne Web Extension</a></li>
+ <li><a href="#ext-osgi" class="nav-link">5.8. Cayenne OSGI extension</a></li>
+ <li><a href="#ext-rop" class="nav-link">5.9. Cayenne ROP Server Extension</a></li>
</ul> </li>
<li><a href="#build_tools" class="nav-link">6. Build Tools</a>
<ul class="sectlevel2 nav">
diff --git a/docs/4.1/cayenne-guide/index.html b/docs/4.1/cayenne-guide/index.html
index 6712aad..66da6cc 100644
--- a/docs/4.1/cayenne-guide/index.html
+++ b/docs/4.1/cayenne-guide/index.html
@@ -140,7 +140,7 @@
<li><a href="#performance-tuning" class="nav-link">2.8. Performance Tuning</a></li>
<li><a href="#customizing-cayenne-runtime" class="nav-link">2.9. Customizing Cayenne Runtime</a></li>
</ul> </li>
- <li><a href="#cayenne-framework-remote-object-persistence" class="nav-link">3. Cayenne Framework - Remote Object Persistence</a>
+ <li><a href="#rop" class="nav-link">3. Cayenne Framework - Remote Object Persistence</a>
<ul class="sectlevel2 nav">
<li><a href="#introduction-to-rop" class="nav-link">3.1. Introduction to ROP</a></li>
<li><a href="#rop-deployment" class="nav-link">3.2. ROP Deployment</a></li>
@@ -152,17 +152,17 @@
<li><a href="#re-relationships-loading-control" class="nav-link">4.3. Other Settings</a></li>
<li><a href="#re-modeler" class="nav-link">4.4. Reverse Engineering in Cayenne Modeler</a></li>
</ul> </li>
- <li><a href="#cayenne-additional-modules" class="nav-link">5. Cayenne Additional Modules</a>
+ <li><a href="#additional-modules" class="nav-link">5. Additional Modules</a>
<ul class="sectlevel2 nav">
- <li><a href="#ext-cache-invalidation" class="nav-link">5.1. Cache invalidation extension</a></li>
+ <li><a href="#ext-cache-invalidation" class="nav-link">5.1. Cache Invalidation Extension</a></li>
<li><a href="#ext-commit-log" class="nav-link">5.2. Commit log extension</a></li>
<li><a href="#ext-crypto" class="nav-link">5.3. Crypto extension</a></li>
<li><a href="#ext-jcache" class="nav-link">5.4. JCache integration</a></li>
<li><a href="#ext-project-compatibility" class="nav-link">5.5. Project compatibility extension</a></li>
- <li><a href="#ext-velocity" class="nav-link">5.6. Apache Velocity extension</a></li>
- <li><a href="#cayenne-web-extension" class="nav-link">5.7. Cayenne Web extension</a></li>
- <li><a href="#cayenne-osgi-extension" class="nav-link">5.8. Cayenne OSGI extension</a></li>
- <li><a href="#cayenne-rop-server-extension" class="nav-link">5.9. Cayenne Rop Server extension</a></li>
+ <li><a href="#ext-velocity" class="nav-link">5.6. Apache Velocity Extension</a></li>
+ <li><a href="#ext-web" class="nav-link">5.7. Cayenne Web Extension</a></li>
+ <li><a href="#ext-osgi" class="nav-link">5.8. Cayenne OSGI extension</a></li>
+ <li><a href="#ext-rop" class="nav-link">5.9. Cayenne ROP Server Extension</a></li>
</ul> </li>
<li><a href="#build_tools" class="nav-link">6. Build Tools</a>
<ul class="sectlevel2 nav">
@@ -216,7 +216,7 @@
<div class="sect2">
<h3 id="setup"><a class="anchor" href="#setup"></a>1.1. Setup</h3>
<div class="sect3">
- <h4 id="system-requirements"><a class="anchor" href="#system-requirements"></a>System Requirements</h4>
+ <h4 id="system-requirements"><a class="anchor" href="#system-requirements"></a>1.1.1. System Requirements</h4>
<div class="ulist">
<ul>
<li> <p>Java: Cayenne runtime framework and CayenneModeler GUI tool are written in 100% Java, and run on any Java-compatible platform. Minimal required JDK version depends on the version of Cayenne you are using, as shown in the following table:</p> </li>
@@ -279,7 +279,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="runModeler"><a class="anchor" href="#runModeler"></a>Running CayenneModeler</h4>
+ <h4 id="runModeler"><a class="anchor" href="#runModeler"></a>1.1.2. Running CayenneModeler</h4>
<div class="paragraph">
<p>CayenneModeler GUI tool is intended to work with object relational mapping projects. While you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne distribution archive from <a href="http://cayenne.apache.org/download.html" class="bare">http://cayenne.apache.org/download.html</a> matching the OS you are using. Of course Java needs to be installed on the machine where y [...]
</div>
@@ -365,7 +365,7 @@
<div class="sect2">
<h3 id="cayenne-mapping-structure"><a class="anchor" href="#cayenne-mapping-structure"></a>1.2. Cayenne Mapping Structure</h3>
<div class="sect3">
- <h4 id="cayenne-project"><a class="anchor" href="#cayenne-project"></a>Cayenne Project</h4>
+ <h4 id="cayenne-project"><a class="anchor" href="#cayenne-project"></a>1.2.1. Cayenne Project</h4>
<div class="paragraph">
<p>A Cayenne project is an XML representation of a model connecting database schema with Java classes. A project is normally created and manipulated via CayenneModeler GUI and then used to initialize Cayenne runtime. A project is made of one or more files. There’s always a root project descriptor file in any valid project. It is normally called cayenne-xyz.xml, where "xyz" is the name of the project.</p>
</div>
@@ -393,25 +393,25 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="datamap"><a class="anchor" href="#datamap"></a>DataMap</h4>
+ <h4 id="datamap"><a class="anchor" href="#datamap"></a>1.2.2. DataMap</h4>
<div class="paragraph">
<p>DataMap is a container of persistent entities and other object-relational metadata. DataMap provides developers with a scope to organize their entities, but it does not provide a namespace for entities. In fact all DataMaps present in runtime are combined in a single namespace. Each DataMap must be associated with a DataNode. This is how Cayenne knows which database to use when running a query.</p>
</div>
</div>
<div class="sect3">
- <h4 id="datanode"><a class="anchor" href="#datanode"></a>DataNode</h4>
+ <h4 id="datanode"><a class="anchor" href="#datanode"></a>1.2.3. DataNode</h4>
<div class="paragraph">
<p>DataNode is model of a database. It is actually pretty simple. It has an arbitrary user-provided name and information needed to create or locate a JDBC DataSource. Most projects only have one DataNode, though there may be any number of nodes if needed.</p>
</div>
</div>
<div class="sect3">
- <h4 id="dbentity"><a class="anchor" href="#dbentity"></a>DbEntity</h4>
+ <h4 id="dbentity"><a class="anchor" href="#dbentity"></a>1.2.4. DbEntity</h4>
<div class="paragraph">
<p>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships are not strictly tied to FK constraints in DB, and should be mapped for all logical "relationships" between the tables.</p>
</div>
</div>
<div class="sect3">
- <h4 id="objentity"><a class="anchor" href="#objentity"></a>ObjEntity</h4>
+ <h4 id="objentity"><a class="anchor" href="#objentity"></a>1.2.5. ObjEntity</h4>
<div class="paragraph">
<p>ObjEntity is a model of a single persistent Java class. ObjEntity is made of ObjAttributes and ObjRelationships. Both correspond to entity class properties. However ObjAttributes represent "simple" properties (normally things like String, numbers, dates, etc.), while ObjRelationships correspond to properties that have a type of another entity.</p>
</div>
@@ -423,19 +423,19 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="embeddable"><a class="anchor" href="#embeddable"></a>Embeddable</h4>
+ <h4 id="embeddable"><a class="anchor" href="#embeddable"></a>1.2.6. Embeddable</h4>
<div class="paragraph">
<p>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity, but maps to multiple columns in the database.</p>
</div>
</div>
<div class="sect3">
- <h4 id="procedure"><a class="anchor" href="#procedure"></a>Procedure</h4>
+ <h4 id="procedure"><a class="anchor" href="#procedure"></a>1.2.7. Procedure</h4>
<div class="paragraph">
<p>A model of a stored procedure in the database.</p>
</div>
</div>
<div class="sect3">
- <h4 id="query"><a class="anchor" href="#query"></a>Query</h4>
+ <h4 id="query"><a class="anchor" href="#query"></a>1.2.8. Query</h4>
<div class="paragraph">
<p>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created in the code. Depending on the circumstances the users may take one or the other approach.</p>
</div>
@@ -444,13 +444,13 @@ total 24
<div class="sect2">
<h3 id="cayenne-modeler"><a class="anchor" href="#cayenne-modeler"></a>1.3. CayenneModeler Application</h3>
<div class="sect3">
- <h4 id="reverse-engineering-database"><a class="anchor" href="#reverse-engineering-database"></a>Reverse Engineering Database</h4>
+ <h4 id="reverse-engineering-database"><a class="anchor" href="#reverse-engineering-database"></a>1.3.1. Reverse Engineering Database</h4>
<div class="paragraph">
<p>See chapter <a href="#re-modeler">Reverse Engineering in Cayenne Modeler</a></p>
</div>
</div>
<div class="sect3">
- <h4 id="generating-database-schema"><a class="anchor" href="#generating-database-schema"></a>Generating Database Schema</h4>
+ <h4 id="generating-database-schema"><a class="anchor" href="#generating-database-schema"></a>1.3.2. Generating Database Schema</h4>
<div class="paragraph">
<p>With Cayenne Modeler you can create simple database schemas without any additional database tools. This is a good option for initial database setup if you completely created you model with the Modeler. You can start SQL schema generation by selecting menu <strong>Tools > Generate Database Schema</strong></p>
</div>
@@ -459,7 +459,7 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="generating-java-classes"><a class="anchor" href="#generating-java-classes"></a>Generating Java Classes</h4>
+ <h4 id="generating-java-classes"><a class="anchor" href="#generating-java-classes"></a>1.3.3. Generating Java Classes</h4>
<div class="paragraph">
<p>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 <a href="#cgen">cgen</a> maven/ant plugin.</p>
</div>
@@ -495,7 +495,7 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="modeling-generic-persistent-classes"><a class="anchor" href="#modeling-generic-persistent-classes"></a>Modeling Generic Persistent Classes</h4>
+ <h4 id="modeling-generic-persistent-classes"><a class="anchor" href="#modeling-generic-persistent-classes"></a>1.3.4. Modeling Generic Persistent Classes</h4>
<div class="paragraph">
<p>Normally each ObjEntity is mapped to a specific Java class (such as Artist or Painting) that explicitly declare all entity properties as pairs of getters and setters. However Cayenne allows to map a completly generic class to any number of entities. The only expectation is that a generic class implements org.apache.cayenne.DataObject. So an ideal candidate for a generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</p>
</div>
@@ -507,7 +507,7 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="modeling-primary-key-generation-strategy"><a class="anchor" href="#modeling-primary-key-generation-strategy"></a>Modeling Primary Key Generation Strategy</h4>
+ <h4 id="modeling-primary-key-generation-strategy"><a class="anchor" href="#modeling-primary-key-generation-strategy"></a>1.3.5. Modeling Primary Key Generation Strategy</h4>
<div class="paragraph">
<p>Cayenne supports three PK generation strategies:</p>
</div>
@@ -536,7 +536,7 @@ total 24
<div class="sect2">
<h3 id="including-cayenne-in-project"><a class="anchor" href="#including-cayenne-in-project"></a>2.1. Including Cayenne in a Project</h3>
<div class="sect3">
- <h4 id="maven"><a class="anchor" href="#maven"></a>Maven</h4>
+ <h4 id="maven"><a class="anchor" href="#maven"></a>2.1.1. Maven</h4>
<div class="paragraph">
<p>To add Cayenne to your Maven project, include <code>cayenne-server</code> in your POM:</p>
</div>
@@ -551,9 +551,9 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="gradle-projects"><a class="anchor" href="#gradle-projects"></a>Gradle Projects</h4>
+ <h4 id="gradle"><a class="anchor" href="#gradle"></a>2.1.2. Gradle</h4>
<div class="paragraph">
- <p>To add Cayenne to your Maven project, include <code>cayenne-server</code> module:</p>
+ <p>To add Cayenne to your Gradle project, include <code>cayenne-server</code> module:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -562,7 +562,7 @@ total 24
</div>
</div>
<div class="sect3">
- <h4 id="ant-etc"><a class="anchor" href="#ant-etc"></a>Ant, etc.</h4>
+ <h4 id="ant-etc"><a class="anchor" href="#ant-etc"></a>2.1.3. Ant, etc.</h4>
<div class="paragraph">
<p>If your environment requires manual dependency management (like Ant), check <code>lib</code> and <code>lib/third-party</code> folders of Cayenne distribution. It contains all Cayenne jars as well as the minimal set of third-party libraries to get you started.</p>
</div>
@@ -571,7 +571,7 @@ total 24
<div class="sect2">
<h3 id="starting-cayenne"><a class="anchor" href="#starting-cayenne"></a>2.2. Starting Cayenne</h3>
<div class="sect3">
- <h4 id="starting-and-stopping-serverruntime"><a class="anchor" href="#starting-and-stopping-serverruntime"></a>Starting and Stopping ServerRuntime</h4>
+ <h4 id="starting-and-stopping-serverruntime"><a class="anchor" href="#starting-and-stopping-serverruntime"></a>2.2.1. Starting and Stopping ServerRuntime</h4>
<div class="paragraph">
<p>In runtime Cayenne is accessed via <code>org.apache.cayenne.configuration.server.ServerRuntime</code>. ServerRuntime is created by calling a convenient builder:</p>
</div>
@@ -612,7 +612,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="merging-multiple-projects"><a class="anchor" href="#merging-multiple-projects"></a>Merging Multiple Projects</h4>
+ <h4 id="merging-multiple-projects"><a class="anchor" href="#merging-multiple-projects"></a>2.2.2. Merging Multiple Projects</h4>
<div class="paragraph">
<p>ServerRuntime requires at least one mapping project to run. But it can also take multiple projects and merge them together in a single configuration. This way different parts of a database can be mapped independently from each other (even by different software providers), and combined in runtime when assembling an application. Doing it is as easy as passing multiple project locations to ServerRuntime builder:</p>
</div>
@@ -640,7 +640,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="web-applications"><a class="anchor" href="#web-applications"></a>Web Applications</h4>
+ <h4 id="web-applications"><a class="anchor" href="#web-applications"></a>2.2.3. Web Applications</h4>
<div class="paragraph">
<p>Web applications can use a variety of mechanisms to configure and start the "services" they need, Cayenne being one of such services. Configuration can be done within standard Servlet specification objects like Servlets, Filters, or ServletContextListeners, or can use Spring, JEE CDI, etc. This is a user’s architectural choice and Cayenne is agnostic to it and will happily work in any environment. As described above, all that is needed is to create an instance of ServerRuntime so [...]
</div>
@@ -695,7 +695,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<div class="sect2">
<h3 id="persistent-objects-objectcontext"><a class="anchor" href="#persistent-objects-objectcontext"></a>2.3. Persistent Objects and ObjectContext</h3>
<div class="sect3">
- <h4 id="objectcontext"><a class="anchor" href="#objectcontext"></a>ObjectContext</h4>
+ <h4 id="objectcontext"><a class="anchor" href="#objectcontext"></a>2.3.1. ObjectContext</h4>
<div class="paragraph">
<p>ObjectContext is an interface that users normally work with to access the database. It provides the API to execute database operations and to manage persistent objects. A context is obtained from the ServerRuntime:</p>
</div>
@@ -715,7 +715,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="persistent-object-and-its-lifecycle"><a class="anchor" href="#persistent-object-and-its-lifecycle"></a>Persistent Object and its Lifecycle</h4>
+ <h4 id="persistent-object-and-its-lifecycle"><a class="anchor" href="#persistent-object-and-its-lifecycle"></a>2.3.2. Persistent Object and its Lifecycle</h4>
<div class="paragraph">
<p>Cayenne can persist Java objects that implement <code>org.apache.cayenne.Persistent</code> interface. Generally persistent classes are generated from the model as described above, so users do not have to worry about superclass and property implementation details.</p>
</div>
@@ -762,7 +762,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</table>
</div>
<div class="sect3">
- <h4 id="objectcontext-persistence-api"><a class="anchor" href="#objectcontext-persistence-api"></a>ObjectContext Persistence API</h4>
+ <h4 id="objectcontext-persistence-api"><a class="anchor" href="#objectcontext-persistence-api"></a>2.3.3. ObjectContext Persistence API</h4>
<div class="paragraph">
<p>One of the first things users usually want to do with an <code>ObjectContext</code> is to select some objects from a database:</p>
</div>
@@ -863,7 +863,7 @@ Artist localArtist = editingContext.localObject(artist);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="cayenne-helper-class"><a class="anchor" href="#cayenne-helper-class"></a>Cayenne Helper Class</h4>
+ <h4 id="cayenne-helper-class"><a class="anchor" href="#cayenne-helper-class"></a>2.3.4. Cayenne Helper Class</h4>
<div class="paragraph">
<p>There is a useful helper class called <code>Cayenne</code> (fully-qualified name <code>org.apache.cayenne.Cayenne</code>) that builds on ObjectContext API to provide a number of very common operations. E.g. get a primary key (most entities do not model PK as an object property) :</p>
</div>
@@ -893,7 +893,7 @@ Artist localArtist = editingContext.localObject(artist);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="objectcontext-nesting"><a class="anchor" href="#objectcontext-nesting"></a>ObjectContext Nesting</h4>
+ <h4 id="objectcontext-nesting"><a class="anchor" href="#objectcontext-nesting"></a>2.3.5. ObjectContext Nesting</h4>
<div class="paragraph">
<p>In all the examples shown so far an ObjectContext would directly connect to a database to select data or synchronize its state (either via commit or rollback). However another context can be used in all these scenarios instead of a database. This concept is called ObjectContext "nesting". Nesting is a parent/child relationship between two contexts, where child is a nested context and selects or commits its objects via a parent.</p>
</div>
@@ -940,7 +940,7 @@ nested.rollbackChanges();</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="generic-persistent-objects"><a class="anchor" href="#generic-persistent-objects"></a>Generic Persistent Objects</h4>
+ <h4 id="generic-persistent-objects"><a class="anchor" href="#generic-persistent-objects"></a>2.3.6. Generic Persistent Objects</h4>
<div class="paragraph">
<p>As described in the CayenneModeler chapter, Cayenne supports mapping of completely generic classes to specific entities. Although for conveniece most applications should stick with entity-specific class mappings, the generic feature offers some interesting possibilities, such as creating mappings completely on the fly in a running application, etc.</p>
</div>
@@ -989,7 +989,7 @@ generic.writeProperty("name", "New Name");</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="transactions"><a class="anchor" href="#transactions"></a>Transactions</h4>
+ <h4 id="transactions"><a class="anchor" href="#transactions"></a>2.3.7. Transactions</h4>
<div class="paragraph">
<p>Considering how much attention is given to managing transactions in most other ORMs, transactions have been conspicuously absent from the ObjectContext discussion till now. The reason is that transactions are seamless in Cayenne in all but a few special cases. ObjectContext is an in-memory container of objects that is disconnected from the database, except when it needs to run an operation. So it does not care about any surrounding transaction scope. Sure enough all database oper [...]
</div>
@@ -1046,7 +1046,7 @@ transactionManager.performInTransaction(transactionalOperation, descriptor);</co
<p>Cayenne provides a simple yet powerful object-based expression language. The most common use 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.</p>
</div>
<div class="sect3">
- <h4 id="path-expressions"><a class="anchor" href="#path-expressions"></a>Path Expressions</h4>
+ <h4 id="path-expressions"><a class="anchor" href="#path-expressions"></a>2.4.1. Path Expressions</h4>
<div class="paragraph">
<p>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 situ [...]
</div>
@@ -1095,7 +1095,7 @@ transactionManager.performInTransaction(transactionalOperation, descriptor);</co
</div>
</div>
<div class="sect3">
- <h4 id="creating-expressions-from-strings"><a class="anchor" href="#creating-expressions-from-strings"></a>Creating Expressions from Strings</h4>
+ <h4 id="creating-expressions-from-strings"><a class="anchor" href="#creating-expressions-from-strings"></a>2.4.2. Creating Expressions from Strings</h4>
<div class="paragraph">
<p>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:</p>
</div>
@@ -1238,7 +1238,7 @@ Expression qualifier1 = template.params(p1);
</div>
</div>
<div class="sect3">
- <h4 id="creating-expressions-via-api"><a class="anchor" href="#creating-expressions-via-api"></a>Creating Expressions via API</h4>
+ <h4 id="creating-expressions-via-api"><a class="anchor" href="#creating-expressions-via-api"></a>2.4.3. Creating Expressions via API</h4>
<div class="paragraph">
<p>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), Property class and Expression class itself. <code>ExpressionFactory</code> contains a number of self-explanatory static methods that can be used to build expressions. E.g.:</p>
</div>
@@ -1290,7 +1290,7 @@ Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="evaluate"><a class="anchor" href="#evaluate"></a>Evaluating Expressions in Memory</h4>
+ <h4 id="evaluate"><a class="anchor" href="#evaluate"></a>2.4.4. Evaluating Expressions in Memory</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1336,7 +1336,7 @@ List<Artist> filtered = e.filterObjects(unfiltered);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="translating-expressions-to-ejbql"><a class="anchor" href="#translating-expressions-to-ejbql"></a>Translating Expressions to EJBQL</h4>
+ <h4 id="translating-expressions-to-ejbql"><a class="anchor" href="#translating-expressions-to-ejbql"></a>2.4.5. Translating Expressions to EJBQL</h4>
<div class="paragraph">
<p><a href="#ejbql">EJBQL</a> 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.</p>
</div>
@@ -1402,7 +1402,7 @@ o.orderList(list);</code></pre>
<p>Native queries describe a desired DB operation using SQL (<code>SQLSelect</code>, <code>SQLExec</code> query), a reference to a stored procedure (<code>ProcedureQuery</code>), etc. The results of native queries are lists of scalars, lists of <code>Object[]</code> or lists of maps (a term "data row" is often used to describe such a map). Some of them can potentially be converted to persistent objects (though usually with considerable effort). Native queries are less (if at all) por [...]
</div>
<div class="sect3">
- <h4 id="select"><a class="anchor" href="#select"></a>ObjectSelect</h4>
+ <h4 id="select"><a class="anchor" href="#select"></a>2.6.1. ObjectSelect</h4>
<div class="admonitionblock note">
<table>
<tbody>
@@ -1414,7 +1414,7 @@ o.orderList(list);</code></pre>
</table>
</div>
<div class="sect4">
- <h5 id="selecting-objects"><a class="anchor" href="#selecting-objects"></a>Selecting objects</h5>
+ <h5 id="selecting-objects"><a class="anchor" href="#selecting-objects"></a>2.6.1.1. Selecting objects</h5>
<div class="paragraph">
<p><code>ObjectSelect</code> is the most commonly used query in Cayenne applications. This may be the only query you will ever need. It returns a list of persistent objects (or data rows) of a certain type specified in the query:</p>
</div>
@@ -1479,7 +1479,7 @@ INFO: === returned 1 row. - took 6 ms.</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="selecting-individual-columns"><a class="anchor" href="#selecting-individual-columns"></a>Selecting individual columns</h5>
+ <h5 id="selecting-individual-columns"><a class="anchor" href="#selecting-individual-columns"></a>2.6.1.2. Selecting individual columns</h5>
<div class="paragraph">
<p><code>ObjectSelect</code> query can be used to fetch individual properties of objects via type-safe API:</p>
</div>
@@ -1502,7 +1502,7 @@ INFO: === returned 1 row. - took 6 ms.</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="selecting-using-aggregate-functions"><a class="anchor" href="#selecting-using-aggregate-functions"></a>Selecting using aggregate functions</h5>
+ <h5 id="selecting-using-aggregate-functions"><a class="anchor" href="#selecting-using-aggregate-functions"></a>2.6.1.3. Selecting using aggregate functions</h5>
<div class="paragraph">
<p>ObjectSelect query supports usage of aggregate functions. Most common variant of aggregation is selecting count of records, this can be done really easy:</p>
</div>
@@ -1548,7 +1548,7 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="selectbyid"><a class="anchor" href="#selectbyid"></a>SelectById</h4>
+ <h4 id="selectbyid"><a class="anchor" href="#selectbyid"></a>2.6.2. SelectById</h4>
<div class="paragraph">
<p>This query allows to search objects by their ID. It’s introduced in Cayenne 4.0 and uses new "fluent" API same as <code>ObjectSelect</code> query.</p>
</div>
@@ -1565,7 +1565,7 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="sqlselect-and-sqlexec"><a class="anchor" href="#sqlselect-and-sqlexec"></a>SQLSelect and SQLExec</h4>
+ <h4 id="sqlselect-and-sqlexec"><a class="anchor" href="#sqlselect-and-sqlexec"></a>2.6.3. SQLSelect and SQLExec</h4>
<div class="paragraph">
<p>SQL is very powerful and allows to manipulate data in ways that can not always be described as a graph of related entities. Cayenne acknowledges this fact and provides a facility to execute SQL, sometimes allowing to map results back to persistent objects. <code>SQLSelect</code> and <code>SQLExec</code> are a pair of queries that allow to run native SQL. <code>SQLSelect</code> can be used (as the name suggests) to select custom data in form of entities, separate columns, collecti [...]
</div>
@@ -1610,12 +1610,12 @@ List<Object[]> result = SQLSelect
</div>
</div>
<div class="sect3">
- <h4 id="sqlscripting"><a class="anchor" href="#sqlscripting"></a>Scripting SQL Queries</h4>
+ <h4 id="sqlscripting"><a class="anchor" href="#sqlscripting"></a>2.6.4. Scripting SQL Queries</h4>
<div class="paragraph">
<p>A powerful feature of <code>SQLSelect</code> and <code>SQLExec</code> is that SQL string is treated by Cayenne as a dynamic template. Before creating a PreparedStatement, the String is evaluated, resolving its dynamic parts. The two main scripting elements are "variables" (that look like <code>$var</code>) and "directives" (that look like <code>#directive(p1 p2 p3)</code>). In the discussion below we’ll use both selecting and updating examples, as scripting works the same way for [...]
</div>
<div class="sect4">
- <h5 id="variable-substitution"><a class="anchor" href="#variable-substitution"></a>Variable Substitution</h5>
+ <h5 id="variable-substitution"><a class="anchor" href="#variable-substitution"></a>2.6.4.1. Variable Substitution</h5>
<div class="paragraph">
<p>All variables in the template string are replaced from query parameters:</p>
</div>
@@ -1631,7 +1631,7 @@ SQLExec query = SQLExec.query("delete from $tableName")
</div>
</div>
<div class="sect4">
- <h5 id="directives"><a class="anchor" href="#directives"></a>Directives</h5>
+ <h5 id="directives"><a class="anchor" href="#directives"></a>2.6.4.2. Directives</h5>
<div class="paragraph">
<p>"Directives" look like <code>#directive(p1 p2 p3)</code> (notice the absence of comma between the arguments). The following directives are supported in SQL templates:</p>
</div>
@@ -1901,7 +1901,7 @@ SQLSelect select = SQLSelect.query(Painting.class, sql)
<tbody>
<tr>
<td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
- <td class="content"> For advanced features you may look at the <a href="#ext-velocity">Apache Velocity extension</a> </td>
+ <td class="content"> For advanced features you may look at the <a href="#ext-velocity">Apache Velocity Extension</a> </td>
</tr>
</tbody>
</table>
@@ -1910,7 +1910,7 @@ SQLSelect select = SQLSelect.query(Painting.class, sql)
</div>
</div>
<div class="sect3">
- <h4 id="mappedselect-and-mappedexec"><a class="anchor" href="#mappedselect-and-mappedexec"></a>MappedSelect and MappedExec</h4>
+ <h4 id="mappedselect-and-mappedexec"><a class="anchor" href="#mappedselect-and-mappedexec"></a>2.6.5. MappedSelect and MappedExec</h4>
<div class="paragraph">
<p><code>MappedSelect</code> and <code>MappedExec</code> is a queries that are just a reference to another queries stored in the DataMap. The actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc. Difference between <code>MappedSelect</code> and <code>MappedExec</code> is (as reflected in their names) whether underlying query intended to select data or just to perform some generic SQL code.</p>
</div>
@@ -1947,7 +1947,7 @@ System.out.println("Rows updated: " + result.firstUpdateCount());</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="procedurecall"><a class="anchor" href="#procedurecall"></a>ProcedureCall</h4>
+ <h4 id="procedurecall"><a class="anchor" href="#procedurecall"></a>2.6.6. ProcedureCall</h4>
<div class="paragraph">
<p>Stored procedures are mapped as separate objects in CayenneModeler. <code>ProcedureCall</code> provides a way to execute them with a certain set of parameters. This query is a "fluent" version of older <code>ProcedureQuery</code>. Just like with <code>SQLTemplate</code>, the outcome of a procedure can be anything - a single result set, multiple result sets, some data modification (returned as an update count), or a combination of these. So use root class to get a single result se [...]
</div>
@@ -1987,7 +1987,7 @@ Object out = result.getOutParam("out_param");</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="ejbql"><a class="anchor" href="#ejbql"></a>EJBQLQuery</h4>
+ <h4 id="ejbql"><a class="anchor" href="#ejbql"></a>2.6.7. EJBQLQuery</h4>
<div class="admonitionblock note">
<table>
<tbody>
@@ -2105,7 +2105,7 @@ List<String> names = context.performQuery(query);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="custom-queries"><a class="anchor" href="#custom-queries"></a>Custom Queries</h4>
+ <h4 id="custom-queries"><a class="anchor" href="#custom-queries"></a>2.6.8. Custom Queries</h4>
<div class="paragraph">
<p>If a user needs some extra functionality not addressed by the existing set of Cayenne queries, he can write his own. The only requirement is to implement <code>org.apache.cayenne.query.Query</code> interface. The easiest way to go about it is to subclass some of the base queries in Cayenne.</p>
</div>
@@ -2167,7 +2167,7 @@ List<String> names = context.performQuery(query);</code></pre>
<p>Cayenne allows to build rather powerful and complex "workflows" or "processors" tied to objects lifecycle, especially with listeners, as they have full access to the application evnironment outside Cayenne. This power comes from such features as filtering which entity events are sent to a given listener and the ability to create a common operation context for multiple callback invocations. All of these are discussed later in this chapter.</p>
</div>
<div class="sect3">
- <h4 id="types-of-lifecycle-events"><a class="anchor" href="#types-of-lifecycle-events"></a>Types of Lifecycle Events</h4>
+ <h4 id="types-of-lifecycle-events"><a class="anchor" href="#types-of-lifecycle-events"></a>2.7.1. Types of Lifecycle Events</h4>
<div class="paragraph">
<p>Cayenne defines the following 8 types of lifecycle events for which callbacks can be regsitered:</p>
</div>
@@ -2231,7 +2231,7 @@ List<String> names = context.performQuery(query);</code></pre>
</table>
</div>
<div class="sect3">
- <h4 id="callbacks-on-persistent-objects"><a class="anchor" href="#callbacks-on-persistent-objects"></a>Callbacks on Persistent Objects</h4>
+ <h4 id="callbacks-on-persistent-objects"><a class="anchor" href="#callbacks-on-persistent-objects"></a>2.7.2. Callbacks on Persistent Objects</h4>
<div class="paragraph">
<p>Callback methods on Persistent classes are mapped in CayenneModeler for each ObjEntity. Empty callback methods are automatically created as a part of class generation (either with Maven, Ant or the Modeler) and are later filled with appropriate logic by the programmer. E.g. assuming we mapped a 'post-add' callback called 'onNewOrder' in ObjEntity 'Order', the following code will be generated:</p>
</div>
@@ -2268,7 +2268,7 @@ public class Order extends _Order {
</div>
</div>
<div class="sect3">
- <h4 id="callbacks-on-non-persistent-listeners"><a class="anchor" href="#callbacks-on-non-persistent-listeners"></a>Callbacks on Non-Persistent Listeners</h4>
+ <h4 id="callbacks-on-non-persistent-listeners"><a class="anchor" href="#callbacks-on-non-persistent-listeners"></a>2.7.3. Callbacks on Non-Persistent Listeners</h4>
<div class="paragraph">
<p>A listener is simply some application class that has one or more annotated callback methods. A callback method signature should be <code>void someMethod(SomePersistentType object)</code>. It can be public, private, protected or use default access:</p>
</div>
@@ -2401,7 +2401,7 @@ public class MyEntity2 extends _MyEntity2 {
</div>
</div>
<div class="sect3">
- <h4 id="combining-listeners-with-datachannel-filters"><a class="anchor" href="#combining-listeners-with-datachannel-filters"></a>Combining Listeners with DataChannel filters</h4>
+ <h4 id="combining-listeners-with-datachannel-filters"><a class="anchor" href="#combining-listeners-with-datachannel-filters"></a>2.7.4. Combining Listeners with DataChannel filters</h4>
<div class="paragraph">
<p>A final touch in the listeners design is preserving the state of the listener within a single select or commit, so that events generated by multiple objects can be collected and processed all together. To do that you will need to implement a <code>DataChannelSyncFilter</code> (and/or <code>DataChannelQueryFilter</code>), and add some callback methods to it. They will store their state in a <code>ThreadLocal</code> variable of the filter. Here is an example filter that does someth [...]
</div>
@@ -2458,7 +2458,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<div class="sect2">
<h3 id="performance-tuning"><a class="anchor" href="#performance-tuning"></a>2.8. Performance Tuning</h3>
<div class="sect3">
- <h4 id="prefetching"><a class="anchor" href="#prefetching"></a>Prefetching</h4>
+ <h4 id="prefetching"><a class="anchor" href="#prefetching"></a>2.8.1. Prefetching</h4>
<div class="paragraph">
<p>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 [...]
</div>
@@ -2501,7 +2501,7 @@ query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());</code></pre>
<p>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).</p>
</div>
<div class="sect4">
- <h5 id="prefetching-semantics"><a class="anchor" href="#prefetching-semantics"></a>Prefetching Semantics</h5>
+ <h5 id="prefetching-semantics"><a class="anchor" href="#prefetching-semantics"></a>2.8.1.1. Prefetching Semantics</h5>
<div class="paragraph">
<p>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 <code>org.apache.cayenne.query.PrefetchTreeNode</code>:</p>
</div>
@@ -2517,7 +2517,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="disjoint-prefetching-semantics"><a class="anchor" href="#disjoint-prefetching-semantics"></a>Disjoint Prefetching Semantics</h5>
+ <h5 id="disjoint-prefetching-semantics"><a class="anchor" href="#disjoint-prefetching-semantics"></a>2.8.1.2. Disjoint Prefetching Semantics</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2526,7 +2526,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="disjoint-by-id-prefetching-semantics"><a class="anchor" href="#disjoint-by-id-prefetching-semantics"></a>Disjoint-by-ID Prefetching Semantics</h5>
+ <h5 id="disjoint-by-id-prefetching-semantics"><a class="anchor" href="#disjoint-by-id-prefetching-semantics"></a>2.8.1.3. Disjoint-by-ID Prefetching Semantics</h5>
<div class="paragraph">
<p>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 <code>Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY</code> (the default number of conditions in t [...]
</div>
@@ -2538,7 +2538,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="joint-prefetching-semantics"><a class="anchor" href="#joint-prefetching-semantics"></a>Joint Prefetching Semantics</h5>
+ <h5 id="joint-prefetching-semantics"><a class="anchor" href="#joint-prefetching-semantics"></a>2.8.1.4. Joint Prefetching Semantics</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2547,7 +2547,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="similar-behaviours-using-ejbql"><a class="anchor" href="#similar-behaviours-using-ejbql"></a>Similar Behaviours Using EJBQL</h5>
+ <h5 id="similar-behaviours-using-ejbql"><a class="anchor" href="#similar-behaviours-using-ejbql"></a>2.8.1.5. Similar Behaviours Using EJBQL</h5>
<div class="paragraph">
<p>It is possible to achieve similar behaviours with <a href="#ejbql">EJBQLQuery</a> queries by employing the "FETCH" keyword.</p>
</div>
@@ -2562,7 +2562,7 @@ PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="data-rows"><a class="anchor" href="#data-rows"></a>Data Rows</h4>
+ <h4 id="data-rows"><a class="anchor" href="#data-rows"></a>2.8.2. Data Rows</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2601,7 +2601,7 @@ for(DataRow row : rows) {
</div>
</div>
<div class="sect3">
- <h4 id="specific-attributes-and-relationships-with-ejbql"><a class="anchor" href="#specific-attributes-and-relationships-with-ejbql"></a>Specific Attributes and Relationships with EJBQL</h4>
+ <h4 id="specific-attributes-and-relationships-with-ejbql"><a class="anchor" href="#specific-attributes-and-relationships-with-ejbql"></a>2.8.3. Specific Attributes and Relationships with EJBQL</h4>
<div class="paragraph">
<p>It is possible to fetch specific attributes and relationships from a model using <a href="#ejbql">EJBQLQuery</a>. The following example would return a java.util.List of String objects;</p>
</div>
@@ -2623,7 +2623,7 @@ for(DataRow row : rows) {
</div>
</div>
<div class="sect3">
- <h4 id="iterated-queries"><a class="anchor" href="#iterated-queries"></a>Iterated Queries</h4>
+ <h4 id="iterated-queries"><a class="anchor" href="#iterated-queries"></a>2.8.4. Iterated Queries</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2674,7 +2674,7 @@ for(DataRow row : rows) {
</div>
</div>
<div class="sect3">
- <h4 id="paginated-queries"><a class="anchor" href="#paginated-queries"></a>Paginated Queries</h4>
+ <h4 id="paginated-queries"><a class="anchor" href="#paginated-queries"></a>2.8.5. Paginated Queries</h4>
<div class="paragraph">
<p>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:</p>
</div>
@@ -2702,12 +2702,12 @@ List<Artist> artists =
</div>
</div>
<div class="sect3">
- <h4 id="caching"><a class="anchor" href="#caching"></a>Caching and Fresh Data</h4>
+ <h4 id="caching"><a class="anchor" href="#caching"></a>2.8.6. Caching and Fresh Data</h4>
<div class="sect4">
- <h5 id="object-caching"><a class="anchor" href="#object-caching"></a>Object Caching</h5>
+ <h5 id="object-caching"><a class="anchor" href="#object-caching"></a>2.8.6.1. Object Caching</h5>
</div>
<div class="sect4">
- <h5 id="query-result-caching"><a class="anchor" href="#query-result-caching"></a>Query Result Caching</h5>
+ <h5 id="query-result-caching"><a class="anchor" href="#query-result-caching"></a>2.8.6.2. Query Result Caching</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2743,7 +2743,7 @@ context.performGenericQuery(refresh);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="turning-off-synchronization-of-objectcontexts"><a class="anchor" href="#turning-off-synchronization-of-objectcontexts"></a>Turning off Synchronization of ObjectContexts</h4>
+ <h4 id="turning-off-synchronization-of-objectcontexts"><a class="anchor" href="#turning-off-synchronization-of-objectcontexts"></a>2.8.7. Turning off Synchronization of ObjectContexts</h4>
<div class="paragraph">
<p>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 use [...]
</div>
@@ -2784,7 +2784,7 @@ context.performGenericQuery(refresh);</code></pre>
<div class="sect2">
<h3 id="customizing-cayenne-runtime"><a class="anchor" href="#customizing-cayenne-runtime"></a>2.9. Customizing Cayenne Runtime</h3>
<div class="sect3">
- <h4 id="dependency-injection-container"><a class="anchor" href="#dependency-injection-container"></a>Dependency Injection Container</h4>
+ <h4 id="dependency-injection-container"><a class="anchor" href="#dependency-injection-container"></a>2.9.1. Dependency Injection Container</h4>
<div class="paragraph">
<p>Cayenne runtime is built around a small powerful dependency injection (DI) container. Just like other popular DI technologies, such as Spring or Guice, Cayenne DI container manages sets of interdependent objects and allows users to configure them. These objects are regular Java objects. We are calling them "services" in this document to distinguish from all other objects that are not configured in the container and are not managed. DI container is responsible for service instanti [...]
</div>
@@ -2798,7 +2798,7 @@ context.performGenericQuery(refresh);</code></pre>
<p>Cayenne DI probably has ~80% of the features expected in a DI container and has no dependency on the rest of Cayenne, so in theory can be used as an application-wide DI engine. But it’s primary purpose is still to serve Cayenne. Hence there are no plans to expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere with Spring, Guice or any other such framework present elsewhere in the application.</p>
</div>
<div class="sect4">
- <h5 id="di-bindings-api"><a class="anchor" href="#di-bindings-api"></a>DI Bindings API</h5>
+ <h5 id="di-bindings-api"><a class="anchor" href="#di-bindings-api"></a>2.9.1.1. DI Bindings API</h5>
<div class="paragraph">
<p>To have a working DI container, we need three things: service interfaces and classes, a module that describes service bindings, a container that loads the module, and resolves the depedencies. Let’s start with service interfaces and classes:</p>
</div>
@@ -2935,7 +2935,7 @@ binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="service-lifecycle"><a class="anchor" href="#service-lifecycle"></a>Service Lifecycle</h5>
+ <h5 id="service-lifecycle"><a class="anchor" href="#service-lifecycle"></a>2.9.1.2. Service Lifecycle</h5>
<div class="paragraph">
<p>An important feature of the Cayenne DI container is instance scope. The default scope (implicitly used in all examples above) is "singleton", meaning that a binding would result in creation of only one service instance, that will be repeatedly returned from <code>Injector.getInstance(..)</code>, as well as injected into classes that declare it as a dependency.</p>
</div>
@@ -2955,14 +2955,14 @@ binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="overriding-services"><a class="anchor" href="#overriding-services"></a>Overriding Services</h5>
+ <h5 id="overriding-services"><a class="anchor" href="#overriding-services"></a>2.9.1.3. Overriding Services</h5>
<div class="paragraph">
<p>Cayenne DI allows to override services already definied in the current module, or more commonly - some other module in the the same container. Actually there’s no special API to override a service, you’d just bind the service key again with a new implementation or provider. The last binding for a key takes precedence. This means that the order of modules is important when configuring a container. The built-in Cayenne injector ensures that Cayenne standard modules are loaded firs [...]
</div>
</div>
</div>
<div class="sect3">
- <h4 id="customization-strategies"><a class="anchor" href="#customization-strategies"></a>Customization Strategies</h4>
+ <h4 id="customization-strategies"><a class="anchor" href="#customization-strategies"></a>2.9.2. Customization Strategies</h4>
<div class="paragraph">
<p>The previous section discussed how Cayenne DI works in general terms. Since Cayenne users will mostly be dealing with an existing Injector provided by ServerRuntime, it is important to understand how to build custom extensions to a preconfigured container. As shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by writing an application DI module (or multiple modules) that configures service overrides. This section shows all the configuration possibi [...]
</div>
@@ -2985,7 +2985,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect4">
- <h5 id="changing-properties-of-existing-services"><a class="anchor" href="#changing-properties-of-existing-services"></a>Changing Properties of Existing Services</h5>
+ <h5 id="changing-properties-of-existing-services"><a class="anchor" href="#changing-properties-of-existing-services"></a>2.9.2.1. Changing Properties of Existing Services</h5>
<div class="paragraph">
<p>Many built-in Cayenne services change their behavior based on a value of some environment property. A user may change Cayenne behavior without even knowing which services are responsible for it, but setting a specific value of a known property. Supported property names are listed in "Appendix A".</p>
</div>
@@ -3008,7 +3008,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect4">
- <h5 id="contributing-to-service-collections"><a class="anchor" href="#contributing-to-service-collections"></a>Contributing to Service Collections</h5>
+ <h5 id="contributing-to-service-collections"><a class="anchor" href="#contributing-to-service-collections"></a>2.9.2.2. Contributing to Service Collections</h5>
<div class="paragraph">
<p>Cayenne can be extended by adding custom objects to named maps or lists bound in DI. We are calling these lists/maps "service collections". A service collection allows things like appending a custom strategy to a list of built-in strategies. E.g. an application that needs to install a custom DbAdapter for some database type may contribute an instance of custom DbAdapterDetector to a <code>o.a.c.configuration.server.DefaultDbAdapterFactory.detectors</code> list:</p>
</div>
@@ -3033,7 +3033,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect4">
- <h5 id="alternative-service-implementations"><a class="anchor" href="#alternative-service-implementations"></a>Alternative Service Implementations</h5>
+ <h5 id="alternative-service-implementations"><a class="anchor" href="#alternative-service-implementations"></a>2.9.2.3. Alternative Service Implementations</h5>
<div class="paragraph">
<p>As mentioned above, custom modules are loaded by ServerRuntime after the built-in modules. So it is easy to redefine a built-in service in Cayenne by rebinding desired implementations or providers. To do that, first we need to know what those services to redefine are. While we describe some of them in the following sections, the best way to get a full list is to check the source code of the Cayenne version you are using and namely look in <code>org.apache.cayenne.configuration.s [...]
</div>
@@ -3049,9 +3049,9 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="using-custom-data-types"><a class="anchor" href="#using-custom-data-types"></a>Using custom data types</h4>
+ <h4 id="using-custom-data-types"><a class="anchor" href="#using-custom-data-types"></a>2.9.3. Using custom data types</h4>
<div class="sect4">
- <h5 id="value-object-type"><a class="anchor" href="#value-object-type"></a>Value object type</h5>
+ <h5 id="value-object-type"><a class="anchor" href="#value-object-type"></a>2.9.3.1. Value object type</h5>
<div class="paragraph">
<p><code>ValueObjectType</code> is a new and lightweight alternative to the Extended Types API described in the following section. In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when <code>ExtendedType</code> should be used: when your value object can be mapped on different JDBC types.</p>
</div>
@@ -3127,7 +3127,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect4">
- <h5 id="extended-types"><a class="anchor" href="#extended-types"></a>Extended Types</h5>
+ <h5 id="extended-types"><a class="anchor" href="#extended-types"></a>2.9.3.2. Extended Types</h5>
<div class="paragraph">
<p>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) and a very specific mapping of these types to Java Object Types, such as java.lang.String, java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from a database "primitive" value, and conversely, how to transform an object of the cust [...]
</div>
@@ -3227,27 +3227,27 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="noteworthy-built-in-services"><a class="anchor" href="#noteworthy-built-in-services"></a>Noteworthy Built-in Services</h4>
+ <h4 id="noteworthy-built-in-services"><a class="anchor" href="#noteworthy-built-in-services"></a>2.9.4. Noteworthy Built-in Services</h4>
<div class="sect4">
- <h5 id="jdbceventlogger"><a class="anchor" href="#jdbceventlogger"></a>JdbcEventLogger</h5>
+ <h5 id="jdbceventlogger"><a class="anchor" href="#jdbceventlogger"></a>2.9.4.1. JdbcEventLogger</h5>
<div class="paragraph">
<p><code>org.apache.cayenne.log.JdbcEventLogger</code> is the service that defines logging API for Cayenne internals. It provides facilities for logging queries, commits, transactions, etc. The default implementation is <code>org.apache.cayenne.log.Slf4jJdbcEventLogger</code> that performs logging via slf4j-api library. Cayenne library includes another potentially useful logger - <code>org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger</code> that produces formatted multiline SQL [...]
</div>
</div>
<div class="sect4">
- <h5 id="datasourcefactory"><a class="anchor" href="#datasourcefactory"></a>DataSourceFactory</h5>
+ <h5 id="datasourcefactory"><a class="anchor" href="#datasourcefactory"></a>2.9.4.2. DataSourceFactory</h5>
<div class="paragraph">
<p>Factory that returns <code>javax.sql.DataSource</code> object based on the configuration provided in the "nodeDescriptor".</p>
</div>
</div>
<div class="sect4">
- <h5 id="datachannelsyncfilter-and-datachannelqueryfilter"><a class="anchor" href="#datachannelsyncfilter-and-datachannelqueryfilter"></a>DataChannelSyncFilter and DataChannelQueryFilter</h5>
+ <h5 id="datachannelsyncfilter-and-datachannelqueryfilter"><a class="anchor" href="#datachannelsyncfilter-and-datachannelqueryfilter"></a>2.9.4.3. DataChannelSyncFilter and DataChannelQueryFilter</h5>
<div class="paragraph">
<p>Interfaces of filters that allow to intercept DataChannel operations. Filters allow to implement chains of custom processors around a DataChannel, that can be used for security, monitoring, business logic, providing context to lifecycle event listeners, etc.</p>
</div>
</div>
<div class="sect4">
- <h5 id="querycache"><a class="anchor" href="#querycache"></a>QueryCache</h5>
+ <h5 id="querycache"><a class="anchor" href="#querycache"></a>2.9.4.4. QueryCache</h5>
<div class="paragraph">
<p>Defines API of a cache that stores query results.</p>
</div>
@@ -3257,12 +3257,12 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect1">
- <h2 id="cayenne-framework-remote-object-persistence"><a class="anchor" href="#cayenne-framework-remote-object-persistence"></a>3. Cayenne Framework - Remote Object Persistence</h2>
+ <h2 id="rop"><a class="anchor" href="#rop"></a>3. Cayenne Framework - Remote Object Persistence</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="introduction-to-rop"><a class="anchor" href="#introduction-to-rop"></a>3.1. Introduction to ROP</h3>
<div class="sect3">
- <h4 id="what-is-rop"><a class="anchor" href="#what-is-rop"></a>What is ROP</h4>
+ <h4 id="what-is-rop"><a class="anchor" href="#what-is-rop"></a>3.1.1. What is ROP</h4>
<div class="paragraph">
<p>"Remote Object Persistence" is a low-overhead web services-based technology that provides lightweight object persistence and query functionality to 'remote' applications. In other words it provides familiar Cayenne API to applications that do not have direct access to the database. Instead such applications would access Cayenne Web Service (CWS). A single abstract data model (expressed as Cayenne XML DataMap) is used on the server and on the client, while execution logic can be p [...]
</div>
@@ -3283,7 +3283,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="main-features"><a class="anchor" href="#main-features"></a>Main Features</h4>
+ <h4 id="main-features"><a class="anchor" href="#main-features"></a>3.1.2. Main Features</h4>
<div class="ulist">
<ul>
<li> <p>Unified approach to lightweight object persistence across multiple tiers of a distributed system.</p> </li>
@@ -3304,7 +3304,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<div class="sect2">
<h3 id="rop-deployment"><a class="anchor" href="#rop-deployment"></a>3.2. ROP Deployment</h3>
<div class="sect3">
- <h4 id="server-security-note"><a class="anchor" href="#server-security-note"></a>Server Security Note</h4>
+ <h4 id="server-security-note"><a class="anchor" href="#server-security-note"></a>3.2.1. Server Security Note</h4>
<div class="paragraph">
<p>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code addressing a security concern related to "session fixation problem" by resetting the existing session ID of any request that requires BASIC authentication. If ROP service is protected with declarative security (see the ROP tutorial and the following chapters on security), this feature prevents the ROP client from attaching to its session, resulting in <code>MissingSessionExceptions</code>.</p>
</div>
@@ -3332,7 +3332,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<div class="sect2">
<h3 id="re-introduction"><a class="anchor" href="#re-introduction"></a>4.1. Introduction</h3>
<div class="sect3">
- <h4 id="db-first-flow-2"><a class="anchor" href="#db-first-flow-2"></a>"DB-first" Flow</h4>
+ <h4 id="db-first-flow-2"><a class="anchor" href="#db-first-flow-2"></a>4.1.1. "DB-first" Flow</h4>
<div class="paragraph">
<p>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 typical [...]
</div>
@@ -3352,7 +3352,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="introduction-to-cdbimport"><a class="anchor" href="#introduction-to-cdbimport"></a>Introduction to "cdbimport"</h4>
+ <h4 id="introduction-to-cdbimport"><a class="anchor" href="#introduction-to-cdbimport"></a>4.1.2. Introduction to "cdbimport"</h4>
<div class="paragraph">
<p>Here is a simple Maven configuration of "cdbimport" (for details see <a href="#mavenCdbimort">cayenne-maven-plugin</a> documentation)</p>
</div>
@@ -3400,7 +3400,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<p>The following use-cases will provide you a better understanding of how filtering works and how you could use it.</p>
</div>
<div class="sect3">
- <h4 id="process-everything-from-schemacatalog"><a class="anchor" href="#process-everything-from-schemacatalog"></a>Process everything from schema/catalog</h4>
+ <h4 id="process-everything-from-schemacatalog"><a class="anchor" href="#process-everything-from-schemacatalog"></a>4.2.1. Process everything from schema/catalog</h4>
<div class="paragraph">
<p>The simplest example of reverse engineering is processing tables from one schema of catalog and there are several options to do this. Basic syntax is described below:</p>
</div>
@@ -3457,7 +3457,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="combine-schema-and-catalog-filters"><a class="anchor" href="#combine-schema-and-catalog-filters"></a>Combine Schema and Catalog filters</h4>
+ <h4 id="combine-schema-and-catalog-filters"><a class="anchor" href="#combine-schema-and-catalog-filters"></a>4.2.2. Combine Schema and Catalog filters</h4>
<div class="paragraph">
<p>Cayenne supports combination of different schemas and catalogs, and it filters data according to your requirements. You could achieve this by the following example of reverse engineering configuration:</p>
</div>
@@ -3533,7 +3533,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="including-and-excluding-tables-columns-procedures-and-relationships"><a class="anchor" href="#including-and-excluding-tables-columns-procedures-and-relationships"></a>Including and Excluding tables, columns, procedures and relationships</h4>
+ <h4 id="including-and-excluding-tables-columns-procedures-and-relationships"><a class="anchor" href="#including-and-excluding-tables-columns-procedures-and-relationships"></a>4.2.3. Including and Excluding tables, columns, procedures and relationships</h4>
<div class="paragraph">
<p>Cayenne reverse engineering let you fine tune table, columns and stored procedures names that you need to import to your model file. In every filter you can use regexp syntax. Here is some examples of configuration for common tasks.</p>
</div>
@@ -3652,7 +3652,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="complete-filtering-example"><a class="anchor" href="#complete-filtering-example"></a>Complete filtering example</h4>
+ <h4 id="complete-filtering-example"><a class="anchor" href="#complete-filtering-example"></a>4.2.4. Complete filtering example</h4>
<div class="paragraph">
<p>Initially, let’s make a small sample. Consider the following reverse engineering configuration.</p>
</div>
@@ -3755,7 +3755,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="ant-configuration-example"><a class="anchor" href="#ant-configuration-example"></a>Ant configuration example</h4>
+ <h4 id="ant-configuration-example"><a class="anchor" href="#ant-configuration-example"></a>4.2.5. Ant configuration example</h4>
<div class="paragraph">
<p>Here is config sample for <code>Ant</code> task:</p>
</div>
@@ -3815,7 +3815,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<p>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.</p>
</div>
<div class="sect3">
- <h4 id="skip-relationships-loading"><a class="anchor" href="#skip-relationships-loading"></a>Skip Relationships Loading</h4>
+ <h4 id="skip-relationships-loading"><a class="anchor" href="#skip-relationships-loading"></a>4.3.1. Skip Relationships Loading</h4>
<div class="paragraph">
<p>You are able to skip relationships loading by the <code><skipRelationshipsLoading></code> element.</p>
</div>
@@ -3828,7 +3828,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="skip-primary-keys-loading"><a class="anchor" href="#skip-primary-keys-loading"></a>Skip Primary Keys Loading</h4>
+ <h4 id="skip-primary-keys-loading"><a class="anchor" href="#skip-primary-keys-loading"></a>4.3.2. Skip Primary Keys Loading</h4>
<div class="paragraph">
<p>Another useful Cayenne reverse engineering property is <code><skipPrimaryKeyLoading></code>. If you decide to support all relationships at the application layer and avoid their management in database, you’ll find useful to turn off primary keys synchronization at all.</p>
</div>
@@ -3841,7 +3841,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="table-types"><a class="anchor" href="#table-types"></a>Table Types</h4>
+ <h4 id="table-types"><a class="anchor" href="#table-types"></a>4.3.3. Table Types</h4>
<div class="paragraph">
<p>By default, cdbimport imports tables and views. Some databases may support other table-like objects, e.g. <code>SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS, SYNONYM</code>, etc. To control which types should be included <code><tableType></tableType></code> element is used. Some examples:</p>
</div>
@@ -3877,7 +3877,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<p>You can find reverse engineering tool in dataMap view on <strong>DbImport Tab</strong>.</p>
</div>
<div class="sect3">
- <h4 id="reverse-engineering-options"><a class="anchor" href="#reverse-engineering-options"></a>Reverse engineering options</h4>
+ <h4 id="reverse-engineering-options"><a class="anchor" href="#reverse-engineering-options"></a>4.4.1. Reverse engineering options</h4>
<div class="imageblock" style="text-align: center">
<div class="content">
<img src="images/re-modeler-reverseengineering-dialog.png" alt="re modeler reverseengineering dialog">
@@ -3911,7 +3911,7 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect3">
- <h4 id="datasource-selection"><a class="anchor" href="#datasource-selection"></a>DataSource selection</h4>
+ <h4 id="datasource-selection"><a class="anchor" href="#datasource-selection"></a>4.4.2. DataSource selection</h4>
<div class="paragraph">
<p>Then you click <code>Run Import</code> or <code>Configure Connection</code> to set DataSource. If you don’t have any DataSource yet you can create one from this menu.</p>
</div>
@@ -3931,41 +3931,35 @@ ServerRuntime runtime = ServerRuntime.builder()
</div>
</div>
<div class="sect1">
- <h2 id="cayenne-additional-modules"><a class="anchor" href="#cayenne-additional-modules"></a>5. Cayenne Additional Modules</h2>
+ <h2 id="additional-modules"><a class="anchor" href="#additional-modules"></a>5. Additional Modules</h2>
<div class="sectionbody">
<div class="sect2">
- <h3 id="ext-cache-invalidation"><a class="anchor" href="#ext-cache-invalidation"></a>5.1. Cache invalidation extension</h3>
- <div class="sect3">
- <h4 id="description"><a class="anchor" href="#description"></a>Description</h4>
- <div class="paragraph">
- <p>Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.</p>
- </div>
+ <h3 id="ext-cache-invalidation"><a class="anchor" href="#ext-cache-invalidation"></a>5.1. Cache Invalidation Extension</h3>
+ <div class="paragraph">
+ <p>Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project"><a class="anchor" href="#including-in-a-project"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-2"><a class="anchor" href="#maven-2"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-2"><a class="anchor" href="#maven-2"></a>5.1.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-cache-invalidation</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle"><a class="anchor" href="#gradle"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-cache-invalidation:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-2"><a class="anchor" href="#gradle-2"></a>5.1.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-cache-invalidation:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage"><a class="anchor" href="#usage"></a>Usage</h4>
+ <h4 id="usage"><a class="anchor" href="#usage"></a>5.1.3. Usage</h4>
<div class="paragraph">
<p>Module supports autoloading mechanism, so no other actions required to enable it. Just mark your entities with @CacheGroups annotation and you are ready to use it:</p>
</div>
@@ -4033,37 +4027,31 @@ public class MyEntity extends _MyEntity {
</div>
<div class="sect2">
<h3 id="ext-commit-log"><a class="anchor" href="#ext-commit-log"></a>5.2. Commit log extension</h3>
- <div class="sect3">
- <h4 id="description-2"><a class="anchor" href="#description-2"></a>Description</h4>
- <div class="paragraph">
- <p>The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.</p>
- </div>
+ <div class="paragraph">
+ <p>The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-2"><a class="anchor" href="#including-in-a-project-2"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-3"><a class="anchor" href="#maven-3"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-3"><a class="anchor" href="#maven-3"></a>5.2.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-commitlog</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-2"><a class="anchor" href="#gradle-2"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-commitlog:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-3"><a class="anchor" href="#gradle-3"></a>5.2.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-commitlog:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage-2"><a class="anchor" href="#usage-2"></a>Usage</h4>
+ <h4 id="usage-2"><a class="anchor" href="#usage-2"></a>5.2.3. Usage</h4>
<div class="paragraph">
<p>In order to use <code>commitlog</code> module you need to perform three steps:</p>
</div>
@@ -4119,39 +4107,33 @@ public class MyEntity extends _MyEntity {
</div>
<div class="sect2">
<h3 id="ext-crypto"><a class="anchor" href="#ext-crypto"></a>5.3. Crypto extension</h3>
- <div class="sect3">
- <h4 id="description-3"><a class="anchor" href="#description-3"></a>Description</h4>
- <div class="paragraph">
- <p>Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.</p>
- </div>
+ <div class="paragraph">
+ <p>Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-3"><a class="anchor" href="#including-in-a-project-3"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-4"><a class="anchor" href="#maven-4"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-4"><a class="anchor" href="#maven-4"></a>5.3.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-crypto</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-3"><a class="anchor" href="#gradle-3"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-crypto:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-4"><a class="anchor" href="#gradle-4"></a>5.3.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-crypto:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage-3"><a class="anchor" href="#usage-3"></a>Usage</h4>
+ <h4 id="usage-3"><a class="anchor" href="#usage-3"></a>5.3.3. Usage</h4>
<div class="sect4">
- <h5 id="setup-your-model-and-db"><a class="anchor" href="#setup-your-model-and-db"></a>Setup your model and DB</h5>
+ <h5 id="setup-your-model-and-db"><a class="anchor" href="#setup-your-model-and-db"></a>5.3.3.1. Setup your model and DB</h5>
<div class="paragraph">
<p>To use crypto module you must prepare your database to allow <code>byte[]</code> storage and properly name columns that will contain encrypted values.</p>
</div>
@@ -4195,7 +4177,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect4">
- <h5 id="setup-keystore"><a class="anchor" href="#setup-keystore"></a>Setup keystore</h5>
+ <h5 id="setup-keystore"><a class="anchor" href="#setup-keystore"></a>5.3.3.2. Setup keystore</h5>
<div class="paragraph">
<p>To perform encryption you must provide <code>KEYSTORE_URL</code> and <code>KEY_PASSWORD</code>. Currently crypto module supports only Java "jceks" KeyStore.</p>
</div>
@@ -4209,7 +4191,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect4">
- <h5 id="additional-settings"><a class="anchor" href="#additional-settings"></a>Additional settings</h5>
+ <h5 id="additional-settings"><a class="anchor" href="#additional-settings"></a>5.3.3.3. Additional settings</h5>
<div class="paragraph">
<p>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).</p>
</div>
@@ -4248,37 +4230,31 @@ public class MyEntity extends _MyEntity {
</div>
<div class="sect2">
<h3 id="ext-jcache"><a class="anchor" href="#ext-jcache"></a>5.4. JCache integration</h3>
- <div class="sect3">
- <h4 id="description-4"><a class="anchor" href="#description-4"></a>Description</h4>
- <div class="paragraph">
- <p>This module allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.</p>
- </div>
+ <div class="paragraph">
+ <p>Allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-4"><a class="anchor" href="#including-in-a-project-4"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-5"><a class="anchor" href="#maven-5"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-5"><a class="anchor" href="#maven-5"></a>5.4.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-jcache</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-4"><a class="anchor" href="#gradle-4"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-jcache:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-5"><a class="anchor" href="#gradle-5"></a>5.4.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-jcache:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage-4"><a class="anchor" href="#usage-4"></a>Usage</h4>
+ <h4 id="usage-4"><a class="anchor" href="#usage-4"></a>5.4.3. Usage</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -4317,128 +4293,113 @@ public class MyEntity extends _MyEntity {
</table>
</div>
<div class="paragraph">
- <p>You may else be interested in <a href="#ext-cache-invalidation">Cache invalidation extension</a>.</p>
+ <p>You may else be interested in <a href="#ext-cache-invalidation">Cache Invalidation Extension</a>.</p>
</div>
- <div class="sect4">
- <h5 id="ehcache-setup-example"><a class="anchor" href="#ehcache-setup-example"></a>Ehcache setup example</h5>
- <div class="paragraph">
- <p>Here is an example of using <code>ehcache</code> as cache manager.</p>
- </div>
- <div class="paragraph">
- <p>First you need to include <code>ehcache</code> dependency:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ </div>
+ <div class="sect3">
+ <h4 id="ehcache-setup-example"><a class="anchor" href="#ehcache-setup-example"></a>5.4.4. Ehcache setup example</h4>
+ <div class="paragraph">
+ <p>Here is an example of using <code>ehcache</code> as cache manager.</p>
+ </div>
+ <div class="paragraph">
+ <p>First you need to include <code>ehcache</code> dependency:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.ehcache</groupId>
<artifactId>ehcache</artifactId>
<version>{ehcache-version}</version>
</dependency></code></pre>
- </div>
</div>
- <div class="paragraph">
- <p>If you need custom configuration you can contribute configuration file to JCache module:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime.builder()
+ </div>
+ <div class="paragraph">
+ <p>If you need custom configuration you can contribute configuration file to JCache module:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime.builder()
.addModule(binder ->
JCacheModule
.contributeJCacheProviderConfig(binder, "file:/ehcache.xml"));</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>As a result you will have <code>ehcache</code> manager as your default cache manager.</p>
</div>
</div>
+ <div class="paragraph">
+ <p>As a result you will have <code>ehcache</code> manager as your default cache manager.</p>
+ </div>
</div>
</div>
<div class="sect2">
<h3 id="ext-project-compatibility"><a class="anchor" href="#ext-project-compatibility"></a>5.5. Project compatibility extension</h3>
- <div class="sect3">
- <h4 id="description-5"><a class="anchor" href="#description-5"></a>Description</h4>
- <div class="paragraph">
- <p>Since version 4.1 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.</p>
- </div>
- <div class="admonitionblock note">
- <table>
- <tbody>
- <tr>
- <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
- <td class="content"> You should prefer explicit project upgrade via Cayenne Modeler. </td>
- </tr>
- </tbody>
- </table>
- </div>
+ <div class="paragraph">
+ <p>Since version 4.1 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.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
+ <td class="content"> You should prefer explicit project upgrade via Cayenne Modeler. </td>
+ </tr>
+ </tbody>
+ </table>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-5"><a class="anchor" href="#including-in-a-project-5"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-6"><a class="anchor" href="#maven-6"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-6"><a class="anchor" href="#maven-6"></a>5.5.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-project-compatibility</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-5"><a class="anchor" href="#gradle-5"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-project-compatibility:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-6"><a class="anchor" href="#gradle-6"></a>5.5.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-project-compatibility:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage-5"><a class="anchor" href="#usage-5"></a>Usage</h4>
+ <h4 id="usage-5"><a class="anchor" href="#usage-5"></a>5.5.3. Usage</h4>
<div class="paragraph">
<p>This module doesn’t require any additional setup.</p>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="ext-velocity"><a class="anchor" href="#ext-velocity"></a>5.6. Apache Velocity extension</h3>
- <div class="sect3">
- <h4 id="description-6"><a class="anchor" href="#description-6"></a>Description</h4>
- <div class="paragraph">
- <p>This module enables usage of full featured Apache Velocity templates in <code>org.apache.cayenne.query.SQLTemplate</code> queries.</p>
- </div>
+ <h3 id="ext-velocity"><a class="anchor" href="#ext-velocity"></a>5.6. Apache Velocity Extension</h3>
+ <div class="paragraph">
+ <p>Enables usage of full featured Apache Velocity templates in <code>SQLSelect</code> / <code>SQLExec</code> queries.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-6"><a class="anchor" href="#including-in-a-project-6"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-7"><a class="anchor" href="#maven-7"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-7"><a class="anchor" href="#maven-7"></a>5.6.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-velocity</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-6"><a class="anchor" href="#gradle-6"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-velocity:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-7"><a class="anchor" href="#gradle-7"></a>5.6.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-velocity:4.1.RC2'</code></pre>
</div>
</div>
</div>
<div class="sect3">
- <h4 id="usage-6"><a class="anchor" href="#usage-6"></a>Usage</h4>
- <div class="paragraph">
- <p>This module doesn’t require any additional setup.</p>
- </div>
+ <h4 id="usage-6"><a class="anchor" href="#usage-6"></a>5.6.3. Usage</h4>
<div class="paragraph">
- <p>In addition of directives mentioned in <a href="#directives">this chapter</a>, this module enables <code>#chain</code> and <code>#chunk</code> directives.</p>
+ <p>This module doesn’t require any additional setup. In addition of directives mentioned in <a href="#directives">this chapter</a>, this module also adds <code>#chain</code> and <code>#chunk</code> directives.</p>
</div>
<div class="paragraph">
<p><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 SQ [...]
@@ -4468,97 +4429,79 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect2">
- <h3 id="cayenne-web-extension"><a class="anchor" href="#cayenne-web-extension"></a>5.7. Cayenne Web extension</h3>
- <div class="sect3">
- <h4 id="description-7"><a class="anchor" href="#description-7"></a>Description</h4>
- <div class="paragraph">
- <p>This module provides basic utilities to bootstrap Cayenne service inside web application.</p>
- </div>
+ <h3 id="ext-web"><a class="anchor" href="#ext-web"></a>5.7. Cayenne Web Extension</h3>
+ <div class="paragraph">
+ <p>Provides basic utilities to bootstrap Cayenne service inside web application.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-7"><a class="anchor" href="#including-in-a-project-7"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-8"><a class="anchor" href="#maven-8"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-8"><a class="anchor" href="#maven-8"></a>5.7.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-web</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-7"><a class="anchor" href="#gradle-7"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-web:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-8"><a class="anchor" href="#gradle-8"></a>5.7.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-web:4.1.RC2'</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="cayenne-osgi-extension"><a class="anchor" href="#cayenne-osgi-extension"></a>5.8. Cayenne OSGI extension</h3>
- <div class="sect3">
- <h4 id="description-8"><a class="anchor" href="#description-8"></a>Description</h4>
- <div class="paragraph">
- <p>This module helps to bootstrap Cayenne in OSGi environment.</p>
- </div>
+ <h3 id="ext-osgi"><a class="anchor" href="#ext-osgi"></a>5.8. Cayenne OSGI extension</h3>
+ <div class="paragraph">
+ <p>Helps to bootstrap Cayenne in OSGi environment.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-8"><a class="anchor" href="#including-in-a-project-8"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-9"><a class="anchor" href="#maven-9"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-9"><a class="anchor" href="#maven-9"></a>5.8.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-osgi</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-8"><a class="anchor" href="#gradle-8"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-osgi:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-9"><a class="anchor" href="#gradle-9"></a>5.8.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-osgi:4.1.RC2'</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="cayenne-rop-server-extension"><a class="anchor" href="#cayenne-rop-server-extension"></a>5.9. Cayenne Rop Server extension</h3>
- <div class="sect3">
- <h4 id="description-9"><a class="anchor" href="#description-9"></a>Description</h4>
- <div class="paragraph">
- <p>This module creates services for the server side of an <a href="#introduction-to-rop">ROP</a> application.</p>
- </div>
+ <h3 id="ext-rop"><a class="anchor" href="#ext-rop"></a>5.9. Cayenne ROP Server Extension</h3>
+ <div class="paragraph">
+ <p>Creates services for the server side of an <a href="#rop">ROP</a> application.</p>
</div>
<div class="sect3">
- <h4 id="including-in-a-project-9"><a class="anchor" href="#including-in-a-project-9"></a>Including in a project</h4>
- <div class="sect4">
- <h5 id="maven-10"><a class="anchor" href="#maven-10"></a>Maven</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
+ <h4 id="maven-10"><a class="anchor" href="#maven-10"></a>5.9.1. Maven</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-rop-server</artifactId>
<version>4.1.RC2</version>
</dependency></code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="gradle-9"><a class="anchor" href="#gradle-9"></a>Gradle</h5>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-rop-server:4.1.RC2'</code></pre>
- </div>
+ </div>
+ <div class="sect3">
+ <h4 id="gradle-10"><a class="anchor" href="#gradle-10"></a>5.9.2. Gradle</h4>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-rop-server:4.1.RC2'</code></pre>
</div>
</div>
</div>
@@ -4577,7 +4520,7 @@ public class MyEntity extends _MyEntity {
<p>The full plugin Maven name is <code>org.apache.cayenne.plugins:cayenne-maven-plugin</code>. It can be executed as <code>mvn cayenne:<goal></code>.</p>
</div>
<div class="sect3">
- <h4 id="cgen"><a class="anchor" href="#cgen"></a>cgen</h4>
+ <h4 id="cgen"><a class="anchor" href="#cgen"></a>6.1.1. cgen</h4>
<div class="paragraph">
<p><code>cgen</code> is a goal that generates and maintains source (.java) files of persistent objects based on a DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (which is the recommended default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and may be later customized b [...]
</div>
@@ -4753,7 +4696,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect3">
- <h4 id="mavenCdbimort"><a class="anchor" href="#mavenCdbimort"></a>cdbimport</h4>
+ <h4 id="mavenCdbimort"><a class="anchor" href="#mavenCdbimort"></a>6.1.2. cdbimport</h4>
<div class="paragraph">
<p><code>cdbimport</code> is a <code>cayenne-maven-plugin</code> goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter <a href="#db-first-flow">DB-First Flow</a></p>
</div>
@@ -4996,7 +4939,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect3">
- <h4 id="cdbgen"><a class="anchor" href="#cdbgen"></a>cdbgen</h4>
+ <h4 id="cdbgen"><a class="anchor" href="#cdbgen"></a>6.1.3. cdbgen</h4>
<div class="paragraph">
<p><code>cdbgen</code> is a <code>cayenne-maven-plugin</code> goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.</p>
</div>
@@ -5205,7 +5148,7 @@ dependencies {
</table>
</div>
<div class="sect3">
- <h4 id="cgen-2"><a class="anchor" href="#cgen-2"></a>cgen</h4>
+ <h4 id="cgen-2"><a class="anchor" href="#cgen-2"></a>6.2.1. cgen</h4>
<div class="paragraph">
<p>Cgen task generates Java classes based on your DataMap, it has same configuration parameters as in Maven Plugin version, described in <a href="#tablecgen">Table, “cgen required parameters”.</a>. If you provided default DataMap via <code>cayenne.defaultDataMap</code>, you can skip <code>cgen</code> configuration as default settings will suffice in common case.</p>
</div>
@@ -5234,7 +5177,7 @@ dependencies {
</div>
</div>
<div class="sect3">
- <h4 id="cdbimport"><a class="anchor" href="#cdbimport"></a>cdbimport</h4>
+ <h4 id="cdbimport"><a class="anchor" href="#cdbimport"></a>6.2.2. cdbimport</h4>
<div class="paragraph">
<p>This task is for creating and synchronizing your Cayenne model from database schema. Full list of parameters are same as in <a href="#cdbimportTable">Maven Plugin</a>, with the exception that Gradle version will use Groovy instead of XML. Here is example of configuration for cdbimport task:</p>
</div>
@@ -5300,7 +5243,7 @@ dependencies {
</div>
</div>
<div class="sect3">
- <h4 id="cdbgen-2"><a class="anchor" href="#cdbgen-2"></a>cdbgen</h4>
+ <h4 id="cdbgen-2"><a class="anchor" href="#cdbgen-2"></a>6.2.3. cdbgen</h4>
<div class="paragraph">
<p>Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters is same as in the <a href="#cdbgenTable">Maven plugin</a>. Here is example of how to configure default <code>cdbgen</code> task:</p>
</div>
@@ -5328,7 +5271,7 @@ dependencies {
</div>
</div>
<div class="sect3">
- <h4 id="link-tasks-to-gradle-build-lifecycle"><a class="anchor" href="#link-tasks-to-gradle-build-lifecycle"></a>Link tasks to Gradle build lifecycle</h4>
+ <h4 id="link-tasks-to-gradle-build-lifecycle"><a class="anchor" href="#link-tasks-to-gradle-build-lifecycle"></a>6.2.4. Link tasks to Gradle build lifecycle</h4>
<div class="paragraph">
<p>You can connect Cayenne tasks to the default build lifecycle. Here is short example of how to connect defaut <code>cgen</code> and <code>cdbimport</code> tasks with <code>compileJava</code> task:</p>
</div>
@@ -5367,13 +5310,13 @@ compileJava.dependsOn cgen</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="cgen-3"><a class="anchor" href="#cgen-3"></a>cgen</h4>
+ <h4 id="cgen-3"><a class="anchor" href="#cgen-3"></a>6.3.1. cgen</h4>
</div>
<div class="sect3">
- <h4 id="cdbgen-3"><a class="anchor" href="#cdbgen-3"></a>cdbgen</h4>
+ <h4 id="cdbgen-3"><a class="anchor" href="#cdbgen-3"></a>6.3.2. cdbgen</h4>
</div>
<div class="sect3">
- <h4 id="cdbimport-2"><a class="anchor" href="#cdbimport-2"></a>cdbimport</h4>
+ <h4 id="cdbimport-2"><a class="anchor" href="#cdbimport-2"></a>6.3.3. cdbimport</h4>
<div class="paragraph">
<p>This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described above. It has exactly the same properties. Here is a usage example:</p>
</div>
diff --git a/docs/4.1/getting-started-db-first/index.html b/docs/4.1/getting-started-db-first/index.html
index 020169d..ec2a1b3 100644
--- a/docs/4.1/getting-started-db-first/index.html
+++ b/docs/4.1/getting-started-db-first/index.html
@@ -189,19 +189,19 @@
<p>This chapter lists the recommended software used in the tutorial.</p>
</div>
<div class="sect3">
- <h4 id="java"><a class="anchor" href="#java"></a>Java</h4>
+ <h4 id="java"><a class="anchor" href="#java"></a>1.1.1. Java</h4>
<div class="paragraph">
<p>Cayenne 4.1 requires JDK 1.8 or newer.</p>
</div>
</div>
<div class="sect3">
- <h4 id="intellij-idea-ide"><a class="anchor" href="#intellij-idea-ide"></a>IntelliJ IDEA IDE</h4>
+ <h4 id="intellij-idea-ide"><a class="anchor" href="#intellij-idea-ide"></a>1.1.2. IntelliJ IDEA IDE</h4>
<div class="paragraph">
<p>Download and install the free IntelliJ IDEA Community Edition IDE. This tutorial uses version 2017.1, but any recent IntelliJ IDEA version and edition will do.</p>
</div>
</div>
<div class="sect3">
- <h4 id="maven"><a class="anchor" href="#maven"></a>Maven</h4>
+ <h4 id="maven"><a class="anchor" href="#maven"></a>1.1.3. Maven</h4>
<div class="paragraph">
<p>Two Maven plugins are used:</p>
</div>
@@ -213,7 +213,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="mysql"><a class="anchor" href="#mysql"></a>MySQL</h4>
+ <h4 id="mysql"><a class="anchor" href="#mysql"></a>1.1.4. MySQL</h4>
<div class="paragraph">
<p>MySQL database server is used for demonstrating Cayenne’s ability to read the DB schema and to build/update the Cayenne model from it.</p>
</div>
@@ -246,7 +246,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
<p>The goal of this chapter is to create a new Java project in IntelliJ IDEA and to setup Maven Cayenne plugin</p>
</div>
<div class="sect3">
- <h4 id="create-a-new-project-in-intellij-idea"><a class="anchor" href="#create-a-new-project-in-intellij-idea"></a>Create a new Project in IntelliJ IDEA</h4>
+ <h4 id="create-a-new-project-in-intellij-idea"><a class="anchor" href="#create-a-new-project-in-intellij-idea"></a>1.2.1. Create a new Project in IntelliJ IDEA</h4>
<div class="paragraph">
<p>In IntelliJ IDEA select <code>File > New > Project…</code> and then select "Maven" and click "Next". In the dialog shown on the screenshot below, fill the "Group Id" and "Artifact Id" fields and click "Next".</p>
</div>
@@ -260,7 +260,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
</div>
</div>
<div class="sect3">
- <h4 id="plugin-setup"><a class="anchor" href="#plugin-setup"></a>Plugin setup</h4>
+ <h4 id="plugin-setup"><a class="anchor" href="#plugin-setup"></a>1.2.2. Plugin setup</h4>
<div class="paragraph">
<p>Next step is setting up Cayenne plugin in <code>pom.xml</code> file. For the convenience let’s define Cayenne version that we will use across project file:</p>
</div>
@@ -300,7 +300,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
<p>Now we have everything ready and can proceed to importing Cayenne model from our Mysql database</p>
</div>
<div class="sect3">
- <h4 id="configuring-plugin"><a class="anchor" href="#configuring-plugin"></a>Configuring plugin</h4>
+ <h4 id="configuring-plugin"><a class="anchor" href="#configuring-plugin"></a>2.1.1. Configuring plugin</h4>
<div class="paragraph">
<p>To let Cayenne plugin do its job we must tell it what to import and where it should get data. So let’s begin, here is sample settings for the data source:</p>
</div>
@@ -363,7 +363,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
</div>
</div>
<div class="sect3">
- <h4 id="running-plugin"><a class="anchor" href="#running-plugin"></a>Running plugin</h4>
+ <h4 id="running-plugin"><a class="anchor" href="#running-plugin"></a>2.1.2. Running plugin</h4>
<div class="paragraph">
<p>Finally we can run db import, it is as easy as just running this command in terminal:</p>
</div>
@@ -425,7 +425,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
</div>
</div>
<div class="sect3">
- <h4 id="setup-modeler-maven-plugin"><a class="anchor" href="#setup-modeler-maven-plugin"></a>Setup Modeler Maven plugin</h4>
+ <h4 id="setup-modeler-maven-plugin"><a class="anchor" href="#setup-modeler-maven-plugin"></a>2.1.3. Setup Modeler Maven plugin</h4>
<div class="paragraph">
<p>Cayenne Modeler can be helpful in case you want to make some customizations to your model, though it’s usage optional.</p>
</div>
@@ -465,7 +465,7 @@ ALTER TABLE painting ADD FOREIGN KEY (GALLERY_ID) REFERENCES gallery (ID) ON DEL
<p>We now have everything we need, let’s try some more features of plugin.</p>
</div>
<div class="sect3">
- <h4 id="update-ddl"><a class="anchor" href="#update-ddl"></a>Update DDL</h4>
+ <h4 id="update-ddl"><a class="anchor" href="#update-ddl"></a>3.1.1. Update DDL</h4>
<div class="paragraph">
<p>To show next feature let’s imagine that over some time our database schema has evolved and we need to synchronize it with our model, no problem we can simply run <code>cdbimport</code> again and all changes will be loaded to model. We use following SQL script to alter our demo database:</p>
</div>
@@ -478,7 +478,7 @@ ALTER TABLE cayenne_demo.painting_info ADD FOREIGN KEY (PAINTING_ID) REFERENCES
</div>
</div>
<div class="sect3">
- <h4 id="run-cdbimport"><a class="anchor" href="#run-cdbimport"></a>Run cdbimport</h4>
+ <h4 id="run-cdbimport"><a class="anchor" href="#run-cdbimport"></a>3.1.2. Run cdbimport</h4>
<div class="paragraph">
<p>Now we can simply run again</p>
</div>
@@ -530,7 +530,7 @@ ALTER TABLE cayenne_demo.painting_info ADD FOREIGN KEY (PAINTING_ID) REFERENCES
</div>
</div>
<div class="sect3">
- <h4 id="customizing-model"><a class="anchor" href="#customizing-model"></a>Customizing Model</h4>
+ <h4 id="customizing-model"><a class="anchor" href="#customizing-model"></a>3.1.3. Customizing Model</h4>
<div class="paragraph">
<p>There is often a need to customize model to better fit it to your application requirements, such customization can be simple removal of toMany part of a relationship between two objects. Let’s do it, in a Modeler just select and remove relationship <code>paintings</code> in Artist object:</p>
</div>
@@ -574,7 +574,7 @@ ALTER TABLE cayenne_demo.painting_info ADD FOREIGN KEY (PAINTING_ID) REFERENCES
<p>Final part of our tutorial is about fine-tuning what you load from DB into your model.</p>
</div>
<div class="sect3">
- <h4 id="update-schema"><a class="anchor" href="#update-schema"></a>Update schema</h4>
+ <h4 id="update-schema"><a class="anchor" href="#update-schema"></a>3.2.1. Update schema</h4>
<div class="paragraph">
<p>Let’s add some information to our database, that we don’t need in our model:</p>
</div>
@@ -588,7 +588,7 @@ ALTER TABLE cayenne_demo.painting ADD COLUMN __service_column INT;</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="configure-filtering"><a class="anchor" href="#configure-filtering"></a>Configure filtering</h4>
+ <h4 id="configure-filtering"><a class="anchor" href="#configure-filtering"></a>3.2.2. Configure filtering</h4>
<div class="paragraph">
<p>Now we need to tell <code>cdbimport</code> what we don’t need in our model, for that we’ll just add following into <code><configuration></code> section:</p>
</div>
@@ -707,7 +707,7 @@ ALTER TABLE cayenne_demo.painting ADD COLUMN __service_column INT;</code></pre>
<p>In this section we’ll write a simple main class to run our application, and get a brief introduction to Cayenne <code>ObjectContext</code>.</p>
</div>
<div class="sect3">
- <h4 id="creating-the-main-class"><a class="anchor" href="#creating-the-main-class"></a>Creating the Main Class</h4>
+ <h4 id="creating-the-main-class"><a class="anchor" href="#creating-the-main-class"></a>4.2.1. Creating the Main Class</h4>
<div class="ulist">
<ul>
<li> <p>In IDEA create a new class called <code>Main</code> in the <code>org.apache.cayenne.tutorial</code> package.</p> </li>
@@ -763,7 +763,7 @@ context.commitChanges();</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="running-application"><a class="anchor" href="#running-application"></a>Running Application</h4>
+ <h4 id="running-application"><a class="anchor" href="#running-application"></a>4.2.2. Running Application</h4>
<div class="paragraph">
<p>Let’s check what happens when you run the application. But before we do that we need to add another dependencies to the <code>pom.xml</code> - MySQL Jdbc driver and simple logger. The following piece of XML needs to be added to the <code><dependencies>…</dependencies></code> section, where we already have Cayenne jars:</p>
</div>
diff --git a/docs/4.1/getting-started-guide/index.html b/docs/4.1/getting-started-guide/index.html
index 0ea73b9..0ddd802 100644
--- a/docs/4.1/getting-started-guide/index.html
+++ b/docs/4.1/getting-started-guide/index.html
@@ -208,7 +208,7 @@
<p>The goal of this chapter is to create a new Java project in IntelliJ IDEA containing a basic Cayenne mapping. It presents an introduction to CayenneModeler GUI tool, showing how to create the initial mapping objects: <code>DataDomain</code>, <code>DataNode</code>, <code>DataMap</code>.</p>
</div>
<div class="sect3">
- <h4 id="create-a-new-project-in-intellij-idea"><a class="anchor" href="#create-a-new-project-in-intellij-idea"></a>Create a new Project in IntelliJ IDEA</h4>
+ <h4 id="create-a-new-project-in-intellij-idea"><a class="anchor" href="#create-a-new-project-in-intellij-idea"></a>2.1.1. Create a new Project in IntelliJ IDEA</h4>
<div class="paragraph">
<p>In IntelliJ IDEA select <code>File > New > Project..</code> and then select <code>Maven</code> and click <code>Next</code>. In the dialog shown on the screenshot below, fill the <code>Group Id</code> and <code>Artifact Id</code> fields and click <code>Next</code>.</p>
</div>
@@ -222,7 +222,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="download-and-start-cayennemodeler"><a class="anchor" href="#download-and-start-cayennemodeler"></a>Download and Start CayenneModeler</h4>
+ <h4 id="download-and-start-cayennemodeler"><a class="anchor" href="#download-and-start-cayennemodeler"></a>2.1.2. Download and Start CayenneModeler</h4>
<div class="paragraph">
<p>Although later in this tutorial we’ll be using Maven to include Cayenne runtime jars in the project, you’ll still need to download Cayenne to get access to the CayenneModeler tool.</p>
</div>
@@ -246,13 +246,13 @@
</div>
</div>
<div class="sect3">
- <h4 id="create-a-new-mapping-project-in-cayennemodeler"><a class="anchor" href="#create-a-new-mapping-project-in-cayennemodeler"></a>Create a New Mapping Project in CayenneModeler</h4>
+ <h4 id="create-a-new-mapping-project-in-cayennemodeler"><a class="anchor" href="#create-a-new-mapping-project-in-cayennemodeler"></a>2.1.3. Create a New Mapping Project in CayenneModeler</h4>
<div class="paragraph">
<p>Click on the <code>New Project</code> button on Welcome screen. A new mapping project will appear that contains a single <strong>DataDomain</strong>. The meaning of a DataDomain is explained elsewhere in the User Guide. For now it is sufficient to understand that DataDomain is the root of your mapping project.</p>
</div>
</div>
<div class="sect3">
- <h4 id="create-a-datanode"><a class="anchor" href="#create-a-datanode"></a>Create a DataNode</h4>
+ <h4 id="create-a-datanode"><a class="anchor" href="#create-a-datanode"></a>2.1.4. Create a DataNode</h4>
<div class="paragraph">
<p>The next project object you will create is a <strong>DataNode</strong>. DataNode is a descriptor of a single database your application will connect to. Cayenne mapping project can use more than one database, but for now, we’ll only use one. With "project" selected on the left, click on <code>Create DataNode</code> button <span class="image"><img src="images/icon-node.png" alt="icon node"></span> on the toolbar (or select <code>Project > Create DataNode</code> from the menu).</p>
</div>
@@ -285,7 +285,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="create-a-datamap"><a class="anchor" href="#create-a-datamap"></a>Create a DataMap</h4>
+ <h4 id="create-a-datamap"><a class="anchor" href="#create-a-datamap"></a>2.1.5. Create a DataMap</h4>
<div class="paragraph">
<p>Now you will create a <strong>DataMap</strong>. DataMap is an object that holds all the mapping information. To create it, click on "Create DataMap" button <span class="image"><img src="images/icon-datamap.png" alt="icon datamap"></span> (or select a corresponding menu item). Note that the newly created DataMap is automatically linked to the DataNode that you created in the previous step. If there is more than one DataNode, you may need to link a DataMap to the correct node manua [...]
</div>
@@ -299,7 +299,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="save-the-project"><a class="anchor" href="#save-the-project"></a>Save the Project</h4>
+ <h4 id="save-the-project"><a class="anchor" href="#save-the-project"></a>2.1.6. Save the Project</h4>
<div class="imageblock" style="float: right">
<div class="content">
<img src="images/idea-xmlfiles.png" alt="idea xmlfiles">
@@ -334,7 +334,7 @@
</table>
</div>
<div class="sect3">
- <h4 id="mapping-database-tables-and-columns"><a class="anchor" href="#mapping-database-tables-and-columns"></a>Mapping Database Tables and Columns</h4>
+ <h4 id="mapping-database-tables-and-columns"><a class="anchor" href="#mapping-database-tables-and-columns"></a>2.2.1. Mapping Database Tables and Columns</h4>
<div class="paragraph">
<p>Lets go back to CayenneModeler where we have the newly created project open and start by adding the ARTIST table. Database tables are called <strong>DbEntities</strong> in Cayenne mapping (those can be actual tables or database views).</p>
</div>
@@ -351,7 +351,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="mapping-database-relationships"><a class="anchor" href="#mapping-database-relationships"></a>Mapping Database Relationships</h4>
+ <h4 id="mapping-database-relationships"><a class="anchor" href="#mapping-database-relationships"></a>2.2.2. Mapping Database Relationships</h4>
<div class="paragraph">
<p>Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables. Start by creating a one-to-many ARTIST/PAINTING relationship:</p>
</div>
@@ -381,7 +381,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="mapping-java-classes"><a class="anchor" href="#mapping-java-classes"></a>Mapping Java Classes</h4>
+ <h4 id="mapping-java-classes"><a class="anchor" href="#mapping-java-classes"></a>2.2.3. Mapping Java Classes</h4>
<div class="paragraph">
<p>Now that the database schema mapping is complete, CayenneModeler can create mappings of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present there is no way to do it for the entire DataMap in one click, so we’ll do it for each table individually.</p>
</div>
@@ -412,7 +412,7 @@
<p>Here we’ll generate the Java classes from the model that was created in the previous section. CayenneModeler can be used to also generate the database schema, but since we specified “CreateIfNoSchemaStrategy” earlier when we created a DataNode, we’ll skip the database schema step. Still be aware that you can do it if you need to via "Tools > Create Database Schema".</p>
</div>
<div class="sect3">
- <h4 id="creating-java-classes-2"><a class="anchor" href="#creating-java-classes-2"></a>Creating Java Classes</h4>
+ <h4 id="creating-java-classes-2"><a class="anchor" href="#creating-java-classes-2"></a>2.3.1. Creating Java Classes</h4>
<div class="ulist">
<ul>
<li> <p>Select "Tools > Generate Classes" menu.</p> </li>
@@ -509,7 +509,7 @@
<p>In this section we’ll write a simple main class to run our application, and get a brief introduction to Cayenne ObjectContext.</p>
</div>
<div class="sect3">
- <h4 id="creating-the-main-class"><a class="anchor" href="#creating-the-main-class"></a>Creating the Main Class</h4>
+ <h4 id="creating-the-main-class"><a class="anchor" href="#creating-the-main-class"></a>3.1.1. Creating the Main Class</h4>
<div class="ulist">
<ul>
<li> <p>In IDEA create a new class called “Main” in the “org.example.cayenne” package.</p> </li>
@@ -555,7 +555,7 @@ public class Main {
</div>
</div>
<div class="sect3">
- <h4 id="running-application"><a class="anchor" href="#running-application"></a>Running Application</h4>
+ <h4 id="running-application"><a class="anchor" href="#running-application"></a>3.1.2. Running Application</h4>
<div class="paragraph">
<p>Let’s check what happens when you run the application. But before we do that we need to add another dependency to the <code>pom.xml</code> - Apache Derby, our embedded database engine. The following piece of XML needs to be added to the <code><dependencies>…</dependencies></code> section, where we already have Cayenne jars:</p>
</div>
@@ -591,7 +591,7 @@ INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</
</div>
</div>
<div class="sect3">
- <h4 id="how-to-configure-cayenne-logging"><a class="anchor" href="#how-to-configure-cayenne-logging"></a>How to Configure Cayenne Logging</h4>
+ <h4 id="how-to-configure-cayenne-logging"><a class="anchor" href="#how-to-configure-cayenne-logging"></a>3.1.3. How to Configure Cayenne Logging</h4>
<div class="paragraph">
<p>Follow the instructions in the logging chapter to tweak verbosity of the logging output.</p>
</div>
@@ -603,7 +603,7 @@ INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</
<p>In this chapter we’ll learn about persistent objects, how to customize them and how to create and save them in DB.</p>
</div>
<div class="sect3">
- <h4 id="inspecting-and-customizing-persistent-objects"><a class="anchor" href="#inspecting-and-customizing-persistent-objects"></a>Inspecting and Customizing Persistent Objects</h4>
+ <h4 id="inspecting-and-customizing-persistent-objects"><a class="anchor" href="#inspecting-and-customizing-persistent-objects"></a>3.2.1. Inspecting and Customizing Persistent Objects</h4>
<div class="paragraph">
<p>Persistent classes in Cayenne implement a DataObject interface. If you inspect any of the classes generated earlier in this tutorial (e.g. <code>org.example.cayenne.persistent.Artist</code>), you’ll see that it extends a class with the name that starts with underscore (<code>org.example.cayenne.persistent.auto._Artist</code>), which in turn extends from <code>org.apache.cayenne.CayenneDataObject</code>. Splitting each persistent class into user-customizable subclass (<code>Xyz</c [...]
</div>
@@ -642,7 +642,7 @@ INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</
</div>
</div>
<div class="sect3">
- <h4 id="create-new-objects"><a class="anchor" href="#create-new-objects"></a>Create New Objects</h4>
+ <h4 id="create-new-objects"><a class="anchor" href="#create-new-objects"></a>3.2.2. Create New Objects</h4>
<div class="paragraph">
<p>Now we’ll create a bunch of objects and save them to the database. An object is created and registered with <code>ObjectContext</code> using “newObject” method. Objects <strong>must</strong> be registered with <code>DataContext</code> to be persisted and to allow setting relationships with other objects. Add this code to the "main" method of the Main class:</p>
</div>
@@ -732,7 +732,7 @@ INFO: +++ transaction committed.</pre>
<p>This chapter shows how to select objects from the database using <code>ObjectSelect</code> query.</p>
</div>
<div class="sect3">
- <h4 id="introducing-objectselect"><a class="anchor" href="#introducing-objectselect"></a>Introducing ObjectSelect</h4>
+ <h4 id="introducing-objectselect"><a class="anchor" href="#introducing-objectselect"></a>3.3.1. Introducing ObjectSelect</h4>
<div class="paragraph">
<p>It was shown before how to persist new objects. Cayenne queries are used to access already saved objects. The primary query type used for selecting objects is <code>ObjectSelect</code>. It can be mapped in CayenneModeler or created via the API. We’ll use the latter approach in this section. We don’t have too much data in the database yet, but we can still demonstrate the main principles below.</p>
</div>
@@ -797,7 +797,7 @@ INFO: === returned 2 rows. - took 25 ms.</pre>
<p>This chapter explains how to model relationship delete rules and how to delete individual objects as well as sets of objects. Also demonstrated the use of Cayenne class to run a query.</p>
</div>
<div class="sect3">
- <h4 id="setting-up-delete-rules"><a class="anchor" href="#setting-up-delete-rules"></a>Setting Up Delete Rules</h4>
+ <h4 id="setting-up-delete-rules"><a class="anchor" href="#setting-up-delete-rules"></a>3.4.1. Setting Up Delete Rules</h4>
<div class="paragraph">
<p>Before we discuss the API for object deletion, lets go back to CayenneModeler and set up some delete rules. Doing this is optional but will simplify correct handling of the objects related to deleted objects. In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for the "paintings" relationship delete rule:</p>
</div>
@@ -820,7 +820,7 @@ INFO: === returned 2 rows. - took 25 ms.</pre>
</div>
</div>
<div class="sect3">
- <h4 id="deleting-objects-2"><a class="anchor" href="#deleting-objects-2"></a>Deleting Objects</h4>
+ <h4 id="deleting-objects-2"><a class="anchor" href="#deleting-objects-2"></a>3.4.2. Deleting Objects</h4>
<div class="paragraph">
<p>While deleting objects is possible via SQL, qualifying a delete on one or more IDs, a more common way in Cayenne (or ORM in general) is to get a hold of the object first, and then delete it via the context. Let’s use utility class Cayenne to find an artist:</p>
</div>
@@ -1052,7 +1052,7 @@ INFO: +++ transaction committed.</pre>
</div>
</div>
<div class="sect3">
- <h4 id="running-web-application"><a class="anchor" href="#running-web-application"></a>Running Web Application</h4>
+ <h4 id="running-web-application"><a class="anchor" href="#running-web-application"></a>4.1.1. Running Web Application</h4>
<div class="paragraph">
<p>We need to add cayenne-web module and javax servlet-api for our application.</p>
</div>
diff --git a/docs/4.1/getting-started-rop/index.html b/docs/4.1/getting-started-rop/index.html
index f0fefd1..6363883 100644
--- a/docs/4.1/getting-started-rop/index.html
+++ b/docs/4.1/getting-started-rop/index.html
@@ -197,7 +197,7 @@
<div class="sect2">
<h3 id="starting-client-project"><a class="anchor" href="#starting-client-project"></a>2.1. Starting Client Project</h3>
<div class="sect3">
- <h4 id="create-an-rop-client-project-in-eclipse"><a class="anchor" href="#create-an-rop-client-project-in-eclipse"></a>Create an ROP Client Project in Eclipse</h4>
+ <h4 id="create-an-rop-client-project-in-eclipse"><a class="anchor" href="#create-an-rop-client-project-in-eclipse"></a>2.1.1. Create an ROP Client Project in Eclipse</h4>
<div class="paragraph">
<p>Creation of a new Eclipse project has been discussed in some details in "Getting Started with Cayenne" guide, so we will omit the screenshots for the common parts.</p>
</div>
@@ -209,7 +209,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="create-client-java-classes"><a class="anchor" href="#create-client-java-classes"></a>Create Client Java Classes</h4>
+ <h4 id="create-client-java-classes"><a class="anchor" href="#create-client-java-classes"></a>2.1.2. Create Client Java Classes</h4>
<div class="paragraph">
<p>The client doesn’t need the XML ORM mapping, as it is loaded from the server. However it needs the client-side Java classes. Let’s generate them from the existing mapping:</p>
</div>
@@ -288,7 +288,7 @@
<div class="sect2">
<h3 id="setting-up-hessian-web-service"><a class="anchor" href="#setting-up-hessian-web-service"></a>2.2. Setting up Hessian Web Service</h3>
<div class="sect3">
- <h4 id="setting-up-dependencies"><a class="anchor" href="#setting-up-dependencies"></a>Setting up Dependencies</h4>
+ <h4 id="setting-up-dependencies"><a class="anchor" href="#setting-up-dependencies"></a>2.2.1. Setting up Dependencies</h4>
<div class="paragraph">
<p>Now lets get back to the "tutorial" project that contains a web application and set up dependencies. Let’s add <code>resin-hessian.jar</code> (and the caucho repo declaration) and <code>cayenne-rop-server</code> to the <code>pom.xml</code></p>
</div>
@@ -351,13 +351,13 @@
</div>
</div>
<div class="sect3">
- <h4 id="client-classes-on-the-server"><a class="anchor" href="#client-classes-on-the-server"></a>Client Classes on the Server</h4>
+ <h4 id="client-classes-on-the-server"><a class="anchor" href="#client-classes-on-the-server"></a>2.2.2. Client Classes on the Server</h4>
<div class="paragraph">
<p>Since ROP web service requires both server and client persistent classes, we need to generate a second copy of the client classes inside the server project. This is a minor inconvenience that will hopefully go away in the future versions of Cayenne. Don’t forget to refresh the project in Eclipse after class generation is done.</p>
</div>
</div>
<div class="sect3">
- <h4 id="configuring-web-xml"><a class="anchor" href="#configuring-web-xml"></a>Configuring web.xml</h4>
+ <h4 id="configuring-web-xml"><a class="anchor" href="#configuring-web-xml"></a>2.2.3. Configuring web.xml</h4>
<div class="paragraph">
<p>Cayenne web service is declared in the web.xml. It is implemented as a servlet <code>org.apache.cayenne.rop.ROPServlet</code>. Open <code>tutorial/src/main/webapp/WEB-INF/web.xml</code> in Eclipse and add a service declaration:</p>
</div>
@@ -399,7 +399,7 @@
</div>
</div>
<div class="sect3">
- <h4 id="running-rop-server"><a class="anchor" href="#running-rop-server"></a>Running ROP Server</h4>
+ <h4 id="running-rop-server"><a class="anchor" href="#running-rop-server"></a>2.2.4. Running ROP Server</h4>
<div class="paragraph">
<p>Use previosly created Eclipse Jetty run configuration available via "Run > Run Configurations…" (or create a new one if none exists yet). You should see output in the Eclipse console similar to the following:</p>
</div>
@@ -432,7 +432,7 @@ INFO: Created connection pool: jdbc:derby:memory:testdb;create=true
<div class="sect2">
<h3 id="porting-existing-code-to-connect-to-a-web-service-instead-of-a-database"><a class="anchor" href="#porting-existing-code-to-connect-to-a-web-service-instead-of-a-database"></a>2.3. Porting Existing Code to Connect to a Web Service Instead of a Database</h3>
<div class="sect3">
- <h4 id="starting-command-line-client"><a class="anchor" href="#starting-command-line-client"></a>Starting Command Line Client</h4>
+ <h4 id="starting-command-line-client"><a class="anchor" href="#starting-command-line-client"></a>2.3.1. Starting Command Line Client</h4>
<div class="paragraph">
<p>One of the benefits of ROP is that the client code is no different from the server code - it uses the same ObjectContext interface for access, same query and commit API. So the code below will be similar to the code presented in the first Cayenne Getting Started Guide, although with a few ROP-specific parts required to bootstrap the ObjectContext.</p>
</div>
@@ -613,7 +613,7 @@ INFO: +++ transaction committed.</pre>
<p>You probably don’t want everybody in the world to connect to your service and access (and update!) arbitrary data in the database. The first step in securing Cayenne service is implementing client authentication. The easiest way to do it is to delegate the authentication task to the web container that is running the service. HessianConnection used in the previous chapter supports BASIC authentication on the client side, so we’ll demonstrate how to set it up here.</p>
</div>
<div class="sect3">
- <h4 id="securing-rop-server-application"><a class="anchor" href="#securing-rop-server-application"></a>Securing ROP Server Application</h4>
+ <h4 id="securing-rop-server-application"><a class="anchor" href="#securing-rop-server-application"></a>2.4.1. Securing ROP Server Application</h4>
<div class="paragraph">
<p>Open web.xml file in the server project and setup security constraints with BASIC authentication for the ROP service:</p>
</div>
@@ -641,7 +641,7 @@ INFO: +++ transaction committed.</pre>
</div>
</div>
<div class="sect3">
- <h4 id="configuring-jetty-for-basic-authentication"><a class="anchor" href="#configuring-jetty-for-basic-authentication"></a>Configuring Jetty for BASIC Authentication</h4>
+ <h4 id="configuring-jetty-for-basic-authentication"><a class="anchor" href="#configuring-jetty-for-basic-authentication"></a>2.4.2. Configuring Jetty for BASIC Authentication</h4>
<div class="admonitionblock note">
<table>
<tbody>
@@ -688,7 +688,7 @@ INFO: +++ transaction committed.</pre>
</div>
</div>
<div class="sect3">
- <h4 id="running-client-with-basic-authentication"><a class="anchor" href="#running-client-with-basic-authentication"></a>Running Client with Basic Authentication</h4>
+ <h4 id="running-client-with-basic-authentication"><a class="anchor" href="#running-client-with-basic-authentication"></a>2.4.3. Running Client with Basic Authentication</h4>
<div class="paragraph">
<p>If you run the client without any changes, you’ll get the following error:</p>
</div>