cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1406588 [2/3] - in /cayenne/site/cms/trunk/content/v31/cayenne-guide: ./ css/ images/
Date Wed, 07 Nov 2012 12:36:49 GMT
Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/including-cayenne-in-project.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/including-cayenne-in-project.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/including-cayenne-in-project.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/including-cayenne-in-project.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,356 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="next" href="starting-cayenne.html" title="Chapter&nbsp;5.&nbsp;Starting Cayenne"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align=
 "right">&nbsp;<a accesskey="n" href="starting-cayenne.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;4.&nbsp;Including Cayenne in a Project"><div class="titlepage"><div><div><h2 class="title"><a name="including-cayenne-in-project"></a>Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="including-cayenne-in-project.html#jar-files-and-depdendencies">Jar Files and Dependencies</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#maven-projects">Maven Projects</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#ant-projects">Ant Projects</a></span></dt></dl></div><div class="section" title="Jar Files and Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="jar-files-and-depdendencies"></a>Jar Files and Dependencies</h2></div></div></div><p>Cayenne distri
 bution contains the following core runtime jars in the distribution
+				<code class="code">lib</code> directory: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">cayenne-server-x.x.jar</span> - contains full
+						Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
+						will use only this file.</p></li><li class="listitem"><p>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
+						the client in an ROP application.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne extensions.</p></li></ul></div><p>When using <code class="code">cayenne-server-x.x.jar</code> you'll need a few third party jars (all
+			included in <code class="code">lib/third-party</code> directory of the distribution): </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://velocity.apache.org/" target="_top">Apache Velocity
+							Template Engine</a>, version 1.6.x (and all its dependencies bundled
+						with velocity-dep)</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/collections/" target="_top">Apache Commons
+							Collections</a>, version 3.2.1</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/logging/" target="_top">Apache
+							Commons Logging</a>, version 1.1</p></li></ul></div><p>Cayenne integrates with various caching, clustering and other frameworks. These
+			optional integrations will require other third-party jars that the users will need to
+			obtain on their own.</p></div><div class="section" title="Maven Projects"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><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><pre class="programlisting">&lt;dependency&gt;
+   &lt;groupId&gt;org.apache.cayenne&lt;/groupId&gt;
+   &lt;artifactId&gt;cayenne-server&lt;/artifactId&gt;
+   &lt;version&gt;X.Y.Z&lt;/version&gt;
+&lt;/dependency&gt;</pre><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 class="code">org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</p><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">maven-cayenne-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><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><p>
+				</p><table frame="void" id="d0e226"><caption>Table&nbsp;4.1.&nbsp;cgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">map</code>
+							</td>
+							<td>File</td>
+							<td>DataMap XML file which serves as a source of metadata for class
+								generation. E.g.
+									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+						</tr><tr>
+							<td><code class="code">destDir</code></td>
+							<td>File</td>
+							<td>Root destination directory for Java classes (ignoring their package
+								names).</td>
+						</tr></tbody></table><p>
+				</p><table frame="void" id="d0e273"><caption>Table&nbsp;4.2.&nbsp;cgen optional parameters</caption><col width="33%"><col width="8%"><col width="59%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">additionalMaps</code>
+							</td>
+							<td>File</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">client</code></td>
+							<td>boolean</td>
+							<td>Whether we are generating classes for the client tier in a Remote
+								Object Persistence application. "False" by default.</td>
+						</tr><tr>
+							<td><code class="code">embeddableTemplate</code></td>
+							<td>String</td>
+							<td>Location of a custom Velocity template file for Embeddable class
+								generation. If omitted, default template is used.</td>
+						</tr><tr>
+							<td><code class="code">embeddableSuperTemplate</code></td>
+							<td>String</td>
+							<td>Location of a custom Velocity template file for Embeddable
+								superclass generation. Ignored unless "makepairs" set to "true". If
+								omitted, default template is used.</td>
+						</tr><tr>
+							<td><code class="code">encoding</code></td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">excludeEntities</code></td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">includeEntities</code></td>
+							<td>String</td>
+							<td>A comma-separated list of ObjEntity patterns (expressed as a perl5
+								regex) to include from template generation. By default all DataMap
+								entities are included.</td>
+						</tr><tr>
+							<td><code class="code">makePairs</code></td>
+							<td>boolean</td>
+							<td>If "true" (a recommended default), will generate subclass/superclass
+								pairs, with all generated code placed in superclass.</td>
+						</tr><tr>
+							<td><code class="code">mode</code></td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">overwrite</code></td>
+							<td>boolean</td>
+							<td>Only has effect when "makePairs" is set to "false". If "overwrite"
+								os "true", will overwrite older versions of generated classes.</td>
+						</tr><tr>
+							<td><code class="code">superPkg</code></td>
+							<td>String</td>
+							<td>Java package name of generated superclasses. Only has effect if
+								"makepairs" and "usePkgPath" are set to "true" (both are true by
+								default). Defines a common package for all generated Java classes.
+								If omitted, each superclass will be placed in the same package as
+								subclass.</td>
+						</tr><tr>
+							<td><code class="code">superTemplate</code></td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">template</code></td>
+							<td>String</td>
+							<td>Location of a custom Velocity template file for ObjEntity class
+								generation. If omitted, default template is used.</td>
+						</tr><tr>
+							<td><code class="code">usePkgPath</code></td>
+							<td>boolean</td>
+							<td>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.</td>
+						</tr></tbody></table><p>Example - a typical class generation scenario, where pairs of classes are
+				generated, and superclasses are placed in a separate package:
+				</p><pre class="programlisting">&lt;plugin&gt;
+	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+	&lt;version&gt;X.Y.Z&lt;/version&gt;
+
+	&lt;!-- 
+	There's an intermittent problem when using Maven/cgen in Eclipse with  m2eclipse plugin that
+    requires placing "configuration" section at the plugin level, instead of execution
+    level.
+	--&gt;
+	&lt;configuration&gt;
+		&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+		&lt;destDir&gt;${project.basedir}/src/main/java&lt;/destDir&gt;
+		&lt;superPkg&gt;org.example.model.auto&lt;/superPkg&gt;
+	&lt;/configuration&gt;
+
+	&lt;executions&gt;
+		&lt;execution&gt;
+			&lt;goals&gt;
+				&lt;goal&gt;cgen&lt;/goal&gt;
+			&lt;/goals&gt;
+		&lt;/execution&gt;
+	&lt;/executions&gt;
+&lt;/plugin&gt;</pre></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbgen"></a>cdbgen</h3></div></div></div><p><code class="code">cdbgen</code> is a <code class="code">maven-cayenne-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><table frame="void" id="d0e474"><caption>Table&nbsp;4.3.&nbsp;cdbgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">map</code>
+							</td>
+							<td>File</td>
+							<td>DataMap XML file which serves as a source of metadata for DB schema
+								generation. E.g.
+									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+						</tr><tr>
+							<td><code class="code">driver</code></td>
+							<td>String</td>
+							<td>A class of JDBC driver to use for the target database.</td>
+						</tr><tr>
+							<td><code class="code">url</code></td>
+							<td>String</td>
+							<td>JDBC connection URL of a target database.</td>
+						</tr></tbody></table><p>
+				</p><table frame="void" width="792" id="d0e534"><caption>Table&nbsp;4.4.&nbsp;cdbgen optional parameters</caption><col width="18%"><col width="7%"><col width="79%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">adapter</code>
+							</td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">createFK</code></td>
+							<td>boolean</td>
+							<td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
+						</tr><tr>
+							<td><code class="code">createPK</code></td>
+							<td>boolean</td>
+							<td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
+								"true".</td>
+						</tr><tr>
+							<td><code class="code">createTables</code></td>
+							<td>boolean</td>
+							<td>Indicates whether cdbgen should create new tables. Default is "true".</td>
+						</tr><tr>
+							<td><code class="code">dropPK</code></td>
+							<td>boolean</td>
+							<td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
+								"false".</td>
+						</tr><tr>
+							<td><code class="code">dropTables</code></td>
+							<td>boolean</td>
+							<td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
+								Default is "false".</td>
+						</tr><tr>
+							<td><code class="code">password</code></td>
+							<td>String</td>
+							<td>Database user password.</td>
+						</tr><tr>
+							<td><code class="code">username</code></td>
+							<td>String</td>
+							<td>Database user name.</td>
+						</tr></tbody></table><p>
+			</p><p>Example - creating a DB schema on a local HSQLDB
+				database:</p><pre class="programlisting">&lt;plugin&gt;
+	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+	&lt;version&gt;X.Y.Z&lt;/version&gt;
+
+	&lt;executions&gt;
+		&lt;execution&gt;
+			&lt;configuration&gt;
+				&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+				&lt;url&gt;jdbc:hsqldb:hsql://localhost/testdb&lt;/url&gt;
+				&lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
+				&lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;                        
+				&lt;username&gt;sa&lt;/username&gt;
+			&lt;/configuration&gt;
+			&lt;goals&gt;
+				&lt;goal&gt;cdbgen&lt;/goal&gt;
+			&lt;/goals&gt;
+		&lt;/execution&gt;
+	&lt;/executions&gt;
+&lt;/plugin&gt;</pre></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbimport"></a>cdbimport</h3></div></div></div><p><code class="code">cdbimport</code> is a <code class="code">maven-cayenne-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, which may be necessary if you are also using the cgen task.</p><table frame="void" id="d0e665"><caption>Table&nbsp;4.5.&nbsp;cdbimport required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">map</code>
+							</td>
+							<td>File</td>
+							<td>DataMap XML file which is the destination of the schema import.
+								Maybe an existing file. If this file does not exist, it is created
+								when cdbimport is executed. E.g.
+									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+						</tr><tr>
+							<td><code class="code">driver</code></td>
+							<td>String</td>
+							<td>A class of JDBC driver to use for the target database.</td>
+						</tr><tr>
+							<td><code class="code">url</code></td>
+							<td>String</td>
+							<td>JDBC connection URL of a target database.</td>
+						</tr></tbody></table><p>
+				</p><table frame="void" width="822" id="d0e725"><caption>Table&nbsp;4.6.&nbsp;cdbimport optional parameters</caption><col width="24%"><col width="7%"><col width="79%"><thead><tr>
+							<th>Name</th>
+							<th>Type</th>
+							<th>Description</th>
+						</tr></thead><tbody><tr>
+							<td><code class="code">adapter</code>
+							</td>
+							<td>String</td>
+							<td>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.</td>
+						</tr><tr>
+							<td><code class="code">importProcedures</code></td>
+							<td>boolean</td>
+							<td>Indicates whether stored procedures should be imported from the
+								database. Default is false. </td>
+						</tr><tr>
+							<td><code class="code">meaningfulPk</code></td>
+							<td>boolean</td>
+							<td>Indicates whether primary keys should be mapped as attributes of the
+								ObjEntity. Default is false. </td>
+						</tr><tr>
+							<td><code class="code">namingStrategy</code></td>
+							<td>String</td>
+							<td>The naming strategy used for mapping database names to object entity
+								names. Default is
+									<code class="code">org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
+							</td>
+						</tr><tr>
+							<td><code class="code">overwriteExisting</code></td>
+							<td>boolean</td>
+							<td>Indicates whether existing DB and object entities should be
+								overwritten. This is an all-or-nothing setting. If you need finer
+								granularity, use the CayenneModeler. Default is "true". </td>
+						</tr><tr>
+							<td><code class="code">password</code></td>
+							<td>String</td>
+							<td>Database user password.</td>
+						</tr><tr>
+							<td><code class="code">procedurePattern</code></td>
+							<td>String</td>
+							<td>Pattern to match stored procedure names against for import. Default
+								is to match all stored procedures. This value is only meaningful if
+								importProcedures is true. </td>
+						</tr><tr>
+							<td><code class="code">schemaName</code></td>
+							<td>String</td>
+							<td>Database schema to import tables/stored procedures from. </td>
+						</tr><tr>
+							<td><code class="code">tablePattern</code></td>
+							<td>String</td>
+							<td>Pattern to match table names against for import. Default is to match
+								all tables. </td>
+						</tr><tr>
+							<td><code class="code">username</code></td>
+							<td>String</td>
+							<td>Database user name.</td>
+						</tr></tbody></table><p>
+			</p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse
+				operation compared to the cdbgen example above)
+				:</p><pre class="programlisting">&lt;plugin&gt;
+	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+	&lt;version&gt;X.Y.Z&lt;/version&gt;
+
+	&lt;executions&gt;
+		&lt;execution&gt;
+			&lt;configuration&gt;
+				&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+				&lt;url&gt;jdbc:hsqldb:hsql://localhost/testdb&lt;/url&gt;
+				&lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
+				&lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;                        
+				&lt;username&gt;sa&lt;/username&gt;
+			&lt;/configuration&gt;
+			&lt;goals&gt;
+				&lt;goal&gt;cdbimport&lt;/goal&gt;
+			&lt;/goals&gt;
+		&lt;/execution&gt;
+	&lt;/executions&gt;
+&lt;/plugin&gt;</pre></div></div><div class="section" title="Ant Projects"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div></div><div class="section" title="cdataport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdataport"></a>cdataport</h3></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a>&nbsp;</td><td width="20
 %" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part&nbsp;II.&nbsp;Cayenne Framework&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;Starting Cayenne</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/index.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/index.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/index.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/index.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,11 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Cayenne Guide</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="next" href="cayenne-guide-part1.html" title="Part&nbsp;I.&nbsp;Object Relational Mapping with Cayenne"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Cayenne Guide</th></tr><tr><td width="20%" align="left">&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="cayenne-guide-part1.html">Next</a></td></tr></table><hr></div><div class="book" title="Cayenne Guide"><div class="titlepage"><div><div><h1 class="title"><a name="cayenne-guide"></a>Cayenne Guide</h1></div><div><p class="copyright">Copyright &copy; 2011-2012 Apache Software Foundation and i
 ndividual authors</p></div><div><div class="legalnotice" title="License"><a name="d0e10"></a><p class="legalnotice-title"><b>License</b></p><p>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</p><p>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.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="part"><a href="cayenne-guide-part1.html">I. Object Relational Mapping with Cayenne</a></span></dt><dd><dl><dt><span class="chapter"><a href="setup.html">1. Setup</a></span></dt><dd><dl><dt><span class="section"><a href="setup.html#system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="setup.html#running-cayennemodeler">Running CayenneModeler</a></span></dt></dl></dd><dt><span class="chapter"><a href="cayenne-mapping-structure.html">2. Cayenne Mapping Structure</a></span></dt><dd><dl><dt><span class="section"><a href="cayenne-mapping-structure.html#cayenne-project">Cayenne Project</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#datamap">DataMap</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#datanode">DataNod
 e</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#dbentity">DbEntity</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#objentity">ObjEntity</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#embeddable">Embeddable</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#procedure">Procedure</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#query">Query</a></span></dt><dt><span class="section"><a href="cayenne-mapping-structure.html#listeners-and-callbacks">Listeners and Callbacks</a></span></dt></dl></dd><dt><span class="chapter"><a href="cayennemodeler-application.html">3. CayenneModeler Application</a></span></dt><dd><dl><dt><span class="section"><a href="cayennemodeler-application.html#working-with-mapping-projects">Working with Mapping Projects</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html
 #reverse-engineering-database">Reverse Engineering Database</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#generating-database-schema">Generating Database Schema</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#migrations">Migrations</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#generating-java-classes">Generating Java Classes</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#modeling-inheritance">Modeling Inheritance</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#modeling-generic-persistence-classes">Modeling Generic Persistent Classes</a></span></dt><dt><span class="section"><a href="cayennemodeler-application.html#modeling-pk-generation-strategy">Modeling Primary Key Generation Strategy</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="cayenne-guide-part2.html">II. Cayenne Framework</a><
 /span></dt><dd><dl><dt><span class="chapter"><a href="including-cayenne-in-project.html">4. Including Cayenne in a Project</a></span></dt><dd><dl><dt><span class="section"><a href="including-cayenne-in-project.html#jar-files-and-depdendencies">Jar Files and Dependencies</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#maven-projects">Maven Projects</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#ant-projects">Ant Projects</a></span></dt></dl></dd><dt><span class="chapter"><a href="starting-cayenne.html">5. Starting Cayenne</a></span></dt><dd><dl><dt><span class="section"><a href="starting-cayenne.html#starting-serverruntime">Starting and Stopping ServerRuntime</a></span></dt><dt><span class="section"><a href="starting-cayenne.html#d0e914">Merging Multiple Projects</a></span></dt><dt><span class="section"><a href="starting-cayenne.html#webapps">Web Applications</a></span></dt></dl></dd><dt><span class="cha
 pter"><a href="persistent-objects-objectcontext.html">6. Persistent Objects and ObjectContext</a></span></dt><dd><dl><dt><span class="section"><a href="persistent-objects-objectcontext.html#objectcontext">ObjectContext</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#persistent-lifecycle">Persistent Object and its Lifecycle</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#persistent-operations">ObjectContext Persistence API</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#cayenne-helper-class">Cayenne Helper Class</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#objectcontext-nesting">ObjectContext Nesting</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#generic-persistent-objects">Generic Persistent Objects</a></span></dt><dt><span class="section"><a href="persistent-objects-objectc
 ontext.html#transactions">Transactions</a></span></dt></dl></dd><dt><span class="chapter"><a href="expressions.html">7. Expressions</a></span></dt><dd><dl><dt><span class="section"><a href="expressions.html#expressions-overview">Expressions Overview</a></span></dt><dt><span class="section"><a href="expressions.html#path-expressions">Path Expressions</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-from-strings">Creating Expressions from Strings </a></span></dt><dt><span class="section"><a href="expressions.html#expressions-with-expressionfactory">Creating Expressions with API</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-in-memory">Evaluating Expressions in Memory</a></span></dt></dl></dd><dt><span class="chapter"><a href="orderings.html">8. Orderings</a></span></dt><dt><span class="chapter"><a href="queries.html">9. Queries</a></span></dt><dd><dl><dt><span class="section"><a href="queries.html#selectquery">Selec
 tQuery</a></span></dt><dt><span class="section"><a href="queries.html#ejbqlquery">EJBQLQuery</a></span></dt><dt><span class="section"><a href="queries.html#sqltemplate">SQLTemplateQuery</a></span></dt><dt><span class="section"><a href="queries.html#procedurequery">ProcedureQuery</a></span></dt><dt><span class="section"><a href="queries.html#namedquery">NamedQuery</a></span></dt><dt><span class="section"><a href="queries.html#custom-queries">Custom Queries</a></span></dt></dl></dd><dt><span class="chapter"><a href="lifecycle-events.html">10. Lifecycle Events</a></span></dt><dd><dl><dt><span class="section"><a href="lifecycle-events.html#types-of-lifecycle-events">Types of Lifecycle Events</a></span></dt><dt><span class="section"><a href="lifecycle-events.html#lifecycle-callbacks-listeners">Lifecycle Callbacks and Listeners</a></span></dt></dl></dd><dt><span class="chapter"><a href="performance-tuning.html">11. Performance Tuning</a></span></dt><dd><dl><dt><span class="section
 "><a href="performance-tuning.html#prefetching">Prefetching</a></span></dt><dt><span class="section"><a href="performance-tuning.html#datarows">Data Rows</a></span></dt><dt><span class="section"><a href="performance-tuning.html#iterated-queries">Iterated Queries</a></span></dt><dt><span class="section"><a href="performance-tuning.html#paginated-queries">Paginated Queries</a></span></dt><dt><span class="section"><a href="performance-tuning.html#caching-and-fresh-data">Caching and Fresh Data</a></span></dt><dt><span class="section"><a href="performance-tuning.html#turning-off-synchronization-of-objectcontexts">Turning off Synchronization of ObjectContexts</a></span></dt></dl></dd><dt><span class="chapter"><a href="customizing-cayenne-runtime.html">12. Customizing Cayenne Runtime</a></span></dt><dd><dl><dt><span class="section"><a href="customizing-cayenne-runtime.html#depdendency-injection-container">Dependency Injection Container</a></span></dt><dt><span class="section"><a hr
 ef="customizing-cayenne-runtime.html#ways-to-customize-runtime"> Customization Strategies</a></span></dt><dt><span class="section"><a href="customizing-cayenne-runtime.html#noteworthy-runtime-components">Noteworthy Built-in Services</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="cayenne-guide-part3.html">III. Cayenne Framework - Remote Object Persistence </a></span></dt><dd><dl><dt><span class="chapter"><a href="introduction-to-rop.html">13. Introduction to ROP</a></span></dt><dd><dl><dt><span class="section"><a href="introduction-to-rop.html#what-is-rop">What is ROP</a></span></dt><dt><span class="section"><a href="introduction-to-rop.html#main-features">Main Features</a></span></dt></dl></dd><dt><span class="chapter"><a href="rop-setup.html">14. ROP Setup</a></span></dt><dd><dl><dt><span class="section"><a href="rop-setup.html#rop-system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="rop-setup.html#rop-jar-files-depe
 ndencies">Jar Files and Dependencies</a></span></dt></dl></dd><dt><span class="chapter"><a href="implementing-rop-server.html">15. Implementing ROP Server</a></span></dt><dt><span class="chapter"><a href="implementing-rop-client.html">16. Implementing ROP Client</a></span></dt><dt><span class="chapter"><a href="rop-deployment.html">17. ROP Deployment</a></span></dt><dd><dl><dt><span class="section"><a href="rop-deployment.html#deploying-rop-server">Deploying ROP Server</a></span></dt><dt><span class="section"><a href="rop-deployment.html#deploying-rop-client">Deploying ROP Client</a></span></dt><dt><span class="section"><a href="rop-deployment.html#rop-security">Security</a></span></dt></dl></dd><dt><span class="chapter"><a href="current-limitations.html">18. Current Limitations</a></span></dt></dl></dd><dt><span class="appendix"><a href="server-configuration-properties.html">A. Configuration Properties</a></span></dt><dt><span class="appendix"><a href="client-configuration-
 properties.html">B. Service Collections</a></span></dt><dt><span class="appendix"><a href="expressions-bnf.html">C. Expressions BNF</a></span></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>4.1. <a href="including-cayenne-in-project.html#d0e226">cgen required parameters</a></dt><dt>4.2. <a href="including-cayenne-in-project.html#d0e273">cgen optional parameters</a></dt><dt>4.3. <a href="including-cayenne-in-project.html#d0e474">cdbgen required parameters</a></dt><dt>4.4. <a href="including-cayenne-in-project.html#d0e534">cdbgen optional parameters</a></dt><dt>4.5. <a href="including-cayenne-in-project.html#d0e665">cdbimport required parameters</a></dt><dt>4.6. <a href="including-cayenne-in-project.html#d0e725">cdbimport optional parameters</a></dt><dt>6.1. <a href="persistent-objects-objectcontext.html#d0e1012">Persistence States</a></dt><dt>A.1. <a href="server-configuration-properties.html#d0e1798">Configuration Properties Recognized by Serv
 erRuntime and/or ClientRuntime</a></dt><dt>B.1. <a href="client-configuration-properties.html#d0e2056">Service Collection Keys Present in ServerRuntime and/or ClientRuntime</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left">&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="cayenne-guide-part1.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right" valign="top">&nbsp;Part&nbsp;I.&nbsp;Object Relational Mapping with Cayenne</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/introduction-to-rop.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/introduction-to-rop.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/introduction-to-rop.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/introduction-to-rop.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,3 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;13.&nbsp;Introduction to ROP</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part3.html" title="Part&nbsp;III.&nbsp;Cayenne Framework - Remote Object Persistence"><link rel="prev" href="cayenne-guide-part3.html" title="Part&nbsp;III.&nbsp;Cayenne Framework - Remote Object Persistence"><link rel="next" href="rop-setup.html" title="Chapter&nbsp;14.&nbsp;ROP Setup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;13.&nbsp;Introduction to ROP</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part3.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;III.&nbsp;Cayenne Framework 
 - Remote Object Persistence </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="rop-setup.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;13.&nbsp;Introduction to ROP"><div class="titlepage"><div><div><h2 class="title"><a name="introduction-to-rop"></a>Chapter&nbsp;13.&nbsp;Introduction to ROP</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="introduction-to-rop.html#what-is-rop">What is ROP</a></span></dt><dt><span class="section"><a href="introduction-to-rop.html#main-features">Main Features</a></span></dt></dl></div><div class="section" title="What is ROP"><div class="titlepage"><div><div><h2 class="title"><a name="what-is-rop"></a>What is ROP</h2></div></div></div></div><div class="section" title="Main Features"><div class="titlepage"><div><div><h2 class="title"><a name="main-features"></a>Main Features</h2></div></div></div></div></div><div class="navfooter"><hr><ta
 ble width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cayenne-guide-part3.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part3.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="rop-setup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part&nbsp;III.&nbsp;Cayenne Framework - Remote Object Persistence &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;14.&nbsp;ROP Setup</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/lifecycle-events.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/lifecycle-events.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/lifecycle-events.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/lifecycle-events.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,3 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;10.&nbsp;Lifecycle Events</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="queries.html" title="Chapter&nbsp;9.&nbsp;Queries"><link rel="next" href="performance-tuning.html" title="Chapter&nbsp;11.&nbsp;Performance Tuning"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;10.&nbsp;Lifecycle Events</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="queries.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="performance-tuni
 ng.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;10.&nbsp;Lifecycle Events"><div class="titlepage"><div><div><h2 class="title"><a name="lifecycle-events"></a>Chapter&nbsp;10.&nbsp;Lifecycle Events</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="lifecycle-events.html#types-of-lifecycle-events">Types of Lifecycle Events</a></span></dt><dt><span class="section"><a href="lifecycle-events.html#lifecycle-callbacks-listeners">Lifecycle Callbacks and Listeners</a></span></dt></dl></div><div class="section" title="Types of Lifecycle Events"><div class="titlepage"><div><div><h2 class="title"><a name="types-of-lifecycle-events"></a>Types of Lifecycle Events</h2></div></div></div></div><div class="section" title="Lifecycle Callbacks and Listeners"><div class="titlepage"><div><div><h2 class="title"><a name="lifecycle-callbacks-listeners"></a>Lifecycle Callbacks and Listeners</h2></div></div>
 </div><div class="section" title="Callback and Listener Methods Semantics"><div class="titlepage"><div><div><h3 class="title"><a name="callback-listener-method-semantics"></a>Callback and Listener Methods Semantics</h3></div></div></div></div><div class="section" title="Registering Callbacks and Listeners"><div class="titlepage"><div><div><h3 class="title"><a name="registering-callbacks-listeners"></a>Registering Callbacks and Listeners</h3></div></div></div></div><div class="section" title="Combining Listeners with DataChannelFilters"><div class="titlepage"><div><div><h3 class="title"><a name="comining-listeners-with-datachannelfilters"></a>Combining Listeners with DataChannelFilters</h3></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td>
 <td width="40%" align="right">&nbsp;<a accesskey="n" href="performance-tuning.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;9.&nbsp;Queries&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;11.&nbsp;Performance Tuning</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/orderings.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/orderings.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/orderings.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/orderings.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,12 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;8.&nbsp;Orderings</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="expressions.html" title="Chapter&nbsp;7.&nbsp;Expressions"><link rel="next" href="queries.html" title="Chapter&nbsp;9.&nbsp;Queries"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;8.&nbsp;Orderings</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="expressions.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="queries.html">Next</a></td></tr></table><hr
 ></div><div class="chapter" title="Chapter&nbsp;8.&nbsp;Orderings"><div class="titlepage"><div><div><h2 class="title"><a name="orderings"></a>Chapter&nbsp;8.&nbsp;Orderings</h2></div></div></div><p>An Ordering object defines how a list of objects should be ordered. Orderings are
+			essentially path expressions combined with a sorting strategy. Creating an Ordering:
+			</p><pre class="programlisting">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASENDING);</pre><p>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
+		occurs in the database). Also like expressions, orderings can be used in memory, naturally -
+		to sort
+		objects:</p><pre class="programlisting">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
+List&lt;Painting&gt; list = ...
+o.orderList(list);</pre><p>Note
+		that unlike filtering with Expressions, ordering is performed in-place. This list object is
+		reordered and no new list is created.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="expressions.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="queries.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;7.&nbsp;Expressions&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;9.&nbsp;Queries</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/performance-tuning.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/performance-tuning.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/performance-tuning.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/performance-tuning.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,65 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;11.&nbsp;Performance Tuning</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="lifecycle-events.html" title="Chapter&nbsp;10.&nbsp;Lifecycle Events"><link rel="next" href="customizing-cayenne-runtime.html" title="Chapter&nbsp;12.&nbsp;Customizing Cayenne Runtime"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;11.&nbsp;Performance Tuning</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="lifecycle-events.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="ri
 ght">&nbsp;<a accesskey="n" href="customizing-cayenne-runtime.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;11.&nbsp;Performance Tuning"><div class="titlepage"><div><div><h2 class="title"><a name="performance-tuning"></a>Chapter&nbsp;11.&nbsp;Performance Tuning</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="performance-tuning.html#prefetching">Prefetching</a></span></dt><dt><span class="section"><a href="performance-tuning.html#datarows">Data Rows</a></span></dt><dt><span class="section"><a href="performance-tuning.html#iterated-queries">Iterated Queries</a></span></dt><dt><span class="section"><a href="performance-tuning.html#paginated-queries">Paginated Queries</a></span></dt><dt><span class="section"><a href="performance-tuning.html#caching-and-fresh-data">Caching and Fresh Data</a></span></dt><dt><span class="section"><a href="performance-tuning.html#turning-off-synchroniza
 tion-of-objectcontexts">Turning off Synchronization of ObjectContexts</a></span></dt></dl></div><div class="section" title="Prefetching"><div class="titlepage"><div><div><h2 class="title"><a name="prefetching"></a>Prefetching</h2></div></div></div><p>Prefetching is a technique that allows to bring back in one query not only the queried
+			objects, but also objects related to them. In other words it is a controlled eager
+			relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning"
+			chapter, as it is a powerful performance optimization method. Another common application
+			of prefetching is for refreshing stale object relationships.</p><p>Prefetching example:
+			</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class);
+
+// this instructs Cayenne to prefetch one of Artist's relationships
+query.addPrefetch("paintings");
+
+// query is expecuted as usual, but the resulting Artists will have
+// their paintings "inflated"
+List&lt;Artist&gt; artists = context.performQuery(query);</pre><p>
+			All types of relationships can be preftetched - to-one, to-many, flattened. </p><p>A prefetch can span multiple relationships:
+			</p><pre class="programlisting"> query.addPrefetch("paintings.gallery");</pre><p>A query can have multiple
+			prefetches:</p><pre class="programlisting">query.addPrefetch("paintings"); 
+query.addPrefetch("paintings.gallery"); </pre><p>If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint"
+			prefetches are executed (see prefetching semantics discussion below for what disjoint and
+			joint prefetches mean).</p><div class="section" title="Prefetching Semantics"><div class="titlepage"><div><div><h3 class="title"><a name="prefetching-semantics"></a>Prefetching Semantics</h3></div></div></div><p>Prefetching semantics defines a strategy to prefetch relationships. Depending on
+				it, Cayenne would generate different types of queries. The end result is the same -
+				query root objects with related objects fully resolved. However semantics can affect
+				preformance, in some cases significantly. There are 3 types of prefetch semantics,
+				all defined as constants in
+				org.apache.cayenne.query.PrefetchTreeNode:</p><pre class="programlisting">PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS
+PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS
+PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</pre><p>Each query has a default prefetch semantics, so generally users do not have to
+				worry about changing it, except when performance is a concern, or a few special
+				cases when a default sematics can't produce the correct result. SelectQuery uses
+				DISJOINT_PREFETCH_SEMANTICS by default. Semantics can be changed as
+				follows:</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class); 
+query.addPrefetch("paintings").setSemantics(
+                PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS); </pre><p>There's no limitation on mixing different types of semantics in the same
+				SelectQuery. Multiple prefetches each can have its own semantics. </p><p>SQLTemplate and ProcedureQuery are both using JOINT_PREFETCH_SEMANTICS and it can
+				not be changed due to the nature of these two queries.</p></div><div class="section" title="Disjoint Prefetching Semantics"><div class="titlepage"><div><div><h3 class="title"><a name="disjoint-prefetch-semantics"></a>Disjoint Prefetching Semantics</h3></div></div></div><p>This semantics (only applicable to SelectQuery) results in Cayenne generatiing one
+				SQL statement for the main objects, and a separate statement for each prefetch path
+				(hence "disjoint" - related objects are not fetched with the main query). Each
+				additional SQL statement uses a qualifier of the main query plus a set of joins
+				traversing the preftech path between the main and related entity. </p><p>This strategy has an advantage of efficient JVM memory use, and faster overall
+				result processing by Cayenne, but it requires (1+N) SQL statements to be executed,
+				where N is the number of prefetched relationships.</p></div><div class="section" title="Disjoint-by-ID Prefetching Semantics"><div class="titlepage"><div><div><h3 class="title"><a name="disjoint-by-id-prefetch-semantics"></a>Disjoint-by-ID Prefetching Semantics</h3></div></div></div><p>This is a variation of disjoint prefetch where related objects are matched against
+				a set of IDs derived from the fetched main objects (or intermediate objects in a
+				multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most
+				DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller
+				queries. The size of  is controlled by the DI property
+				Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in
+				the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL
+				statements for each query using disjoint-by-ID prefetches, where N is the number of
+				relationships to prefetch, and M is the number of queries for a given prefetch that
+				is dependent on the number of objects in the result (ideally M = 1).</p><p>The advantage of this type of prefetch is that matching database rows by ID may be
+				much faster than matching the qualifier of the original query. Moreover this is
+					<span class="bold"><strong>the only type of prefetch</strong></span> that can handle
+				SelectQueries with <span class="bold"><strong>fetch limit</strong></span>. Both joint and
+				regular disjoint prefetches may produce invalid results or generate inefficient
+				fetch-the-entire table SQL when fetch limit is in effect. </p><p>The disadvantage is that query SQL can get unwieldy for large result sets, as each
+				object will have to have its own condition in the WHERE clause of the generated
+				SQL.</p></div><div class="section" title="Joint Prefetching Semantics"><div class="titlepage"><div><div><h3 class="title"><a name="joint-prefetch-semantics"></a>Joint Prefetching Semantics</h3></div></div></div><p>Joint senantics results in a single SQL statement for root objects and any number
+				of jointly prefetched paths. Cayenne processes in memory a cartesian product of the
+				entities involved, converting it to an object tree. It uses OUTER joins to connect
+				prefetched entities.</p><p>Joint is the most efficient prefetch type of the three as far as generated SQL
+				goes. There's always just 1 SQL query generated. Its downsides are the potentially
+				increased amount of data that needs to get across the network between the
+				application server and the database, and more data processing that needs to be done
+				on the Cayenne side.</p></div></div><div class="section" title="Data Rows"><div class="titlepage"><div><div><h2 class="title"><a name="datarows"></a>Data Rows</h2></div></div></div></div><div class="section" title="Iterated Queries"><div class="titlepage"><div><div><h2 class="title"><a name="iterated-queries"></a>Iterated Queries</h2></div></div></div></div><div class="section" title="Paginated Queries"><div class="titlepage"><div><div><h2 class="title"><a name="paginated-queries"></a>Paginated Queries</h2></div></div></div></div><div class="section" title="Caching and Fresh Data"><div class="titlepage"><div><div><h2 class="title"><a name="caching-and-fresh-data"></a>Caching and Fresh Data</h2></div></div></div><div class="section" title="Object Caching"><div class="titlepage"><div><div><h3 class="title"><a name="object-caching"></a>Object Caching</h3></div></div></div></div><div class="section" title="Query Result Caching"><div class="titlepage"><div><div><h3 class="tit
 le"><a name="query-result-caching"></a>Query Result Caching</h3></div></div></div></div></div><div class="section" title="Turning off Synchronization of ObjectContexts"><div class="titlepage"><div><div><h2 class="title"><a name="turning-off-synchronization-of-objectcontexts"></a>Turning off Synchronization of ObjectContexts</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lifecycle-events.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="customizing-cayenne-runtime.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;10.&nbsp;Lifecycle Events&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;12.&nbsp;Customizi
 ng Cayenne Runtime</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/persistent-objects-objectcontext.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/persistent-objects-objectcontext.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/persistent-objects-objectcontext.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/persistent-objects-objectcontext.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,211 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="starting-cayenne.html" title="Chapter&nbsp;5.&nbsp;Starting Cayenne"><link rel="next" href="expressions.html" title="Chapter&nbsp;7.&nbsp;Expressions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="starting-cayenne.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="ri
 ght">&nbsp;<a accesskey="n" href="expressions.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext"><div class="titlepage"><div><div><h2 class="title"><a name="persistent-objects-objectcontext"></a>Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="persistent-objects-objectcontext.html#objectcontext">ObjectContext</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#persistent-lifecycle">Persistent Object and its Lifecycle</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#persistent-operations">ObjectContext Persistence API</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#cayenne-helper-class">Cayenne Helper Class</a></span></dt><dt><span class="section"><a href="persistent-obj
 ects-objectcontext.html#objectcontext-nesting">ObjectContext Nesting</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#generic-persistent-objects">Generic Persistent Objects</a></span></dt><dt><span class="section"><a href="persistent-objects-objectcontext.html#transactions">Transactions</a></span></dt></dl></div><div class="section" title="ObjectContext"><div class="titlepage"><div><div><h2 class="title"><a name="objectcontext"></a>ObjectContext</h2></div></div></div><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><pre class="programlisting">ObjectContext context = runtime.getContext();</pre><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><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><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 class="section" title="Persistent Object and its Lifecycle"><div class="titlepage"><div><div><h2 class="title"><a name="persistent-lifecycle"></a>Persistent Object and its Lifecycle</h2></div></div></div><p>Cayenne can persist Java objects that implement <code class="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><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 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><p>Each persistent object belongs to a single ObjectContext, and can be in one of the following
+			persistence states (as defined in <code class="code">org.apache.cayenne.PersistenceState</code>)
+				:</p><table frame="void" id="d0e1012"><caption>Table&nbsp;6.1.&nbsp;Persistence States</caption><col width="16%"><col width="84%"><tbody><tr>
+						<td>TRANSIENT</td>
+						<td>The object is not registered with an ObjectContext and will not be
+							persisted.</td>
+					</tr><tr>
+						<td>NEW</td>
+						<td>The object is freshly registered in an ObjectContext, but has not been
+							saved to the database yet and there is no matching database row.</td>
+					</tr><tr>
+						<td>COMMITTED</td>
+						<td>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.</td>
+					</tr><tr>
+						<td>MODIFIED</td>
+						<td>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.</td>
+					</tr><tr>
+						<td>HOLLOW</td>
+						<td>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.</td>
+					</tr><tr>
+						<td>DELETED</td>
+						<td>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.</td>
+					</tr></tbody></table></div><div class="section" title="ObjectContext Persistence API"><div class="titlepage"><div><div><h2 class="title"><a name="persistent-operations"></a>ObjectContext Persistence API</h2></div></div></div><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 "<span class="italic">performQuery</span>"
+			method:</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class);
+List&lt;Artist&gt; artists = context.performQuery(query);</pre><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><p>Some queries can be quite complex, returning multiple result sets or even updating the
+			database. For such queries ObjectContext provides "<span class="italic">performGenericQuery</span>"method. While not nearly as commonly-used as
+			"performQuery", it is nevertheless important in some situations.
+			E.g.:</p><pre class="programlisting">Collection&lt;Query&gt; queries = ... // multiple queries that need to be run together
+QueryChain query = new QueryChain(queries);
+
+QueryResponse response = context.performGenericQuery(query);</pre><p>An application might modify selected objects. E.g.:</p><pre class="programlisting">Artist selectedArtist = artists.get(0);
+selectedArtist.setName("Dali");</pre><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
+				"<span class="italic">commitChanges</span>":</p><pre class="programlisting">context.commitChanges();</pre><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><p>If instead of commit, we wanted to reset all changed objects to the previously
+			committed state, we'd call <span class="emphasis"><em>rollbackChanges</em></span>
+			instead:</p><pre class="programlisting">context.rollbackChanges();</pre><p>"<span class="italic">newObject</span>" method call creates a persistent object
+			and sets its state to
+			"NEW":</p><pre class="programlisting">Artist newArtist = context.newObject(Artist.class);
+newArtist.setName("Picasso");</pre><p>It will only exist in memory until "commitChanges" 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 INSERT SQL statement to permanently store the object.</p><p><span class="emphasis"><em>deleteObjects</em></span> method takes one or more Persistent objects and
+			marks them as
+			"DELETED":</p><pre class="programlisting">context.deleteObjects(artist1);
+context.deleteObjects(artist2, artist3, artist4);</pre><p>Additionally
+			"deleteObjects" 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 "commitChanges" is called.
+			Similarly "rollbackChanges" will undo the effect of "newObject" and
+			"deleteObjects".</p><p><span class="emphasis"><em>localObject</em></span> returns a copy of a given persistent object that is
+			"local" to a given ObjectContext:</p><p>Since an application often works with more than one context, "localObject" 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><pre class="programlisting">ObjectContext editingContext = runtime.getContext();
+Artist localArtist = editingContext.localObject(artist);</pre><p>Often an appliction needs to inspect mapping metadata. This information is stored in
+			the EntityResolver object, accessible via the
+			ObjectContext:</p><pre class="programlisting">EntityResolver resolver = objectContext.getEntityResolver();</pre><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 en bulk,
+			etc. Check the latest JavaDocs for details.</p></div><div class="section" title="Cayenne Helper Class"><div class="titlepage"><div><div><h2 class="title"><a name="cayenne-helper-class"></a>Cayenne Helper Class</h2></div></div></div><p>There is a useful helper class called "Cayenne" (fully-qualified name
+				<code class="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><pre class="programlisting">long pk = Cayenne.longPKForObject(artist);</pre><p>It also provides the reverse operation - finding an object given a known
+			PK:</p><pre class="programlisting">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</pre><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><pre class="programlisting">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</pre><p>Feel free to explore Cayenne class API for other useful methods.</p></div><div class="section" title="ObjectContext Nesting"><div class="titlepage"><div><div><h2 class="title"><a name="objectcontext-nesting"></a>ObjectContext Nesting</h2></div></div></div><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><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><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><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><p>To create a nested context, use an instance of ServerRuntime, passing it the desired
+			parent:</p><pre class="programlisting">ObjectContext parent = runtime.getContext();
+ObjectContext nested = runtime.getContext((DataChannel) parent);</pre><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><pre class="programlisting">// merges nested context changes into the parent context
+nested.commitChangesToParent();
+
+// regular 'commitChanges' cascades commit through the chain 
+// of parent contexts all the way to the database
+nested.commitChanges();</pre><pre class="programlisting">// unrolls all local changes, getting context in a state identical to parent
+nested.rollbackChangesLocally();
+
+// regular 'rollbackChanges' cascades rollback through the chain of contexts 
+// all the way to the topmost parent
+nested.rollbackChanges();</pre></div><div class="section" title="Generic Persistent Objects"><div class="titlepage"><div><div><h2 class="title"><a name="generic-persistent-objects"></a>Generic Persistent Objects</h2></div></div></div><p>As described in the CayenneModeler chapter, Cayenne supports mapping of completely
+			generic classes to specific entities. Although for conveniece most applications should
+			stick with entity-specific class mappings, the generic feature offers some interesting
+			possibilities, such as creating mappings completely on the fly in a running application,
+			etc.</p><p>Generic objects are first class citizens in Cayenne, and all common persistent
+			operations apply to them as well. There are some pecularities however, described
+			below.</p><p>When creating a new generic object, either cast your ObjectContext to DataContext
+			(that provides "newObject(String)" API), or provide your object with an explicit
+			ObjectId:</p><pre class="programlisting">DataObject generic = ((DataContext) context).newObject("GenericEntity");</pre><pre class="programlisting">DataObject generic = new CayenneDataObject();
+generic.setObjectId(new ObjectId("GenericEntity"));
+context.registerNewObject(generic);</pre><p>SelectQuery
+			for generic object should be created passing entity name String in constructor, instead
+			of a Java
+			class:</p><pre class="programlisting">SelectQuery query = new SelectQuery("GenericEntity");</pre><p>Use
+			DataObject API to access and modify properties of a generic
+			object:</p><pre class="programlisting">String name = (String) generic.readProperty("name");
+generic.writeProperty("name", "New Name");</pre><p>This
+			is how an application can obtain entity name of a generic
+			object:</p><pre class="programlisting">String entityName = generic.getObjectId().getEntityName();</pre></div><div class="section" title="Transactions"><div class="titlepage"><div><div><h2 class="title"><a name="transactions"></a>Transactions</h2></div></div></div><p>Considering how much attention is given to managing transactions in most other ORMs,
+			transactions have been conspicuously absent from the ObjectContext discussion till now.
+			The reason is that transactions are seamless in Cayenne in all but a few special cases.
+			ObjectContext is an in-memory container of objects that is disconnected from the
+			database, except when it needs to run an operation. So it does not care about any
+			surrounding transaction scope. Sure enough all database operations are transactional, so
+			when an application does a commit, all SQL execution is wrapped in a database
+			transaction. But this is done behind the scenes and is rarely a concern to the
+			application code.</p><p>Two cases where transactions need to be taken into consideration are container-managed
+			and application-managed transactions. </p><p>If you are using an EJB container (or some other JTA environment), you'll likely need
+			to switch Cayenne runtime into "external transactions mode".  This is either done in the
+			Modeler (check DataDomain &gt; 'Container-Managed Transactions' checkbox), or in the
+			code:</p><pre class="programlisting">runtime.getDataDomain().setUsingExternalTransactions(true);</pre><p>In
+			this case Cayenne assumes that JDBC Connections obtained by runtime whenever that might
+			happen are all coming from a transactional DataSource managed by the container. In this
+			case Cayenne does not attempt to commit or rollback the connections, leaving it up to
+			the container to do that when appropriate.</p><p>In the second scenario, an application might need to define its own transaction scope
+			that spans more than one Cayenne operation. E.g. two sequential commits that need to be
+			rolled back together in case of failure. This can be done with an explicit thread-bound
+			transaction that surrounds a set of operations. Application is responsible for
+			committing or rolling it
+			back:</p><pre class="programlisting">Transaction tx = runtime.getDataDomain().createTransaction();
+Transaction.bindThreadTransaction(tx);
+
+try {
+    // commit one or more contexts
+    context1.commitChanges();
+    context2.commitChanges();
+    ....
+    // after changing some objects in context1, commit again
+    context1.commitChnages();
+    ....
+    // if no failures, commit
+    tx.commit();
+}
+catch (Exception ex) {
+    tx.setRollbackOnly();
+}
+finally {
+    Transaction.bindThreadTransaction(null);
+ 
+    if (tx.getStatus() == Transaction.STATUS_MARKED_ROLLEDBACK) {
+        try {
+           tx.rollback();
+        }
+        catch (Exception rollbackEx) {
+        }
+    }
+} </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="starting-cayenne.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="expressions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;5.&nbsp;Starting Cayenne&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;7.&nbsp;Expressions</td></tr></table></div></body></html>
\ No newline at end of file

Added: cayenne/site/cms/trunk/content/v31/cayenne-guide/queries.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/v31/cayenne-guide/queries.html?rev=1406588&view=auto
==============================================================================
--- cayenne/site/cms/trunk/content/v31/cayenne-guide/queries.html (added)
+++ cayenne/site/cms/trunk/content/v31/cayenne-guide/queries.html Wed Nov  7 12:36:48 2012
@@ -0,0 +1,35 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+   <title>Chapter&nbsp;9.&nbsp;Queries</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="orderings.html" title="Chapter&nbsp;8.&nbsp;Orderings"><link rel="next" href="lifecycle-events.html" title="Chapter&nbsp;10.&nbsp;Lifecycle Events"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;9.&nbsp;Queries</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="orderings.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="lifecycle-events.html">Next</a></t
 d></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;9.&nbsp;Queries"><div class="titlepage"><div><div><h2 class="title"><a name="queries"></a>Chapter&nbsp;9.&nbsp;Queries</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="queries.html#selectquery">SelectQuery</a></span></dt><dt><span class="section"><a href="queries.html#ejbqlquery">EJBQLQuery</a></span></dt><dt><span class="section"><a href="queries.html#sqltemplate">SQLTemplateQuery</a></span></dt><dt><span class="section"><a href="queries.html#procedurequery">ProcedureQuery</a></span></dt><dt><span class="section"><a href="queries.html#namedquery">NamedQuery</a></span></dt><dt><span class="section"><a href="queries.html#custom-queries">Custom Queries</a></span></dt></dl></div><p>Queries are Java objects used by the application to communicate with the database. Cayenne
+		knows how to translate queries into SQL statements appropriate for a particular database
+		engine. Most often queries are used to find objects matching certain criteria, but there are
+		other types of queries too. E.g. those allowing to run native SQL, call DB stored
+		procedures, etc. When committing objects, Cayenne itself creates special queries to
+		insert/update/delete rows in the dabase.</p><p>There is a number of built-in queries in Cayenne, described later in this chapter. Users can
+		also define their own query types to abstract certain DB interactions that for whatever
+		reason can not be adequately described by the built-in set. </p><p>Queries can be roughly categorized as "object" and "native". Object queries (most notably
+		SelectQuery and EJBQLQuery) are built with abstractions originating in the object model (the
+		"object" side in the "object-relational" divide). E.g. SelectQuery is assembled from a Java
+		class of the objects to fetch, a qualifier expression, orderings, etc. - all of this
+		expressed in terms of the object model.</p><p>Native queries describe a desired DB operation as SQL code (SQLTemplate query) or a reference
+		to a stored procedure (ProcedureQuery), etc. The results of native queries are usually
+		presented as Lists of Maps, with each map representing a row in the DB. They can potentially
+		be converted to objects, however often it takes a considerable effort to do so. Native
+		queries are also less (if at all) portable across databases than object queries. </p><div class="section" title="SelectQuery"><div class="titlepage"><div><div><h2 class="title"><a name="selectquery"></a>SelectQuery</h2></div></div></div><p>SelectQuery is the most commonly used query in user applications. It returns a list of
+			persistent objects of a certain type specified in the
+			query:</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class);
+List&lt;Artist&gt; objects = context.performQuery(query);</pre><p>This
+			returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
+			following SQL
+			printed:</p><pre class="programlisting">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
+INFO: === returned 5 row. - took 5 ms.</pre><p>This SQL was generated by Cayenne from the SelectQuery above. SelectQuery can use a
+			qualifier to select only the data that you care about. Qualifier is simply an Expression
+			(Expressions where discussed in the previous chapter). If you only want artists whose
+			name begins with 'Pablo', you might use the following qualifier expression:
+			</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class, 
+        ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "Pablo%"));
+List&lt;Artist&gt; objects = context.performQuery(query);</pre><p>The
+			SQL will look different this
+			time:</p><pre class="programlisting">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ? 
+[bind: 1-&gt;NAME:'Pablo%']
+INFO: === returned 1 row. - took 6 ms.</pre></div><div class="section" title="EJBQLQuery"><div class="titlepage"><div><div><h2 class="title"><a name="ejbqlquery"></a>EJBQLQuery</h2></div></div></div></div><div class="section" title="SQLTemplateQuery"><div class="titlepage"><div><div><h2 class="title"><a name="sqltemplate"></a>SQLTemplateQuery</h2></div></div></div></div><div class="section" title="ProcedureQuery"><div class="titlepage"><div><div><h2 class="title"><a name="procedurequery"></a>ProcedureQuery</h2></div></div></div></div><div class="section" title="NamedQuery"><div class="titlepage"><div><div><h2 class="title"><a name="namedquery"></a>NamedQuery</h2></div></div></div></div><div class="section" title="Custom Queries"><div class="titlepage"><div><div><h2 class="title"><a name="custom-queries"></a>Custom Queries</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey=
 "p" href="orderings.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="lifecycle-events.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;8.&nbsp;Orderings&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;10.&nbsp;Lifecycle Events</td></tr></table></div></body></html>
\ No newline at end of file



Mime
View raw message