cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1072639 - in /cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation: Cayenne Guide/Caching and Fresh Data/Query Result Caching/ Cayenne Guide/Customization/Extended Types/ Cayenne Guide/DataContext/Obtaining DataContext/ Cayenne...
Date Sun, 20 Feb 2011 17:21:02 GMT
Author: aadamchik
Date: Sun Feb 20 17:21:02 2011
New Revision: 1072639

URL: http://svn.apache.org/viewvc?rev=1072639&view=rev
Log:
refreshing 3.1 docs from wiki

Modified:
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Stored Procedures/Executing a Stored Procedure/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Delete/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Java Classes/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Object Relational Mapping/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Setup/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Starting Project/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Webapp/index.html
    cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Overview/Guide to 3.1 Features/index.html

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Caching%20and%20Fresh%20Data/Query%20Result%20Caching/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html Sun Feb 20 17:21:02 2011
@@ -146,17 +146,17 @@ cayenne.group.artists.cron = 10 1 * * *
 
 <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
 <pre>cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JMSBroadcastingListener
-# other JMS paramaters go here...</pre>
+# other JMS parameters go here...</pre>
 </div></div>
 
 <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
 <pre>cache.event.listeners=com.opensymphony.oscache.plugins.clustersupport.JavaGroupsBroadcastingListener
-# other JavaGroups paramaters go here...</pre>
+# other JavaGroups parameters go here...</pre>
 </div></div>
 
 <h3><a name="QueryResultCaching-QueryCacheConclusions"></a>Query Cache Conclusions</h3>
 
-<p>The consequence of consistently using caching strategies and coming up with reasonable set of ache groups is that many applications no longer has to cache fetched lists explicitly. Re-running a query with a one of the caching strategies (especially with "LOCAL_CACHE") becomes an extremely fast operation. Also the code becomes cleaner, as the state is stored in Cayenne, not in the application code. One possible exception from this rule is when the application needs to access the same list between requests, regardless of whether it is stale or not. </p>
+<p>The consequence of consistently using caching strategies and coming up with a reasonable set of cache groups is that applications no longer have to cache fetched lists explicitly. Re-running a query with a one of the caching strategies (especially with "LOCAL_CACHE") becomes an extremely fast operation. Also the code becomes cleaner, as the state is stored in Cayenne, not in the application code. One possible exception from this rule is when an application needs to access the same list between requests, regardless of whether it is stale or not. </p>
 
 </div>
 </div>

Modified: 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?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Customization/Extended Types/index.html Sun Feb 20 17:21:02 2011
@@ -55,11 +55,11 @@
 </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>
+<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 conversely, 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>
+<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. Configuring an ExtendedType is has in the code, some time during Cayenne startup. The following code sample demonstrates this procedure:</p>
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <pre class="code-java"><span class="code-comment">// create custom ExtendedType instance
 </span>ExtendedType customType = <span class="code-keyword">new</span> MyCustomType();
@@ -70,15 +70,14 @@
 </span>DataNode node = domain.getNode(<span class="code-quote">"node_name"</span>);
 
 <span class="code-comment">// install ExtendedType
-</span>node.getAdapter().getExtendedTypes().registerType(customType);
-</pre>
+</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>
+<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, incompleteness 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>
 
-<h3><a name="ExtendedTypes-Threetierconsiderations"></a>Three tier considerations</h3>
+<h3><a name="ExtendedTypes-ROPConsiderations"></a>ROP Considerations</h3>
 
 <p>If you are using Cayenne in a three tier (ROP) environment, serialization of the extended type becomes important. More information can be found <a href="../../../../Documentation/Remote Object Persistence Guide/Remote Object Persistence Customization/index.html" title="Remote Object Persistence Customization">here.</a></p></div>
 </div>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/Obtaining%20DataContext/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html Sun Feb 20 17:21:02 2011
@@ -59,82 +59,43 @@
 <li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
 </ul>
 </div>
-<div id="ConfluenceContent"><div class='panelMacro'><table class='warningMacro'><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>TODO... The API below looks different in 3.1</td></tr></table></div>
+<div id="ConfluenceContent"><p>Depending on deployment environment and application needs, Cayenne can be configured in a few different ways to make DataContext instances available. This is discussed in detail in deployment chapter. But basically it comes down to getting a hold of an instance of <tt>ServerRuntime</tt> and calling <tt>getContext()</tt> on it as described below.</p>
 
-<p>Depending on deployment environment and application needs, Cayenne can be configured in a few different ways to make DataContext instances available. This is discussed in detail in deployment chapter. In this chapter we assume a properly deployed application and will concentrate on how to obtain a DataContext for the database access. The following are the most common ways to achieve that:</p>
-
-<h3><a name="ObtainingDataContext-CreatingDataContextontheSpot"></a>Creating DataContext on the Spot</h3>
-
-<p>A new DataContext instance normally can be created using the following code:</p>
+<h3><a name="ObtainingDataContext-ObtainingaDataContextfromtheDIRuntime"></a>Obtaining a DataContext from the DI Runtime</h3>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
-...
-DataContext context = DataContext.createDataContext();</pre>
+<pre class="code-java">ServerRuntime runtime = ...
+ObjectContext context = runtime.getContext()</pre>
 </div></div>
 
-<p>This approach may be used in standalone applications, where the notion of a "session" is user-defined. In web applications the correct instance of DataContext is usually bound to a session or a request thread externally, and all that is needed is to retrieve it, as discussed below. Creating a new DataContext for each request is not a recommended practice.</p>
-
-<h3><a name="ObtainingDataContext-RetrievingSessionBoundDataContextinWebApplications"></a>Retrieving Session-Bound DataContext in Web Applications</h3>
-
-<p>A web application can be configured to automatically create a new instance of DataContext for each new HttpSession, and set it as a session attribute. Retrieving it from a session is done with the following code:</p>
+<p>Note that every call to <tt>getContext()</tt> returns a new instance. Also note that it returns <tt>ObjectContext</tt> (an interface implemented by <tt>DataContext</tt>). If you need to use DataContext API not declared in ObjectContext, you may use a cast:</p>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.conf.ServletUtil;
-<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
-...
-
-<span class="code-comment">// assume <span class="code-keyword">this</span> exists
-</span>HttpSession session;
-DataContext context = ServletUtil.getSessionContext(session);</pre>
+<pre class="code-java">ServerRuntime runtime = ...
+DataContext context = (DataContext) runtime.getContext()</pre>
 </div></div>
 
+<p>But if you don't, we recommend to stick with ObjectContext in your code, as it makes the code more flexible and portable to the future versions of Cayenne.</p>
 
-<h3><a name="ObtainingDataContext-RetrievingThreadBoundDataContext."></a>Retrieving Thread-Bound DataContext.</h3>
+<h3><a name="ObtainingDataContext-RetrievingThreadBoundDataContext"></a>Retrieving Thread-Bound DataContext</h3>
 
-<p>An application can bind a DataContext to a current execution thread. Later on the code that needs DB access can retrieve this DataContext without making any assumptions about the environment. This approach is universal and works in all types of applications (web, standalone, etc.). Previously bound DataContext can be retrieved by calling <tt>DataContext.getThreadDataContext()</tt> static method. If no DataContext was bound to the current thread, this method throws IllegalStateException:</p>
+<p>An application can bind a context to a current execution thread (e.g. via <tt>CayenneFilter</tt> or manually). Later on the code that needs DB access can retrieve this DataContext without making any assumptions about the environment. This approach is universal and works in all types of applications (web, standalone, etc.). Previously bound context can be retrieved by calling <tt>BaseContext.getThreadObjectContext()</tt> static method. If no context was bound to the current thread, this method throws IllegalStateException (same rules for casting ObjectContext to DataContext as above apply) :</p>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
-...
-<span class="code-comment">// we are positive there is DataContext in the current thread, and <span class="code-keyword">do</span> not want
+<pre class="code-java"><span class="code-comment">// we are positive there is DataContext in the current thread, and <span class="code-keyword">do</span> not want
 </span><span class="code-comment">// to handle possible exception...
-</span>DataContext context = DataContext.getThreadDataContext();
-</pre>
+</span>DataContext context = (DataContext) BaseContext.getThreadObjectContext();</pre>
 </div></div>
 
-
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
-...
-<span class="code-comment">// we want to handle the condition of no thread context...
+<pre class="code-java"><span class="code-comment">// we want to handle the condition of no thread-bound context...
 </span><span class="code-keyword">try</span> {
-    DataContext context = DataContext.getThreadDataContext();
+    DataContext context = (DataContext) BaseContext.getThreadObjectContext();
 }
 <span class="code-keyword">catch</span>(IllegalStateException ex) {
     <span class="code-comment">// handle failure
 </span>    ....
 }</pre>
-</div></div>
-
-
-<h3><a name="ObtainingDataContext-MultipleDataDomains%28Advanced%29"></a>Multiple DataDomains (Advanced)</h3>
-
-<p>Cayenne can be configured to support mass database hosting. This is a so-called Application Service Provider (ASP) scenario. Basic architecture of such setup is a single application supporting multiple databases (or more generally - data sources), each one with same or similar schema. Each data source corresponds to an individual ASP "customer" using the system. Each customer has a number of users that will log in to the system and are only allowed to view data from their data source.</p>
-
-<p>This approach, though not required for most normal applications, could be quiet common and powerful in some enterprise systems. To implement it, each DataContext must be limited to access only a relevant subset of datasources.</p>
-
-<p>Considering that behind the scenes a source of DataContext instances is an object called DataDomain, Cayenne allows creation of multiple DataDomains per project. Each DataDomain would support a single "customer". Creation of DataContext in this case is done using DataDomain name as a parameter:</p>
-
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
-...
-
-<span class="code-comment">// domain name string is initialized depending on
-</span><span class="code-comment">// the application logic. For instance it can be based
-</span><span class="code-comment">// on the logged in user's company, etc.
-</span><span class="code-object">String</span> domainName = ...;
-DataContext context = DataContext.createDataContext(domainName);</pre>
 </div></div></div>
 </div>
   <div class="clearer">.</div>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/Caching%20Query%20Results/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html Sun Feb 20 17:21:02 2011
@@ -61,11 +61,7 @@
 <li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</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>
-
-<div class='panelMacro'><table class='noteMacro'><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>Upgrading to Cayenne 1.2 and Newer</b><br /><tt>org.apache.cayenne.query.GenericSelectQuery</tt> interface that defined cache policy types is deprecated. Cache policies are now a part of the new <tt>org.apache.cayenne.query.QueryMetadata</tt> interface.</td></tr></table></div>
-
-<p>The following cache policies are supported:</p>
+<div id="ConfluenceContent"><p>Cayenne provides a way to cache query results, avoiding unneeded database trips for the frequently used queries. Caching strategy is configured per query. A strategy can be set via API or in CayenneModeler. Possible strategies, as defined in the <tt>org.apache.cayenne.query.QueryCacheStrategy</tt> enum are the following:</p>
 
 <div class='table-wrap'>
 <table class='confluenceTable'><tbody>
@@ -75,29 +71,29 @@
 <th class='confluenceTh'>Cache Behavior</th>
 </tr>
 <tr>
-<td class='confluenceTd'><em>(default policy)</em> <tt>QueryMetadata.NO_CACHE</tt> </td>
+<td class='confluenceTd'><em>(default)</em> <tt>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'><tt>LOCAL_CACHE</tt></td>
+<td class='confluenceTd'>ObjectContext</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>
+<td class='confluenceTd'><tt>LOCAL_CACHE_REFRESH</tt></td>
+<td class='confluenceTd'>ObjectContext</td>
+<td class='confluenceTd'>Never use cache, always 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'><tt>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'><tt>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>
+<td class='confluenceTd'>Never use cache, always do a fetch and store result in cache for future use</td>
 </tr>
 </tbody></table>
 </div>
@@ -105,86 +101,57 @@
 
 <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>When creating queries in the code, users may set a desired cache strategy per query. Below we will create a query and set its caching policy to LOCAL_CACHE:</p>
 
-<p>Below we will create a query and set its caching policy to LOCAL_CACHE:</p>
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <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 class="code-comment">// set local cache strategy, meaning the cache will be stored in the ObjectContext 
 </span><span class="code-comment">// and not shared between different contexts
-</span>query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE);
+</span>query.setCacheStrategy(QueryCacheStrategy.LOCAL_CACHE);
 
-DataContext context = ... <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+ObjectContext 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 class="code-comment">// <span class="code-keyword">if</span> there was no cache at <span class="code-keyword">this</span> point, the query will hit the database, 
+</span><span class="code-comment">// and will store the result in the cache
 </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>
+<p>Now if we rerun the same query (or create a new instance of the query with the same set of parameters), we'll get cached result, which will be much faster than fetching it from DB. </p>
 
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">List objects1 = context.performQuery(query);
-</pre>
-</div></div>
+<blockquote><p>The point about 2 separate queries reusing the same cache entry is worth repeating. A cache key for each query is automatically generated by Cayenne based on the type of the query and its parameters (such as qualifier, ordering, etc.). So a query itself does not need to be cached by the user code for future reuse. New queries can be created as needed.</p></blockquote>
 
-<p>Here we want to refresh the cache, but still keep caching the fresh result:</p>
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE_REFRESH);
+<pre class="code-java"><span class="code-comment">// creating a <span class="code-keyword">new</span> query, same as the previous one
+</span>SelectQuery query1 = <span class="code-keyword">new</span> SelectQuery(Artist.class);
 
-List objects2 = context.performQuery(query);
+<span class="code-comment">// <span class="code-keyword">this</span> will hit the local cache
+</span>List objects1 = context.performQuery(query1);
 </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>
-
-
-<div class='panelMacro'><table class='noteMacro'><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>Upgrading to Cayenne 1.2 and Newer</b><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></div>
-
-
-<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><span class="image-wrap" style=""><img src="caching.jpg?version=2&amp;modificationDate=1139788141000" style="border: 0px solid black" /></span></p>
-
-<p>Then it can be executed via DataContext:</p>
+<p>Or if we want to refresh the cache, but still keep caching the result after that:</p>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">List objects1 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">false</span>);
+<pre class="code-java">query1.setCachePolicy(QueryCacheStrategy.LOCAL_CACHE_REFRESH);
+List objects2 = context.performQuery(query1);
 </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>
+<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 ObjectContexts that work on top of a given DataDomain. </p>
 
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">List objects2 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">true</span>);
-</pre>
-</div></div>
+<p>There's another optional query property called "<tt>cacheGroups</tt>" that allows to fine-tune cache expiration in a declarative fashion. When creating a query, a user would specify the names of the cache groups (which are really cache <em>expiration</em> groups) associated with this query, and then separately define expiration policies for the cache groups present in the application. See <a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html" title="Query Result Caching">Query Result Caching</a> for more details.</p>
 
-<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>
+<h3><a name="CachingQueryResults-QueriesMappedinCayenneModeler"></a>Queries Mapped in CayenneModeler</h3>
 
-<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<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>Named queries created in CayenneModeler can also be configured to use caching, with the same cache strategy and cache groups parameters:</p>
 
-<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<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>
+<p><span class="image-wrap" style=""><img src="caching.jpg?version=2&amp;modificationDate=1139788141000" style="border: 0px solid black" /></span></p>
 
-</div>
+<p>NamedQueries that are using caching can be executed just like any other <a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html" title="NamedQuery">NamedQuery</a>.</p></div>
 </div>
   <div class="clearer">.</div>
   <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Stored Procedures/Executing a Stored Procedure/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Stored%20Procedures/Executing%20a%20Stored%20Procedure/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Stored Procedures/Executing a Stored Procedure/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Stored Procedures/Executing a Stored Procedure/index.html Sun Feb 20 17:21:02 2011
@@ -54,36 +54,34 @@
 <li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
 </ul>
 </div>
-<div id="ConfluenceContent">
-<h3><a name="ExecutingaStoredProcedure-UsingQueryResponsetoProcessComplexResults"></a>Using QueryResponse to Process Complex Results</h3>
+<div id="ConfluenceContent"><h3><a name="ExecutingaStoredProcedure-UsingQueryResponsetoProcessComplexResults"></a>Using QueryResponse to Process Complex Results</h3>
 
 <p>Previous chapter showed how to select a single set of data rows using a ProcedureQuery. In a more general case stored procedures can return multiple sets of data, either as ResultSets or via OUT parameters, execute update/delete/insert queries, etc. To collect the results of execution of such stored procedure, you need to run a query using context's <tt>"performGenericQuery"</tt> method and inspect returned QueryResponse.</p>
 
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">DataContext ctxt;
+<pre class="code-java">DataContext context;
 
 <span class="code-comment">// <span class="code-quote">"my_procedure"</span> is a name of a stored procedure,
 </span><span class="code-comment">// that must exist in the DataMap
 </span>ProcedureQuery query = <span class="code-keyword">new</span> ProcedureQuery(<span class="code-quote">"my_procedure"</span>);
 
 <span class="code-comment">// Set <span class="code-quote">"IN"</span> parameter values
-</span>query.addParam(<span class="code-quote">"parameter1"</span>, <span class="code-quote">"abc"</span>);
-query.addParam(<span class="code-quote">"parameter2"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(3000));
+</span>query.addParameter(<span class="code-quote">"parameter1"</span>, <span class="code-quote">"abc"</span>);
+query.addParameter(<span class="code-quote">"parameter2"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(3000));
 
 <span class="code-comment">// run query
-</span>QueryResponse result = ctxt.performGenericQuery(query);
+</span>QueryResponse result = context.performGenericQuery(query);
 
 <span class="code-comment">// check the results
-</span>Iterator it = rowSets.iterator();
-<span class="code-keyword">while</span>(result.next()) {
-     <span class="code-keyword">if</span> (result.isList()) {
-          List list = result.currentList();
-          <span class="code-comment">// ...
+</span><span class="code-keyword">for</span> (result.reset(); result.next();) {
+     <span class="code-keyword">if</span> (response.isList()) {
+         List list = result.currentList();
+         <span class="code-comment">// ...
 </span>     }
-     <span class="code-keyword">else</span> {
-          <span class="code-object">int</span>[] updateCounts = result.currentUpdateCount();
-          <span class="code-comment">// ...
+    <span class="code-keyword">else</span> {
+         <span class="code-object">int</span>[] updateCounts = result.currentUpdateCount();
+         <span class="code-comment">// ...
 </span>     }
 }
 </pre>
@@ -94,18 +92,18 @@ query.addParam(<span class="code-quote">
 <p>Stored Procedure can return data back to the application as ResultSets or via OUT parameters. To simplify the processing of the query output, QueryResponse treats OUT parameters as if it was a separate ResultSet. If a stored procedure declares any OUT or INOUT parameters, QueryResponse will contain their returned values in the very first result list:</p>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
-<pre class="code-java">DataContext ctxt;
+<pre class="code-java">DataContext context;
 
 <span class="code-comment">// <span class="code-quote">"my_procedure"</span> is a name of a stored procedure,
 </span><span class="code-comment">// that must exist in the DataMap
 </span>ProcedureQuery query = <span class="code-keyword">new</span> ProcedureQuery(<span class="code-quote">"my_procedure"</span>);
 
 <span class="code-comment">// Set <span class="code-quote">"IN"</span> parameter values
-</span>query.addParam(<span class="code-quote">"paramter1"</span>, <span class="code-quote">"abc"</span>);
-query.addParam(<span class="code-quote">"parameter2"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(3000));
+</span>query.addParameter(<span class="code-quote">"paramter1"</span>, <span class="code-quote">"abc"</span>);
+query.addParameter(<span class="code-quote">"parameter2"</span>, <span class="code-keyword">new</span> <span class="code-object">Integer</span>(3000));
 
 <span class="code-comment">// run query
-</span>QueryResponse result = ctxt.performGenericQuery(query);
+</span>QueryResponse result = context.performGenericQuery(query);
 
 <span class="code-comment">// read OUT parameters
 </span>List outList = result.firstList();

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Delete/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Delete/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Delete/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Delete/index.html Sun Feb 20 17:21:02 2011
@@ -68,7 +68,7 @@
 
 <p>In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for the "paintings" relationship delete rule:</p>
 
-<p><span class="image-wrap" style=""><img src="modeler-deleterule.png?version=1&amp;modificationDate=1289712910487" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="modeler-deleterule.png?version=1&amp;modificationDate=1289712910000" style="border: 0px solid black" /></span></p>
 
 <p>Repeat this step for other relationships:</p>
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Java Classes/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Java%20Classes/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Java Classes/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Java Classes/index.html Sun Feb 20 17:21:02 2011
@@ -98,7 +98,7 @@
 
 <p>Now let's check the entity class pairs. Each one is made of a superclass (e.g. <em>Artist) and a subclass (e.g. Artist). You <b>should not</b> modify the superclasses whose names start with "</em>" (underscore), as they will be replaced on subsequent generator runs. Instead all custom logic should be placed in the subclasses in <tt>"org.example.cayenne.persistent"</tt> package - those will never be overwritten by the class generator.</p>
 
-<p><span class="image-wrap" style=""><img src="eclipse-generatedclasses.png?version=1&amp;modificationDate=1289712337909" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="eclipse-generatedclasses.png?version=1&amp;modificationDate=1289712337000" style="border: 0px solid black" /></span></p>
 
 
 <div class='panelMacro'><table class='noteMacro'><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 Generation Hint</b><br />Often you'd start by generating classes from the Modeler, but at the later stages of the project the generation is usually automated either via <a href="../../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">Ant cgen task</a> or <a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html" title="maven2-cgen">Maven cgen mojo</a>. All three methods are interchangeable, however Ant and Maven methods would ensure that you never forget to regenerate classes on mapping changes, as they are integrated into the build cycle.</td></tr></table></div>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Object Relational Mapping/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Object%20Relational%20Mapping/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Object Relational Mapping/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Object Relational Mapping/index.html Sun Feb 20 17:21:02 2011
@@ -62,7 +62,7 @@
 </div>
 <div id="ConfluenceContent"><p>The goal of this section is to learn how to create a simple Object-Relational model with CayenneModeler. We will create a complete ORM model for the following database schema:</p>
 
-<p><span class="image-wrap" style=""><img src="database-schema.jpg?version=1&amp;modificationDate=1289713490301" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="database-schema.jpg?version=1&amp;modificationDate=1289713490000" style="border: 0px solid black" /></span></p>
 
 <div class='panelMacro'><table class='noteMacro'><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>Very often you'd have an existing database already, and it can be quickly imported in Cayenne via <tt>"Tools &gt; Reengineer Database Schema"</tt>. This will save you lots of time compared to manual mapping. However understanding how to create the mapping by hand is important, so we are showing the "manual" approach below.</td></tr></table></div>
 
@@ -72,7 +72,7 @@
 
 <p>Select "UntitledDomainMap" on the left-hand side project tree and click "Create DbEntity" button (or use <tt>"Project &gt; Create DbEntity"</tt> menu). A new DbEntity is created. In "DbEntity Name" field enter "ARTIST". Then click on "Create Attribute" button on the entity toolbar (third button from the left). This action changes the view to the "Attribute" tab and adds a new attribute (attribute means a "table column" in this case) called "untitledAttr". Let's rename it to ID, make it an INTEGER and make it a PK:</p>
 
-<p><span class="image-wrap" style=""><img src="modeler-artistid.png?version=1&amp;modificationDate=1289713490497" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="modeler-artistid.png?version=1&amp;modificationDate=1289713490000" style="border: 0px solid black" /></span></p>
 
 <p>Similarly add NAME VARCHAR(200) and DATE_OF_BIRTH DATE attributes.  After that repeat this procedure for PAINTING and GALLERY entities to match DB schema shown above.</p>
 
@@ -93,7 +93,7 @@
 </ul>
 
 
-<p><span class="image-wrap" style=""><img src="modeler-dbrelationship.png?version=1&amp;modificationDate=1289713492360" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="modeler-dbrelationship.png?version=1&amp;modificationDate=1289713492000" style="border: 0px solid black" /></span></p>
 
 <ul>
 	<li>Click "Done" to confirm the changes and close the dialog.</li>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Setup/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Setup/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Setup/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Setup/index.html Sun Feb 20 17:21:02 2011
@@ -72,7 +72,7 @@
 
 <p>After downloading Eclipse, unpack it somewhere in the filesystem, and start it. The only plugin that you need for the tutorial is <a href="http://m2eclipse.sonatype.org/" class="external-link" rel="nofollow">m2eclipse</a>. To install it, in Eclipse go to "Help &gt; Install New Software", then click on "Add.." to add a new download site, and enter "Maven" in the "Name" field, and "http://m2eclipse.sonatype.org/sites/m2e" in the "Location" field. You may install any of the optional components that you think you need, but for this tutorial we only select a few basic components as shown on the following screenshot:</p>
 
-<p><span class="image-wrap" style=""><img src="maven-plugin-install.png?version=1&amp;modificationDate=1289713231089" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="maven-plugin-install.png?version=1&amp;modificationDate=1289713231000" style="border: 0px solid black" /></span></p>
 
 <p>From here follow the Eclipse dialog instructions to finish the installation.</p>
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Starting Project/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Starting%20Project/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Starting Project/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Starting Project/index.html Sun Feb 20 17:21:02 2011
@@ -62,10 +62,10 @@
 </div>
 <div id="ConfluenceContent"><p>The goal of this section is to create a new Java project in Eclipse containing a basic Cayenne mapping. It presents an introduction to CayenneModeler GUI tool, showing how to create the initial mapping objects: DataDomain, DataNode, DataMap.</p>
 
-<h3><a name="TutorialStartingProject-CreateanewProjectinEclipse"></a>Create a new Project in Eclipse</h3>
+<h3><a name="TutorialStartingProject-CreateanewProjectinEclipse"></a>Create a new Project in Eclipse </h3>
 
 <p>In Eclipse select <tt>"File &gt; New &gt; Other..."</tt> and then <tt>"Maven &gt; Maven Project"</tt>. Click "Next". On the following screen check "Create a simple project" checkbox and click "Next" again. In the dialog shown on the screenshot below, fill the "Group Id" and "Artifact Id" fields and click "Finish". <br/>
-<span class="image-wrap" style=""><img src="tutorial-eclipse-project.png?version=1&amp;modificationDate=1289713366735" style="border: 0px solid black" /></span></p>
+<span class="image-wrap" style=""><img src="tutorial-eclipse-project.png?version=1&amp;modificationDate=1289713366000" style="border: 0px solid black" /></span></p>
 
 <p>Now you should have a new empty project in the Eclipse workspace. Check that the project Java compiler settings are correct. Rightclick on the "tutorial" project, select <tt>"Properties &gt; Java Compiler"</tt> and ensure that "Compiler compliance level" is at least "1.5" (some versions of Maven plugin seem to be setting it to 1.4 by default).</p>
 
@@ -77,7 +77,7 @@
 
 <p>Download the latest release <a href="http://cayenne.apache.org/download.html" class="external-link" rel="nofollow">from here</a>. Unpack the distribution somewhere in the file system and start CayenneModeler, following <a href="../../../../Documentation/Modeler Guide/Introduction to CayenneModeler/Running CayenneModeler/index.html" title="Running CayenneModeler">platform-specific instructions</a>. On most platforms it is done simply by doubleclicking the Modeler icon. The welcome screen of the Modeler looks like this:</p>
 
-<p><span class="image-wrap" style=""><img src="modeler-started.png?version=1&amp;modificationDate=1289713364249" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="modeler-started.png?version=1&amp;modificationDate=1289713364000" style="border: 0px solid black" /></span></p>
 
 <h3><a name="TutorialStartingProject-CreateaNewMappingProjectinCayenneModeler"></a>Create a New Mapping Project in CayenneModeler</h3>
 
@@ -99,7 +99,7 @@
 
 <p>Also you will need to change "Schema Update Strategy". Select <tt>"org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy"</tt> from the dropdown, so that Cayenne creates a new schema on Derby based on the ORM mapping when the application starts.</p>
 
-<p><span class="image-wrap" style=""><img src="base-datanode.png?version=1&amp;modificationDate=1289713359050" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="base-datanode.png?version=1&amp;modificationDate=1289713359000" style="border: 0px solid black" /></span></p>
 
 
 <h3><a name="TutorialStartingProject-CreateaDataMap"></a>Create a DataMap</h3>
@@ -108,13 +108,13 @@
 
 <p>You can leave all the DataMap defaults unchanged except for one - "Java Package". Enter "org.example.cayenne.persistent". This name will later be used for all persistent classes.</p>
 
-<p><span class="image-wrap" style=""><img src="base-datamap.png?version=1&amp;modificationDate=1289713358895" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="base-datamap.png?version=1&amp;modificationDate=1289713358000" style="border: 0px solid black" /></span></p>
 
 <h3><a name="TutorialStartingProject-SavetheProject"></a>Save the Project</h3>
 
 <p>Before you proceed with the actual mapping, let's save the project. Click on "Save" button in the toolbar and navigate to the <tt>"tutorial"</tt> Eclipse project folder that was created earlier in this section and its <tt>"src/main/resources"</tt> subfolder and save the project there. Now go back to Eclipse, right click on "tutorial" project and select "Refresh", you will see three Cayenne XML files.</p>
 
-<p><span class="image-wrap" style=""><img src="eclipse-xmlfiles.png?version=1&amp;modificationDate=1289713363197" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="eclipse-xmlfiles.png?version=1&amp;modificationDate=1289713363000" style="border: 0px solid black" /></span></p>
 
 <p>Note that the location of the XML files is not coincidental. Cayenne runtime looks for <tt>"cayenne.xml"</tt> file in the application CLASSPATH and <tt>"src/main/resources"</tt> folder should already be a "class folder" in Eclipse for our project (and is also a standard location that Maven would copy to a jar file, if we were using Maven from command-line).</p>
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Webapp/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Tutorial/Tutorial%20Webapp/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Webapp/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Tutorial/Tutorial Webapp/index.html Sun Feb 20 17:21:02 2011
@@ -248,7 +248,7 @@
 </ul>
 
 
-<p><span class="image-wrap" style=""><img src="eclipse-mvnrun.png?version=1&amp;modificationDate=1289712767171" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="eclipse-mvnrun.png?version=1&amp;modificationDate=1289712767000" style="border: 0px solid black" /></span></p>
 
 <ul>
 	<li>Click "Apply" and "Run". On the first execution it may take a few minutes for Jetty plugin to download all dependencies, but eventually you'll see the logs like this:</li>
@@ -331,7 +331,7 @@ INFO: +++ transaction committed.</pre>
 </ul>
 
 
-<p><span class="image-wrap" style=""><img src="firefox-webapp.png?version=1&amp;modificationDate=1289712761139" style="border: 0px solid black" /></span></p>
+<p><span class="image-wrap" style=""><img src="firefox-webapp.png?version=1&amp;modificationDate=1289712761000" style="border: 0px solid black" /></span></p>
 
 <p>You are done with the tutorial!</p></div>
 </div>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Overview/Guide to 3.1 Features/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Overview/Guide%20to%203.1%20Features/index.html?rev=1072639&r1=1072638&r2=1072639&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Overview/Guide to 3.1 Features/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Overview/Guide to 3.1 Features/index.html Sun Feb 20 17:21:02 2011
@@ -47,6 +47,7 @@
 	<li><a href="#Guideto3.1Features-CayenneConfiguration">Cayenne Configuration</a></li>
 	<li><a href="#Guideto3.1Features-FrameworkAPI">Framework API</a></li>
 	<li><a href="#Guideto3.1Features-CayenneModeler">CayenneModeler</a></li>
+	<li><a href="#Guideto3.1Features-LifecycleExtensions">Lifecycle Extensions</a></li>
 </ul>
 
 
@@ -67,7 +68,7 @@
 
 <h3><a name="Guideto3.1Features-DependencyInjectionContainer"></a>Dependency Injection Container</h3>
 
-<p>Cayenne 3.1 runtime stack is built around the ideas of Dependency Injection (DI), making it extremely flexible and easy to extend. It bundles a small, flexible annotations-based <a href="../../../Documentation/Overview/Guide to 3.1 Features/Dependency Injection Container/index.html" title="Dependency Injection Container">DI</a> to configure its services. The idea behind Cayenne DI is to provide DI services and extension points to Cayenne, but do not interfere with other DI containers that may be present in the application. I.e. it is invisible to the users who do not care about advanced Cayenne customization.</p>
+<p>Cayenne 3.1 runtime stack is built around the ideas of Dependency Injection (DI), making it extremely flexible and easy to extend. It bundles a small, flexible annotations-based <a href="../../../Documentation/Overview/Guide to 3.1 Features/Dependency Injection Container/index.html" title="Dependency Injection Container">DI container</a> to configure its services. The container provides DI services and exposes Cayenne extension points, but does not interfere with other DI containers that may be present in the application. I.e. it is invisible to the users who do not care about advanced Cayenne customization.</p>
 
 <h3><a name="Guideto3.1Features-BootstrappingCayenneinVariousEnvironments"></a>Bootstrapping Cayenne in Various Environments</h3>
 
@@ -92,14 +93,72 @@
 
 <h2><a name="Guideto3.1Features-FrameworkAPI"></a>Framework API</h2>
 
-<p><em>TODO... See UPGRADE.txt for the list of changes</em></p>
+<p><em>See UPGRADE.txt for the full list of changes</em></p>
+
+<h3><a name="Guideto3.1Features-LifecycleListenerAnnotations"></a>Lifecycle Listener Annotations</h3>
+
+<p>Cayenne 3.1 features support for annotations on lifecycle listeners (but not yet on entity callback methods) that simplifies registering listeners via API. Our experience with Cayenne 3.0 shows that mapping listeners in the Modeler doesn't scale well to complex applications, and 3.0 API for mapping the listeners is hard to use. In 3.1 you can annotate listener methods and register multiple callback methods with a single call. </p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-comment">// declare a listener with annotated methods
+</span>class MyListener {
+    @PostLoad(Entity1.class)
+    @PostPersist(Entity1.class)
+    void postLoad(<span class="code-object">Object</span> object) {
+        ....
+    }
+}
+
+<span class="code-comment">// register a listener
+</span>ServerRuntime runtime = ..
+MyListener listener = <span class="code-keyword">new</span> MyListener();
+runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listener);</pre>
+</div></div>
+
+<p>Moreover, unlike JPA annotations, Cayenne allows to attach a listener to a set of entities not known to the listener upfront, but that are all annotated with some custom annotation:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">class MyListener {
+    @PostLoad(entityAnnotations = CustomAnnotation.class)
+    void postLoad(<span class="code-object">Object</span> object) {
+        ....
+    }
+}</pre>
+</div></div>
+
+
+<h3><a name="Guideto3.1Features-DataChannelFilterforInterceptingDataDomainOperations"></a>DataChannelFilter for Intercepting DataDomain Operations</h3>
+
+<p>Cayenne now features a <tt>DataChannelFilter</tt> interface that allows to intercept and alter all DataChannel traffic (i.e. selects and commits between a DataContext and DataDomain). It provides a chain of command API very similar to servlet filters. Filters are widely used by "<tt>cayenne-lifecyle</tt>" extensions and allow to build powerful custom object lifecycle-aware code. To install a filter, the following API is used:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">class MyFilter implement DataChannelFilter { .. }
+
+MyFilter filter = <span class="code-keyword">new</span> MyFilter();
+ServerRuntime runtime = ..
+runtime.getDataDomain().addFilter(filter);</pre>
+</div></div>
+
+<p>Very often filters mark some of their own methods with lifecycle annotations so that certain operations can be triggered by Cayenne inside the scope of filter's <tt>onQuery()</tt> or <tt>onSync()</tt> methods. To ensure annotated methods are invoked, filter registration should be combined with listener registration:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">MyFilter filter = <span class="code-keyword">new</span> MyFilter();
+ServerRuntime runtime = ..
+runtime.getDataDomain().addFilter(filter);
+runtime.getDataDomain().getEntityResolver().getCallbackRegistry().addListener(filter);
+<span class="code-comment">// noticed that by <span class="code-keyword">default</span> runtime.getDataDomain() is equivalent to runtime.getChannel()</span></pre>
+</div></div>
+
 
 <h2><a name="Guideto3.1Features-CayenneModeler"></a>CayenneModeler</h2>
 
 <h3><a name="Guideto3.1Features-JavaPreferencesAPI"></a>Java Preferences API</h3>
 
 <p>We got rid of HSQLDB-based preferences storage, and are using standard Java Preferences API for the Modeler preferences. This solved a long-standing stability issue with Modeler preferences. So no more lost user preferences.</p>
-</div>
+
+<h2><a name="Guideto3.1Features-LifecycleExtensions"></a>Lifecycle Extensions</h2>
+
+<p>Cayenne 3.1 includes an optional <tt>cayenne-lifecyle</tt> module that implements a few useful extensions based on DataChannelFilters and lifecycle annotations. Those include a concept of UUID (which is a String URL-friendly representation of ObjectId), support for (de)referencing objects by UUID, UUID-based relationships, annotation-based cache groups invalidation, annotation-based audit of object changes, etc.</p></div>
 </div>
   <div class="clearer">.</div>
   <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>



Mime
View raw message