You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/05 13:17:30 UTC
[5/6] cayenne-website git commit: Update 4.0 and 4.1 docs
http://git-wip-us.apache.org/repos/asf/cayenne-website/blob/ecbc2ebc/src/main/site/content/docs/4.0/cayenne-guide.html
----------------------------------------------------------------------
diff --git a/src/main/site/content/docs/4.0/cayenne-guide.html b/src/main/site/content/docs/4.0/cayenne-guide.html
new file mode 100644
index 0000000..87bfca8
--- /dev/null
+++ b/src/main/site/content/docs/4.0/cayenne-guide.html
@@ -0,0 +1,5604 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+title: "Cayenne Guide"
+description: "Cayenne Guide"
+cayenneVersion: "4.0"
+weight: 10
+menu:
+ footer:
+ weight: 20
+ parent: docs
+ name: "Cayenne Guide (4.0)"
+---
+<div class="sect1">
+ <h2 id="object-relational-mapping-with-cayenne"><a class="anchor" href="#object-relational-mapping-with-cayenne"></a>1. Object Relational Mapping with Cayenne</h2>
+ <div class="sectionbody">
+ <div class="sect2">
+ <h3 id="setup"><a class="anchor" href="#setup"></a>1.1. Setup</h3>
+ <div class="sect3">
+ <h4 id="system-requirements"><a class="anchor" href="#system-requirements"></a>System Requirements</h4>
+ <div class="ulist">
+ <ul>
+ <li> <p>Java: Cayenne runtime framework and CayenneModeler GUI tool are written in 100% Java, and run on any Java-compatible platform. Minimal required JDK version depends on the version of Cayenne you are using, as shown in the following table:</p> </li>
+ </ul>
+ </div>
+ <table id="versionHistory" class="tableblock frame-all grid-all spread table table-bordered">
+ <caption class="title">
+ Table 1. Cayenne Version History
+ </caption>
+ <colgroup>
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3334%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Cayenne Version</th>
+ <th class="tableblock halign-left valign-top">Java Version</th>
+ <th class="tableblock halign-left valign-top">Status</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">4.1</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.8 or newer</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Development</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">4.0</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.7 or newer</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Beta</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">3.1</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.5 or newer</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Stable</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">3.0</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.5</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Aging</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">1.2 / 2.0</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.4</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Legacy</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">1.1</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Java 1.3</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Legacy</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="ulist">
+ <ul>
+ <li> <p>JDBC Driver: An appropriate DB-specific JDBC driver is needed to access the database. It can be included in the application or used in web container DataSource configuration.</p> </li>
+ <li> <p>Third-party Libraries: Cayenne runtime framework has a minimal set of required and a few more optional dependencies on third-party open source packages. See <a href="#include">"Including Cayenne in a Project"</a>. chapter for details.</p> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="runModeler"><a class="anchor" href="#runModeler"></a>Running CayenneModeler</h4>
+ <div class="paragraph">
+ <p>CayenneModeler GUI tool is intended to work with object relational mapping projects. While you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne distribution archive from <a href="http://cayenne.apache.org/download.html" class="bare">http://cayenne.apache.org/download.html</a> matching the OS you are using. Of course Java needs to be installed on the machine where you are going to run the Modeler.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>OS X distribution contains CayenneModeler.app at the root of the distribution disk image.</p> </li>
+ <li> <p>Windows distribution contains CayenneModeler.exe file in the bin directory.</p> </li>
+ <li> <p>Cross-platform distribution (targeting Linux, but as the name implies, compatible with any OS) contains a runnable CayenneModeler.jar in the bin directory. It can be executed either by double-clicking, or if the environment is not configured to execute jars, by running from command-line:</p> </li>
+ </ul>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code>$ java -jar CayenneModeler.jar</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The Modeler can also be started from Maven. While it may look like an exotic way to start a GUI application, it has its benefits - no need to download Cayenne distribution, the version of the Modeler always matches the version of the framework, the plugin can find mapping files in the project automatically. So it is an attractive option to some developers. Maven option requires a declaration in the POM:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-xml xml" data-lang="xml"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-modeler-maven-plugin</artifactId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </plugin>
+ </plugins>
+</build></code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>And then can be run as</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>$ mvn cayenne-modeler:run</pre>
+ </div>
+ </div>
+ <table id="pluginParameteres" class="tableblock frame-all grid-all spread table table-bordered">
+ <caption class="title">
+ Table 2. Modeler plugin parameters
+ </caption>
+ <colgroup>
+ <col style="width: 22.2222%;">
+ <col style="width: 11.1111%;">
+ <col style="width: 66.6667%;">
+ </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">modelFile</p></td>
+ <td class="tableblock halign-left valign-middle"><p class="tableblock">File</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Name of the model file to open. Here is some simple example:</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-modeler-maven-plugin</artifactId>
+ <version>${cayenne.version}</version>
+ <configuration>
+ <modelFile>src/main/resources/cayenne.xml</modelFile>
+ </configuration>
+</plugin></code></pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="cayenne-mapping-structure"><a class="anchor" href="#cayenne-mapping-structure"></a>1.2. Cayenne Mapping Structure</h3>
+ <div class="sect3">
+ <h4 id="cayenne-project"><a class="anchor" href="#cayenne-project"></a>Cayenne Project</h4>
+ <div class="paragraph">
+ <p>A Cayenne project is an XML representation of a model connecting database schema with Java classes. A project is normally created and manipulated via CayenneModeler GUI and then used to initialize Cayenne runtime. A project is made of one or more files. There’s always a root project descriptor file in any valid project. It is normally called cayenne-xyz.xml, where "xyz" is the name of the project.</p>
+ </div>
+ <div class="paragraph">
+ <p>Project descriptor can reference DataMap files, one per DataMap. DataMap files are normally called xyz.map.xml, where "xyz" is the name of the DataMap. For legacy reasons this naming convention is different from the convention for the root project descriptor above, and we may align it in the future versions. Here is how a typical project might look on the file system:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>$ ls -l
+total 24
+-rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
+-rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>DataMap are referenced by name in the root descriptor:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-xml xml" data-lang="xml"><map name="datamap"/></code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Map files are resolved by Cayenne by appending ".map.xml" extension to the map name, and resolving the resulting string relative to the root descriptor URI. The following sections discuss varios ORM model objects, without regards to their XML representation. XML format details are really unimportant to the Cayenne users.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="datamap"><a class="anchor" href="#datamap"></a>DataMap</h4>
+ <div class="paragraph">
+ <p>DataMap is a container of persistent entities and other object-relational metadata. DataMap provides developers with a scope to organize their entities, but it does not provide a namespace for entities. In fact all DataMaps present in runtime are combined in a single namespace. Each DataMap must be associated with a DataNode. This is how Cayenne knows which database to use when running a query.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="datanode"><a class="anchor" href="#datanode"></a>DataNode</h4>
+ <div class="paragraph">
+ <p>DataNode is model of a database. It is actually pretty simple. It has an arbitrary user-provided name and information needed to create or locate a JDBC DataSource. Most projects only have one DataNode, though there may be any number of nodes if needed.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="dbentity"><a class="anchor" href="#dbentity"></a>DbEntity</h4>
+ <div class="paragraph">
+ <p>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships are not strictly tied to FK constraints in DB, and should be mapped for all logical "relationships" between the tables.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="objentity"><a class="anchor" href="#objentity"></a>ObjEntity</h4>
+ <div class="paragraph">
+ <p>ObjEntity is a model of a single persistent Java class. ObjEntity is made of ObjAttributes and ObjRelationships. Both correspond to entity class properties. However ObjAttributes represent "simple" properties (normally things like String, numbers, dates, etc.), while ObjRelationships correspond to properties that have a type of another entity.</p>
+ </div>
+ <div class="paragraph">
+ <p>ObjEntity maps to one or more DbEntities. There’s always one "root" DbEntity for each ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a chain of DbRelationships ("flattened" ObjRelationship).</p>
+ </div>
+ <div class="paragraph">
+ <p>ObjEntities may also contain mapping of their lifecycle callback methods.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="embeddable"><a class="anchor" href="#embeddable"></a>Embeddable</h4>
+ <div class="paragraph">
+ <p>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity, but maps to multiple columns in the database.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="procedure"><a class="anchor" href="#procedure"></a>Procedure</h4>
+ <div class="paragraph">
+ <p>A model of a stored procedure in the database.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="query"><a class="anchor" href="#query"></a>Query</h4>
+ <div class="paragraph">
+ <p>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created in the code. Depending on the circumstances the users may take one or the other approach.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="cayennemodeler-application"><a class="anchor" href="#cayennemodeler-application"></a>1.3. CayenneModeler Application</h3>
+ <div class="sect3">
+ <h4 id="working-with-mapping-projects"><a class="anchor" href="#working-with-mapping-projects"></a>Working with Mapping Projects</h4>
+ </div>
+ <div class="sect3">
+ <h4 id="reverse-engineering-database"><a class="anchor" href="#reverse-engineering-database"></a>Reverse Engineering Database</h4>
+ <div class="paragraph">
+ <p>See chapter <a href="#reverse">Reverse Engineering in Cayenne Modeler</a></p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="generating-database-schema"><a class="anchor" href="#generating-database-schema"></a>Generating Database Schema</h4>
+ <div class="paragraph">
+ <p>With Cayenne Modeler you can create simple database schemas without any additional database tools. This is a good option for initial database setup if you completely created you model with the Modeler. You can start SQL schema generation by selecting menu <strong>Tools > Generate Database Schema</strong></p>
+ </div>
+ <div class="paragraph">
+ <p>You can select what database parts should be generated and what tables you want</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="migrations"><a class="anchor" href="#migrations"></a>Migrations</h4>
+ </div>
+ <div class="sect3">
+ <h4 id="generating-java-classes"><a class="anchor" href="#generating-java-classes"></a>Generating Java Classes</h4>
+ <div class="paragraph">
+ <p>Before using Cayenne in you code you need to generate java source code for persistent objects. This can be done with Modeler GUI or via <a href="#cgen">cgen</a> maven/ant plugin.</p>
+ </div>
+ <div class="paragraph">
+ <p>To generate classes in the modeler use <strong>Tools > Generate Classes</strong></p>
+ </div>
+ <div class="paragraph">
+ <p>There is three default types of code generation</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><strong>Standard Persistent Objects</strong></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Default type of generation suitable for almost all cases. Use this type unless you now what exactly you need to customize.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><strong>Client Persistent Objects</strong></p> </li>
+ <li> <p><strong>Advanced</strong></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>In advanced mode you can control almost all aspects of code generation including custom templates for java code. See default Cayenne templates on GitHub as an example.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="modeling-inheritance"><a class="anchor" href="#modeling-inheritance"></a>Modeling Inheritance</h4>
+ </div>
+ <div class="sect3">
+ <h4 id="modeling-generic-persistent-classes"><a class="anchor" href="#modeling-generic-persistent-classes"></a>Modeling Generic Persistent Classes</h4>
+ <div class="paragraph">
+ <p>Normally each ObjEntity is mapped to a specific Java class (such as Artist or Painting) that explicitly declare all entity properties as pairs of getters and setters. However Cayenne allows to map a completly generic class to any number of entities. The only expectation is that a generic class implements org.apache.cayenne.DataObject. So an ideal candidate for a generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</p>
+ </div>
+ <div class="paragraph">
+ <p>If you don’t enter anything for Java Class of an ObjEntity, Cayenne assumes generic mapping and uses the following implicit rules to determine a class of a generic object. If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new objects. If not, <code>org.apache.cayenne.CayenneDataObject</code> is used.</p>
+ </div>
+ <div class="paragraph">
+ <p>Class generation procedures (either done in the Modeler or with Ant or Maven) would skip entities that are mapped to CayenneDataObject explicitly or have no class mapping.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="mapping-objattributes-to-custom-classes"><a class="anchor" href="#mapping-objattributes-to-custom-classes"></a>Mapping ObjAttributes to Custom Classes</h4>
+ </div>
+ <div class="sect3">
+ <h4 id="modeling-primary-key-generation-strategy"><a class="anchor" href="#modeling-primary-key-generation-strategy"></a>Modeling Primary Key Generation Strategy</h4>
+ </div>
+ </div>
+ </div>
+</div>
+<div class="sect1">
+ <h2 id="cayenne-framework"><a class="anchor" href="#cayenne-framework"></a>2. Cayenne Framework</h2>
+ <div class="sectionbody">
+ <div class="sect2">
+ <h3 id="include"><a class="anchor" href="#include"></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>
+ <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>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>cayenne-di-4.0.B3-SNAPSHOT.jar</code> - Cayenne dependency injection (DI) container library. All applications will require this file.</p> </li>
+ <li> <p><code>cayenne-server-4.0.B3-SNAPSHOT.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.0.B3-SNAPSHOT.jar</code> - a client-side runtime for <a href="#rop">ROP applications</a>.</p> </li>
+ <li> <p>Other cayenne-* jars - various Cayenne tools extensions.</p> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="dependencies"><a class="anchor" href="#dependencies"></a>Dependencies</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>
+ </div>
+ <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>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="maven-projects"><a class="anchor" href="#maven-projects"></a>Maven Projects</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>
+ </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.0.B3-SNAPSHOT</version>
+</dependency></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>
+ </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 overwritten and may be later customized by the user. If "makePairs" is set to "false", a single class will be generated for each ObjEntity.</p>
+ </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 spread 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>
+ <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>${project.basedir}/src/main/resources/my.map.xml</pre>
+ </div>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="cgenOptional" class="tableblock frame-all grid-all spread 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>
+ </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.0.B3-SNAPSHOT</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="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 spread 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>
+ <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>${project.basedir}/src/main/resources/my.map.xml</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 spread 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 spread 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>
+ <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.0.B3-SNAPSHOT</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 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="#dbFirstFlow">"DB-First Flow"</a></p>
+ </div>
+ <table id="cdbimportTable" class="tableblock frame-all grid-all spread 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>
+ <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 settings, such as default Java package, will be preserved (unless changed explicitly in the plugin configuration).</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="#dbFirstFlow">"DB-First Flow"</a> chapter.</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <table id="cdbimportDataSource" class="tableblock frame-all grid-all spread 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 spread 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">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>org.apache.cayenne.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>
+ <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 <code>DATE</code>, <code>TIME</code> and <code>TIMESTAMP</code> 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>
+ <div class="paragraph">
+ <p>Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see <a href="#dbFirstFlow">"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.0.B3-SNAPSHOT</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="sect3">
+ <h4 id="gradle-projects"><a class="anchor" href="#gradle-projects"></a>Gradle Projects</h4>
+ <div class="paragraph">
+ <p>To include Cayenne into your Gradle project you have two options:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Simply add Cayenne as a dependency:</p> </li>
+ </ul>
+ </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.0.B3-SNAPSHOT'</code></pre>
+ </div>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Or you can use Cayenne Gradle plugin</p> </li>
+ </ul>
+ </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.0.B3-SNAPSHOT'
+ }
+}
+
+// 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')
+ compile cayenne.dependency('java8')
+}</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>
+ </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>
+ <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="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>
+ <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'
+
+ 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 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>
+ </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>
+ </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>
+ </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="sect4">
+ <h5 id="cgen-3"><a class="anchor" href="#cgen-3"></a>cgen</h5>
+ </div>
+ <div class="sect4">
+ <h5 id="cdbgen-3"><a class="anchor" href="#cdbgen-3"></a>cdbgen</h5>
+ </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>
+ </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>
+ </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>
+ </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>
+ </div>
+ <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="#customize">"Customizing Cayenne Runtime"</a> chapter. Here we’ll just show an example of how an application might turn on external transactions:</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>
+ </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>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">runtime.shutdown();</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="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 DataNodes 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>DataDomainProvider.createAndInitDataDomain()</code>.</p> </li>
+ </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 somewhere and provide the application code with means to access it. And shut it down when the application ends to avoid container leaks.</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>
+ </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>
+ <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="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-and-objectcontext"><a class="anchor" href="#persistent-objects-and-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 each unique database row. This allows users to isolate object changes from one another by using separate ObjectContexts.</p>
+ </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 carrying uncommitted changes to objects from request to request, until he decides to commit or rollback them). Even for a single user it might make sense to use mutliple ObjectContexts (e.g. request-scoped contexts to allow concurrent requests from the browser that change and commit objects independently).</p>
+ </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 interface</code>. 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 - objectId, persistenceState and objectContext. 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 spread 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 ObjectContext is to select some objects from a database. This is done by calling "performQuery" method:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">SelectQuery query = new SelectQuery(Artist.class);
+List<Artist> artists = context.performQuery(query);</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>We’ll discuss queries in some detail in the following chapters. The example above is self-explanatory - we create a SelectQuery that matches all Artist objects present in the database, and then call "performQuery", getting a list of Artist objects.</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 "performGenericQuery"method. While not nearly as commonly-used as "performQuery", 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 "MODIFIED" by Cayenne. Cayenne tracks all in-memory changes until a user calls "commitChanges":</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 "commitChanges" commits just one object, but generally it can be any number of objects.</p>
+ </div>
+ <di
<TRUNCATED>