You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2007/07/08 21:11:53 UTC
svn commit: r554413 [9/17] - in
/cayenne/main/trunk/docs/doc/src/main/resources/doc: ./ Documentation/
Documentation/Cayenne Guide/ Documentation/Cayenne Guide/Ant Tasks/
Documentation/Cayenne Guide/Ant Tasks/cdataport/ Documentation/Cayenne
Guide/Ant ...
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,101 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Maven2 Plugins</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Maven2 Plugins</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html">maven2-cgen</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="Maven2Plugins-Maven2Plugins"></a>Maven2 Plugins</h2>
+
+<p>Cayenne ships with Maven 2 plugins that provide Maven 2 frontend to a number of useful operations in Cayenne. The following tasks are included:</p>
+
+<ul>
+ <li><b><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html" title="maven2-cgen">maven2-cgen</a></b> - Java class generator</li>
+ <li><b><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdbgen&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdbgen" class="createlink">maven2-cdbgen<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></b> - Database schema generator</li>
+ <li><b><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdeploy&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdeploy" class="createlink">maven2-cdeploy<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></b> - Deployment configurator</li>
+ <li><b><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdataport&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdataport" class="createlink">maven2-cdataport<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></b> - Data porting tool.</li>
+</ul>
+
+
+<h3><a name="Maven2Plugins-ImportingCayennePlugininpom.xml"></a>Importing Cayenne Plugin in pom.xml</h3>
+
+<p>You need to add the Cayenne plugin to your project by adding the following:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>maven-cayenne-plugin</artifactId>
+ <version>3.0M1</version>
+ </plugin>
+ </plugins>
+</build></pre>
+</div></div>
+
+<h3><a name="Maven2Plugins-Sections"></a>Sections</h3>
+
+<ol>
+ <li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html" title="maven2-cgen">maven2-cgen</a></li>
+ <li><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdbgen&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdbgen" class="createlink">maven2-cdbgen<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></li>
+ <li><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdeploy&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdeploy" class="createlink">maven2-cdeploy<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></li>
+ <li><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=maven2-cdataport&linkCreation=true&fromPageId=28627" title="Create Page: maven2-cdataport" class="createlink">maven2-cdataport<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></li>
+</ol>
+
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/maven2-cgen/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,242 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - maven2-cgen</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">maven2-cgen</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html">maven2-cgen</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>
+<p>This documentation is very much work-in-progress and subject to change.</p></td></tr></table>
+
+<p><tt>cgen</tt> is an Maven 2 mojo that generates and maintains DataObjects source files based on Cayenne DataMap. By default, it is bound to the <tt>generate-sources</tt> phase. If "makePairs" is set to "true" (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, <tt>cgen</tt> can also be used to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.</p>
+
+<h3><a name="maven2-cgen-Parameters%28asXMLelements%29"></a>Parameters (as XML elements)</h3>
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'>Attribute</th>
+<th class='confluenceTh'>Description</th>
+<th class='confluenceTh'>Required</th>
+</tr>
+<tr>
+<td class='confluenceTd'>map</td>
+<td class='confluenceTd'>DataMap XML file to use as a base for class generation.</td>
+<td class='confluenceTd'>Yes</td>
+</tr>
+<tr>
+<td class='confluenceTd'>additionalMaps</td>
+<td class='confluenceTd'>Path to additional DataMap XML files to use for class generation.</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>destDir</td>
+<td class='confluenceTd'>Destination directory for Java classes (ignoring their package names).</td>
+<td class='confluenceTd'>Yes</td>
+</tr>
+<tr>
+<td class='confluenceTd'>overwrite</td>
+<td class='confluenceTd'>If set to "true", will overwrite older versions of generated classes. Ignored unless makepairs is set to "false".</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>makePairs</td>
+<td class='confluenceTd'>If set to "true", will generate subclass/superclass pairs, with all generated code included in superclass (default is "true").</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>template</td>
+<td class='confluenceTd'>Location of Velocity template file for Java class generation. If omitted, default template is used.</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>superTemplate</td>
+<td class='confluenceTd'>Location of Velocity template file for Java superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>superPkg</td>
+<td class='confluenceTd'>Java package name of generated superclasses. Ignored unless "makepairs" set to "true". If omitted, each superclass will be assigned the same package as subclass. Note that having superclass in a different package would only make sense when "usepkgpath" is set to "true". Otherwise classes from different packages will end up in the same directory.</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>usePkgPath</td>
+<td class='confluenceTd'>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>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>encoding</td>
+<td class='confluenceTd'>Specify generated file encoding if different from the default on current platform. Target encoding must be supported by the JVM running Ant build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See Sun Java Docs for java.nio.charset.Charset for more information.</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>version</td>
+<td class='confluenceTd'>Specifies template location and generator behavior. "1.1" is the old behavior, with templates located in "dotemplates" and "classgen" as the only velocity context attribute. "1.2" is the new behavior, with templates located in "dotemplates/v1.2" and "objEntity", "entityUtils", "stringUtils", and "importUtils" in the velocity context. (Default is "1.1")</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>excludeEntities</td>
+<td class='confluenceTd'>Entities (expressed as a perl5 regex) to exclude from template generation. (Default is to include all entities in the DataMap)</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>includeEntities</td>
+<td class='confluenceTd'>Entities (expressed as a perl5 regex) to include in template generation. (Default is to include all entities in the DataMap)</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>outputPattern</td>
+<td class='confluenceTd'>Name of file for generated output. (Default is "*.java")</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>mode</td>
+<td class='confluenceTd'>Specifies generator iteration target. "entity" performs one iteration for each selected entity. "datamap" performs one iteration per datamap (This is always one iteration since cgen currently supports specifying one-and-only-one datamap). (Default is "entity")</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>client</td>
+<td class='confluenceTd'>Whether we are generating classes for the client tier in a <a href="../../../../Documentation/Remote Object Persistence Guide/index.html" title="Remote Object Persistence Guide">Remote Object Persistence</a> application. Default is "false"</td>
+<td class='confluenceTd'>No</td>
+</tr>
+</tbody></table>
+
+<h3><a name="maven2-cgen-Examples"></a>Examples</h3>
+
+<p>Load the Maven 2 plugin and configure the <tt>cgen</tt> mojo: </p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><build></span>
+ <span class="code-tag"><plugins></span>
+ <span class="code-tag"><plugin></span>
+ <span class="code-tag"><groupId></span>org.apache.cayenne.plugins<span class="code-tag"></groupId></span>
+ <span class="code-tag"><artifactId></span>cayenne-maven-plugin<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><executions></span>
+ <span class="code-tag"><execution></span>
+ <span class="code-tag"><id></span>cgen<span class="code-tag"></id></span>
+ <span class="code-tag"><configuration></span>
+ <span class="code-tag"><span class="code-comment"><!-- Configuration items go in here. See table, above. --></span></span>
+ <span class="code-tag"></configuration></span>
+ <span class="code-tag"><goals></span>
+ <span class="code-tag"><goal></span>cgen<span class="code-tag"></goal></span>
+ <span class="code-tag"></goals></span>
+ <span class="code-tag"></execution></span>
+ <span class="code-tag"></executions></span>
+ <span class="code-tag"></plugin></span>
+ <span class="code-tag"></plugins></span>
+<span class="code-tag"></build></span></pre>
+</div></div>
+
+<p>Here is an example of using CGen to generate DataObject subclass/superclass pairs from DataMap located in "src/datamap.xml". All generated subclasses and superclasses will be saved in the same directory "src/java/dobj" regardless of their package names:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><build></span>
+ <span class="code-tag"><plugins></span>
+ <span class="code-tag"><plugin></span>
+ <span class="code-tag"><groupId></span>org.apache.cayenne.plugins<span class="code-tag"></groupId></span>
+ <span class="code-tag"><artifactId></span>cayenne-maven-plugin<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><executions></span>
+ <span class="code-tag"><execution></span>
+ <span class="code-tag"><id></span>cgen<span class="code-tag"></id></span>
+ <span class="code-tag"><configuration></span>
+ <span class="code-tag"><map></span>${project.build.sourceDirectory}/datamap.xml<span class="code-tag"></map></span>
+ <span class="code-tag"><destDir></span>${project.build.sourceDirectory}/dobj<span class="code-tag"></destDir></span>
+ <span class="code-tag"><usePkgPath></span>true<span class="code-tag"></usePkgPath></span>
+ <span class="code-tag"></configuration></span>
+ <span class="code-tag"><goals></span>
+ <span class="code-tag"><goal></span>cgen<span class="code-tag"></goal></span>
+ <span class="code-tag"></goals></span>
+ <span class="code-tag"></execution></span>
+ <span class="code-tag"></executions></span>
+ <span class="code-tag"></plugin></span>
+ <span class="code-tag"></plugins></span>
+<span class="code-tag"></build></span></pre>
+</div></div>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The follow example includes the use of Velocity template overriding, which is not yet functional in the plugin.</td></tr></table>
+
+<p>Here is an example of using CGen to generate html pages for all entities starting with "Artist" in the DataMap:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><build></span>
+ <span class="code-tag"><plugins></span>
+ <span class="code-tag"><plugin></span>
+ <span class="code-tag"><groupId></span>org.apache.cayenne.plugins<span class="code-tag"></groupId></span>
+ <span class="code-tag"><artifactId></span>cayenne-maven-plugin<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><executions></span>
+ <span class="code-tag"><execution></span>
+ <span class="code-tag"><id></span>cgen<span class="code-tag"></id></span>
+ <span class="code-tag"><configuration></span>
+ <span class="code-tag"><map></span>${project.build.sourceDirectory}/datamap.xml<span class="code-tag"></map></span>
+ <span class="code-tag"><destDir></span>${project.build.sourceDirectory}/doc/web<span class="code-tag"></destDir></span>
+ <span class="code-tag"><makePairs></span>false<span class="code-tag"></makePairs></span>
+ <span class="code-tag"><usePkgPath></span>false<span class="code-tag"></usePkgPath></span>
+ <span class="code-tag"><template></span>EntityReport.vm<span class="code-tag"></template></span>
+ <span class="code-tag"><includeEntities></span>Artist*<span class="code-tag"></includeEntities></span>
+ <span class="code-tag"><outputPattern></span>*Report.html<span class="code-tag"></outputPattern></span>
+ <span class="code-tag"></configuration></span>
+ <span class="code-tag"><goals></span>
+ <span class="code-tag"><goal></span>cgen<span class="code-tag"></goal></span>
+ <span class="code-tag"></goals></span>
+ <span class="code-tag"></execution></span>
+ <span class="code-tag"></executions></span>
+ <span class="code-tag"></plugin></span>
+ <span class="code-tag"></plugins></span>
+<span class="code-tag"></build></span></pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Caching%20Lookup%20Tables/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,80 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Caching Lookup Tables</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Caching Lookup Tables</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent">
+<p>Query result caching feature can be used to implement caching of lookup tables. "Lookup" or "configuration" tables can be loosely defined as small tables that change rarely and mostly used in read-only fashion. Examples of such tables are COUNTRY, USER_TYPE, AREA_CODE, etc. Often data from such tables is displayed in a combo box or dropdown.</p>
+
+<p>For performance reasons it makes sense to store the lookup data in the shared cache. The following steps could be taken to create and use a shared query for a Country entity:</p>
+
+<ul>
+ <li>Create a named SelectQuery in CayenneModeler. Call it something like "AllCountries". Select a root to be Country ObjEntity, select shared caching and uncheck "refresh" checkbox.</li>
+ <li>Whenever a list of countries is needed, use a local DataContext to get it from cache - <tt>context.performQuery("AllCountries", false)</tt>.</li>
+</ul>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Data%20Rows/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,109 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Data Rows</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Data Rows</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>DataObjects creation and registering with DataContext is an expensive operation. There are cases when only a few objects are really used, but the application still has to fetch a lot of objects. For instance when a user performs a search, result may contain thousands of records, but user will only check 2-3 of them. Cayenne allows programmers to explicitly disable objects creation for such cases. Results will be returned in the form of java.util.Map's. In Cayenne such maps are called <tt>DataRows</tt>.</p>
+
+<p>Benefits of Data Rows:</p>
+
+<ul>
+ <li>Fetch speed increase. Our tests show 2x to 5x performance increase.</li>
+ <li>Using regular Cayenne query API.</li>
+ <li>Using same DataMaps.</li>
+ <li>Easy to convert to DataObjects.</li>
+</ul>
+
+
+<p>Data rows don't have all the object-oriented features of DataObjects. In particular, data rows don't support relationships. It is easy to create a DataObject from a row though. See examples below.</p>
+
+<p>Data rows example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.apache.art.Artist;
+...
+DataContext ctxt;
+
+<span class="code-comment">// create a query returning data rows
+</span>SelectQuery q = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+q.setFetchingDataRows(<span class="code-keyword">true</span>);
+
+List artistRows = ctxt.performQuery(q);
+
+<span class="code-comment">// since query was configured to <span class="code-keyword">return</span> data rows,
+</span><span class="code-comment">// result list elements are java.util.Map's
+</span>Map row = (Map)artistRows.get(0);
+
+<span class="code-comment">// convert row to an artist
+</span>Artist artist = (Artist)ctxt.objectFromDataRow(<span class="code-quote">"Artist"</span>, row);
+...</pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Iterating%20Through%20Data%20Rows/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,121 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Iterating Through Data Rows</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Iterating Through Data Rows</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>There are cases when the result sets are so large that even when fetching data rows, application can run out of memory. For instance, a user may be creating a report that requires in-memory processing of hundreds of thousands of database rows. In such cases normal Cayenne behavior of reading the whole java.sql.ResultSet in the memory before returning it to the user may result in an application exhausing all memory and crashing.</p>
+
+<p>Cayenne solves this by allowing to obtain results in the form of ResultIterator. ResultIterator is connected to an open java.sql.ResultSet, therefore its methods may throw checked exceptions. ResultIterator returns data rows (not DataObjects) one at a time, reading them on demand from the open ResultSet. Each data row can be converted to a DataObject or accessed directly. Open ResultIterator locks the database connection, therefore <b>ResultIterator always requires explicit closing in the user code</b>.</p>
+<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In web applications, programmers must ensure that no open ResultIterators are kept between HTTP requests. Failure to do so may result in too many database connections being locked, thus quickly exhausting connection pool. In general, an application with Web GUI is NOT a good candidate for implementation using ResultIterators.</td></tr></table>
+
+<p>When working with open ResultIterator, users still can perform any other database operations: select queries, traversing object relationships, etc. Any parallel data operation will internally check out an unused connection from the connection pool as it would normally do, while ResultIterator still locks its own connection.</p>
+
+<p>ResultIterator annotated example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.apache.cayenne.access.ResultIterator;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.apache.cayenne.CayenneException;
+<span class="code-keyword">import</span> org.apache.art.Artist;
+...
+DataContext ctxt;
+
+<span class="code-comment">// create a usual query
+</span>SelectQuery q = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+ResultIterator it = <span class="code-keyword">null</span>;
+
+<span class="code-comment">// ResultIterator operations all <span class="code-keyword">throw</span> checked CayenneException
+</span><span class="code-keyword">try</span> {
+ <span class="code-comment">// special <span class="code-quote">"performIteratedQuery"</span> method is used
+</span> it = ctxt.performIteratedQuery(q);
+
+ <span class="code-keyword">while</span>(it.hasNextRow()) {
+ <span class="code-comment">// ResultIterator always returns data rows
+</span> Map row = it.nextDataRow();
+
+ <span class="code-comment">// <span class="code-keyword">do</span> something with the row...
+</span> ...
+ }
+}
+<span class="code-keyword">catch</span>(CayenneException ex) {
+ ex.printStackTrace();
+}
+<span class="code-keyword">finally</span> {
+ <span class="code-keyword">try</span> {
+ <span class="code-comment">// explicit closing of the iterator is required !!!
+</span> it.close();
+ }
+ <span class="code-keyword">catch</span>(CayenneException closeEx) {
+ closeEx.printStackTrace();
+ }
+}
+...</pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Paginated%20Queries/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,111 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Paginated Queries</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Paginated Queries</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Another common situation found in interactive applications is when it is needed to fetch a large number of rows, and at the same time only a small subset of objects is accessed directly. An example of such application would be a search page. User would like to see how many total results exist that match a certain criteria, but she will only look at a few pages of results out of possibly hundreds or thousands. It will be extremely inefficient to fetch all objects in the memory.</p>
+
+<p>A solution offered by Cayenne is "paginated" queries. A user can set a size of a "page" of a select query. If page size is greater than zero, on query execution Cayenne will only fetch the first "page" as DataObjects. For the rest of the result set, only primary keys are read. When a user accesses an object that has not been resolved yet, the whole page containing this object will be resolved all at once. Most important, this happens totally transparent to the user.</p>
+
+<p>Our tests show almost an order of magnitude speed increase when comparing the time it takes to read a full list of 2000 objects, and the time it takes to do the initial paginated query fetch with page size of 50.</p>
+
+<p>Paged query example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.apache.art.Artist;
+...
+DataContext ctxt;
+
+<span class="code-comment">// create a query returning data rows
+</span>SelectQuery q = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+q.setPageSize(50);
+
+<span class="code-comment">// the fact that result is paged is transparent
+</span>List artistRows = ctxt.performQuery(q);
+
+
+<span class="code-comment">// we are reading from the first page (index < 50),
+</span><span class="code-comment">// <span class="code-keyword">this</span> will simply <span class="code-keyword">return</span> an object
+</span>Artist artist1 = (Artist)artistRows.get(3);
+
+<span class="code-comment">// we are reading from the 4th page,
+</span><span class="code-comment">// <span class="code-keyword">this</span> will transparently resolve all objects on <span class="code-quote">"Page #4"</span>
+</span><span class="code-comment">// and then <span class="code-keyword">return</span> an object in question
+</span>Artist artist2 = (Artist)artistRows.get(153);
+
+
+<span class="code-comment">// This is safe and will NOT trigger a full fetch
+</span><span class="code-object">int</span> size = artistRows.size();
+...</pre>
+</div></div>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='tipMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Combining data rows and paginated queries</b><br />Cayenne supports combining both performance optimizations in the same query - fetching data rows (see previous chapters) and paginated queries. So if users work with tabular data and don't care much about real objects, combining the two approaches would improve speed and memory use even more. </td></tr></table></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Prefetching/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,183 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Prefetching</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Prefetching</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h3><a name="Prefetching-IntroductiontoPrefetching"></a>Introduction to Prefetching</h3>
+
+<p>Prefetching is a performance optimization technique that allows to bring back more than one type of objects in a single query. Prefetches are configured in terms of relationship paths from the query root entity to the "prefetched" entity. E.g.:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// configure query with prefetches
+</span>SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+query.addPrefetch(<span class="code-quote">"paintingArray"</span>);
+...
+<span class="code-comment">// execute query and <span class="code-keyword">do</span> something with results
+</span>List artists = context.performQuery(query);
+Iterator it = artists.iterator();
+<span class="code-keyword">while</span>(it.hasNext()) {
+ Artist a = (Artist) it.next();
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"paintings: "</span> + a.getPaintingArray().size());
+}</pre>
+</div></div>
+
+<p>When prefetching is set, corresponding relationships are "inflated" with database objects within a single <tt>performQuery</tt> run, leaving it up to Cayenne to optimize retrieval of multiple entities. For instance the example above results in just two SQL queries issued to the database internally, while running the same query without a prefetch and later iterating over artists will result in <tt>1 + N</tt> queries, where <tt>N</tt> is the number of artists returned. </p>
+
+<h3><a name="Prefetching-PrefetchingHints"></a>Prefetching Hints</h3>
+
+<ul>
+ <li>All types of relationships can be prefetched - to-one, to-many, flattened.</li>
+ <li>A prefetch can span more than one relationship:
+<div class="code"><div class="codeContent">
+<pre class="code-java">query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);</pre>
+</div></div></li>
+ <li>A query can have more than one prefetch path at the same time:
+<div class="code"><div class="codeContent">
+<pre class="code-java">query.addPrefetch(<span class="code-quote">"paintingArray"</span>);
+query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);</pre>
+</div></div></li>
+ <li><font color="red">PREFETCH LIMITATION:</font> To-many relationships should not be prefetched if a query qualifier can potentially reduce a number of related objects, resulting in incorrect relationship list. E.g.:
+<div class="code"><div class="codeContent">
+<pre class="code-java">SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+
+Expression exp = ExpressionFactory.matchExp(<span class="code-quote">"paintingArray.paintingTitle"</span>, <span class="code-quote">"Some Painting"</span>);
+
+<span class="code-comment">// INVALID!! since there can be more than one painting per artist, <span class="code-keyword">this</span> prefetch
+</span><span class="code-comment">// wouldn't work.
+</span>query.addPrefetch(<span class="code-quote">"paintingArray"</span>);</pre>
+</div></div>
+<p>In the future versions of Cayenne this will be addressed by using SQL subqueries. For now it is programmer's responsibility to avoid such prefetches.</p></li>
+ <li>If SelectQuery is fetching data rows, all default prefetches are ignored, though custom joint prefetches (see below) will be included.</li>
+ <li>When you customize SelectQuery prefetches to use joint semantics (see below how customization can be done), be aware that joint prefetch adds an extra inner join to the main query. This may result in fewer objects returned than expected. If you are SQL-savvy it may be helpful to think of disjoint prefetches as analogous to SQL outer joins and joint prefetches - to SQL inner joins.</li>
+</ul>
+
+
+<p><em>The rest of this page describes advanced use and can be skipped.</em></p>
+
+
+<h3><a name="Prefetching-PrefetchSemantics"></a>Prefetch Semantics</h3>
+
+<p><em>(semantics flavors were introduced in 1.2M3, with some changes in 1.2M8)</em></p>
+
+<p>Queries store prefetching information as trees of <tt>PrefetchTreeNode</tt> objects:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">PrefetchTreeNode treeRoot = query.getPrefetchTree();
+<span class="code-keyword">if</span>(treeRoot != <span class="code-keyword">null</span>) {
+ <span class="code-comment">// <span class="code-keyword">do</span> something with tree nodes
+</span>}</pre>
+</div></div>
+
+<p>Each node specifies the name of prefetch path segment and execution semantics. There are two flavors of prefetch semantics - <b>joint</b> and <b>disjoint</b>. Semantics of each node is initially determined by Cayenne when a new prefetch path is added, and can be later customized by the user (e.g., see joint example below).</p>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>
+<p>In most cases prefetch semantics is of no concern to the users. Cayenne will do its best to configure the right semantics on the fly. Don't tweak semantics unless you understand the implications and have some proof that different semantics would result in better select performance on your database. </p></td></tr></table>
+
+<p>Some internal semantics rules:</p>
+
+<ul>
+ <li>SelectQuery uses disjoint prefetches by default.</li>
+ <li>SQLTemplate and ProcedureQuery use joint prefetches and can not use disjoint semantics due to their nature.</li>
+ <li>Prefetches with different semantics can be mixed freely within a query, as long as there is no conflict with other rules.</li>
+</ul>
+
+
+
+<h3><a name="Prefetching-DisjointPrefetches"></a>Disjoint Prefetches</h3>
+
+<p><em>(available since 1.0)</em></p>
+
+<p>"Disjoint" prefetches (aka "normal prefetches", as this is how Cayenne implemented prefetching since 1.0) internally result in a separate SQL statement per prefetch path.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+
+<span class="code-comment">// <span class="code-quote">"disjoint"</span> is <span class="code-keyword">default</span> semantics of SelectQuery
+</span>query.addPrefetch(<span class="code-quote">"paintingArray"</span>);
+query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);
+
+<span class="code-comment">// <span class="code-keyword">this</span> will result in 1 main SQL query plus 2 extra prefetch queries
+</span>context.performQuery(query);</pre>
+</div></div>
+
+<h3><a name="Prefetching-JointPrefetches"></a>Joint Prefetches</h3>
+
+<p><em>(available since 1.2M3, with significant API changes in 1.2M8)</em></p>
+
+<p>"Joint" is prefetch type that issues a single SQL statement for multiple prefetch paths. Cayenne processes in memory a cartesian product of the entities involved, converting it to an object tree. SQLTemplate and ProcedureQuery create joint prefetches by default. SelectQuery needs to be told to use joint prefetch:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// after adding a <span class="code-keyword">new</span> prefetch, change its semantics to joint
+</span>query.addPrefetch(<span class="code-quote">"paintingArray"</span>).setSemantics(
+ PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS);
+
+context.performQuery(query);</pre>
+</div></div>
+
+<p>Code above will result in a single SQL statement issued.</p>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Turning%20off%20Context%20Synchronization/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,90 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Turning off Context Synchronization</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Turning off Context Synchronization</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent">
+<p>A big part of commit operation is updating peer DataContexts with the changes committed to the database. The conext synchronization operation has <tt>O(N)</tt> performance, where <tt>N</tt> is the number of peer DataContexts. In a web application <tt>N</tt> is often the number of concurrent sessions, which can be quite big. The throughout of high volume applications can be improved by turning off peer synchronization. One possible way to do that is via a custom <a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html" title="DataContextFactory">DataContextFactory</a>:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class IsolatedDataContextFactory <span class="code-keyword">implements</span> DataContextFactory {
+
+ <span class="code-keyword">public</span> DataContext createDataContext(DataChannel parent, ObjectStore objectStore) {
+
+ <span class="code-comment">// stop listening <span class="code-keyword">for</span> peer events
+</span> parent.getEventManager().removeListener(objectStore);
+ <span class="code-keyword">return</span> <span class="code-keyword">new</span> DataContext(parent, objectStore);
+ }
+}</pre>
+</div></div>
+
+<p>Of course doing this may result in some stale data in the peer DataContexts, so a decision whether to use this particular technique should be made based on the application specifics. Also a factory can have logic to selectively turn off synchronization for a subset of DataContexts based on some criteria.</p>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='tipMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Don't use this for idle applications</b><br />Note that this optimization does not affect percieved user commit time, as synchronization is done in a separate thread. It only affects the overall throughput. So it only makes sense if your application already utilizes close to a 100% of CPU.</td></tr></table>
+
+<p><em>Further improvements in this area are tracked via <span class="nobr"><a href="http://issues.apache.org/cayenne/browse/CAY-554" title="Visit page outside Confluence" rel="nofollow">CAY-554 Jira issue<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>.</em></p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,91 @@
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Performance Tuning</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Performance Tuning</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html">Turning off Context Synchronization</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="PerformanceTuning-PerformanceTuning"></a>Performance Tuning</h2>
+<p>Most performance problems in database applications, including those using ORM, are related to the inefficient queries and/or large volumes of data in the database. Here is a few common issues that a typical application may run into:</p>
+
+<ul>
+ <li>Converting a large ResultSet into objects takes very long time.</li>
+ <li>Storing objects from a large ResultSet takes large amounts of memory. Application may eventually run out of memory and crash.</li>
+ <li>Given a list of objects, there may be a need to retrieve a list of related objects. Often this is done in a suboptimal way, by issuing a single query for each dependent object.</li>
+</ul>
+
+
+<p>There is no single solution to all performance problems. Cayenne offers a few strategies to improve performance. They should be applied where appropriate.</p>
+
+<h3><a name="PerformanceTuning-Sections"></a>Sections</h3>
+
+<ol>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html" title="Prefetching">Prefetching</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html" title="Data Rows">Data Rows</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html" title="Iterating Through Data Rows">Iterating Through Data Rows</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html" title="Paginated Queries">Paginated Queries</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Caching Lookup Tables/index.html" title="Caching Lookup Tables">Caching Lookup Tables</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/Turning off Context Synchronization/index.html" title="Turning off Context Synchronization">Turning off Context Synchronization</a></li>
+</ol>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/caching.jpg
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/Caching%20Query%20Results/caching.jpg?view=auto&rev=554413
==============================================================================
Binary file - no diff available.
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/caching.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream