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 <[email protected]>
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>
