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 [2/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/Ant Tasks/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Ant%20Tasks/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Ant Tasks/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Ant Tasks/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,99 @@
+<!--
+ 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 - Ant Tasks</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">Ant Tasks</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><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html">cgen</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdbgen/index.html">cdbgen</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdeploy/index.html">cdeploy</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdataport/index.html">cdataport</a></li>
+</ul>
+</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="AntTasks-Anttasks"></a>Ant tasks</h2>
+
+<p>Cayenne ships with Ant tasks that provide Ant frontend to a number of useful operations in Cayenne. The following tasks are included:</p>
+
+<ul>
+ <li><b><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">cgen</a></b> - Java class generator</li>
+ <li><b><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdbgen/index.html" title="cdbgen">cdbgen</a></b> - Database schema generator</li>
+ <li><b><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdeploy/index.html" title="cdeploy">cdeploy</a></b> - Deployment configurator</li>
+ <li><b><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdataport/index.html" title="cdataport">cdataport</a></b> - Data porting tool.</li>
+</ul>
+
+
+<h3><a name="AntTasks-ImportingCayenneTasksinbuild.xml"></a>Importing Cayenne Tasks in build.xml</h3>
+<p>Cayenne tasks above can be imported individually using Ant taskdef, as described in each task documentation page. However the users of Ant 1.6 and newer can take advantage of Antlib Ant feature. <span class="nobr"><a href="http://ant.apache.org/manual/CoreTypes/antlib.html" title="Visit page outside Confluence" rel="nofollow">Antlib<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> allows 3rd party tasks and types to be defined easily. Cayenne has an embedded antlib.xml descriptor file in the package <tt>org.apache.cayenne.tools</tt>. All of Cayenne's Ant tasks can be defined at once using the following definition in your Ant build file:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><typedef resource=<span class="code-quote">"org/apache/cayenne/tools/antlib.xml"</span>></span>
+ <span class="code-tag"><classpath refid=<span class="code-quote">"classpath"</span>/></span>
+<span class="code-tag"></typedef></span></pre>
+</div></div>
+
+<p>When using the Antlib construct, omit the <tt><taskdef></tt> elements shown in the examples of each task, as the antlib.xml file defines all of the Cayenne Ant tasks. </p>
+
+<h3><a name="AntTasks-Sections"></a>Sections</h3>
+
+<ol>
+ <li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">cgen</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdbgen/index.html" title="cdbgen">cdbgen</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdeploy/index.html" title="cdeploy">cdeploy</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/cdataport/index.html" title="cdataport">cdataport</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/Ant Tasks/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Caching%20and%20Fresh%20Data/RefreshQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,105 @@
+<!--
+ 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 - RefreshQuery</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">RefreshQuery</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html">RefreshQuery</a><ul>
+</ul>
+</li>
+</ul>
+</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="RefreshQuery-Refreshacollectionofobjects"></a>Refresh a collection of objects</h3>
+
+<p>Internally Cayenne will remove those objects from caches. All object relationships should be invalidated as well. No query results are affected, but objects in those result lists should get invalidated. </p>
+
+<p><em>Limitation: shared list cache stores all results as DataRows and doesn't use uniquing ... so such refresh would fail to invalidate ids stored in the shared cache; possible solution - store ObjectIds in the shared cache instead of full DataRows and resolve them on the fly.</em></p>
+
+<h3><a name="RefreshQuery-Refreshasingleobject"></a>Refresh a single object</h3>
+
+<p>A special case of refresh collection of objects. Should probably use the same logic.</p>
+
+<h3><a name="RefreshQuery-Refreshresultsofaquery"></a>Refresh results of a query</h3>
+
+<p>Query lists are removed from caches. Since any objects matched by query need to be refreshed as well, the query is executed eagerly.</p>
+
+<h3><a name="RefreshQuery-Refreshresultsofagroupofqueriesidentifiedbyoneormorecachegroupnames."></a>Refresh results of a group of queries identified by one or more cache group names.</h3>
+
+<p>Removes or invalidates query results for the specified group keys, in hope that the objects will be refreshed the next time any query from the group is executed.</p>
+
+<p><em>Limitation: This is the only case that doesn't allow to target individual objects.</em></p>
+
+<h3><a name="RefreshQuery-RefreshAll"></a>Refresh All</h3>
+
+<p>Refreshes all objects (including reverting and refreshing dirty objects) and all query results. This can be done lazily. Not sure if we need fine-grained control (refresh a single context; refresh shared caches). </p>
+
+<h2><a name="RefreshQuery-ProposedSolution%3ARefreshQuery"></a>Proposed Solution: RefreshQuery</h2>
+
+<p>Related JIRA issue: <span class="nobr"><a href="http://issues.apache.org/cayenne/browse/CAY-632" title="Visit page outside Confluence" rel="nofollow">http://issues.apache.org/cayenne/browse/CAY-632<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span><br/>
+RefreshQuery: <span class="nobr"><a href="http://svn.apache.org/repos/asf/incubator/cayenne/main/trunk/core/cayenne-jdk1.4/src/main/java/org/apache/cayenne/query/RefreshQuery.java" title="Visit page outside Confluence" rel="nofollow">http://svn.apache.org/repos/asf/incubator/cayenne/main/trunk/core/cayenne-jdk1.4/src/main/java/org/apache/cayenne/query/RefreshQuery.java<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></p>
+
+<p>There are the following advantages to this approach:</p>
+
+<ul>
+ <li>Hiding the difference between "eager refresh" (refetch) and "lazy refresh" (invalidate), leaving it up to Cayenne to decide. For instance if Cayenne can't reliably match all objects in memory, it would do a refetch; if it can - it will do invalidate).</li>
+ <li>Invalidate query lists and objects in those queries in one shot. (In case a query result is cached and there is a way to infer the objects involved; otherwise it will do a fetch).</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/Caching and Fresh Data/RefreshQuery/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Caching%20and%20Fresh%20Data/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,96 @@
+<!--
+ 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 and Fresh Data</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 and Fresh Data</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><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html">RefreshQuery</a></li>
+</ul>
+</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="CachingandFreshData-WhatIsCachedinCayenne"></a>What Is Cached in Cayenne</h2>
+
+<p>Using multiple levels of caching in Cayenne allows to significantly improve performance, reducing the number of trips to the database. There are two things that Cayenne can cache - individual objects and query results (i.e. lists of objects). These two types are handled differently by Cayenne, as described below.</p>
+
+<h2><a name="CachingandFreshData-CachingPersistentObjects"></a>Caching Persistent Objects</h2>
+
+<p>Individual objects are <a href="../../../Documentation/Cayenne Guide/Design/Object Caching/index.html" title="Object Caching">cached by Cayenne</a> by default as they are fetched from the database or created by the user. Such caching is both a performance optimization mechanism and a way to ensure internal object <a href="http://cwiki.apache.org/confluence/confluence/display/CAYDOC/Cayenne%20Contract#CayenneContract-Uniquing" title="Uniquing on Cayenne Contract">uniquing</a>. Users normally do not need to do anything special for this to work. Still there are a few parameters that can be configured </p>
+
+<h2><a name="CachingandFreshData-CachingQueryResultsPluggableCache"></a>Caching Query Results - Pluggable Cache</h2>
+
+<p>Out of the box Cayenne provides two implementations of the pluggable cache factory:</p>
+
+<ul>
+ <li><tt>'org.apache.cayenne.cache.MapQueryCacheFactory'</tt> is a default factory that uses an LRU map to store query results. LRU map ensures that cached results would not take up all available memory, but otherwise it has no cache expiration mechanism.</li>
+</ul>
+
+
+<ul>
+ <li><tt>'org.apache.cayenne.cache.OSQueryCacheFactory'</tt> is a factory that installs OpenSymphony <span class="nobr"><a href="http://www.opensymphony.com/oscache/wiki/Configuration.html" title="Visit page outside Confluence" rel="nofollow">OSCache<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> as a cache provider for Cayenne queries. It allows to configure cache expiration policies and cross-VM synchronization via an <tt>"oscache.properties"</tt> that should be placed in the CLASSPATH.</li>
+</ul>
+
+
+<h2><a name="CachingandFreshData-CacheGroups"></a>Cache Groups</h2>
+
+<h2><a name="CachingandFreshData-RefreshingtheData"></a>Refreshing the Data</h2>
+
+
+<h3><a name="CachingandFreshData-Sections"></a>Sections</h3>
+
+<ol>
+ <li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/RefreshQuery/index.html" title="RefreshQuery">RefreshQuery</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/Caching and Fresh Data/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Customization/Custom%20Query%20Cache%20Provider/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,86 @@
+<!--
+ 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 - Custom Query Cache Provider</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">Custom Query Cache Provider</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></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/Extended Types/index.html">Extended Types</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html">Custom Query Cache Provider</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>By default Cayenne stores cached query results in an LRUMap (<tt>'org.apache.cayenne.cache.MapQueryCacheFactory'</tt>) and can also be configured to use OSCache (via <tt>'org.apache.cayenne.cache.OSQueryCacheFactory'</tt>). If none of these cache engines suit specific application needs, users can hook up their own. </p>
+
+<p>Assuming you have some cache management library that you want to integrate with Cayenne, you need to implement a <tt>'org.apache.cayenne.cache.QueryCacheFactory'</tt> interface that creates an instance of <tt>'org.apache.cayenne.cache.QueryCache'</tt> that is a facade to your cache engine.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">class MyFactory <span class="code-keyword">implements</span> QueryCacheFactory {
+ <span class="code-keyword">public</span> QueryCache getQueryCache(Map properties) {
+ <span class="code-keyword">return</span> <span class="code-keyword">new</span> MyQueryCache(properties);
+ }
+}</pre>
+</div></div>
+
+<p>Custom factory can be set on the DataDomain:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+domain.setQueryCacheFactory(<span class="code-keyword">new</span> MyFactory());</pre>
+</div></div>
+
+<p><em>TODO: pending <span class="nobr"><a href="https://issues.apache.org/cayenne/browse/CAY-825" title="Visit page outside Confluence" rel="nofollow">CAY-825 implementation<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, setting custom factory should be possible via CayenneModeler.</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/Customization/Custom Query Cache Provider/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Customization/Extended%20Types/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,86 @@
+<!--
+ 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 - Extended Types</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">Extended Types</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></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/Extended Types/index.html">Extended Types</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html">Custom Query Cache Provider</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) and a very specific mapping of these types to Java Object Types, such as java.lang.String, java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver. CayenneModeler allows to configure an arbitrary Java class as an <tt>org.apache.cayenne.map.ObjAttribute</tt> type by simply entering a fully-qualified name such class in the type column of an ObjAttribute. However there is more to it than just that. Cayenne needs to know how to instantiate this type from a database "primitive" value, and conversly, how to transform an object of the custom type to a JDBC-compatible object.</p>
+
+<h3><a name="ExtendedTypes-SupportingNonStandardTypes"></a>Supporting Non-Standard Types</h3>
+
+<p><tt>org.apache.cayenne.access.types.ExtendedType</tt> interface serves to integrate a custom attribute type to Cayenne. An implementation must provide <tt>ExtendedType.getClassName()</tt> method that returns a fully qualified Java class name for the supported custom type, and a number of methods that convert data between JDBC and custom type. Installing an ExtendedType currently has to be done in the code, some time during Cayenne startup (modeler support will be added in the future). The following code sample demonstrates this procedure:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// create custom ExtendedType instance
+</span>ExtendedType customType = <span class="code-keyword">new</span> MyCustomType();
+
+<span class="code-comment">// Find DataNode
+</span>DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+DataNode node = domain.getNode(<span class="code-quote">"node_name_from_the_project"</span>);
+
+<span class="code-comment">// install ExtendedType
+</span>node.getAdapter().getExtendedTypes().registerType(customType);</pre>
+</div></div>
+
+<h3><a name="ExtendedTypes-DbAdaptersandExtendedTypes"></a>DbAdapters and Extended Types</h3>
+
+<p>As shown in the example above, ExtendedTypes are stored by <a href="../../../../Documentation/Cayenne Guide/Design/Runtime Components/DbAdapter/index.html" title="DbAdapter">DbAdapter</a>. In fact DbAdapters often install their own extended types to address incompatibilities, incompletness and differences between JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc. Adapters provided with Cayenne override <tt>configureExtendedTypes()</tt> method to install their own types, possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</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/Customization/Extended Types/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Customization/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,76 @@
+<!--
+ 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 - Customization</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">Customization</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></li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a><ul>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/Extended Types/index.html">Extended Types</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html">Custom Query Cache Provider</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="Customization-Customizing"></a>Customizing</h2>
+
+<p>Here we will discuss Cayenne extension points and customization techniques:</p>
+
+<h3><a name="Customization-Sections"></a>Sections</h3>
+
+<ol>
+ <li><span class="nobr"><a href="/confluence/pages/createpage.action?spaceKey=CAYDOC&title=Custom%20DbAdapter&linkCreation=true&fromPageId=10515" title="Create Page: Custom DbAdapter" class="createlink">Custom DbAdapter<sup><img class="rendericon" src="../../../images/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Customization/Extended Types/index.html" title="Extended Types">Extended Types</a></li>
+ <li><a href="../../../Documentation/Cayenne Guide/Customization/Custom Query Cache Provider/index.html" title="Custom Query Cache Provider">Custom Query Cache Provider</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/Customization/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/DataContextDelegate/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,93 @@
+<!--
+ 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 - DataContextDelegate</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">DataContextDelegate</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</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></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>DataContext supports runtime customization via a DataContextDelegate interface. A user can assign a custom delegate instance to a DataContext by calling DataContext.setDelegate(..). Delegate is optional, and if it is not set, DataContext would go on with its default behavior. If a delegate is set, DataContext consults with it at some critical points in the normal flow execution. A delegate can modify the flow, abort an operation, modify objects participating in an operation, or perform any other tasks it deems necessary.</p>
+
+<p>DataContextDelegate currently has two groups of methods - method to filter select queries, and methods to react to external updates of the ObjectStore:</p>
+
+<ul>
+ <li><tt>public Query willPerformQuery(DataContext context, Query query)</tt></li>
+</ul>
+
+
+<p>Called from DataContext.performQuery(...) before running any select query, including prefetch queries. Implementation has a choice to modify an original query, replace it with alternative one, or return NULL, blocking query execution alltogether.</p>
+
+<ul>
+ <li><tt>public boolean shouldMergeChanges(DataObject object, DataRow snapshotInStore)</tt><br/>
+ <tt>public boolean shouldProcessDelete(DataObject object)</tt><br/>
+ <tt>public void finishedMergeChanges(DataObject object)</tt><br/>
+ <tt>public void finishedProcessDelete(DataObject object)</tt></li>
+</ul>
+
+
+<p>These methods are called by the ObjectStore whenever it performs an update of its state triggered by external events. Default ObjectStore behavior is to merge all changes to the existing objects, and change deleted objects state to TRANSIENT, removing them from the store. Delegate has an option to abort standard processing by returning "false" from "should*" methods.</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/DataContext/DataContextDelegate/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextFactory/datacontextfactory.jpg
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/DataContextFactory/datacontextfactory.jpg?view=auto&rev=554413
==============================================================================
Binary file - no diff available.
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextFactory/datacontextfactory.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/DataContextFactory/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,75 @@
+<!--
+ 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 - DataContextFactory</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">DataContextFactory</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</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></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>To customize how the DataContext is built, an <em>optional</em> DataContextFactory can be registered with DataDomain in the Modeler. The class name you enter must implement <tt>org.apache.cayenne.access.DataContextFactory</tt> interface. If a factory is entered, Cayenne will use it in <a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html" title="Obtaining DataContext">all places</a> where the DataContext is created. A single factory instance is reused for the life of the DataDomain.</p>
+
+<p><img src="datacontextfactory.jpg" align="absmiddle" border="0" /></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/DataContext/DataContextFactory/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/DataObject%20State%20Management/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,197 @@
+<!--
+ 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 - DataObject State Management</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">DataObject State Management</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</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></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>Arguably the second most important function of DataContext (first is performing queries) is keeping track of changes made to the registered DataObjects. "Registered" is a keyword here - registering an object with DataContext is what gives this object its persistent qualities.</p>
+
+<h3><a name="DataObjectStateManagement-HowtoRegisteraDataObject"></a>How to Register a DataObject</h3>
+
+<p>Behind the scenes "registering an object" results in storing this object in a map using its ObjectId as a key, setting "dataContext" property of a DataObject to the current DataContext, and taking a snapshot of all persistent properties to be able to track later modifications. Objects can become "registered" in two ways:</p>
+
+<ul>
+ <li>automatically when they are fetched via query API</li>
+ <li>explicitly for the newly created objects</li>
+</ul>
+
+
+<p>Whenever a selecting query is executed by a DataContext, all fetched objects are automatically registered with this DataContext. On the other hand, newly created objects must be registered explicitly:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+Artist artist = <span class="code-keyword">new</span> Artist();
+context.registerNewObject(artist);
+
+<span class="code-comment">// after the line above is executed, artist object acquired <span class="code-quote">"persistent"</span> behavior
+</span><span class="code-comment">// and is said to be <span class="code-quote">"managed"</span> by DataContext</span></pre>
+</div></div>
+
+<p>This code can be simplified - object creation and registrations steps can be combined in one method call:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+Artist artist = (Artist) context.newObject(Artist.class);</pre>
+</div></div>
+
+<p>This method relies on the presence of a no-argument constructor in the DataObject class.</p>
+
+<h3><a name="DataObjectStateManagement-CheckingtheStateofRegisteredDataObjects"></a>Checking the State of Registered DataObjects</h3>
+
+<p>State transitions of DataObjects from persistence point of view are discussed in the "Design" chapter. State of each individual object is described by an integer constant obtained via a call to DataObject.getPeristenceState(). Allowed states are defined as static variables in PersistenceState class.</p>
+
+<p>When a new object is inserted to the DataContext as described above, it becomes "NEW":</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// artist will become PersistenceState.NEW
+</span>Artist artist = (Artist) context.newObject(Artist.class);</pre>
+</div></div>
+
+<p>When a DataContext is committed, such object becomes "COMMITTED":</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// artist will become PersistenceState.COMMITTED
+</span>context.commitChanges();</pre>
+</div></div>
+
+<p>When any of the attributes or relationships of the fetched or committed object are changed, such an object becomes MODIFIED:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// <span class="code-keyword">this</span> will change the object state to PersistenceState.MODIFIED
+</span>artist.setName(<span class="code-quote">"NewName"</span>);</pre>
+</div></div>
+
+<p>When a fetched or committed object is explicitly deleted from the DataContext, object becomes DELETED:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// <span class="code-keyword">this</span> will change the object state to PersistenceState.DELETED
+</span>context.deleteObject(artist);</pre>
+</div></div>
+
+<p>DataContext is said to have changes if it has one or more registered objects in a state PersistenceState.MODIFIED, PersistenceState.NEW or PersistenceState.DELETED. DataContext provides the following method to check if it has any changed objects:</p>
+
+<ul>
+ <li><tt>public boolean hasChanges()</tt></li>
+</ul>
+
+
+<p>There is also a way to obtain a list of changed objects in each one of the above states:</p>
+
+<ul>
+ <li><tt>public java.util.Collection newObjects()</tt></li>
+ <li><tt>public java.util.Collection deletedObjects()</tt></li>
+ <li><tt>public java.util.Collection modifiedObjects()</tt></li>
+</ul>
+
+
+<h3><a name="DataObjectStateManagement-SavingAllUncommittedDataObjects"></a>Saving All Uncommitted DataObjects</h3>
+
+<p>All of the uncommitted objects ("uncommitted" means "new", "modified" or "deleted") are saved ("committed") to the database with a single method call on the DataContext:</p>
+
+<ul>
+ <li><tt>public void commitChanges()</tt></li>
+</ul>
+
+
+<p>Method commitChanges takes care of building correct SQL statements, generating primary keys and transactional behaviour. It roughly follows this scenario:</p>
+
+<ul>
+ <li>Checks if there are any changed objects (also detecting "phantom" modifications, e.g. if an object property was "updated" with the equivalent value).</li>
+ <li>Validates "dirty" objects (for more information on validation see <a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html" title="DataObject Validation">this page</a>).</li>
+ <li>Generates primary keys for any NEW objects that require autogenerated key.</li>
+ <li>Builds any needed INSERT, UPDATE, DELETE queries.</li>
+ <li>Starts the database transaction.</li>
+ <li>Runs the queries.</li>
+ <li>Commits transaction.</li>
+ <li>Changes all committed objects state to PersistenceState.COMMITTED.</li>
+ <li>Updates internally stored snapshots of the recently saved objects.</li>
+</ul>
+
+
+
+<h3><a name="DataObjectStateManagement-UndoingAllUncommittedChanges"></a>Undoing All Uncommitted Changes</h3>
+
+<p>There is a way for the DataContext to undo all uncommitted changes:</p>
+
+<ul>
+ <li><tt>public void rollbackChanges()</tt></li>
+</ul>
+
+
+<p>This will restore the persistence state and the values of all registered objects to the values that objects had when they were fetched or the last commitChanges was executed. This effectively restores previously committed state of the object graph. Note that any NEW objects are unregistered from the context.</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/DataContext/DataObject State Management/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/Moving%20Objects%20Between%20Contexts/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,93 @@
+<!--
+ 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 - Moving Objects Between Contexts</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">Moving Objects Between Contexts</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</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></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="MovingObjectsBetweenContexts-MovingObjectsBetweenContexts"></a>Moving Objects Between Contexts</h2>
+<p>Each instance of a DataObject belongs to only one DataContext for the duration of the object lifecycle. Sometimes there maybe a need to transfer a list of objects from one DataContext to another. The goal of this operation is to be able to use such objects in relationships with objects of the target DataContext. Most common use for this feature is the following. An application may have a "shared" DataContext that is used to fetch "static" read only lookup data. To avoid fetching the same data over and over again for each session, objects from the shared DataContext can be transferred to a session DataContext by calling <tt>DataContext.localObject()</tt>:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext sessionContext = DataContext.getThreadDataContext();
+
+HttpSession session; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// assume that ServletContext contains a list of UserType DataObjects
+</span><span class="code-comment">// fetched via some global DataContext
+</span>List sharedUserTypes = (List) session.getServletContext().getAttribute("userTypes);
+UserType sharedType = (UserType) sharedUserTypes.get(0);
+
+UserType localType = (UserType) sessionContext.localObject(sharedType.getObjectId(), sharedType);
+User user; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// now it is safe to use the UserType in relationships with other
+</span><span class="code-comment">// session objects
+</span>user.setUserType(localType);
+...</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/DataContext/Moving Objects Between Contexts/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/Nested%20DataContexts/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,116 @@
+<!--
+ 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 - Nested DataContexts</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">Nested DataContexts</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</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></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>One of the goals of the DataContext is to provide an isolated area where local object changes can be performed without affecting other similar areas or the underlying storage. At some point in time users would either commit changes to the underlying storage or undo them (roll them back). </p>
+
+<p>If a DataContext is directly attached to the DataDomain, a call to <tt>DataContext.commitChanges()</tt> results in changes written to the database. On the other hand if DataContext's direct parent in the access stack is not a DataDomain, but another DataContext, changes can be saved to the parent without saving them to the database. Such child context is often called "nested".</p>
+
+<p>Nested contexts are useful in many situations, such as nested UI dialogs, complicated workflows, etc.</p>
+
+<h3><a name="NestedDataContexts-CreatingNestedDataContext"></a>Creating Nested DataContext</h3>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext parent = ...
+DataContext child = context.createChildDataContext();</pre>
+</div></div>
+
+<p>Note that if there was a DataContextFactory configured for the DataDomain at the top of the context hierarchy, such factory will be used internally by <tt>createChildDataContext</tt> method. Also child DataContext inherits parent's <tt>"ValidatingObjectsOnCommit"</tt> property.</p>
+
+<h3><a name="NestedDataContexts-UsingNestedDataContext"></a>Using Nested DataContext</h3>
+
+<p>A nested DataContext does everything a regular DataContext can do, i.e. perform queries, register new objects, delete objects, etc. A specific behavior is the ability to choose between a cascading or one-level commit or rollback.</p>
+
+<p>Regular <tt>"commitChanges"</tt> call does a cascading commit through the stack of parents all the way to the database:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.commitChanges();</pre>
+</div></div>
+
+<p>However it is possible to commit to parent, without triggering a DB commit:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.commitChangesToParent();</pre>
+</div></div>
+
+<p>Same thing with rollback, <tt>"rollbackChanges"</tt> does a cascading rollback:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.rollbackChanges();</pre>
+</div></div>
+
+<p>While <tt>"rollbackChangesLocally"</tt> only affects the nested context, and not even sent to the parent:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.rollbackChangesLocally();</pre>
+</div></div>
+
+
+<h3><a name="NestedDataContexts-NestedDataContextsPerformance"></a>Nested DataContexts Performance</h3>
+
+<p>All cascading operations (such as a select query or a cascading update) initiated by a nested DataContext will have to travel through the stack of parent contexts, incurring certain delay at each stack level. The delay is due to the fact that each DataContext has to update its own objects during most operations. So nesting should only be used when application specifics require to do so. Also nesting of more than a few levels should be avoided.</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/DataContext/Nested DataContexts/index.html
------------------------------------------------------------------------------
svn:eol-style = native