You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2019/11/06 09:15:22 UTC
[cayenne-website] branch master updated: refreshing 4.1 docs with
the latest edits
This is an automated email from the ASF dual-hosted git repository.
aadamchik pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne-website.git
The following commit(s) were added to refs/heads/master by this push:
new d260898 refreshing 4.1 docs with the latest edits
d260898 is described below
commit d260898a7a8e06edec096b2e9a8a65212f6dffd1
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Wed Nov 6 12:15:16 2019 +0300
refreshing 4.1 docs with the latest edits
---
src/main/site/content/docs/4.1/cayenne-guide.html | 2742 ++++++++++----------
.../site/content/docs/4.1/cayenne-guide.toc.html | 15 +-
2 files changed, 1354 insertions(+), 1403 deletions(-)
diff --git a/src/main/site/content/docs/4.1/cayenne-guide.html b/src/main/site/content/docs/4.1/cayenne-guide.html
index 9f4ff53..833dcde 100644
--- a/src/main/site/content/docs/4.1/cayenne-guide.html
+++ b/src/main/site/content/docs/4.1/cayenne-guide.html
@@ -260,7 +260,7 @@ total 24
</div>
</div>
<div class="sect2">
- <h3 id="cayennemodeler-application"><a class="anchor" href="#cayennemodeler-application"></a>1.3. CayenneModeler Application</h3>
+ <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>
<div class="paragraph">
@@ -354,1240 +354,387 @@ 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="jar-files"><a class="anchor" href="#jar-files"></a>Jar Files</h4>
+ <h4 id="maven"><a class="anchor" href="#maven"></a>Maven</h4>
<div class="paragraph">
- <p>This is an overview of Cayenne jars that is agnostic of the build tool used. The following are the important libraries:</p>
+ <p>To add Cayenne to your Maven project, include <code>cayenne-server</code> in your POM:</p>
</div>
- <div class="ulist">
- <ul>
- <li> <p><code>cayenne-di-4.1.RC2.jar</code> - Cayenne dependency injection (DI) container library. All applications will require this file.</p> </li>
- <li> <p><code>cayenne-server-4.1.RC2.jar</code> - contains main Cayenne runtime (adapters, DB access classes, etc.). Most applications will require this file.</p> </li>
- <li> <p><code>cayenne-client-4.1.RC2.jar</code> - a client-side runtime for <a href="#introduction-to-rop">ROP applications</a></p> </li>
- <li> <p>Other cayenne-* jars - various Cayenne tools extensions.</p> </li>
- </ul>
+ <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-server</artifactId>
+ <version>4.1.RC2</version>
+</dependency></code></pre>
+ </div>
</div>
</div>
<div class="sect3">
- <h4 id="dependencies"><a class="anchor" href="#dependencies"></a>Dependencies</h4>
+ <h4 id="gradle-projects"><a class="anchor" href="#gradle-projects"></a>Gradle Projects</h4>
<div class="paragraph">
- <p>With modern build tools like Maven and Gradle, you should not worry about tracking dependencies. If you have one of those, you can skip this section and go straight to the Maven section below. However if your environment requires manual dependency resolution (like Ant), the distribution provides all of Cayenne jars plus a minimal set of third-party dependencies to get you started in a default configuration. Check lib and <code>lib/third-party</code> folders for those.</p>
+ <p>To add Cayenne to your Maven project, include <code>cayenne-server</code> module:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-server:4.1.RC2'</code></pre>
+ </div>
</div>
+ </div>
+ <div class="sect3">
+ <h4 id="ant-etc"><a class="anchor" href="#ant-etc"></a>Ant, etc.</h4>
<div class="paragraph">
- <p>Dependencies for non-standard configurations will need to be figured out by the users on their own. Check <code>pom.xml</code> files of the corresponding Cayenne modules in one of the searchable Maven archives out there to get an idea of those dependencies (e.g. <a href="http://search.maven.org" class="bare">http://search.maven.org</a>).</p>
+ <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>
</div>
+ </div>
+ <div class="sect2">
+ <h3 id="starting-cayenne"><a class="anchor" href="#starting-cayenne"></a>2.2. Starting Cayenne</h3>
<div class="sect3">
- <h4 id="maven-projects"><a class="anchor" href="#maven-projects"></a>Maven Projects</h4>
+ <h4 id="starting-and-stopping-serverruntime"><a class="anchor" href="#starting-and-stopping-serverruntime"></a>Starting and Stopping ServerRuntime</h4>
<div class="paragraph">
- <p>If you are using Maven, you won’t have to deal with figuring out the dependencies. You can simply include cayenne-server artifact in your POM:</p>
+ <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>
<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-server</artifactId>
- <version>4.1.RC2</version>
-</dependency></code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .build();</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project tasks, such as synching generated Java classes with the mapping, described in the following subsection. The full plugin name is <code>org.apache.cayenne.plugins:cayenne-maven-plugin</code>.</p>
+ <p>The parameter you pass to the builder is a location of the main project file. Location is a '/'-separated path (same path separator is used on UNIX and Windows) that is resolved relative to the application classpath. The project file can be placed in the root package or in a subpackage (e.g. in the code above it is in "com/example" subpackage).</p>
</div>
- <div class="sect4">
- <h5 id="cgen"><a class="anchor" href="#cgen"></a>cgen</h5>
- <div class="paragraph">
- <p><code>cgen</code> is a <code>cayenne-maven-plugin</code> 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 overwr [...]
+ <div class="paragraph">
+ <p>ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the container are discussed in <a href="#customizing-cayenne-runtime">Customizing Cayenne Runtime</a> chapter. Here we’ll just show an example of how [...]
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">Module extensions = binder ->
+ ServerModule.contributeProperties(binder)
+ .put(Constants.SERVER_EXTERNAL_TX_PROPERTY, "true");
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .addModule(extensions)
+ .build();</code></pre>
</div>
- <div class="paragraph">
- <p>By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.</p>
- </div>
- <table id="tablecgen" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 3. cgen required parameters
- </caption>
- <colgroup>
- <col style="width: 16.6666%;">
- <col style="width: 16.6666%;">
- <col style="width: 66.6668%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-top">
- <div class="content">
- <div class="paragraph">
- <p>DataMap XML file which serves as a source of metadata for class generation. E.g.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code>${project.basedir}/src/main/resources/my.map.xml</code></pre>
- </div>
- </div>
- </div></td>
- </tr>
- </tbody>
- </table>
- <table id="cgenOptional" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 4. cgen optional parameters
- </caption>
- <colgroup>
- <col style="width: 25%;">
- <col style="width: 12.5%;">
- <col style="width: 62.5%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">additionalMaps</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A directory that contains additional DataMap XML files that may be needed to resolve cross-DataMap relationships for the the main DataMap, for which class generation occurs.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">client</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether we are generating classes for the client tier in a Remote Object Persistence application. "False" by default.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">destDir</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Root destination directory for Java classes (ignoring their package names). The default is "src/main/java".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">embeddableTemplate</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for Embeddable class generation. If omitted, default template is used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">embeddableSuperTemplate</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">encoding</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Generated files encoding if different from the default on current platform. Target encoding must be supported by the JVM running the build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See javadocs for java.nio.charset.Charset for more information.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">excludeEntities</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to exclude from template generation. By default none of the DataMap entities are excluded.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">includeEntities</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to include from template generation. By default all DataMap entities are included.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">makePairs</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">If "true" (a recommended default), will generate subclass/superclass pairs, with all generated code placed in superclass.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">mode</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Specifies class generator iteration target. There are three possible values: "entity" (default), "datamap", "all". "entity" performs one generator iteration for each included ObjEntity, applying either standard to custom entity templates. "datamap" performs a single iteration, applying DataMap templates. "All" is a combination of entity and datamap.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">overwrite</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Only has effect when "makePairs" is set to "false". If "overwrite" is "true", will overwrite older versions of generated classes.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">superPkg</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Java package name of all generated superclasses. If omitted, each superclass will be placed in the subpackage of its subclass called "auto". Doesn’t have any effect if either "makepairs" or "usePkgPath" are false (both are true by default).</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">superTemplate</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for ObjEntity superclass generation. Only has effect if "makepairs" set to "true". If omitted, default template is used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">template</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for ObjEntity class generation. If omitted, default template is used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">usePkgPath</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true" (default), a directory tree will be generated in "destDir" corresponding to the class package structure, if set to "false", classes will be generated in "destDir" ignoring their package.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">createPropertyNames</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will generate String Property names. Default is "false"</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">force</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will force run from maven/gradle.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">createPKProperties</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will generate PK attributes as Properties. Default is "false".</p></td>
- </tr>
- </tbody>
- </table>
- <div class="paragraph">
- <p>Example - a typical class generation scenario, where pairs of classes are generated with default Maven source destination and superclass package:</p>
+ </div>
+ <div class="paragraph">
+ <p>It is a good idea to shut down the runtime when it is no longer needed, usually before the application itself is shutdown:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">runtime.shutdown();</code></pre>
</div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-xml xml" data-lang="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>4.1.RC2</version>
-
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- </configuration>
-
- <executions>
- <execution>
- <goals>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></code></pre>
- </div>
+ </div>
+ <div class="paragraph">
+ <p>When a runtime object has the same scope as the application, this may not be always necessary, however in some cases it is essential, and is generally considered a good practice. E.g. in a web container hot redeploy of a webapp will cause resource leaks and eventual OutOfMemoryError if the application fails to shutdown CayenneRuntime.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="merging-multiple-projects"><a class="anchor" href="#merging-multiple-projects"></a>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>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .addConfig("org/foo/cayenne-library1.xml")
+ .addConfig("org/foo/cayenne-library2.xml")
+ .build();</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="cdbgen"><a class="anchor" href="#cdbgen"></a>cdbgen</h5>
- <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>
- <table id="cdbgenTable" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 5. cdbgen required parameters
- </caption>
- <colgroup>
- <col style="width: 16.6666%;">
- <col style="width: 16.6666%;">
- <col style="width: 66.6668%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-top">
- <div class="content">
- <div class="paragraph">
- <p>DataMap XML file which serves as a source of metadata for class generation. E.g.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code>${project.basedir}/src/main/resources/my.map.xml</code></pre>
- </div>
- </div>
- </div></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">dataSource</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains Data Source parameters</p></td>
- </tr>
- </tbody>
- </table>
- <table id="dataSourceParameteres" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 6. <dataSource> parameters
- </caption>
- <colgroup>
- <col style="width: 20%;">
- <col style="width: 10%;">
- <col style="width: 20%;">
- <col style="width: 50%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Required</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">driver</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A class of JDBC driver to use for the target database.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">url</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">JDBC URL of a target database.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">username</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user name.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">password</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user password.</p></td>
- </tr>
- </tbody>
- </table>
- <table id="cdbgenOptionl" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 7. cdbgen optional parameters
- </caption>
- <colgroup>
- <col style="width: 16.6666%;">
- <col style="width: 16.6666%;">
- <col style="width: 66.6668%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">adapter</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">createFK</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create foreign key constraints. Default is "true".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">createPK</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">createTables</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create new tables. Default is "true".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">dropPK</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">dropTables</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".</p></td>
- </tr>
- </tbody>
- </table>
- <div class="paragraph">
- <p>Example - creating a DB schema on a local HSQLDB database:</p>
+ <div class="paragraph">
+ <p>When the projects are merged, the following rules are applied:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>The order of projects matters during merge. If there are two conflicting metadata objects belonging to two projects, an object from the last project takes precedence over the object from the first one. This makes possible to override pieces of metadata. This is also similar to how DI modules are merged in Cayenne.</p> </li>
+ <li> <p>Runtime DataDomain name is set to the name of the last project in the list.</p> </li>
+ <li> <p>Runtime DataDomain properties are the same as the properties of the last project in the list. I.e. properties are not merged to avoid invalid combinations and unexpected runtime behavior.</p> </li>
+ <li> <p>If there are two or more DataMaps with the same name, only one DataMap is used in the merged project, the rest are discarded. Same precedence rules apply - DataMap from the project with the highest index in the project list overrides all other DataMaps with the same name.</p> </li>
+ <li> <p>If there are two or more DataNodes with the same name, only one DataNode is used in the merged project, the rest are discarded. DataNode coming from project with the highest index in the project list is chosen per precedence rule above.</p> </li>
+ <li> <p>There is a notion of "default" DataNode. After the merge if any DataMaps are not explicitly linked to DataNodes, their queries will be executed via a default DataNode. This makes it possible to build mapping "libraries" that are only associated with a specific database in runtime. If there’s only one DataNode in the merged project, it will be automatically chosen as default. A possible way to explicitly designate a specific node as default is to override <code>DataDomainPro [...]
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="web-applications"><a class="anchor" href="#web-applications"></a>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>
+ <div class="paragraph">
+ <p>Still Cayenne includes a piece of web app configuration code that can assist in quickly setting up simple Cayenne-enabled web applications. We are talking about CayenneFilter. It is declared in web.xml:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><web-app>
+ ...
+ <filter>
+ <filter-name>cayenne-project</filter-name>
+ <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>cayenne-project</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ ...
+ </web-app></code></pre>
</div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-xml xml" data-lang="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>4.1.RC2</version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <dataSource>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </dataSource>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></code></pre>
- </div>
+ </div>
+ <div class="paragraph">
+ <p>When started by the web container, it creates a instance of ServerRuntime and stores it in the ServletContext. Note that the name of Cayenne XML project file is derived from the "filter-name". In the example above CayenneFilter will look for an XML file "cayenne-project.xml". This can be overridden with "configuration-location" init parameter.</p>
+ </div>
+ <div class="paragraph">
+ <p>When the application runs, all HTTP requests matching the filter url-pattern will have access to a session-scoped ObjectContext like this:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java"> ObjectContext context = BaseContext.getThreadObjectContext();</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="mavenCdbimort"><a class="anchor" href="#mavenCdbimort"></a>cdbimport</h5>
- <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>
- <table id="cdbimportTable" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 8. cdbimport parameters
- </caption>
- <colgroup>
- <col style="width: 20%;">
- <col style="width: 10%;">
- <col style="width: 20%;">
- <col style="width: 50%;">
- </colgroup>
- <thead>
+ <div class="paragraph">
+ <p>Of course the ObjectContext scope, and other behavior of the Cayenne runtime can be customized via dependency injection. For this another filter init parameter called "extra-modules" is used. "extra-modules" is a comma or space-separated list of class names, with each class implementing Module interface. These optional custom modules are loaded after the the standard ones, which allows users to override all standard definitions.</p>
+ </div>
+ <div class="paragraph">
+ <p>For those interested in the DI container contents of the runtime created by CayenneFilter, it is the same ServerRuntime as would’ve been created by other means, but with an extra <code>org.apache.cayenne.configuration.web.WebModule</code> module that provides <code>org.apache.cayenne.configuration.web.RequestHandler</code> service. This is the service to override in the custom modules if you need to provide a different ObjectContext scope, etc.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
<tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Required</th>
- <th class="tableblock halign-left valign-top">Description</th>
+ <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
+ <td class="content"> You should not think of CayenneFilter as the only way to start and use Cayenne in a web application. In fact CayenneFilter is entirely optional. Use it if you don’t have any special design for application service management. If you do, simply integrate Cayenne into that design. </td>
</tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">DataMap XML file which is the destination of the schema import. Can be an existing file. If this file does not exist, it is created when cdbimport is executed. E.g. <code>${project.basedir}/src/main/resources/my.map.xml</code>. If "overwrite" is true (the default), an existing DataMap will be used as a template for the new imported DataMap, i.e. all its entities will be cleared and recreated, but its common se [...]
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">cayenneProject</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Project XML file which will be used. Can be an existing file, in this case data map will be added to project if it’s not already there. If this file does not exist, it is created when cdbimport is executed. E.g. <code>${project.basedir}/src/main/resources/cayenne-project.xml</code>.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">adapter</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is optional. If not specified, AutoAdapter is used, which will attempt to guess the DB type.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">dataSource</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains Data Source parameters.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">dbimport</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <a href="#db-first-flow">DB-First Flow</a> chapter.</p></td>
- </tr>
- </tbody>
- </table>
- <table id="cdbimportDataSource" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 9. <dataSource> parameters
- </caption>
- <colgroup>
- <col style="width: 20%;">
- <col style="width: 10%;">
- <col style="width: 20%;">
- <col style="width: 50%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Required</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">driver</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A class of JDBC driver to use for the target database.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">url</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">JDBC URL of a target database.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">username</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user name.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">password</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user password.</p></td>
- </tr>
- </tbody>
- </table>
- <table id="dbimportParameters" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 10. <dbimport> parameters
- </caption>
- <colgroup>
- <col style="width: 37.5%;">
- <col style="width: 12.5%;">
- <col style="width: 50%;">
- </colgroup>
- <thead>
- <tr>
- <th class="tableblock halign-left valign-top">Name</th>
- <th class="tableblock halign-left valign-top">Type</th>
- <th class="tableblock halign-left valign-top">Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">defaultPackage</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A Java package that will be set as the imported DataMap default and a package of all the persistent Java classes. This is a required attribute if the "map" itself does not already contain a default package, as otherwise all the persistent classes will be mapped with no package, and will not compile.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">forceDataMapCatalog</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting <code>forceDataMapCatalog</code> to <code>true</code> will set DbEntity catalog to one in the DataMap. Default value is <code>false</code>.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">forceDataMapSchema</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting <code>forceDataMapSchema</code> to <code>true</code> will set DbEntity schema to one in the DataMap. Default value is <code>false</code>.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">meaningfulPkTables</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of Perl5 patterns that defines which imported tables should have their primary key columns mapped as ObjAttributes. "*" would indicate all tables.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock"><a id="namingStrategy"></a>namingStrategy</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">The naming strategy used for mapping database names to object entity names. Default is <code>o.a.c.dbsync.naming.DefaultObjectNameGenerator</code>.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">skipPrimaryKeyLoading</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether to load primary keys. Default "false".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">skipRelationshipsLoading</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether to load relationships. Default "false".</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">stripFromTableNames</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
- <td class="tableblock halign-left valign-top">
- <div class="content">
- <div class="paragraph">
- <p>Regex that matches the part of the table name that needs to be stripped off when generating ObjEntity name. Here are some examples:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><!-- Strip prefix -->
-<stripFromTableNames>^myt_</stripFromTableNames>
-
-<!-- Strip suffix -->
-<stripFromTableNames>_s$</stripFromTableNames>
-
-<!-- Strip multiple occurrences in the middle -->
-<stripFromTableNames>_abc</stripFromTableNames></code></pre>
- </div>
- </div>
- </div></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">usePrimitives</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether numeric and boolean data types should be mapped as Java primitives or Java classes. Default is "true", i.e. primitives will be used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">useJava7Types</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether <em>DATE</em>, <em>TIME</em> and <em>TIMESTAMP</em> data types should be mapped as <code>java.util.Date</code> or <code>java.time.* classes</code>. Default is "false", i.e. <code>java.time.*</code> will be used.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">filters configuration</p></td>
- <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
- <td class="tableblock halign-left valign-top">
- <div class="content">
- <div class="paragraph">
- <p>Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <a href="#db-first-flow">DB-First Flow</a> chapter. Here is some simple example:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dbimport>
- <catalog name="test_catalog">
- <schema name="test_schema">
- <includeTable>.*</includeTable>
- <excludeTable>test_table</excludeTable>
- </schema>
- </catalog>
-
- <includeProcedure pattern=".*"/>
-</dbimport></code></pre>
- </div>
- </div>
- </div></td>
- </tr>
- </tbody>
+ </tbody>
</table>
- <div class="paragraph">
- <p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) :</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version>4.1.RC2</version>
-
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <dataSource>
- <url>jdbc:mysql://127.0.0.1/mydb</url>
- <driver>com.mysql.jdbc.Driver</driver>
- <username>sa</username>
- </dataSource>
- <dbimport>
- <defaultPackage>com.example.cayenne</defaultPackage>
- </dbimport>
- </configuration>
- <goals>
- <goal>cdbimport</goal>
- </goals>
- </execution>
- </executions>
-</plugin></code></pre>
- </div>
+ </div>
+ </div>
+ </div>
+ <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>
+ <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>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext context = runtime.newContext();</code></pre>
</div>
</div>
+ <div class="paragraph">
+ <p>The call above creates a new instance of ObjectContext that can access the database via this runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects. ObjectContext guarantees that for each database row with a unique ID it will contain at most one instance of an object, thus ensuring object graph consistency between multiple selects (a feature called "uniquing"). At the same time different ObjectContexts will have independent copies of objects for eac [...]
+ </div>
+ <div class="paragraph">
+ <p>These properties directly affect the strategies for scoping and sharing (or not sharing) ObjectContexts. Contexts that are only used to fetch objects from the database and whose objects are never modified by the application can be shared between mutliple users (and multiple threads). Contexts that store modified objects should be accessed only by a single user (e.g. a web application user might reuse a context instance between multiple web requests in the same HttpSession, thus c [...]
+ </div>
+ <div class="paragraph">
+ <p>ObjectContext is serializable and does not permanently hold to any of the application resources. So it does not have to be closed. If the context is not used anymore, it should simply be allowed to go out of scope and get garbage collected, just like any other Java object.</p>
+ </div>
</div>
<div class="sect3">
- <h4 id="gradle-projects"><a class="anchor" href="#gradle-projects"></a>Gradle Projects</h4>
+ <h4 id="persistent-object-and-its-lifecycle"><a class="anchor" href="#persistent-object-and-its-lifecycle"></a>Persistent Object and its Lifecycle</h4>
<div class="paragraph">
- <p>To include Cayenne into your Gradle project you have two options:</p>
+ <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>
- <div class="ulist">
- <ul>
- <li> <p>Simply add Cayenne as a dependency:</p> </li>
- </ul>
+ <div class="paragraph">
+ <p>Persistent interface provides access to 3 persistence-related properties - <em>objectId</em>, <em>persistenceState</em> and <em>objectContext</em>. All 3 are initialized by Cayenne runtime framework. Application code should not attempt to change them. However it is allowed to read them, which provides valuable runtime information. E.g. ObjectId can be used for quick equality check of 2 objects, knowing persistence state would allow highlighting changed objects, etc.</p>
+ </div>
+ <div class="paragraph">
+ <p>Each persistent object belongs to a single ObjectContext, and can be in one of the following persistence states (as defined in <code>org.apache.cayenne.PersistenceState</code>) :</p>
+ </div>
+ <table id="persistenceStates" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 3. Persistence States
+ </caption>
+ <colgroup>
+ <col style="width: 20%;">
+ <col style="width: 80%;">
+ </colgroup>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>TRANSIENT</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is not registered with an ObjectContext and will not be persisted.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>NEW</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is freshly registered in an ObjectContext, but has not been saved to the database yet and there is no matching database row.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>COMMITED</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, and the object state corresponds to the last known state of the matching database row.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>MODIFIED</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object in-memory state has diverged from the last known state of the matching database row.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>HOLLOW</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object state is unknown. Whenever an application tries to access a property of such object, Cayenne attempts reading its values from the database and "inflate" the object, turning it to COMMITED.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>DELETED</strong></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext and has been marked for deletion in-memory. The corresponding row in the database will get deleted upon ObjectContext commit, and the object state will be turned into TRANSIENT.</p></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="objectcontext-persistence-api"><a class="anchor" href="#objectcontext-persistence-api"></a>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>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">compile 'org.apache.cayenne:cayenne-server:4.1.RC2'</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">List<Artist> artists = ObjectSelect.query(Artist.class)
+ .select(context);</code></pre>
</div>
</div>
- <div class="ulist">
- <ul>
- <li> <p>Or you can use Cayenne Gradle plugin</p> </li>
- </ul>
+ <div class="paragraph">
+ <p>We’ll discuss queries in some detail in the <a href="#queries">Queries</a> chapter. The example above is self-explanatory - we create a <code>ObjectSelect</code> that matches all <code>Artist</code> objects present in the database, and then use <code>select</code> to get the result.</p>
</div>
- <div class="sect4">
- <h5 id="gradle-plugin"><a class="anchor" href="#gradle-plugin"></a>Gradle Plugin</h5>
- <div class="paragraph">
- <p>Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping or synching mapping with the database. Plugin also provides <code>cayenne</code> extension that have some useful utility methods. Here is example of how to include Cayenne plugin into your project:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">buildscript {
- // add Maven Central repository
- repositories {
- mavenCentral()
- }
- // add Cayenne Gradle Plugin
- dependencies {
- classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '4.1.RC2'
- }
-}
-
-// apply plugin
-apply plugin: 'org.apache.cayenne'
-
-// set default DataMap
-cayenne.defaultDataMap 'datamap.map.xml'
+ <div class="paragraph">
+ <p>Some queries can be quite complex, returning multiple result sets or even updating the database. For such queries ObjectContext provides <code>performGenericQuery()</code> method. While not commonly-used, it is nevertheless important in some situations. E.g.:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">Collection<Query> queries = ... // multiple queries that need to be run together
+QueryChain query = new QueryChain(queries);
-// add Cayenne dependencies to your project
-dependencies {
- // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
- compile cayenne.dependency('server')
-}</code></pre>
- </div>
- </div>
- <div class="sect5">
- <h6 id="warning"><a class="anchor" href="#warning"></a>Warning</h6>
- <div class="paragraph">
- <p>Cayenne Gradle plugin is experimental and it’s API can change later.</p>
- </div>
+QueryResponse response = context.performGenericQuery(query);</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="cgen-2"><a class="anchor" href="#cgen-2"></a>cgen</h5>
- <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>
- <div class="paragraph">
- <p>Here is how you can change settings of the default <code>cgen</code> task:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cgen {
- client = false
- mode = 'all'
- overwrite = true
- createPropertiesNames = true
-}</code></pre>
- </div>
+ <div class="paragraph">
+ <p>An application might modify selected objects. E.g.:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist selectedArtist = artists.get(0);
+selectedArtist.setName("Dali");</code></pre>
</div>
- <div class="paragraph">
- <p>And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):</p>
+ </div>
+ <div class="paragraph">
+ <p>The first time the object property is changed, the object’s state is automatically set to <strong>MODIFIED</strong> by Cayenne. Cayenne tracks all in-memory changes until a user calls <code>commitChanges</code>:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">context.commitChanges();</code></pre>
</div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">task clientCgen(type: cayenne.cgen) {
- client = true
-}</code></pre>
- </div>
+ </div>
+ <div class="paragraph">
+ <p>At this point all in-memory changes are analyzed and a minimal set of SQL statements is issued in a single transaction to synchronize the database with the in-memory state. In our example <code>commitChanges</code> commits just one object, but generally it can be any number of objects.</p>
+ </div>
+ <div class="paragraph">
+ <p>If instead of commit, we wanted to reset all changed objects to the previously committed state, we’d call <code>rollbackChanges</code> instead:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">context.rollbackChanges();</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="cdbimport"><a class="anchor" href="#cdbimport"></a>cdbimport</h5>
- <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 Maven Plugin version, described in <a href="#cdbimportTable">Table, “cdbimport parameters”</a>, with exception that Gradle version will use Groovy instead of XML.</p>
- </div>
- <div class="paragraph">
- <p>Here is example of configuration for cdbimport task:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cdbimport {
- // map can be skipped if it is defined in cayenne.defaultDataMap
- map 'datamap.map.xml'
- // optional project file, will be created if missing
- cayenneProject 'cayenne-project.xml'
-
- dataSource {
- driver 'com.mysql.cj.jdbc.Driver'
- url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
- username 'root'
- password ''
- }
-
- dbImport
- // additional settings
- usePrimitives false
- defaultPackage 'org.apache.cayenne.test'
-
- // DB filter configuration
- catalog 'catalog-1'
- schema 'schema-1'
-
- catalog {
- name 'catalog-2'
-
- includeTable 'table0', {
- excludeColumns '_column_'
- }
-
- includeTables 'table1', 'table2', 'table3'
-
- includeTable 'table4', {
- includeColumns 'id', 'type', 'data'
- }
-
- excludeTable '^GENERATED_.*'
- }
-
- catalog {
- name 'catalog-3'
- schema {
- name 'schema-2'
- includeTable 'test_table'
- includeTable 'test_table2', {
- excludeColumn '__excluded'
- }
- }
- }
-
- includeProcedure 'procedure_test_1'
-
- includeColumns 'id', 'version'
-
- tableTypes 'TABLE', 'VIEW'
- }
-}</code></pre>
- </div>
- </div>
+ <div class="paragraph">
+ <p><code>newObject</code> method call creates a persistent object and sets its state to <strong>NEW</strong>:</p>
</div>
- <div class="sect4">
- <h5 id="cdbgen-2"><a class="anchor" href="#cdbgen-2"></a>cdbgen</h5>
- <div class="paragraph">
- <p>Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters are same as in Maven Plugin version, described in <a href="#cdbgenTable">Table , “cdbgen required parameters”</a></p>
- </div>
- <div class="paragraph">
- <p>Here is example of how to configure default <code>cdbgen</code> task:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cdbgen {
-
- adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
-
- dataSource {
- driver 'org.apache.derby.jdbc.EmbeddedDriver'
- url 'jdbc:derby:build/testdb;create=true'
- username 'sa'
- password ''
- }
-
- dropTables true
- dropPk true
-
- createTables true
- createPk true
- createFk true
-}</code></pre>
- </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist newArtist = context.newObject(Artist.class);
+newArtist.setName("Picasso");</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="link-tasks-to-gradle-build-lifecycle"><a class="anchor" href="#link-tasks-to-gradle-build-lifecycle"></a>Link tasks to Gradle build lifecycle</h5>
- <div class="paragraph">
- <p>With gradle you can easily connect Cayenne tasks to 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>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cgen.dependsOn cdbimport
-compileJava.dependsOn cgen</code></pre>
- </div>
- </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"> Running <code>cdbimport</code> automatically with build not always a good choice, e.g. in case of complex model that you need to alter in the Cayenne Modeler after import. </td>
- </tr>
- </tbody>
- </table>
- </div>
+ <div class="paragraph">
+ <p>It will only exist in memory until <code>commitChanges</code> is issued. On commit Cayenne might generate a new primary key (unless a user set it explicitly, or a PK was inferred from a relationship) and issue an <code>INSERT</code> SQL statement to permanently store the object.</p>
</div>
- </div>
- <div class="sect3">
- <h4 id="ant-projects"><a class="anchor" href="#ant-projects"></a>Ant Projects</h4>
<div class="paragraph">
- <p>Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen", "cdbimport". Configuration parameters are also similar (except Maven can guess many defaults that Ant can’t). To include Ant tasks in the project, use the following Antlib:</p>
+ <p><code>deleteObjects</code> method takes one or more Persistent objects and marks them as <strong>DELETED</strong>:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><typedef resource="org/apache/cayenne/tools/antlib.xml">
- <classpath>
- <fileset dir="lib" >
- <include name="cayenne-ant-*.jar" />
- <include name="cayenne-cgen-*.jar" />
- <include name="cayenne-dbsync-*.jar" />
- <include name="cayenne-di-*.jar" />
- <include name="cayenne-project-*.jar" />
- <include name="cayenne-server-*.jar" />
- <include name="commons-collections-*.jar" />
- <include name="commons-lang-*.jar" />
- <include name="slf4j-api-*.jar" />
- <include name="velocity-*.jar" />
- <include name="vpp-2.2.1.jar" />
- </fileset>
- </classpath>
-</typedef></code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">context.deleteObjects(artist1);
+context.deleteObjects(artist2, artist3, artist4);</code></pre>
</div>
</div>
- <div class="sect4">
- <h5 id="cgen-3"><a class="anchor" href="#cgen-3"></a>cgen</h5>
+ <div class="paragraph">
+ <p>Additionally <code>deleteObjects</code> processes all delete rules modeled for the affected objects. This may result in implicitly deleting or modifying extra related objects. Same as insert and update, delete operations are sent to the database only when <code>commitChanges</code> is called. Similarly <code>rollbackChanges</code> will undo the effect of <code>newObject</code> and <code>deleteObjects</code>.</p>
</div>
- <div class="sect4">
- <h5 id="cdbgen-3"><a class="anchor" href="#cdbgen-3"></a>cdbgen</h5>
+ <div class="paragraph">
+ <p><code>localObject</code> returns a copy of a given persistent object that is <em>local</em> to a given ObjectContext:</p>
</div>
- <div class="sect4">
- <h5 id="cdbimport-2"><a class="anchor" href="#cdbimport-2"></a>cdbimport</h5>
- <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>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
- driver="com.mysql.jdbc.Driver"
- url="jdbc:mysql://127.0.0.1/mydb"
- username="sa"
- defaultPackage="com.example.cayenne"/></code></pre>
- </div>
+ <div class="paragraph">
+ <p>Since an application often works with more than one context, <code>localObject</code> is a rather common operation. E.g. to improve performance a user might utilize a single shared context to select and cache data, and then occasionally transfer some selected objects to another context to modify and commit them:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext editingContext = runtime.newContext();
+Artist localArtist = editingContext.localObject(artist);</code></pre>
</div>
</div>
- </div>
- </div>
- <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>
<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>
+ <p>Often an application needs to inspect mapping metadata. This information is stored in the <code>EntityResolver</code> object, accessible via the <code>ObjectContext</code>:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .build();</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">EntityResolver resolver = objectContext.getEntityResolver();</code></pre>
</div>
</div>
<div class="paragraph">
- <p>The parameter you pass to the builder is a location of the main project file. Location is a '/'-separated path (same path separator is used on UNIX and Windows) that is resolved relative to the application classpath. The project file can be placed in the root package or in a subpackage (e.g. in the code above it is in "com/example" subpackage).</p>
+ <p>Here we discussed the most commonly used subset of the ObjectContext API. There are other useful methods, e.g. those allowing to inspect registered objects state in bulk, etc. Check the latest JavaDocs for details.</p>
</div>
+ </div>
+ <div class="sect3">
+ <h4 id="cayenne-helper-class"><a class="anchor" href="#cayenne-helper-class"></a>Cayenne Helper Class</h4>
<div class="paragraph">
- <p>ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the container are discussed in <a href="#customizing-cayenne-runtime">Customizing Cayenne Runtime</a> chapter. Here we’ll just show an example of how [...]
+ <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>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Module extensions = binder ->
- ServerModule.contributeProperties(binder)
- .put(Constants.SERVER_EXTERNAL_TX_PROPERTY, "true");
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .addModule(extensions)
- .build();</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">long pk = Cayenne.longPKForObject(artist);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>It is a good idea to shut down the runtime when it is no longer needed, usually before the application itself is shutdown:</p>
+ <p>It also provides the reverse operation - finding an object given a known PK:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">runtime.shutdown();</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>When a runtime object has the same scope as the application, this may not be always necessary, however in some cases it is essential, and is generally considered a good practice. E.g. in a web container hot redeploy of a webapp will cause resource leaks and eventual OutOfMemoryError if the application fails to shutdown CayenneRuntime.</p>
- </div>
- </div>
- <div class="sect3">
- <h4 id="merging-multiple-projects"><a class="anchor" href="#merging-multiple-projects"></a>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>
+ <p>If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find this object. It throws an exception if more than one object matched the query:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .addConfig("org/foo/cayenne-library1.xml")
- .addConfig("org/foo/cayenne-library2.xml")
- .build();</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</code></pre>
</div>
</div>
<div class="paragraph">
- <p>When the projects are merged, the following rules are applied:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>The order of projects matters during merge. If there are two conflicting metadata objects belonging to two projects, an object from the last project takes precedence over the object from the first one. This makes possible to override pieces of metadata. This is also similar to how DI modules are merged in Cayenne.</p> </li>
- <li> <p>Runtime DataDomain name is set to the name of the last project in the list.</p> </li>
- <li> <p>Runtime DataDomain properties are the same as the properties of the last project in the list. I.e. properties are not merged to avoid invalid combinations and unexpected runtime behavior.</p> </li>
- <li> <p>If there are two or more DataMaps with the same name, only one DataMap is used in the merged project, the rest are discarded. Same precedence rules apply - DataMap from the project with the highest index in the project list overrides all other DataMaps with the same name.</p> </li>
- <li> <p>If there are two or more DataNodes with the same name, only one DataNode is used in the merged project, the rest are discarded. DataNode coming from project with the highest index in the project list is chosen per precedence rule above.</p> </li>
- <li> <p>There is a notion of "default" DataNode. After the merge if any DataMaps are not explicitly linked to DataNodes, their queries will be executed via a default DataNode. This makes it possible to build mapping "libraries" that are only associated with a specific database in runtime. If there’s only one DataNode in the merged project, it will be automatically chosen as default. A possible way to explicitly designate a specific node as default is to override <code>DataDomainPro [...]
- </ul>
+ <p>Feel free to explore Cayenne class API for other useful methods.</p>
</div>
</div>
<div class="sect3">
- <h4 id="web-applications"><a class="anchor" href="#web-applications"></a>Web Applications</h4>
+ <h4 id="objectcontext-nesting"><a class="anchor" href="#objectcontext-nesting"></a>ObjectContext Nesting</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 [...]
+ <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>
<div class="paragraph">
- <p>Still Cayenne includes a piece of web app configuration code that can assist in quickly setting up simple Cayenne-enabled web applications. We are talking about CayenneFilter. It is declared in web.xml:</p>
+ <p>Nesting is useful to create isolated object editing areas (child contexts) that need to all be committed to an intermediate in-memory store (parent context), or rolled back without affecting changes already recorded in the parent. Think cascading GUI dialogs, or parallel AJAX requests coming to the same session.</p>
</div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-XML XML" data-lang="XML"><web-app>
- ...
- <filter>
- <filter-name>cayenne-project</filter-name>
- <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
- </filter>
- <filter-mapping>
- <filter-name>cayenne-project</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
- ...
- </web-app></code></pre>
- </div>
+ <div class="paragraph">
+ <p>In theory Cayenne supports any number of nesting levels, however applications should generally stay with one or two, as deep hierarchies will most certainly degrade the performance of the deeply nested child contexts. This is due to the fact that each context in a nesting chain has to update its own objects during most operations.</p>
</div>
<div class="paragraph">
- <p>When started by the web container, it creates a instance of ServerRuntime and stores it in the ServletContext. Note that the name of Cayenne XML project file is derived from the "filter-name". In the example above CayenneFilter will look for an XML file "cayenne-project.xml". This can be overridden with "configuration-location" init parameter.</p>
+ <p>Cayenne ROP is an extreme case of nesting when a child context is located in a separate JVM and communicates with its parent via a web service. ROP is discussed in details in the following chapters. Here we concentrate on the same-VM nesting.</p>
</div>
<div class="paragraph">
- <p>When the application runs, all HTTP requests matching the filter url-pattern will have access to a session-scoped ObjectContext like this:</p>
+ <p>To create a nested context, use an instance of ServerRuntime, passing it the desired parent:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java"> ObjectContext context = BaseContext.getThreadObjectContext();</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext parent = runtime.newContext();
+ObjectContext nested = runtime.newContext(parent);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Of course the ObjectContext scope, and other behavior of the Cayenne runtime can be customized via dependency injection. For this another filter init parameter called "extra-modules" is used. "extra-modules" is a comma or space-separated list of class names, with each class implementing Module interface. These optional custom modules are loaded after the the standard ones, which allows users to override all standard definitions.</p>
- </div>
- <div class="paragraph">
- <p>For those interested in the DI container contents of the runtime created by CayenneFilter, it is the same ServerRuntime as would’ve been created by other means, but with an extra <code>org.apache.cayenne.configuration.web.WebModule</code> module that provides <code>org.apache.cayenne.configuration.web.RequestHandler</code> service. This is the service to override in the custom modules if you need to provide a different ObjectContext scope, etc.</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 not think of CayenneFilter as the only way to start and use Cayenne in a web application. In fact CayenneFilter is entirely optional. Use it if you don’t have any special design for application service management. If you do, simply integrate Cayenne into that design. </td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- </div>
- <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>
- <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>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext context = runtime.newContext();</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>The call above creates a new instance of ObjectContext that can access the database via this runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects. ObjectContext guarantees that for each database row with a unique ID it will contain at most one instance of an object, thus ensuring object graph consistency between multiple selects (a feature called "uniquing"). At the same time different ObjectContexts will have independent copies of objects for eac [...]
- </div>
- <div class="paragraph">
- <p>These properties directly affect the strategies for scoping and sharing (or not sharing) ObjectContexts. Contexts that are only used to fetch objects from the database and whose objects are never modified by the application can be shared between mutliple users (and multiple threads). Contexts that store modified objects should be accessed only by a single user (e.g. a web application user might reuse a context instance between multiple web requests in the same HttpSession, thus c [...]
- </div>
- <div class="paragraph">
- <p>ObjectContext is serializable and does not permanently hold to any of the application resources. So it does not have to be closed. If the context is not used anymore, it should simply be allowed to go out of scope and get garbage collected, just like any other Java object.</p>
- </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>
- <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>
- <div class="paragraph">
- <p>Persistent interface provides access to 3 persistence-related properties - <em>objectId</em>, <em>persistenceState</em> and <em>objectContext</em>. All 3 are initialized by Cayenne runtime framework. Application code should not attempt to change them. However it is allowed to read them, which provides valuable runtime information. E.g. ObjectId can be used for quick equality check of 2 objects, knowing persistence state would allow highlighting changed objects, etc.</p>
- </div>
- <div class="paragraph">
- <p>Each persistent object belongs to a single ObjectContext, and can be in one of the following persistence states (as defined in <code>org.apache.cayenne.PersistenceState</code>) :</p>
- </div>
- <table id="persistenceStates" class="tableblock frame-all grid-all stretch table table-bordered">
- <caption class="title">
- Table 11. Persistence States
- </caption>
- <colgroup>
- <col style="width: 20%;">
- <col style="width: 80%;">
- </colgroup>
- <tbody>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>TRANSIENT</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is not registered with an ObjectContext and will not be persisted.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>NEW</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is freshly registered in an ObjectContext, but has not been saved to the database yet and there is no matching database row.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>COMMITED</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, and the object state corresponds to the last known state of the matching database row.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>MODIFIED</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object in-memory state has diverged from the last known state of the matching database row.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>HOLLOW</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object state is unknown. Whenever an application tries to access a property of such object, Cayenne attempts reading its values from the database and "inflate" the object, turning it to COMMITED.</p></td>
- </tr>
- <tr>
- <td class="tableblock halign-center valign-middle"><p class="tableblock"><strong>DELETED</strong></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">The object is registered in an ObjectContext and has been marked for deletion in-memory. The corresponding row in the database will get deleted upon ObjectContext commit, and the object state will be turned into TRANSIENT.</p></td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="sect3">
- <h4 id="objectcontext-persistence-api"><a class="anchor" href="#objectcontext-persistence-api"></a>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>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">List<Artist> artists = ObjectSelect.query(Artist.class)
- .select(context);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>We’ll discuss queries in some detail in the <a href="#queries">Queries</a> chapter. The example above is self-explanatory - we create a <code>ObjectSelect</code> that matches all <code>Artist</code> objects present in the database, and then use <code>select</code> to get the result.</p>
- </div>
- <div class="paragraph">
- <p>Some queries can be quite complex, returning multiple result sets or even updating the database. For such queries ObjectContext provides <code>performGenericQuery()</code> method. While not commonly-used, it is nevertheless important in some situations. E.g.:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Collection<Query> queries = ... // multiple queries that need to be run together
-QueryChain query = new QueryChain(queries);
-
-QueryResponse response = context.performGenericQuery(query);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>An application might modify selected objects. E.g.:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist selectedArtist = artists.get(0);
-selectedArtist.setName("Dali");</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>The first time the object property is changed, the object’s state is automatically set to <strong>MODIFIED</strong> by Cayenne. Cayenne tracks all in-memory changes until a user calls <code>commitChanges</code>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">context.commitChanges();</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>At this point all in-memory changes are analyzed and a minimal set of SQL statements is issued in a single transaction to synchronize the database with the in-memory state. In our example <code>commitChanges</code> commits just one object, but generally it can be any number of objects.</p>
- </div>
- <div class="paragraph">
- <p>If instead of commit, we wanted to reset all changed objects to the previously committed state, we’d call <code>rollbackChanges</code> instead:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">context.rollbackChanges();</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p><code>newObject</code> method call creates a persistent object and sets its state to <strong>NEW</strong>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist newArtist = context.newObject(Artist.class);
-newArtist.setName("Picasso");</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>It will only exist in memory until <code>commitChanges</code> is issued. On commit Cayenne might generate a new primary key (unless a user set it explicitly, or a PK was inferred from a relationship) and issue an <code>INSERT</code> SQL statement to permanently store the object.</p>
- </div>
- <div class="paragraph">
- <p><code>deleteObjects</code> method takes one or more Persistent objects and marks them as <strong>DELETED</strong>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">context.deleteObjects(artist1);
-context.deleteObjects(artist2, artist3, artist4);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Additionally <code>deleteObjects</code> processes all delete rules modeled for the affected objects. This may result in implicitly deleting or modifying extra related objects. Same as insert and update, delete operations are sent to the database only when <code>commitChanges</code> is called. Similarly <code>rollbackChanges</code> will undo the effect of <code>newObject</code> and <code>deleteObjects</code>.</p>
- </div>
- <div class="paragraph">
- <p><code>localObject</code> returns a copy of a given persistent object that is <em>local</em> to a given ObjectContext:</p>
- </div>
- <div class="paragraph">
- <p>Since an application often works with more than one context, <code>localObject</code> is a rather common operation. E.g. to improve performance a user might utilize a single shared context to select and cache data, and then occasionally transfer some selected objects to another context to modify and commit them:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext editingContext = runtime.newContext();
-Artist localArtist = editingContext.localObject(artist);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Often an application needs to inspect mapping metadata. This information is stored in the <code>EntityResolver</code> object, accessible via the <code>ObjectContext</code>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EntityResolver resolver = objectContext.getEntityResolver();</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Here we discussed the most commonly used subset of the ObjectContext API. There are other useful methods, e.g. those allowing to inspect registered objects state in bulk, etc. Check the latest JavaDocs for details.</p>
- </div>
- </div>
- <div class="sect3">
- <h4 id="cayenne-helper-class"><a class="anchor" href="#cayenne-helper-class"></a>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>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">long pk = Cayenne.longPKForObject(artist);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>It also provides the reverse operation - finding an object given a known PK:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find this object. It throws an exception if more than one object matched the query:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Feel free to explore Cayenne class API for other useful methods.</p>
- </div>
- </div>
- <div class="sect3">
- <h4 id="objectcontext-nesting"><a class="anchor" href="#objectcontext-nesting"></a>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>
- <div class="paragraph">
- <p>Nesting is useful to create isolated object editing areas (child contexts) that need to all be committed to an intermediate in-memory store (parent context), or rolled back without affecting changes already recorded in the parent. Think cascading GUI dialogs, or parallel AJAX requests coming to the same session.</p>
- </div>
- <div class="paragraph">
- <p>In theory Cayenne supports any number of nesting levels, however applications should generally stay with one or two, as deep hierarchies will most certainly degrade the performance of the deeply nested child contexts. This is due to the fact that each context in a nesting chain has to update its own objects during most operations.</p>
- </div>
- <div class="paragraph">
- <p>Cayenne ROP is an extreme case of nesting when a child context is located in a separate JVM and communicates with its parent via a web service. ROP is discussed in details in the following chapters. Here we concentrate on the same-VM nesting.</p>
- </div>
- <div class="paragraph">
- <p>To create a nested context, use an instance of ServerRuntime, passing it the desired parent:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">ObjectContext parent = runtime.newContext();
-ObjectContext nested = runtime.newContext(parent);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>From here a nested context operates just like a regular context (you can perform queries, create and delete objects, etc.). The only difference is that commit and rollback operations can either be limited to synchronization with the parent, or cascade all the way to the database:</p>
+ <p>From here a nested context operates just like a regular context (you can perform queries, create and delete objects, etc.). The only difference is that commit and rollback operations can either be limited to synchronization with the parent, or cascade all the way to the database:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -1713,11 +860,8 @@ transactionManager.performInTransaction(transactionalOperation, descriptor);</co
</div>
<div class="sect2">
<h3 id="expressions"><a class="anchor" href="#expressions"></a>2.4. Expressions</h3>
- <div class="sect3">
- <h4 id="expressions-overview"><a class="anchor" href="#expressions-overview"></a>Expressions Overview</h4>
- <div class="paragraph">
- <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="paragraph">
+ <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>
@@ -1964,7 +1108,7 @@ Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="evaluete"><a class="anchor" href="#evaluete"></a>Evaluating Expressions in Memory</h4>
+ <h4 id="evaluate"><a class="anchor" href="#evaluate"></a>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>
@@ -2222,144 +1366,26 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="ejbql"><a class="anchor" href="#ejbql"></a>EJBQLQuery</h4>
- <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"> As soon as all of the <code>EJBQLQuery</code> capabilities become available in <code>ObjectSelect</code>, we are planning to deprecate <code>EJBQLQuery</code>. </td>
- </tr>
- </tbody>
- </table>
+ <h4 id="selectbyid"><a class="anchor" href="#selectbyid"></a>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>
<div class="paragraph">
- <p>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence API (JPA) approaches in Cayenne. It is a parameterized object query that is created from query String. A String used to build EJBQLQuery follows JPQL (JPA Query Language) syntax:</p>
+ <p>Here is example of how to use it:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>JPQL details can be found in any JPA manual. Here we’ll focus on how this fits into Cayenne and what are the differences between EJBQL and other Cayenne queries.</p>
- </div>
- <div class="paragraph">
- <p>Although most frequently EJBQLQuery is used as an alternative to ObjectSelect, there are also DELETE and UPDATE varieties available.</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"> DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the database instead. </td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery select =
- new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
-List<Artist> artists = context.performQuery(select);</code></pre>
- </div>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery delete = new EJBQLQuery("delete from Painting");
-context.performGenericQuery(delete);</code></pre>
- </div>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery update =
- new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
-context.performGenericQuery(update);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>In most cases <code>ObjectSelect</code> is preferred to <code>EJBQLQuery</code>, as it is API-based, and provides you with better compile-time checks. However sometimes you may want a completely scriptable object query. This is when you might prefer EJBQL. A more practical reason for picking EJBQL over <code>ObjectSelect</code> though is that the former offers a few extra capabilities, such as subqueries.</p>
- </div>
- <div class="paragraph">
- <p>Just like <code>ObjectSelect</code> <code>EJBQLQuery</code> can return a List of Object[] elements, where each entry in an array is either a DataObject or a scalar, depending on the query SELECT clause.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a");
-List<Object[]> result = context.performQuery(query);
-for(Object[] artistWithCount : result) {
- Artist a = (Artist) artistWithCount[0];
- int hasPaintings = (Integer) artistWithCount[1];
-}</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>A result can also be a list of scalars:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
-List<String> names = context.performQuery(query);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>EJBQLQuery supports an "IN" clause with three different usage-patterns. The following example would require three individual positional parameters (named parameters could also have been used) to be supplied.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in (?1,?2,?3)</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>The following example requires a single positional parameter to be supplied. The parameter can be any concrete implementation of the <code>java.util.Collection</code> interface such as <code>java.util.List</code> or <code>java.util.Set</code>.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in ?1</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>The following example is functionally identical to the one prior.</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in (?1)</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>It is possible to convert an <a href="#expressions">Expression</a> object used with a <a href="#select">ObjectSelect</a> to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.</p>
- </div>
- <div class="paragraph">
- <p>While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few notable differences:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>Null handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.</p> </li>
- <li> <p>Expression Parameters: SelectQuery uses "$" to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".</p> </li>
- </ul>
- </div>
- </div>
- <div class="sect3">
- <h4 id="selectbyid"><a class="anchor" href="#selectbyid"></a>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>
- <div class="paragraph">
- <p>Here is example of how to use it:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist artistWithId1 = SelectById.query(Artist.class, 1)
- .prefetch(Artist.PAINTING_ARRAY.joint())
- .localCache()
- .selectOne(context);</code></pre>
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist artistWithId1 = SelectById.query(Artist.class, 1)
+ .prefetch(Artist.PAINTING_ARRAY.joint())
+ .localCache()
+ .selectOne(context);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="sqlselect-and-sqlexec"><a class="anchor" href="#sqlselect-and-sqlexec"></a>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 name suggests) to select custom data in form of entities, separate columns, collection o [...]
+ <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>
<div class="paragraph">
<p>Both queries support advanced SQL templating, with variable substitution and special directives as described <a href="#sqlscripting">in the next chapter</a>. Here we’ll just provide a few simple examples:</p>
@@ -2381,12 +1407,12 @@ List<String> paintingNames = SQLSelect
// Selecting DataRow with predefined types
List<DataRow> result = SQLSelect
- .dataRowQuery("SELECT * FROM ARTIST", Integer.class, String.class, LocalDateTime.class)
+ .dataRowQuery("SELECT * FROM ARTIST", Integer.class, String.class, LocalDate.class)
.select(context);
// Selecting Object[] with predefined types
List<Object[]> result = SQLSelect
- .scalarQuery("SELECT * FROM ARTIST", Integer.class, String.class, LocalDateTime.class)
+ .scalarQuery("SELECT * FROM ARTIST", Integer.class, String.class, LocalDate.class)
.select(context);</code></pre>
</div>
</div>
@@ -2404,7 +1430,7 @@ List<Object[]> result = SQLSelect
<div class="sect3">
<h4 id="sqlscripting"><a class="anchor" href="#sqlscripting"></a>Scripting SQL Queries</h4>
<div class="paragraph">
- <p>A powerful feature of <code>SQLSelect</code> and <code>SQLExec</code> is that a SQL string is treated by Cayenne as a dynamic template. Before sending it to DB as a PreparedStatement, the String is evaluated, resolving the 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 [...]
+ <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>
@@ -2425,7 +1451,7 @@ SQLExec query = SQLExec.query("delete from $tableName")
<div class="sect4">
<h5 id="directives"><a class="anchor" href="#directives"></a>Directives</h5>
<div class="paragraph">
- <p>"Directives" look like <code>#directive(p1 p2 p3)</code> (notice the absence of comma between the arguments). The folliwng directives are supported in SQL templates:</p>
+ <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>
<div class="sect5">
<h6 id="bind"><a class="anchor" href="#bind"></a>#bind</h6>
@@ -2779,6 +1805,124 @@ Object out = result.getOutParam("out_param");</code></pre>
</div>
</div>
<div class="sect3">
+ <h4 id="ejbql"><a class="anchor" href="#ejbql"></a>EJBQLQuery</h4>
+ <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"> As soon as all of the <code>EJBQLQuery</code> capabilities become available in <code>ObjectSelect</code>, we are planning to deprecate <code>EJBQLQuery</code>. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence API (JPA) approaches in Cayenne. It is a parameterized object query that is created from query String. A String used to build EJBQLQuery follows JPQL (JPA Query Language) syntax:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>JPQL details can be found in any JPA manual. Here we’ll focus on how this fits into Cayenne and what are the differences between EJBQL and other Cayenne queries.</p>
+ </div>
+ <div class="paragraph">
+ <p>Although most frequently EJBQLQuery is used as an alternative to ObjectSelect, there are also DELETE and UPDATE varieties available.</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"> DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the database instead. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery select =
+ new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
+List<Artist> artists = context.performQuery(select);</code></pre>
+ </div>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery delete = new EJBQLQuery("delete from Painting");
+context.performGenericQuery(delete);</code></pre>
+ </div>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery update =
+ new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
+context.performGenericQuery(update);</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>In most cases <code>ObjectSelect</code> is preferred to <code>EJBQLQuery</code>, as it is API-based, and provides you with better compile-time checks. However sometimes you may want a completely scriptable object query. This is when you might prefer EJBQL. A more practical reason for picking EJBQL over <code>ObjectSelect</code> though is that the former offers a few extra capabilities, such as subqueries.</p>
+ </div>
+ <div class="paragraph">
+ <p>Just like <code>ObjectSelect</code> <code>EJBQLQuery</code> can return a List of Object[] elements, where each entry in an array is either a DataObject or a scalar, depending on the query SELECT clause.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a");
+List<Object[]> result = context.performQuery(query);
+for(Object[] artistWithCount : result) {
+ Artist a = (Artist) artistWithCount[0];
+ int hasPaintings = (Integer) artistWithCount[1];
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>A result can also be a list of scalars:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
+List<String> names = context.performQuery(query);</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>EJBQLQuery supports an "IN" clause with three different usage-patterns. The following example would require three individual positional parameters (named parameters could also have been used) to be supplied.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in (?1,?2,?3)</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The following example requires a single positional parameter to be supplied. The parameter can be any concrete implementation of the <code>java.util.Collection</code> interface such as <code>java.util.List</code> or <code>java.util.Set</code>.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in ?1</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The following example is functionally identical to the one prior.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">select p from Painting p where p.paintingTitle in (?1)</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>It is possible to convert an <a href="#expressions">Expression</a> object used with a <a href="#select">ObjectSelect</a> to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.</p>
+ </div>
+ <div class="paragraph">
+ <p>While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few notable differences:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Null handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.</p> </li>
+ <li> <p>Expression Parameters: SelectQuery uses "$" to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".</p> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
<h4 id="custom-queries"><a class="anchor" href="#custom-queries"></a>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>
@@ -2847,7 +1991,7 @@ Object out = result.getOutParam("out_param");</code></pre>
</div>
<table id="lifecycleEvent" class="tableblock frame-all grid-all stretch table table-bordered">
<caption class="title">
- Table 12. Lifecycle Event Types
+ Table 4. Lifecycle Event Types
</caption>
<colgroup>
<col style="width: 20%;">
@@ -3479,14 +2623,14 @@ context.performGenericQuery(refresh);</code></pre>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-Java Java" data-lang="Java">public interface Service1 {
- public String getString();
+ String getString();
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-Java Java" data-lang="Java">public interface Service2 {
- public int getInt();
+ int getInt();
}</code></pre>
</div>
</div>
@@ -4545,7 +3689,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<div class="sect2">
<h3 id="re-modeler"><a class="anchor" href="#re-modeler"></a>4.4. Reverse Engineering in Cayenne Modeler</h3>
<div class="paragraph">
- <p>Alternative aproach to using <a href="#cdbimport">cdbimport</a> is doing reverse engineering from <a href="#cayennemodeler-application">CayenneModeler</a>. Currently modeler GUI doesn’t support all features of ant/maven tasks but it suffice for general DB import. Especially it’s a good place to quickly start working on your data model.</p>
+ <p>Alternative aproach to using <a href="#cdbimport">cdbimport</a> is doing reverse engineering from <a href="#cayenne-modeler">CayenneModeler</a>. Currently modeler GUI doesn’t support all features of ant/maven tasks but it suffice for general DB import. Especially it’s a good place to quickly start working on your data model.</p>
</div>
<div class="paragraph">
<p>You can find reverse engineering tool in dataMap view on <strong>DbImport Tab</strong>.</p>
@@ -4618,7 +3762,7 @@ ServerRuntime runtime = ServerRuntime.builder()
<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"><a class="anchor" href="#maven"></a>Maven</h5>
+ <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>
@@ -4716,7 +3860,7 @@ public class MyEntity extends _MyEntity {
<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-2"><a class="anchor" href="#maven-2"></a>Maven</h5>
+ <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>
@@ -4802,7 +3946,7 @@ public class MyEntity extends _MyEntity {
<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-3"><a class="anchor" href="#maven-3"></a>Maven</h5>
+ <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>
@@ -4931,7 +4075,7 @@ public class MyEntity extends _MyEntity {
<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-4"><a class="anchor" href="#maven-4"></a>Maven</h5>
+ <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>
@@ -5048,7 +4192,7 @@ public class MyEntity extends _MyEntity {
<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-5"><a class="anchor" href="#maven-5"></a>Maven</h5>
+ <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>
@@ -5086,7 +4230,7 @@ public class MyEntity extends _MyEntity {
<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-6"><a class="anchor" href="#maven-6"></a>Maven</h5>
+ <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>
@@ -5097,142 +4241,967 @@ public class MyEntity extends _MyEntity {
</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="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>
+ </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>
+ <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>
+ </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 [...]
+ </div>
+ <div class="paragraph">
+ <p>Semantics:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code>#chain(operator) ... #end
+#chain(operator prefix) ... #end
+#chunk() ... #end
+#chunk(param) ... #end</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Full example:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code>#chain('OR' 'WHERE')
+ #chunk($name) NAME LIKE #bind($name) #end
+ #chunk($id) ARTIST_ID > #bind($id) #end
+#end"</code></pre>
+ </div>
+ </div>
+ </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>
+ </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>
+ <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>
+ </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>
+ </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>
+ <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>
+ </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>
+ </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>
+ <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>
+ </div>
+ </div>
+ </div>
+</div>
+<div class="sect1">
+ <h2 id="build_tools"><a class="anchor" href="#build_tools"></a>6. Build Tools</h2>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>While we encourage the use of <a href="#cayenne-modeler">CayenneModeler</a> for tasks such as DB reverse-engineering and code generation, Cayenne also provides an option to execute them from your preferred build tool. It may be occasionally useful to keep them as a part of the build. This chapter shows how to use them in <a href="#maven_plugin">Maven</a>, <a href="#gradle_plugin">Gradle</a> or <a href="#ant_tasks">Ant</a>.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="maven_plugin"><a class="anchor" href="#maven_plugin"></a>6.1. Maven Plugin</h3>
+ <div class="paragraph">
+ <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>
+ <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>
+ <div class="paragraph">
+ <p>By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.</p>
+ </div>
+ <table id="tablecgen" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 5. cgen required parameters
+ </caption>
+ <colgroup>
+ <col style="width: 16.6666%;">
+ <col style="width: 16.6666%;">
+ <col style="width: 66.6668%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="content">
+ <div class="paragraph">
+ <p>DataMap XML file which serves as a source of metadata for class generation. E.g.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code>${project.basedir}/src/main/resources/my.map.xml</code></pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="cgenOptional" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 6. cgen optional parameters
+ </caption>
+ <colgroup>
+ <col style="width: 25%;">
+ <col style="width: 12.5%;">
+ <col style="width: 62.5%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">additionalMaps</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A directory that contains additional DataMap XML files that may be needed to resolve cross-DataMap relationships for the the main DataMap, for which class generation occurs.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">client</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether we are generating classes for the client tier in a Remote Object Persistence application. "False" by default.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">destDir</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Root destination directory for Java classes (ignoring their package names). The default is "src/main/java".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">embeddableTemplate</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for Embeddable class generation. If omitted, default template is used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">embeddableSuperTemplate</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">encoding</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Generated files encoding if different from the default on current platform. Target encoding must be supported by the JVM running the build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See javadocs for java.nio.charset.Charset for more information.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">excludeEntities</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to exclude from template generation. By default none of the DataMap entities are excluded.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">includeEntities</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to include from template generation. By default all DataMap entities are included.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">makePairs</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">If "true" (a recommended default), will generate subclass/superclass pairs, with all generated code placed in superclass.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">mode</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Specifies class generator iteration target. There are three possible values: "entity" (default), "datamap", "all". "entity" performs one generator iteration for each included ObjEntity, applying either standard to custom entity templates. "datamap" performs a single iteration, applying DataMap templates. "All" is a combination of entity and datamap.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">overwrite</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Only has effect when "makePairs" is set to "false". If "overwrite" is "true", will overwrite older versions of generated classes.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">superPkg</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Java package name of all generated superclasses. If omitted, each superclass will be placed in the subpackage of its subclass called "auto". Doesn’t have any effect if either "makepairs" or "usePkgPath" are false (both are true by default).</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">superTemplate</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for ObjEntity superclass generation. Only has effect if "makepairs" set to "true". If omitted, default template is used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">template</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Location of a custom Velocity template file for ObjEntity class generation. If omitted, default template is used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">usePkgPath</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true" (default), a directory tree will be generated in "destDir" corresponding to the class package structure, if set to "false", classes will be generated in "destDir" ignoring their package.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">createPropertyNames</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will generate String Property names. Default is "false"</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">force</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will force run from maven/gradle.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">createPKProperties</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">If set to "true", will generate PK attributes as Properties. Default is "false".</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>Example - a typical class generation scenario, where pairs of classes are generated with default Maven source destination and superclass package:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-xml xml" data-lang="xml"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>4.1.RC2</version>
+
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ </configuration>
+
+ <executions>
+ <execution>
+ <goals>
+ <goal>cgen</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="mavenCdbimort"><a class="anchor" href="#mavenCdbimort"></a>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>
+ <table id="cdbimportTable" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 7. cdbimport parameters
+ </caption>
+ <colgroup>
+ <col style="width: 20%;">
+ <col style="width: 10%;">
+ <col style="width: 20%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Required</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">DataMap XML file which is the destination of the schema import. Can be an existing file. If this file does not exist, it is created when cdbimport is executed. E.g. <code>${project.basedir}/src/main/resources/my.map.xml</code>. If "overwrite" is true (the default), an existing DataMap will be used as a template for the new imported DataMap, i.e. all its entities will be cleared and recreated, but its common set [...]
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">cayenneProject</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Project XML file which will be used. Can be an existing file, in this case data map will be added to project if it’s not already there. If this file does not exist, it is created when cdbimport is executed. E.g. <code>${project.basedir}/src/main/resources/cayenne-project.xml</code>.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">adapter</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is optional. If not specified, AutoAdapter is used, which will attempt to guess the DB type.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">dataSource</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains Data Source parameters.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">dbimport</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <a href="#db-first-flow">DB-First Flow</a> chapter.</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="cdbimportDataSource" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 8. <dataSource> parameters
+ </caption>
+ <colgroup>
+ <col style="width: 20%;">
+ <col style="width: 10%;">
+ <col style="width: 20%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Required</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">driver</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A class of JDBC driver to use for the target database.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">url</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">JDBC URL of a target database.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">username</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user name.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">password</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user password.</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="dbimportParameters" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 9. <dbimport> parameters
+ </caption>
+ <colgroup>
+ <col style="width: 37.5%;">
+ <col style="width: 12.5%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">defaultPackage</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A Java package that will be set as the imported DataMap default and a package of all the persistent Java classes. This is a required attribute if the "map" itself does not already contain a default package, as otherwise all the persistent classes will be mapped with no package, and will not compile.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">forceDataMapCatalog</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting <code>forceDataMapCatalog</code> to <code>true</code> will set DbEntity catalog to one in the DataMap. Default value is <code>false</code>.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">forceDataMapSchema</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting <code>forceDataMapSchema</code> to <code>true</code> will set DbEntity schema to one in the DataMap. Default value is <code>false</code>.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">meaningfulPkTables</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A comma-separated list of Perl5 patterns that defines which imported tables should have their primary key columns mapped as ObjAttributes. "*" would indicate all tables.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock"><a id="namingStrategy"></a>namingStrategy</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">The naming strategy used for mapping database names to object entity names. Default is <code>o.a.c.dbsync.naming.DefaultObjectNameGenerator</code>.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">skipPrimaryKeyLoading</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether to load primary keys. Default "false".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">skipRelationshipsLoading</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether to load relationships. Default "false".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">stripFromTableNames</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="content">
+ <div class="paragraph">
+ <p>Regex that matches the part of the table name that needs to be stripped off when generating ObjEntity name. Here are some examples:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><!-- Strip prefix -->
+<stripFromTableNames>^myt_</stripFromTableNames>
+
+<!-- Strip suffix -->
+<stripFromTableNames>_s$</stripFromTableNames>
+
+<!-- Strip multiple occurrences in the middle -->
+<stripFromTableNames>_abc</stripFromTableNames></code></pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">usePrimitives</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether numeric and boolean data types should be mapped as Java primitives or Java classes. Default is "true", i.e. primitives will be used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">useJava7Types</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Whether <em>DATE</em>, <em>TIME</em> and <em>TIMESTAMP</em> data types should be mapped as <code>java.util.Date</code> or <code>java.time.* classes</code>. Default is "false", i.e. <code>java.time.*</code> will be used.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">filters configuration</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="content">
+ <div class="paragraph">
+ <p>Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <a href="#db-first-flow">DB-First Flow</a> chapter. Here is some simple example:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><dbimport>
+ <catalog name="test_catalog">
+ <schema name="test_schema">
+ <includeTable>.*</includeTable>
+ <excludeTable>test_table</excludeTable>
+ </schema>
+ </catalog>
+
+ <includeProcedure pattern=".*"/>
+</dbimport></code></pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) :</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>4.1.RC2</version>
+
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <dataSource>
+ <url>jdbc:mysql://127.0.0.1/mydb</url>
+ <driver>com.mysql.jdbc.Driver</driver>
+ <username>sa</username>
+ </dataSource>
+ <dbimport>
+ <defaultPackage>com.example.cayenne</defaultPackage>
+ </dbimport>
+ </configuration>
+ <goals>
+ <goal>cdbimport</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="cdbgen"><a class="anchor" href="#cdbgen"></a>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>
+ <table id="cdbgenTable" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 10. cdbgen required parameters
+ </caption>
+ <colgroup>
+ <col style="width: 16.6666%;">
+ <col style="width: 16.6666%;">
+ <col style="width: 66.6668%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">map</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="content">
+ <div class="paragraph">
+ <p>DataMap XML file which serves as a source of metadata for class generation. E.g.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code>${project.basedir}/src/main/resources/my.map.xml</code></pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">dataSource</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">XML</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">An object that contains Data Source parameters</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="dataSourceParameteres" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 11. <dataSource> parameters
+ </caption>
+ <colgroup>
+ <col style="width: 20%;">
+ <col style="width: 10%;">
+ <col style="width: 20%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Required</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">driver</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">A class of JDBC driver to use for the target database.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">url</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Yes</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">JDBC URL of a target database.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">username</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user name.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">password</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">No</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Database user password.</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="cdbgenOptionl" class="tableblock frame-all grid-all stretch table table-bordered">
+ <caption class="title">
+ Table 12. cdbgen optional parameters
+ </caption>
+ <colgroup>
+ <col style="width: 16.6666%;">
+ <col style="width: 16.6666%;">
+ <col style="width: 66.6668%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Type</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">adapter</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">String</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">createFK</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create foreign key constraints. Default is "true".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">createPK</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">createTables</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should create new tables. Default is "true".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">dropPK</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">dropTables</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>Example - creating a DB schema on a local HSQLDB database:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-xml xml" data-lang="xml"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>4.1.RC2</version>
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
+ <dataSource>
+ <url>jdbc:hsqldb:hsql://localhost/testdb</url>
+ <driver>org.hsqldb.jdbcDriver</driver>
+ <username>sa</username>
+ </dataSource>
+ </configuration>
+ <goals>
+ <goal>cdbgen</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></code></pre>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="gradle_plugin"><a class="anchor" href="#gradle_plugin"></a>6.2. Gradle Plugin</h3>
+ <div class="paragraph">
+ <p>Cayenne Gradle plugin provides tasks similar to <a href="#maven_plugin">Maven plugin</a>. It also provides <code>cayenne</code> extension that has some useful utility methods. Here is example of how to include Cayenne plugin into your project:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">buildscript {
+ // add Maven Central repository
+ repositories {
+ mavenCentral()
+ }
+ // add Cayenne Gradle Plugin
+ dependencies {
+ classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '4.1.RC2'
+ }
+}
+
+// apply plugin
+apply plugin: 'org.apache.cayenne'
+
+// set default DataMap
+cayenne.defaultDataMap 'datamap.map.xml'
+
+// add Cayenne dependencies to your project
+dependencies {
+ // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
+ compile cayenne.dependency('server')
+}</code></pre>
</div>
</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"> Cayenne Gradle plugin is experimental and it’s API may still change. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
<div class="sect3">
- <h4 id="usage-6"><a class="anchor" href="#usage-6"></a>Usage</h4>
+ <h4 id="cgen-2"><a class="anchor" href="#cgen-2"></a>cgen</h4>
<div class="paragraph">
- <p>This module doesn’t require any additional setup.</p>
+ <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>
<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>Here is how you can change settings of the default <code>cgen</code> task:</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 [...]
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cgen {
+ client = false
+ mode = 'all'
+ overwrite = true
+ createPropertiesNames = true
+}</code></pre>
+ </div>
</div>
<div class="paragraph">
- <p>Semantics:</p>
+ <p>And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code>#chain(operator) ... #end
-#chain(operator prefix) ... #end
-#chunk() ... #end
-#chunk(param) ... #end</code></pre>
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">task clientCgen(type: cayenne.cgen) {
+ client = true
+}</code></pre>
</div>
</div>
+ </div>
+ <div class="sect3">
+ <h4 id="cdbimport"><a class="anchor" href="#cdbimport"></a>cdbimport</h4>
<div class="paragraph">
- <p>Full example:</p>
+ <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>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code>#chain('OR' 'WHERE')
- #chunk($name) NAME LIKE #bind($name) #end
- #chunk($id) ARTIST_ID > #bind($id) #end
-#end"</code></pre>
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cdbimport {
+ // map can be skipped if it is defined in cayenne.defaultDataMap
+ map 'datamap.map.xml'
+ // optional project file, will be created if missing
+ cayenneProject 'cayenne-project.xml'
+
+ dataSource {
+ driver 'com.mysql.cj.jdbc.Driver'
+ url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
+ username 'root'
+ password ''
+ }
+
+ dbImport
+ // additional settings
+ usePrimitives false
+ defaultPackage 'org.apache.cayenne.test'
+
+ // DB filter configuration
+ catalog 'catalog-1'
+ schema 'schema-1'
+
+ catalog {
+ name 'catalog-2'
+
+ includeTable 'table0', {
+ excludeColumns '_column_'
+ }
+
+ includeTables 'table1', 'table2', 'table3'
+
+ includeTable 'table4', {
+ includeColumns 'id', 'type', 'data'
+ }
+
+ excludeTable '^GENERATED_.*'
+ }
+
+ catalog {
+ name 'catalog-3'
+ schema {
+ name 'schema-2'
+ includeTable 'test_table'
+ includeTable 'test_table2', {
+ excludeColumn '__excluded'
+ }
+ }
+ }
+
+ includeProcedure 'procedure_test_1'
+
+ includeColumns 'id', 'version'
+
+ tableTypes 'TABLE', 'VIEW'
+ }
+}</code></pre>
</div>
</div>
</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>
+ <h4 id="cdbgen-2"><a class="anchor" href="#cdbgen-2"></a>cdbgen</h4>
<div class="paragraph">
- <p>This module provides basic utilities to bootstrap Cayenne service inside web application.</p>
+ <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>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cdbgen {
+
+ adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
+
+ dataSource {
+ driver 'org.apache.derby.jdbc.EmbeddedDriver'
+ url 'jdbc:derby:build/testdb;create=true'
+ username 'sa'
+ password ''
+ }
+
+ dropTables true
+ dropPk true
+
+ createTables true
+ createPk true
+ createFk true
+}</code></pre>
+ </div>
</div>
</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-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>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-web</artifactId>
- <version>4.1.RC2</version>
-</dependency></code></pre>
- </div>
- </div>
+ <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>
+ <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>
- <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 class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-Groovy Groovy" data-lang="Groovy">cgen.dependsOn cdbimport
+compileJava.dependsOn cgen</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>
+ <h3 id="ant_tasks"><a class="anchor" href="#ant_tasks"></a>6.3. Ant Tasks</h3>
+ <div class="paragraph">
+ <p>Ant tasks are the same as <a href="#maven_plugin">Maven plugin goals</a> described previously, namely "cgen", "cdbgen", "cdbimport". Configuration parameters are also similar (except Maven can guess many defaults that Ant can’t). To include Ant tasks in the project, use the following Antlib:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"><typedef resource="org/apache/cayenne/tools/antlib.xml">
+ <classpath>
+ <fileset dir="lib" >
+ <include name="cayenne-ant-*.jar" />
+ <include name="cayenne-cgen-*.jar" />
+ <include name="cayenne-dbsync-*.jar" />
+ <include name="cayenne-di-*.jar" />
+ <include name="cayenne-project-*.jar" />
+ <include name="cayenne-server-*.jar" />
+ <include name="commons-collections-*.jar" />
+ <include name="commons-lang-*.jar" />
+ <include name="slf4j-api-*.jar" />
+ <include name="velocity-*.jar" />
+ <include name="vpp-2.2.1.jar" />
+ </fileset>
+ </classpath>
+</typedef></code></pre>
</div>
</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-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>
- <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>
+ <h4 id="cgen-3"><a class="anchor" href="#cgen-3"></a>cgen</h4>
</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>
+ <h4 id="cdbgen-3"><a class="anchor" href="#cdbgen-3"></a>cdbgen</h4>
</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-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>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-rop-server</artifactId>
- <version>4.1.RC2</version>
-</dependency></code></pre>
- </div>
- </div>
+ <h4 id="cdbimport-2"><a class="anchor" href="#cdbimport-2"></a>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>
- <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 class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-XML XML" data-lang="XML"> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+ driver="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://127.0.0.1/mydb"
+ username="sa"
+ defaultPackage="com.example.cayenne"/></code></pre>
</div>
</div>
</div>
@@ -5240,7 +5209,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect1">
- <h2 id="appendix-a-configuration-properties"><a class="anchor" href="#appendix-a-configuration-properties"></a>6. Appendix A. Configuration Properties</h2>
+ <h2 id="appendix-a-configuration-properties"><a class="anchor" href="#appendix-a-configuration-properties"></a>7. Appendix A. Configuration Properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Note that the property names below are defined as constants in <code>org.apache.cayenne.configuration.Constants</code> interface.</p>
@@ -5413,7 +5382,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect1">
- <h2 id="appendix-b-service-collections"><a class="anchor" href="#appendix-b-service-collections"></a>7. Appendix B. Service Collections</h2>
+ <h2 id="appendix-b-service-collections"><a class="anchor" href="#appendix-b-service-collections"></a>8. Appendix B. Service Collections</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Note that the collection keys below are defined as constants in <code>org.apache.cayenne.configuration.Constants</code> interface.</p>
@@ -5480,7 +5449,7 @@ public class MyEntity extends _MyEntity {
</div>
</div>
<div class="sect1">
- <h2 id="appendixC"><a class="anchor" href="#appendixC"></a>8. Appendix C. Expressions BNF</h2>
+ <h2 id="appendixC"><a class="anchor" href="#appendixC"></a>9. Appendix C. Expressions BNF</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
@@ -5607,27 +5576,4 @@ NON-TERMINALS
</div>
</div>
</div>
-</div>
-<div class="sect1">
- <h2 id="list-of-tables"><a class="anchor" href="#list-of-tables"></a>9. List of tables</h2>
- <div class="sectionbody">
- <div class="ulist">
- <ul>
- <li> <p><a href="#versionHistory">Cayenne Version History</a></p> </li>
- <li> <p><a href="#pluginParameteres">modeler plugin parameters</a></p> </li>
- <li> <p><a href="#tablecgen">cgen required parameters</a></p> </li>
- <li> <p><a href="#cgenOptional">cgen optional parameters</a></p> </li>
- <li> <p><a href="#cdbgenTable">cdbgen required parameters</a></p> </li>
- <li> <p><a href="#dataSourceParameteres"><dataSource> parameters</a></p> </li>
- <li> <p><a href="#cdbgenOptionl">cdbgen optional parameters</a></p> </li>
- <li> <p><a href="#cdbimportTable">cdbimport parameters</a></p> </li>
- <li> <p><a href="#cdbimportDataSource"><dataSource> parameters</a></p> </li>
- <li> <p><a href="#dbimportParameters"><dbimport> parameters</a></p> </li>
- <li> <p><a href="#persistenceStates">Persistence States</a></p> </li>
- <li> <p><a href="#lifecycleEvent">Lifecycle Event Types</a></p> </li>
- <li> <p><a href="#configProperties">Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</a></p> </li>
- <li> <p><a href="#serviceCollections">Service Collection Keys Present in ServerRuntime and/or ClientRuntime</a></p> </li>
- </ul>
- </div>
- </div>
</div>
\ No newline at end of file
diff --git a/src/main/site/content/docs/4.1/cayenne-guide.toc.html b/src/main/site/content/docs/4.1/cayenne-guide.toc.html
index 120252d..3489bb1 100644
--- a/src/main/site/content/docs/4.1/cayenne-guide.toc.html
+++ b/src/main/site/content/docs/4.1/cayenne-guide.toc.html
@@ -7,7 +7,7 @@
<ul class="sectlevel2 nav">
<li><a href="#setup" class="nav-link">1.1. Setup</a></li>
<li><a href="#cayenne-mapping-structure" class="nav-link">1.2. Cayenne Mapping Structure</a></li>
- <li><a href="#cayennemodeler-application" class="nav-link">1.3. CayenneModeler Application</a></li>
+ <li><a href="#cayenne-modeler" class="nav-link">1.3. CayenneModeler Application</a></li>
</ul> </li>
<li><a href="#cayenne-framework" class="nav-link">2. Cayenne Framework</a>
<ul class="sectlevel2 nav">
@@ -45,9 +45,14 @@
<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>
</ul> </li>
- <li><a href="#appendix-a-configuration-properties" class="nav-link">6. Appendix A. Configuration Properties</a></li>
- <li><a href="#appendix-b-service-collections" class="nav-link">7. Appendix B. Service Collections</a></li>
- <li><a href="#appendixC" class="nav-link">8. Appendix C. Expressions BNF</a></li>
- <li><a href="#list-of-tables" class="nav-link">9. List of tables</a></li>
+ <li><a href="#build_tools" class="nav-link">6. Build Tools</a>
+ <ul class="sectlevel2 nav">
+ <li><a href="#maven_plugin" class="nav-link">6.1. Maven Plugin</a></li>
+ <li><a href="#gradle_plugin" class="nav-link">6.2. Gradle Plugin</a></li>
+ <li><a href="#ant_tasks" class="nav-link">6.3. Ant Tasks</a></li>
+ </ul> </li>
+ <li><a href="#appendix-a-configuration-properties" class="nav-link">7. Appendix A. Configuration Properties</a></li>
+ <li><a href="#appendix-b-service-collections" class="nav-link">8. Appendix B. Service Collections</a></li>
+ <li><a href="#appendixC" class="nav-link">9. Appendix C. Expressions BNF</a></li>
</ul>
</div>
\ No newline at end of file