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 2006/05/10 03:11:01 UTC
svn commit: r405581 [11/14] - in
/incubator/cayenne/main/trunk/cayenne/cayenne-other: docs/ docs/images/
wiki-docs/ wiki-docs/Documentation/ wiki-docs/Documentation/Modeler Guide/
wiki-docs/Documentation/Modeler Guide/Cayenne Project Structure/ wiki-do...
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Introduction/Guide%20to%201.2%20Features/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,201 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Guide to 1.2 Features</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><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">Guide to 1.2 Features</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a><ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/Acknowledgements/index.html">Acknowledgements</a></li>
+<li><a href="../../../../Documentation/User Guide/Introduction/Guide to 1.1 features/index.html">Guide to 1.1 features</a></li>
+<li><a href="../../../../Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html">Guide to 1.2 Features</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Introduction/License/index.html">License</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>This page shows what's new in 1.2 release. The roadmap (unfinished tasks) can be viewed <span class="error">[here]</span>.</p>
+
+<h2><a name="Guideto1.2Features-CoreFramework"></a>Core Framework </h2>
+
+<h4><a name="Guideto1.2Features-RemoteObjectPersistenceRemoteObjectPersistenceGuide"></a><a href="../../../../Documentation/Remote Object Persistence Guide/index.html" title="Remote Object Persistence Guide">Remote Object Persistence</a> </h4>
+
+<p>Cayenne Remote Object Persistence is a low-overhead web services-based technology that provides lightweight generic object persistence and data query functionality to 'remote' applications. It allows to use the same object model and the same context capabilities in a system with more than one Java tier. Now persistence features can be implemented consistently across a set of collaborating applications with different responsibilities and security context.</p>
+
+
+<h4><a name="Guideto1.2Features-ObjectContextAPICAY%3AObjectContext"></a><span class="error">[ObjectContext API]</span></h4>
+
+<p><em>ObjectContext API is currently of practical interest to the remote client tier. Regular applications should continue using DataContext</em></p>
+
+<p><span class="error">[ObjectContext]</span> is a new interface that is a generalization of the traditional DataContext. In fact DataContext is one of its main implementors. It works with <tt>Persistent</tt> objects, that are a simplified version of <tt>DataObjects</tt>. </p>
+
+
+<h4><a name="Guideto1.2Features-QueryEnhancements"></a>Query Enhancements</h4>
+
+<ul>
+ <li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html" title="Prefetching">Prefetching</a>
+ <ul>
+ <li>Cayenne now supports prefetching of flattened relationships.</li>
+ <li>New "joint" prefetch semantics is introduced.</li>
+ <li>Semantics of prefetching now can be customized by users via <tt>PrefetchTreeNode</tt> API.</li>
+ <li>SQLTemplate and ProcedureQuery can be configured to emulate joint prefetching behavior.</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><a href="../../../../Documentation/User Guide/Queries/Customizing Queries/index.html" title="Customizing Queries">Customizing Queries</a>: In 1.2 Queries can have behavior in addition to storing query parameters. Now queries can route themselves and also handle their own execution at the JDBC level. This opens endless possibilities for custom extensions.</li>
+</ul>
+
+
+<ul>
+ <li>New Query Types: <a href="../../../../Documentation/User Guide/Queries/Customizing Queries/index.html" title="Customizing Queries">Customizing Queries</a> support in the access stack made it possible to include new useful types of queries:
+ <ul>
+ <li><a href="../../../../Documentation/User Guide/Queries/QueryChain/index.html" title="QueryChain">QueryChain</a></li>
+ <li><a href="../../../../Documentation/User Guide/Queries/ObjectIdQuery/index.html" title="ObjectIdQuery">ObjectIdQuery</a></li>
+ <li><a href="../../../../Documentation/User Guide/Queries/RelationshipQuery/index.html" title="RelationshipQuery">RelationshipQuery</a></li>
+ <li><a href="../../../../Documentation/User Guide/Queries/NamedQuery/index.html" title="NamedQuery">NamedQuery</a></li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li>More consistent <a href="../../../../Documentation/User Guide/Queries/Caching Query Results/index.html" title="Caching Query Results">cache/refresh API</a></li>
+</ul>
+
+
+<h4><a name="Guideto1.2Features-GeneratedColumns"></a><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html" title="Generated Columns">Generated Columns</a></h4>
+
+<p>Cayenne now supports auto-increment/identity columns as an alternative mechanism for primary key generation.</p>
+
+<h4><a name="Guideto1.2Features-DTDChanges"></a>DTD Changes</h4>
+
+<p>...</p>
+
+<h4><a name="Guideto1.2Features-JDK1.5FeaturesSupport"></a>JDK 1.5 Features Support</h4>
+
+<ul>
+ <li>Mapping Properties as Enums. Numeric or character database columns can now be mapped as custom Enums. Cayenne supports this out of the box without any special configuration. Assumption is made that character columns store the <b>name</b> of a given Enum object, while numeric columns store a position of a given Enum object in the Enum class.</li>
+</ul>
+
+
+<h4><a name="Guideto1.2Features-GenericPersistentClass"></a><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html" title="Generic Persistent Class">Generic Persistent Class</a></h4>
+
+<p>Cayenne allows CayenneDataObject (or its subclass) to be used as a generic persistent object, skipping class generation and compilation steps. Use only when appropriate!</p>
+
+<h4><a name="Guideto1.2Features-WebApplicationContextFilter"></a>WebApplicationContextFilter</h4>
+
+<p>A Servlet Specification 2.3 compatible way to bind DataContext to the request thread. See chapter 12.2.4 of the new User Guide shipped with 1.2 milestones for details.</p>
+
+<h4><a name="Guideto1.2Features-DBCPDataSourceFactory%3ADBCPPoolSupport"></a>DBCPDataSourceFactory: DBCP Pool Support</h4>
+
+<p>A connection pool from jakarta-commons DBCP project is now supported via the modeler - just select DBCPDataSourceFactory from the DataSource factories dropdown. The new factory loads its configuration from a specified properties file (see DBCPDataSourcefactory Javadocs for supported properties). DBCP connection pool is much more advanced than the one provided by Cayenne and supports a dozen or so runtime parameters. See Javadocs for org.objectsyle.cayenne.conf.DBCPDataSourceFactory for details.</p>
+
+<h4><a name="Guideto1.2Features-DatabaseAdapterImprovements%2FNewAdapters"></a>Database Adapter Improvements/New Adapters</h4>
+
+<ul>
+ <li>New adapter for Cloudscape/Derby</li>
+ <li>New adapter for FrontBase</li>
+ <li>New adapter for Ingres <em>(as of M12 it still has a few unresolved issues)</em></li>
+ <li>MySQL adapter is improved to support referential integrity constraints for InnoDB tables.</li>
+ <li>Adapter Auto Detection. Users no longer need to specify DbAdapter in the Modeler. All standard adapters are "guessed" by Cayenne in runtime using database metadata. Only custom adapters need to be set explicitly, using the new "Adapter" tab in the DataNode Editor panel. This simplifies configuration, makes deployment more transparent, and allows Cayenne to dynamically tweak adapter settings depending on the underlying database version and runtime parameters.</li>
+ <li><span class="nobr"><a href="http://objectstyle.org/cayenne/userguide/access-stack/extended-types.html" title="Visit page outside Confluence" rel="nofollow">Extended type mechanism<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> now allows mapping a persistent property as an interface. This can be achieved via ExtendedTypeFactory API. A custom <tt>ExtendedTypeFactory</tt> is registered in a manner similar to ExtendedType with adapter's <tt>ExtendedTypeMap</tt>: <tt>extendedTypeMap.addFactory(myFactory)</tt>. Cayenne already takes advantage of this API by providing a factory that handles an arbitrary JDK 1.5 Enum via reflection.</li>
+</ul>
+
+
+
+<h4><a name="Guideto1.2Features-DataContextImprovements"></a>DataContext Improvements</h4>
+
+<ul>
+ <li>User Properties Map. DataContext now maintains an internal map of user-defined values. This allows users to associate certain data with a given DataContext.</li>
+</ul>
+
+
+<ul>
+ <li>DataContextFactory (available since M6). DataContext allows to register an optional factory class (via the Modeler or in the API) that will be used to create DataContexts. This way users can implement DataContext subclasses that will seamlessly integrate in the existing Cayenne stack.</li>
+</ul>
+
+
+<ul>
+ <li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html" title="Nested DataContexts">DataContexts Nesting</a> that allows to perform partial in-memory commits/rollbacks.</li>
+</ul>
+
+
+<h4><a name="Guideto1.2Features-XMLSerializationCAY%3AXMLSerialization"></a><span class="error">[XML Serialization]</span></h4>
+
+<p>A new package <tt>org.objectstyle.cayenne.xml</tt> provides a way to encode arbitrary Java objects to XML and decode them from XML. It allows a great degree of control over the XML structure, thus simplifying integration with third party XML message systems. M5 features the first usable release of this feature. However there may be more changes in the course of 1.2.</p>
+
+<p><em>Need to document this better, for now see Javadocs for <tt>org.objectstyle.cayenne.xml.XMLEncoder</tt> and <tt>org.objectstyle.cayenne.xml.XMLDecoder</tt>.</em></p>
+
+<h4><a name="Guideto1.2Features-LoadingJNDIDataNodesfromLocalPreferencesUsingJNDI"></a><a href="../../../../Documentation/User Guide/Deployment/Using JNDI/index.html" title="Using JNDI">Loading JNDI DataNodes from Local Preferences</a></h4>
+
+<p>If a DataNode is configured to use JNDIDataSourceFactory, you can setup a "Local DataSource" via Modeler preferences with the name matching the JNDI name. After that when you run your application locally without a JNDI container, Cayenne would use local preferences database.</p>
+
+
+<h2><a name="Guideto1.2Features-Tools%3ACayenneModeler%2CAntTools"></a>Tools: CayenneModeler, Ant Tools</h2>
+
+<h4><a name="Guideto1.2Features-GeneralUIRework"></a>General UI Rework</h4>
+
+<p>CayenneModeler is significantly more user friendly compared to 1.1.</p>
+
+<ul>
+ <li>Modeler is packaged as a native application for Windows and Mac OS X.</li>
+ <li>Entity editors have their own "local" toolbars for working with attributes and relationships instead of trying to locate a needed button in the common top toolbar.</li>
+ <li>There are two history navigation buttons allowing to quickly return back to the places that you've recently visited.</li>
+ <li>There are new PK generator options at the DbEntity level.</li>
+ <li>A number of visual bug fixes, new icons, etc.</li>
+ <li>A number of performance enhancements.</li>
+</ul>
+
+
+
+<h4><a name="Guideto1.2Features-AntTaskImprovements"></a>Ant Task Improvements</h4>
+
+<ul>
+ <li>Antlib descriptor for Cayenne Ant Tasks</li>
+ <li>Vastly extended and improved <tt>cgen</tt>. See <tt>cgen</tt> task documetation in the user guide shipped with release for more details. Note that cgen maybe split in two tasks to make it simpler.</li>
+ <li>New <tt>cdbgen</tt> task</li>
+ <li>New <tt>cdataport</tt> database data porting task. <em>(moved from examples with improvements)</em></li>
+</ul>
+
+
+<h4><a name="Guideto1.2Features-CodeGenerationImprovements"></a>Code Generation Improvements</h4>
+
+<ul>
+ <li>Customizable Encoding Of Generated Files. Desired encoding for generated Java files can be specified in the Modeler in Preferences and as an "encoding" attribute of the cgen Ant task. This is helpful in cross-platform development situations.</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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/License/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Introduction/License/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/License/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/License/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,104 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - License</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><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">License</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a><ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/Acknowledgements/index.html">Acknowledgements</a></li>
+<li><a href="../../../../Documentation/User Guide/Introduction/Guide to 1.1 features/index.html">Guide to 1.1 features</a></li>
+<li><a href="../../../../Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html">Guide to 1.2 Features</a></li>
+<li><a href="../../../../Documentation/User Guide/Introduction/License/index.html">License</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>This software is distributed and should be used on terms of BSD software license. In short, it is free of charge, and unrestricted for commercial use as well. Full license text can be found here:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>The ObjectStyle Group Software License, version 1.1
+ObjectStyle Group - http://objectstyle.org/
+
+Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
+of the software. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+
+3. The end-user documentation included with the redistribution, if any,
+ must include the following acknowlegement:
+ "This product includes software developed by independent contributors
+ and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
+ Alternately, this acknowlegement may appear in the software itself,
+ if and wherever such third-party acknowlegements normally appear.
+
+4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
+ or promote products derived from this software without prior written
+ permission. For written permission, email
+ "andrus at objectstyle dot org".
+
+5. Products derived from this software may not be called "ObjectStyle"
+ or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
+ names without prior written permission.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
+ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+====================================================================
+
+This software consists of voluntary contributions made by many
+individuals and hosted on ObjectStyle Group web site. For more
+information on the ObjectStyle Group, please see http://objectstyle.org/.
+</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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/License/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Introduction/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,62 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Introduction</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><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">Introduction</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/User Guide/Introduction/index.html">Introduction</a><ul>
+<li><a href="../../../Documentation/User Guide/Introduction/Acknowledgements/index.html">Acknowledgements</a></li>
+<li><a href="../../../Documentation/User Guide/Introduction/Guide to 1.1 features/index.html">Guide to 1.1 features</a></li>
+<li><a href="../../../Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html">Guide to 1.2 Features</a></li>
+<li><a href="../../../Documentation/User Guide/Introduction/License/index.html">License</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne is a powerful, full-featured OpenSource Object/Relational framework. Cayenne is written in Java and is intended for Java developers working with relational databases. Cayenne has been successfully deployed in production environments on high volume sites.</p>
+
+<p>Cayenne allows to reduce the development time in any database project by creating an object-oriented abstraction of the database schema. Development teams using Cayenne will be able to concentrate on the core business requirements and the data model instead of the SQL details.</p>
+
+<p>Among other things Cayenne provides management of persistent Java objects mapped to relational databases, single method call queries and updates (including atomic updates of all modified objects), seamless integration of multiple databases into a single virtual data source. Cayenne is distributed with CayenneModeler - a complete GUI mapping tool that supports reverse-engineering of RDBMS schema, working with database mappings and generation of Java source code for the persistent objects.</p>
+
+<p>Cayenne comes with a comprehensive set of HTML documentation and full source code, including source code for the GUI tools. Cayenne free support is provided via user mailing lists. Commerical support and consulting services are also available. </p>
+
+<h3><a name="Introduction-Sections"></a>Sections</h3>
+<ul>
+ <li><a href="../../../Documentation/User Guide/Introduction/Guide to 1.2 Features/index.html" title="Guide to 1.2 Features">Guide to 1.2 Features</a></li>
+ <li><a href="../../../Documentation/User Guide/Introduction/Guide to 1.1 features/index.html" title="Guide to 1.1 features">Guide to 1.1 Features</a></li>
+ <li><a href="../../../Documentation/User Guide/Introduction/Acknowledgements/index.html" title="Acknowledgements">Acknowledgements</a></li>
+ <li><a href="../../../Documentation/User Guide/Introduction/License/index.html" title="License">License</a></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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Introduction/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/Caching%20Lookup%20Tables/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,58 @@
+<html>
+ <head>
+ <title>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://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User 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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Data Rows/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/Data%20Rows/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Data Rows/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Data Rows/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,88 @@
+<html>
+ <head>
+ <title>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://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User 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.objectstyle.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.objectstyle.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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Data Rows/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/Iterating%20Through%20Data%20Rows/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,100 @@
+<html>
+ <head>
+ <title>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://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User 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.objectstyle.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.access.ResultIterator;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.CayenneException;
+<span class="code-keyword">import</span> org.objectstyle.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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Paginated Queries/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/Paginated%20Queries/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Paginated Queries/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Paginated Queries/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,90 @@
+<html>
+ <head>
+ <title>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://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User 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.objectstyle.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.objectstyle.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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Paginated Queries/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Prefetching/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/Prefetching/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Prefetching/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Prefetching/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,162 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Prefetching</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h3><a name="Prefetching-IntroductiontoPrefetching"></a>Introduction to Prefetching</h3>
+
+<p><span class="nobr"><a href="http://objectstyle.org/cayenne/userguide/perform/prefetching.html" title="Visit page outside Confluence" rel="nofollow">Prefetching<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> 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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/Prefetching/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Performance%20Tuning/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,57 @@
+<html>
+ <head>
+ <title>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://objectstyle.org/cayenne/"><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/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a><ul>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/Caching Lookup Tables/index.html">Caching Lookup Tables</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/Data Rows/index.html">Data Rows</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/Iterating Through Data Rows/index.html">Iterating Through Data Rows</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/Paginated Queries/index.html">Paginated Queries</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html">Prefetching</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><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></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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Performance Tuning/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/caching.jpg
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Queries/Caching%20Query%20Results/caching.jpg?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/caching.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Queries/Caching%20Query%20Results/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,173 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Caching Query Results</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><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 Query Results</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../Documentation/User Guide/Queries/Caching Query Results/index.html">Caching Query Results</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/Parameterized Queries/index.html">Parameterized Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/Qualifier Expressions/index.html">Qualifier Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/Scripting SQLTemplate/index.html">Scripting SQLTemplate</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/SelectQuery Customization/index.html">SelectQuery Customization</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/Using Orderings/index.html">Using Orderings</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne provides a way to cache query results, avoiding unneeded database trips for the frequently used queries. Caching policy is configured per query. Policy can be set via the API or in CayenneModeler.</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><b class="strong">Upgrading to Cayenne 1.2 and Newer</b><br /><tt>org.objectstyle.cayenne.query.GenericSelectQuery</tt> interface that defined cache policy types is deprecated. Cache policies are now a part of the new <tt>org.objectstyle.cayenne.query.QueryMetadata</tt> interface.</td></tr></table>
+
+<p>The following cache policies are supported:</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'>Policy</th>
+<th class='confluenceTh'>Cache Scope</th>
+<th class='confluenceTh'>Cache Behavior</th>
+</tr>
+<tr>
+<td class='confluenceTd'><em>(default policy)</em> <tt>QueryMetadata.NO_CACHE</tt> </td>
+<td class='confluenceTd'>N/A</td>
+<td class='confluenceTd'>Always fetch, never use cache, never save to cache</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.LOCAL_CACHE</tt></td>
+<td class='confluenceTd'>DataContext</td>
+<td class='confluenceTd'>If result is previously cached, use it, otherwise do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.LOCAL_CACHE_REFRESH</tt></td>
+<td class='confluenceTd'>DataContext</td>
+<td class='confluenceTd'>Never use cache, alwyas do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.SHARED_CACHE</tt></td>
+<td class='confluenceTd'>DataDomain (usually shared by all contexts in the same JVM)</td>
+<td class='confluenceTd'>If result is previously cached, use it, otherwise do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.SHARED_CACHE_REFRESH</tt></td>
+<td class='confluenceTd'>DataDomain (usually shared by all contexts in the same JVM)</td>
+<td class='confluenceTd'>Never use cache, alwyas do a fetch and store result in cache for future use</td>
+</tr>
+</tbody></table>
+
+<p>It is important to understand that caching of <b>result lists</b> is done independently from caching of <b>individual DataObjects and DataRows</b>. Therefore the API is different as well. Also cached results lists are not synchronized across VMs (even the shared cache).</p>
+
+
+<h3><a name="CachingQueryResults-APIforResultCaching"></a>API for Result Caching</h3>
+
+<p>Users must set two Query parameters to configure caching - query <b>name</b> that is used as a key to result cache and query <b>cache policy</b> (one of the policies above). Note that if two unrelated queries have the same name, they will hit the same cache entry. This is not a bug, this is a feature that should be taken into consideration when naming queries.</p>
+
+<p>Below we will create a query and set its caching policy to LOCAL_CACHE:</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">// set query name that will be used as a unique key to perform result caching
+</span>query.setName(<span class="code-quote">"MySelect"</span>);
+
+<span class="code-comment">// set local cache policy, meaning the cache will be stored in the DataContext
+</span><span class="code-comment">// and not shared between different contexts
+</span>query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE);
+
+DataContext context = ... <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// there is probably no cache at <span class="code-keyword">this</span> point, so the query will hit the database
+</span>List objects = context.performQuery(query);</pre>
+</div></div>
+
+<p>Reruning the query in the same DataContext at a later time will be much faster as it will be hitting the cache:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects1 = context.performQuery(query);</pre>
+</div></div>
+
+<p>Here we want to refresh the cache, but still keep caching the fresh result:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE_REFRESH);
+
+List objects2 = context.performQuery(query);</pre>
+</div></div>
+
+<p>The example above shows caching with <tt>SelectQuery</tt>, but it works exactly the same way for <tt>SQLTemplate</tt> and <tt>ProcedureQuery</tt>. Similarly <tt>SHARED_CACHE</tt> and <tt>SHARED_CACHE_REFRESH</tt> cache policies create cache shared by all DataDontexts that work with a given DataDomain. </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><b class="strong">Upgrading to Cayenne 1.2 and Newer</b><br /><br/>
+Cache refreshing API has changed in 1.2. Cayenne 1.1 relied on the use of <tt>SelectQuery.setRefreshingObjects(..)</tt> to determine whether to expire cached result lists. This is no longer the case (setting this flag only refreshes <b>individual objects</b> as it should, and has no effect whatsoever on list caching). Instead caching and cache refreshing is controlled by the cache policy as described above.</td></tr></table>
+
+
+<h3><a name="CachingQueryResults-QueriesMappedinCayenneModeler"></a>Queries Mapped in CayenneModeler</h3>
+
+<p>The easiest way to set up caching is by creating a named query in CayenneModeler with the appropriate caching type.</p>
+
+<p><img src="caching.jpg" align="absmiddle" border="0" /></p>
+
+<p>Then it can be executed via DataContext:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects1 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">false</span>);</pre>
+</div></div>
+
+<p>The second "false" parameter above indicated that if possible, cached result should be used. Now if we want to force refresh, it can be changed to true (for just this invocation - this does not affect the underlying saved query)</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects2 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">true</span>);</pre>
+</div></div>
+
+<p>Note that parameterized named queries will still work correctly with the cache. We've already mentioned that the users must ensure that two queries must have different names if they fetch logically different data. This is NOT the case with queries stored in the DataMap. If you run the same named query with different sets of parameters, Cayenne will internally generate unique cache keys for each distinct parameter set.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">Map parameters = Collections.singletonMap(<span class="code-quote">"key"</span>, <span class="code-quote">"value1"</span>);
+List objects1 = context.performQuery(<span class="code-quote">"MyQuery"</span>, parameters, <span class="code-keyword">false</span>);</pre>
+</div></div>
+
+<p>Now if we run the same query with a different set of parameters, Cayenne will do the right thing and create a separate entry in the cache:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">Map parameters = Collections.singletonMap(<span class="code-quote">"key"</span>, <span class="code-quote">"value2"</span>);
+List objects2 = context.performQuery(<span class="code-quote">"MyQuery"</span>, parameters, <span class="code-keyword">false</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-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Queries/Caching Query Results/index.html
------------------------------------------------------------------------------
svn:eol-style = native