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 [10/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/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?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,189 @@
+<!--
+ 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 Query Results</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 Query Results</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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>Cayenne provides a way to cache query results, avoiding unneeded database trips for the frequently used queries. Caching policy is configured per query. Policy can be set via the API or in CayenneModeler.</p>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Upgrading to Cayenne 1.2 and Newer</b><br /><tt>org.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>
+
+<p>The following cache policies are supported:</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'>Policy</th>
+<th class='confluenceTh'>Cache Scope</th>
+<th class='confluenceTh'>Cache Behavior</th>
+</tr>
+<tr>
+<td class='confluenceTd'><em>(default policy)</em> <tt>QueryMetadata.NO_CACHE</tt> </td>
+<td class='confluenceTd'>N/A</td>
+<td class='confluenceTd'>Always fetch, never use cache, never save to cache</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.LOCAL_CACHE</tt></td>
+<td class='confluenceTd'>DataContext</td>
+<td class='confluenceTd'>If result is previously cached, use it, otherwise do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.LOCAL_CACHE_REFRESH</tt></td>
+<td class='confluenceTd'>DataContext</td>
+<td class='confluenceTd'>Never use cache, alwyas do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.SHARED_CACHE</tt></td>
+<td class='confluenceTd'>DataDomain (usually shared by all contexts in the same JVM)</td>
+<td class='confluenceTd'>If result is previously cached, use it, otherwise do a fetch and store result in cache for future use</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>QueryMetadata.SHARED_CACHE_REFRESH</tt></td>
+<td class='confluenceTd'>DataDomain (usually shared by all contexts in the same JVM)</td>
+<td class='confluenceTd'>Never use cache, alwyas do a fetch and store result in cache for future use</td>
+</tr>
+</tbody></table>
+
+<p>It is important to understand that caching of <b>result lists</b> is done independently from caching of <b>individual DataObjects and DataRows</b>. Therefore the API is different as well. Also cached results lists are not synchronized across VMs (even the shared cache).</p>
+
+
+<h3><a name="CachingQueryResults-APIforResultCaching"></a>API for Result Caching</h3>
+
+<p>Users must set two Query parameters to configure caching - query <b>name</b> that is used as a key to result cache and query <b>cache policy</b> (one of the policies above). Note that if two unrelated queries have the same name, they will hit the same cache entry. This is not a bug, this is a feature that should be taken into consideration when naming queries.</p>
+
+<p>Below we will create a query and set its caching policy to LOCAL_CACHE:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
+
+<span class="code-comment">// set query name that will be used as a unique key to perform result caching
+</span>query.setName(<span class="code-quote">"MySelect"</span>);
+
+<span class="code-comment">// set local cache policy, meaning the cache will be stored in the DataContext
+</span><span class="code-comment">// and not shared between different contexts
+</span>query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE);
+
+DataContext context = ... <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// there is probably no cache at <span class="code-keyword">this</span> point, so the query will hit the database
+</span>List objects = context.performQuery(query);</pre>
+</div></div>
+
+<p>Reruning the query in the same DataContext at a later time will be much faster as it will be hitting the cache:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects1 = context.performQuery(query);</pre>
+</div></div>
+
+<p>Here we want to refresh the cache, but still keep caching the fresh result:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">query.setCachePolicy(GenericSelectQuery.LOCAL_CACHE_REFRESH);
+
+List objects2 = context.performQuery(query);</pre>
+</div></div>
+
+<p>The example above shows caching with <tt>SelectQuery</tt>, but it works exactly the same way for <tt>SQLTemplate</tt> and <tt>ProcedureQuery</tt>. Similarly <tt>SHARED_CACHE</tt> and <tt>SHARED_CACHE_REFRESH</tt> cache policies create cache shared by all DataDontexts that work with a given DataDomain. </p>
+
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Upgrading to Cayenne 1.2 and Newer</b><br /><br/>
+Cache refreshing API has changed in 1.2. Cayenne 1.1 relied on the use of <tt>SelectQuery.setRefreshingObjects(..)</tt> to determine whether to expire cached result lists. This is no longer the case (setting this flag only refreshes <b>individual objects</b> as it should, and has no effect whatsoever on list caching). Instead caching and cache refreshing is controlled by the cache policy as described above.</td></tr></table>
+
+
+<h3><a name="CachingQueryResults-QueriesMappedinCayenneModeler"></a>Queries Mapped in CayenneModeler</h3>
+
+<p>The easiest way to set up caching is by creating a named query in CayenneModeler with the appropriate caching type.</p>
+
+<p><img src="caching.jpg" align="absmiddle" border="0" /></p>
+
+<p>Then it can be executed via DataContext:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects1 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">false</span>);</pre>
+</div></div>
+
+<p>The second "false" parameter above indicated that if possible, cached result should be used. Now if we want to force refresh, it can be changed to true (for just this invocation - this does not affect the underlying saved query)</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List objects2 = context.performQuery(<span class="code-quote">"MyQuery"</span>, <span class="code-keyword">true</span>);</pre>
+</div></div>
+
+<p>Note that parameterized named queries will still work correctly with the cache. We've already mentioned that the users must ensure that two queries must have different names if they fetch logically different data. This is NOT the case with queries stored in the DataMap. If you run the same named query with different sets of parameters, Cayenne will internally generate unique cache keys for each distinct parameter set.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">Map parameters = Collections.singletonMap(<span class="code-quote">"key"</span>, <span class="code-quote">"value1"</span>);
+List objects1 = context.performQuery(<span class="code-quote">"MyQuery"</span>, parameters, <span class="code-keyword">false</span>);</pre>
+</div></div>
+
+<p>Now if we run the same query with a different set of parameters, Cayenne will do the right thing and create a separate entry in the cache:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">Map parameters = Collections.singletonMap(<span class="code-quote">"key"</span>, <span class="code-quote">"value2"</span>);
+List objects2 = context.performQuery(<span class="code-quote">"MyQuery"</span>, parameters, <span class="code-keyword">false</span>);</pre>
+</div></div>
+
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Caching Query Results/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Customizing Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/Customizing%20Queries/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Customizing Queries/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Customizing Queries/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,161 @@
+<!--
+ 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 - Customizing Queries</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Customizing Queries</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a><ul>
+</ul>
+</li>
+</ul>
+</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>Any object that implements <tt>org.apache.cayenne.query.Query</tt> interface can be executed with a DataContext. </p>
+
+<h3><a name="CustomizingQueries-UnderstandingQueryInterface"></a>Understanding Query Interface</h3>
+
+<p>The interface defines the following methods (ommitting irrelevant deprecated ones):</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Query <span class="code-keyword">extends</span> Serializable {
+
+ <span class="code-object">String</span> getName();
+
+ QueryMetadata getMetaData(EntityResolver resolver);
+
+ void route(QueryRouter router, EntityResolver resolver, Query substitutedQuery);
+
+ SQLAction createSQLAction(SQLActionVisitor visitor);
+}</pre>
+</div></div>
+
+<ul>
+ <li><tt>getName</tt> returns a symbolic name of the query. The name may be used as a key to find queries stored in the DataMap. Some query implementors reuse the name as a QueryMetadata cache key. Generally the name can be null.</li>
+</ul>
+
+
+<ul>
+ <li><tt>getMetaData</tt> is called at various stages of the execution by Cayenne access stack to retrieve query parameters. <tt>EntityResolver</tt> instance is passed to this method, meaning that the query doesn't need to store direct references to Cayenne mapping objects and can resolve them at runtime.</li>
+</ul>
+
+
+<ul>
+ <li><tt>route</tt> is invoked when Cayenne decides which DataNode (database) to use when running a query. Routing decision is made by the Query istelf by calling <tt>QueryRouter.route(..)</tt>. This is an important extension point. For instance all Cayenne "indirect" queries implement this method to create (or somehow resolve) one or more substitute queries and route them instead of self.</li>
+</ul>
+
+
+<ul>
+ <li><tt>createSQLAction</tt> allows to fully customize Query execution at the JDBC level. In the simplest case an implementor calls one of the methods on <tt>SQLActionVisitor</tt> to return a standard action for a specific type of query. However it can provide its own <tt>SQLAction</tt> that accesses the database in some special way.</li>
+</ul>
+
+
+<h3><a name="CustomizingQueries-IndirectQueries"></a>Indirect Queries</h3>
+
+<p>One customization strategy is an "indirect" query that encapsulates some user-defined operation and in runtime resolves to one or more standard Cayenne queries. Indirect queries can be created from scratch or by extending <tt>org.apache.cayenne.query.IndirectQuery</tt>. As an example lets implement a "CountQuery" query that returns a number of rows in a given table:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class CountQuery <span class="code-keyword">extends</span> IndirectQuery {
+ <span class="code-keyword">protected</span> <span class="code-object">Class</span> objectClass;
+
+ <span class="code-keyword">public</span> CountQuery(<span class="code-object">Class</span> objectClass) {
+ <span class="code-keyword">this</span>.objectClass = objectClass;
+ }
+
+ <span class="code-keyword">protected</span> Query createReplacementQuery(EntityResolver resolver) {
+ DbEntity entity = resolver.lookupDbEntity(objectClass);
+
+ <span class="code-keyword">if</span> (entity == <span class="code-keyword">null</span>) {
+ <span class="code-keyword">throw</span> <span class="code-keyword">new</span> CayenneRuntimeException(
+ <span class="code-quote">"No entity is mapped <span class="code-keyword">for</span> java class: "</span>
+ + objectClass.getName());
+ }
+
+ <span class="code-object">String</span> sql = <span class="code-quote">"SELECT #result('count(*)' '<span class="code-object">int</span>' 'C') FROM "</span>
+ + entity.getName();
+ SQLTemplate replacement = <span class="code-keyword">new</span> SQLTemplate(entity, sql);
+ replacement.setFetchingDataRows(<span class="code-keyword">true</span>);
+ <span class="code-keyword">return</span> replacement;
+ }
+}</pre>
+</div></div>
+
+<p>Now you can run the query like that:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">CountQuery query = <span class="code-keyword">new</span> CountQuery(Artist.class);
+DataContext context = DataContext.createDataContext();
+
+Map row = (Map) context.performQuery(query).get(0);
+<span class="code-object">System</span>.out.println(<span class="code-quote">"Count: "</span> + row.get(<span class="code-quote">"C"</span>));</pre>
+</div></div>
+
+
+<p>For other real-life examples of indirect queries take a look at the source code of the following Cayenne queries: <a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html" title="QueryChain">QueryChain</a>, <a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html" title="ObjectIdQuery">ObjectIdQuery</a>, <a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html" title="RelationshipQuery">RelationshipQuery</a>, <a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html" title="NamedQuery">NamedQuery</a>. </p>
+
+
+<h3><a name="CustomizingQueries-SubclassingStandardQueries"></a>Subclassing Standard Queries</h3>
+
+<p>All standard queries can be subclassed, overriding some of their methods. For instance overriding <tt>route</tt> and/or <tt>createSQLAction</tt> would allow to implement custom callbacks at different points of query lifecycle.</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/Queries/Customizing Queries/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/EJBQLQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,135 @@
+<!--
+ 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 - EJBQLQuery</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">EJBQLQuery</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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><em>(available since 3.0 in both classic and JPA modes; as of June 2007 only a subset of EJBQL syntax is supported)</em></p>
+
+<p>EJBQL is an object query language that is not unlike SQL, only it operates in terms of the Java object model. In fact "EJB" in its name is entirely misleading - the language is applicable in the non-"enterprise" environments just as well. Standard EJBQL syntax is specified in the <a href="../../../../Documentation/JPA Guide/index.html" title="JPA Guide">JPA specification</a>, still Cayenne supports it in a classic mode, and no JPA runtime is required to execute such queries. This chapter deals specifically with classic mode operation. </p>
+
+<h3><a name="EJBQLQuery-EJBQLSyntax"></a>EJBQL Syntax</h3>
+
+<p>Details of the syntax are available in various JPA literature. Here is an example of an EJBQL query:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">select p from Painting p WHERE p.estimatedPrice > 3000</pre>
+</div></div>
+
+<p>Visually it looks like SQL, only instead of tables, object entities are used; and instead of columns and joins, path expressions are used (not unlike Cayenne <a href="../../../../Documentation/Cayenne Guide/Expressions/Path Expressions/index.html" title="Path Expressions">path expressions</a>).</p>
+
+<p><em>(TODO: would be nice to fill in more examples)</em></p>
+
+<h3><a name="EJBQLQuery-CreatinganEJBQLQuery"></a>Creating an EJBQLQuery</h3>
+
+<p>Creating an EJBQLQuery is simple - just pass a valid EJBQL string to the constructor:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">EJBQLQuery query = <span class="code-keyword">new</span> EJBQLQuery(<span class="code-quote">"select a FROM Artist a"</span>);</pre>
+</div></div>
+
+<p>Further you can use the query object the same way as any other Cayenne query to select objects or to modify the database.</p>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>As of June 2007, only selecting EJBQL syntax is supported; there are various other limitations</td></tr></table>
+
+<p>Select objects:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">List artists = context.performQuery(query);</pre>
+</div></div>
+
+
+<h3><a name="EJBQLQuery-EJBQLQueryvs.SelectQuery"></a>EJBQLQuery vs. SelectQuery</h3>
+
+<p><em>TODO: general comparison</em> </p>
+
+
+<p>Aside from noted different capabilities, EJBQLQuery and SelectQuery differ in some areas where they provide similar functionality. These differences are caused by the need for EJBQL syntax to follow the official specification, so it can't work "the Cayenne way":</p>
+
+<ul>
+ <li><b>Null Handling</b>: SelectQuery <a href="../../../../Documentation/Cayenne Guide/Expressions/NULL Handling/index.html" title="NULL Handling">would translate</a> the expressions matching NULL values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.</li>
+</ul>
+
+
+<ul>
+ <li><b>Expression Parameters</b>: SelectQuery <a href="../../../../Documentation/Cayenne Guide/Expressions/Building Expressions/index.html" title="Building Expressions">uses "$"</a> to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".</li>
+</ul>
+
+
+
+<h3><a name="EJBQLQuery-EJBQLQueryvs.SQLTemplate"></a>EJBQLQuery vs. SQLTemplate</h3>
+
+<p><em>TODO: general comparison</em> </p>
+
+<ul>
+ <li><b>Null Handling</b>:</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/Queries/EJBQLQuery/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/NamedQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/NamedQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/NamedQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/NamedQuery/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 - NamedQuery</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">NamedQuery</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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><tt>NamedQuery</tt> is a query that is a reference to another query stored in the DataMap. It can hold named parameters that will be passed to the named query on execution.</p>
+
+<p>Assuming that there a query called "Login" was previously mapped in the Modeler, we can do this:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-object">String</span>[] keys = <span class="code-keyword">new</span> <span class="code-object">String</span>[] {<span class="code-quote">"loginid"</span>, <span class="code-quote">"password"</span>};
+<span class="code-object">Object</span>[] values = <span class="code-keyword">new</span> <span class="code-object">String</span>[] {<span class="code-quote">"joe"</span>, <span class="code-quote">"secret"</span>};
+
+NamedQuery query = <span class="code-keyword">new</span> NamedQuery(<span class="code-quote">"Login"</span>, keys, values);
+
+List matchingUsers = context.performQuery(query);</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/Queries/NamedQuery/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/ObjectIdQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,127 @@
+<!--
+ 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 - ObjectIdQuery</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">ObjectIdQuery</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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><em>(DataObjectUtils API below is available since 1.2M10. SingleObjectQuery, a precursor of ObjectIdQuery, was available since 1.2M9. In 1.2M12 SingleObjectQuery was renamed to ObjectIdQuery)</em></p>
+
+<p><tt>ObjectIdQuery</tt> is a query that selects objects matching an ObjectId. Considering that ObjectId must be unique, the result of such query is a single object or no objects.</p>
+
+<p>Normally if you need to find an object that matches a certain primary key value, you would use <tt>DataObjectUtils.objectForPK(DataContext,String,int)</tt>. This method will look up an object in the cache, and only run a query if it is not yet cached. <tt>ObjectIdQuery</tt> gives the user more control of the object caching behavior. It supports three possible caching policies:</p>
+
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'>Policy</th>
+<th class='confluenceTh'>Cache Behavior</th>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>ObjectIdQuery.CACHE</tt> </td>
+<td class='confluenceTd'>This policy is similar to DataObjectUtils behavior. If an object is already cached (either at the DataContext or DataDomain level), it is returned, otherwise the fetch is performed.</td>
+</tr>
+<tr>
+<td class='confluenceTd'><em>(default policy)</em> <tt>ObjectIdQuery.CACHE_REFRESH</tt> </td>
+<td class='confluenceTd'>This policy forces a database fetch. If an object is already cached (either at the DataContext or DataDomain level), cache is refreshed with a new version and a fresh object is included in the result.</td>
+</tr>
+<tr>
+<td class='confluenceTd'><tt>ObjectIdQuery.CACHE_NO_REFRESH</tt> </td>
+<td class='confluenceTd'>This policy suppresses database fetch. If an object is already cached (either at the DataContext or DataDomain level), query returns this object. Otherwise it returns an empty result.</td>
+</tr>
+</tbody></table>
+
+<p>An example of getting a guranteed fresh object:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">ObjectId id = <span class="code-keyword">new</span> ObjectId(<span class="code-quote">"Artist"</span>, Artist.ARTIST_ID_PK_COLUMN, 55);
+
+<span class="code-comment">// <span class="code-keyword">this</span> constructor implicitly uses <span class="code-quote">"CACHE_REFRESH"</span> policy, so a fresh object will be returned
+</span>ObjectIdQuery query = <span class="code-keyword">new</span> ObjectIdQuery(id);
+
+DataContext context = ...
+Artist object = (Artist) DataObjectUtils.objectForQuery(context, query);</pre>
+</div></div>
+
+<p>An example of checking whether an object is already cached:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">ObjectId id = <span class="code-keyword">new</span> ObjectId(<span class="code-quote">"Artist"</span>, Artist.ARTIST_ID_PK_COLUMN, 55);
+ObjectIdQuery query = <span class="code-keyword">new</span> ObjectIdQuery(id, <span class="code-keyword">false</span>, ObjectIdQuery.CACHE_NO_REFRESH);
+
+DataContext context = ...
+Artist object = (Artist) DataObjectUtils.objectForQuery(context, query);
+<span class="code-keyword">if</span>(object == <span class="code-keyword">null</span>) {
+ <span class="code-comment">// not cached
+</span>}
+<span class="code-keyword">else</span> {
+ <span class="code-comment">// cached
+</span>}</pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/Queries%20Stored%20in%20DataMap/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,101 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<html>
+ <head>
+ <title>Apache Cayenne Documentation - Queries Stored in DataMap</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">Queries Stored in DataMap</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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 facilitate reuse of queries users can assign symbolic names to them and store such named queries in a DataMap. Normally this is done by <a href="../../../../Documentation/Modeler Guide/Modeling Queries/index.html" title="Modeling Queries">creating a query in CayenneModeler</a>. Storing queries in a DataMap reduces the amount of code and speeds up query creation process.</p>
+
+<p>This example shows how to get a shared instance of a stored query, and use it as a template for customized query.</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = ... <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// 1. lookup prototype
+</span>
+<span class="code-comment">// note a <span class="code-keyword">cast</span> to SelectQuery... Generally DataMap can store any type of queries
+</span>SelectQuery prototype = (SelectQuery) context.getEntityResolver().lookupQuery(<span class="code-quote">"MySelect"</span>);
+
+<span class="code-comment">// 2. customize query
+</span>Map params = <span class="code-keyword">new</span> HashMap();
+params.put(<span class="code-quote">"aname"</span>, <span class="code-quote">"Monet"</span>);
+SelectQuery query = prototype.queryWithParameters(params);
+
+<span class="code-comment">// 3. execute query
+</span>List objects = context.performQuery(query);</pre>
+</div></div>
+<p>DataContext supports running a named query with preset parameters directly:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = ... <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// <span class="code-quote">"<span class="code-keyword">false</span>"</span> indicates that a cached result should be used <span class="code-keyword">if</span> available
+</span>List objects = context.performQuery(<span class="code-quote">"MySelect"</span>, <span class="code-keyword">false</span>);</pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2007 Apache Software Foundation
+ </div>
+
+</body>
+</html>
Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/QueryChain/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/QueryChain/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/QueryChain/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/QueryChain/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,85 @@
+<!--
+ 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 - QueryChain</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">QueryChain</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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><tt>QueryChain</tt>, as the name implies, is a Query that is itself a collection of other queries. It simplifies an execution of multiple queries in a single batch. E.g.:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">QueryChain query = <span class="code-keyword">new</span> QueryChain();
+query.addQuery(<span class="code-keyword">new</span> SQLTemplate(Project.class, <span class="code-quote">"delete from project"</span>));
+query.addQuery(<span class="code-keyword">new</span> SQLTemplate(Project.class, <span class="code-quote">"delete from person"</span>));
+query.addQuery(<span class="code-keyword">new</span> SQLTemplate(Project.class, <span class="code-quote">"delete from department"</span>));
+
+DataContext context = ...
+context.performNonSelectingQuery(query);</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/Queries/QueryChain/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/RelationshipQuery/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,82 @@
+<!--
+ 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 - RelationshipQuery</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">RelationshipQuery</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><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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><tt>RelationshipQuery</tt> is used by Cayenne internally to fetch object(s) related to a single given object via a mapped ObjRelationship. In some cases the query can be used directly in the application, e.g. if we want to refresh related objects.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">ObjectId id = <span class="code-keyword">new</span> ObjectId(<span class="code-quote">"Artist"</span>, <span class="code-quote">"ARTIST_ID"</span>, 55);
+RelationshipQuery query = <span class="code-keyword">new</span> RelationshipQuery(id, <span class="code-quote">"paintingArray"</span>, <span class="code-keyword">true</span>);
+List paintings = context.performQuery(query);</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/Queries/RelationshipQuery/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SQLTemplate%20Query/Advanced%20SQLTemplate/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,102 @@
+<!--
+ 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 - Advanced SQLTemplate</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">Advanced SQLTemplate</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><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html">SQLTemplate Basics</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html">Scripting SQLTemplate</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html">Advanced SQLTemplate</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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"><h3><a name="AdvancedSQLTemplate-ControllingResultDataRowCaps"></a>Controlling Result DataRow Caps</h3>
+
+<p><em>(available since 3.0)</em></p>
+
+<p>Queries like <tt>"SELECT * FROM..."</tt> and even <tt>"SELECT COLUMN1, COLUMN2, ... FROM ..."</tt> can sometimes result in Cayenne exceptions on attempts to convert fetched DataRows to objects. Essentially any query that is not using a <a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html" title="Scripting SQLTemplate">#result directive</a> to describe the result set is prone to this problem, as different databases may produce different capitalization of the <tt>java.sql.ResultSet</tt> columns. </p>
+
+<p>The most universal way to address this issue is to describe each column explicitly in the SQLTemplate via <tt>#result</tt> directive, as mentioned above: <tt>"SELECT #result('column1'), #result('column2'), .."</tt>. However this becomes unpractical for the tables with lots of columns. For such cases Cayenne provides a shortcut based on the fact that normally an ORM mapping follows some naming convention for the column names. Simply put, for case-insensitive databases developers normall use either <b>all lowercase</b> or <b>all uppercase</b> column names.</p>
+
+<p>Here is the API to force Cayenne to follow the naming convention (also available as a dropdown in the Modeler). <em>Note that you shouldn't bother with this unless you are getting CayenneRuntimeExceptions when fetching with SQLTemplate.</em></p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">SQLTemplate query = <span class="code-keyword">new</span> SQLTemplate(<span class="code-quote">"SELECT * FROM ARTIST"</span>);
+query.setColumnNamesCapitalization(SQLTemplate.LOWERCASE_COLUMN_NAMES);
+List objects = context.performQuery(query);</pre>
+</div></div>
+
+<p>or </p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">SQLTemplate query = <span class="code-keyword">new</span> SQLTemplate(<span class="code-quote">"SELECT * FROM ARTIST"</span>);
+query.setColumnNamesCapitalization(SQLTemplate.UPPERCASE_COLUMN_NAMES);
+List objects = context.performQuery(query);</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/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Queries/SQLTemplate%20Query/SQLTemplate%20Basics/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html Sun Jul 8 12:11:31 2007
@@ -0,0 +1,133 @@
+<!--
+ 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 - SQLTemplate Basics</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">SQLTemplate Basics</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><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SelectQuery/index.html">SelectQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/index.html">SQLTemplate Query</a><ul>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/SQLTemplate Basics/index.html">SQLTemplate Basics</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Scripting SQLTemplate/index.html">Scripting SQLTemplate</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html">Advanced SQLTemplate</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/EJBQLQuery/index.html">EJBQLQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/NamedQuery/index.html">NamedQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/ObjectIdQuery/index.html">ObjectIdQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/QueryChain/index.html">QueryChain</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/RelationshipQuery/index.html">RelationshipQuery</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Queries Stored in DataMap/index.html">Queries Stored in DataMap</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Caching Query Results/index.html">Caching Query Results</a></li>
+<li><a href="../../../../../Documentation/Cayenne Guide/Queries/Customizing Queries/index.html">Customizing Queries</a></li>
+</ul>
+</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"><h3><a name="SQLTemplateBasics-CreatingSQLTemplate"></a>Creating SQLTemplate</h3>
+
+<p>SQLTemplates can be built using CayenneModeler. Here we demonstrate how to do the same thing via API. SQLTemplate consists of root and dynamic template string. Dynamic behavior of the template is discussed in subsequent chapters, for now it is sufficient to know that the template string is simply a valid SQL statement in the target database SQL dialect.</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SQLTemplate;
+...
+<span class="code-comment">// create selecting SQLTemplate
+</span>SQLTemplate selectQuery = <span class="code-keyword">new</span> SQLTemplate(Artist.class, <span class="code-quote">"select * from ARTIST"</span>);
+...
+<span class="code-comment">// create updating SQLTemplate
+</span>SQLTemplate updateQuery = <span class="code-keyword">new</span> SQLTemplate(Artist.class, <span class="code-quote">"delete from ARTIST"</span>);</pre>
+</div></div>
+
+<h3><a name="SQLTemplateBasics-SelectingObjectswithSQLTemplate"></a>Selecting Objects with SQLTemplate</h3>
+
+<p>Selecting SQLTemplate is very similar to SelectQuery in many respects. It can be executed via <tt>DataContext.performQuery(..)</tt> and supports the same configuration parameters, such as fetch limit, pagination, etc. It can be configured to return DataObjects (default) or data rows.</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SQLTemplate;
+...
+<span class="code-comment">// fetch all artists, but no more than 1000 objects...
+</span>SQLTemplate rawSelect = <span class="code-keyword">new</span> SQLTemplate(Artist.class, <span class="code-quote">"select * from ARTIST"</span>);
+rawSelect.setFetchLimit(1000);
+
+List artists = dataContext.performQuery(rawSelect);</pre>
+</div></div>
+
+<h3><a name="SQLTemplateBasics-ModifyingDatawithSQLTemplate"></a>Modifying Data with SQLTemplate</h3>
+
+<p>Non-selecting SQLTemplate allows to execute arbitrary SQL that modifies the database, but does not return the results. <tt>DataContext.performNonSelectingQuery(..)</tt> is used for this task.</p>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>When changing or deleting data via SQLTemplate you must realize that such changes are done directly to the database, bypassing the context, and therefore may potentially leave object graph in an inconsistent state.</td></tr></table>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.query.SQLTemplate;
+...
+<span class="code-comment">// fetch all artists, but no more than 1000 objects...
+</span>SQLTemplate rawDelete = <span class="code-keyword">new</span> SQLTemplate(Artist.class, <span class="code-quote">"delete from ARTIST"</span>);
+<span class="code-object">int</span>[] deleteCounts = dataContext.performNonSelectingQuery(rawDelete);</pre>
+</div></div>
+
+<h3><a name="SQLTemplateBasics-CustomizingSQLDialects"></a>Customizing SQL Dialects</h3>
+
+<p>Even though SQL is an industry standard, different DB vendors still have their own dialects and extensions. Two versions of the same query written for Oracle and PostgreSQL may look quiet different.</p>
+
+<p>Each SQLTemplate query has a default template, usually set in constructor. Internally it also keeps a map of alternative templates. This map normally uses a fully-qualified class name of the target DbAdapter as a key. This way Cayenne can determine which one of the SQL strings to use during the execution. Alternative SQL strings are configured using <tt>SQLTemplate.setTemplate(...)</tt>:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// build template with <span class="code-keyword">default</span> SQL
+</span>SQLTemplate query = <span class="code-keyword">new</span> SQLTemplate(Artist.class, <span class="code-quote">"select * from ARTIST"</span>);
+
+<span class="code-comment">// <span class="code-keyword">for</span> Postgres it would be nice to trim the CHAR ARTIST_NAME column
+</span><span class="code-comment">// or otherwise it will be returned padded with spaces
+</span><span class="code-object">String</span> pgTemplate = <span class="code-quote">"SELECT ARTIST_ID, RTRIM(ARTIST_NAME), DATE_OF_BIRTH FROM ARTIST"</span>;
+query.setTemplate(PostgresAdapter.class.getName(), pgTemplate);</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/Queries/SQLTemplate Query/SQLTemplate Basics/index.html
------------------------------------------------------------------------------
svn:eol-style = native