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 2009/10/25 13:06:25 UTC
svn commit: r829552 [3/6] - in
/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation: ./
Cayenne Guide/Ant Tasks/ Cayenne Guide/Ant Tasks/cdataport/ Cayenne
Guide/Ant Tasks/cdbgen/ Cayenne Guide/Ant Tasks/cdbimport/ Cayenne
Guide/Ant Tasks/...
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Understanding Transactions/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Understanding%20Transactions/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Understanding Transactions/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Understanding Transactions/index.html Sun Oct 25 12:06:20 2009
@@ -68,17 +68,18 @@
<p>Similar to the Java EE approach, Cayenne transactions are bound to the current thread for the duration of the execution. For instance this is how Cayenne does an internal check of whether there is a transaction in progress:</p>
-<div class="code"><div class="codeContent">
+<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.Transaction;
...
Transaction currentTx = Transaction.getThreadTransaction();
<span class="code-keyword">if</span>(currentTx != <span class="code-keyword">null</span>) {
<span class="code-comment">// transaction in process...
-</span>}</pre>
+</span>}
+</pre>
</div></div>
<p>When a Transaction is created inside Cayenne, it is immediately bound to the thread:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">Transaction tx = ...;
Transaction.bindThreadTransaction(tx);</pre>
</div></div>
@@ -96,7 +97,7 @@
<p>Later in <b>step 4</b> DataNodes will attach any of the Connections they obtains to the ongoing transaction:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> java.sql.Connection;
...
Connection connection = ...
@@ -106,7 +107,7 @@
<h3><a name="UnderstandingTransactions-TransactionLifecycleCallbacks%3ATransactionDelegate"></a>Transaction Lifecycle Callbacks: TransactionDelegate</h3>
<p>If you want to execute some custom code, such as Cayenne queries or raw JDBC queries at certain points in transaction lifecycle, you need to implement a <tt>org.apache.cayenne.access.TransactionDelegate</tt> callback interface:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyTxCallback <span class="code-keyword">implements</span> TransactionDelegate {
<span class="code-keyword">public</span> <span class="code-object">boolean</span> willCommit(Transaction transaction) {
@@ -138,13 +139,15 @@
<span class="code-keyword">public</span> <span class="code-object">boolean</span> willAddConnection(Transaction transaction, Connection connection) {
<span class="code-keyword">return</span> <span class="code-keyword">true</span>;
}
-}</pre>
+}
+</pre>
</div></div>
<p>Then an instance can be registered with the DataDomain. </p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">DataDomain domain = Configuration.getSharedConfiguration().getDomain();
-domain.setTransactionDelegate(<span class="code-keyword">new</span> MyTxCallback());</pre>
+domain.setTransactionDelegate(<span class="code-keyword">new</span> MyTxCallback());
+</pre>
</div></div>
<p>The delegate is shared by all DataContexts.</p>
@@ -153,17 +156,18 @@
<p>If the application needs to define its own transactional scope (e.g. wrap more than one <tt>DataContext.commitChanges()</tt> in a single database transaction), an explict <tt>org.apache.cayenne.access.Transaction</tt> can be started. It will serve as a simple substitute for the JTA transactions (of course JTA UserTransaction can be used instead if desired).</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>If the user code starts a Transaction, it <b>must</b> explicitly invoke "commit/rollback" methods and unbind the Transaction from the current thread when it is finished. Failure to do that may result in connection leaks. Of course if Cayenne starts an implicit transaction, it does the cleanup internally on its own.</td></tr></table>
+<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>If the user code starts a Transaction, it <b>must</b> explicitly invoke "commit/rollback" methods and unbind the Transaction from the current thread when it is finished. Failure to do that may result in connection leaks. Of course if Cayenne starts an implicit transaction, it does the cleanup internally on its own.</td></tr></table></div>
<p>Below is an example of user-controlled Transaction code. First it obtains a new transaction from the DataDomain (alternatively users can create Transaction subclasses of their own):</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">DataDomain domain = Configuration.getSharedConfiguration().getDomain();
-Transaction tx = domain.createTransaction();</pre>
+Transaction tx = domain.createTransaction();
+</pre>
</div></div>
<p>As we must finish transaction regardless of the outcome, wrap the rest of the code in try/catch/finally. Don't foget to bind/unbind the transaction, so that Cayenne stack is aware of it:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">Transaction.bindThreadTransaction(tx);
<span class="code-keyword">try</span> {
@@ -185,7 +189,8 @@
<span class="code-keyword">catch</span> (Exception rollbackEx) {
}
}
-}</pre>
+}
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/BNF for ExpressionParser/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/BNF%20for%20ExpressionParser/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/BNF for ExpressionParser/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/BNF for ExpressionParser/index.html Sun Oct 25 12:06:20 2009
@@ -59,7 +59,7 @@
</div>
<div id="ConfluenceContent"><h2><a name="BNFforExpressionParser-BNFforExpressionParser.jj"></a>BNF for ExpressionParser.jj</h2>
-<div class="preformatted"><div class="preformattedContent">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>NON-TERMINALS
expression ::= orCondition <EOF>
orCondition ::= andCondition ( "or" andCondition )*
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Building Expressions/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/Building%20Expressions/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Building Expressions/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Building Expressions/index.html Sun Oct 25 12:06:20 2009
@@ -57,10 +57,11 @@
<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
</ul>
</div>
-<div id="ConfluenceContent"><p>The Expression class (<tt>org.apache.cayenne.exp.Expression</tt>) provides <tt>Expression.fromString(String)</tt> as a convenience method to create expressions of arbitrary complexity. The structure of expressions is fairly intuitive, with the <span class="nobr"><a href="http://incubator.apache.org/cayenne/1_2/grammar/ExpressionParser.html" title="Visit page outside Confluence" rel="nofollow">formal grammar<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> showing the formal syntax and operators currently supported, but this topic is devoted to showing examples of usage. To demonstrate, an expression that matches Paintings with names that start with "A" and a price less than $1000.00 can be written as:</p>
+<div id="ConfluenceContent"><p>The Expression class (<tt>org.apache.cayenne.exp.Expression</tt>) provides <tt>Expression.fromString(String)</tt> as a convenience method to create expressions of arbitrary complexity. The structure of expressions is fairly intuitive, with the <a href="http://incubator.apache.org/cayenne/1_2/grammar/ExpressionParser.html" rel="nofollow">formal grammar</a> showing the formal syntax and operators currently supported, but this topic is devoted to showing examples of usage. To demonstrate, an expression that matches Paintings with names that start with "A" and a price less than $1000.00 can be written as:</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java">Expression e = Expression.fromString(<span class="code-quote">"paintingTitle like 'A%' and estimatedPrice < 1000"</span>);</pre>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">Expression e = Expression.fromString(<span class="code-quote">"paintingTitle like 'A%' and estimatedPrice < 1000"</span>);
+</pre>
</div></div>
<p>As you can see, the Expression class provides an easy way to specify the <tt>WHERE</tt> portion of a database query.</p>
@@ -69,47 +70,51 @@
<p>Expressions used as query qualifiers must use binary operators:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// valid qualifier
</span>Expression e1 = Expression.fromString(<span class="code-quote">"artistName like 'A%'"</span>);
<span class="code-comment">// INVALID QUALIFIER - <span class="code-keyword">this</span> will result in a SQL exception even
</span><span class="code-comment">// though it is still a valid Cayenne expression
-</span>Expression e2 = Expression.fromString(<span class="code-quote">"artistName"</span>);</pre>
+</span>Expression e2 = Expression.fromString(<span class="code-quote">"artistName"</span>);
+</pre>
</div></div>
<h3><a name="BuildingExpressions-CharacterConstants"></a>Character Constants</h3>
<p>Character constants should be enclosed in single or double quotes:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// e1 and e2 are equivalent
</span>Expression e1 = Expression.fromString(<span class="code-quote">"name = 'ABC'"</span>);
-Expression e2 = Expression.fromString(<span class="code-quote">"name = \"</span>ABC\"");</pre>
+Expression e2 = Expression.fromString(<span class="code-quote">"name = \"</span>ABC\"");
+</pre>
</div></div>
<h3><a name="BuildingExpressions-CaseSensitive"></a>Case Sensitive</h3>
<p>Predefined expression operators are all case sensitive and are usually lowercase. Complex words mostly follow the "Java naming style":</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// correct
</span>Expression e1 = Expression.fromString(<span class="code-quote">"artistName likeIgnoreCase 'A%'"</span>);
<span class="code-comment">// INCORRECT - will result in ParseException
-</span>Expression e2 = Expression.fromString(<span class="code-quote">"artistName LIKEIGNORECASE 'A%'"</span>);</pre>
+</span>Expression e2 = Expression.fromString(<span class="code-quote">"artistName LIKEIGNORECASE 'A%'"</span>);
+</pre>
</div></div>
<h3><a name="BuildingExpressions-Groupings"></a>Groupings</h3>
<p>Grouping of operations is done with parenthesis:</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java">Expression e1 = Expression.fromString(<span class="code-quote">"value = (estimatedPrice + 250.00) * 3"</span>);</pre>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">Expression e1 = Expression.fromString(<span class="code-quote">"value = (estimatedPrice + 250.00) * 3"</span>);
+</pre>
</div></div>
<h3><a name="BuildingExpressions-Prefixes"></a>Prefixes</h3>
<p>Object expressions are unquoted strings, <b>optionally</b> prefixed by "obj:". Database expressions are unquoted strings, <b>always</b> prefixed with "db:":</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// object path
</span>Expression e1 = Expression.fromString(<span class="code-quote">"artistName = 'Salvador Dali'"</span>);
@@ -117,7 +122,8 @@
</span>Expression e2 = Expression.fromString(<span class="code-quote">"obj:artistName = 'Salvador Dali'"</span>);
<span class="code-comment">// database path, <span class="code-quote">"db:"</span> prefix is mandatory
-</span>Expression e3 = Expression.fromString(<span class="code-quote">"db:ARTIST_NAME = 'Salvador Dali'"</span>);</pre>
+</span>Expression e3 = Expression.fromString(<span class="code-quote">"db:ARTIST_NAME = 'Salvador Dali'"</span>);
+</pre>
</div></div>
<p>Please note that "obj:" and "db:" are case sensitive.</p>
@@ -126,7 +132,7 @@
<h3><a name="BuildingExpressions-NamedParameterExpressions"></a>Named Parameter Expressions</h3>
<p>Expressions can have named parameters (names that start with "$"). Parameterized expressions are an easy way to create reusable expression templates:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">final</span> Expression template = Expression.fromString(<span class="code-quote">"artistName = $name"</span>);
SelectQuery query;
List values;
@@ -138,11 +144,12 @@
...
params.put(<span class="code-quote">"name"</span>, <span class="code-quote">"Monet"</span>);
query = <span class="code-keyword">new</span> SelectQuery(Artist.class, template.expWithParameters(params));
-values = dataContext.performQuery(query);</pre>
+values = dataContext.performQuery(query);
+</pre>
</div></div>
<p>To create a named parameterized expression with a LIKE clause, the wildcard(s) must be part of the values in the Map and not the expression string itself:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">final</span> Expression template = Expression.fromString(<span class="code-quote">"artistName like $name"</span>);
SelectQuery query;
List values;
@@ -151,14 +158,15 @@
params.put(<span class="code-quote">"name"</span>, <span class="code-quote">"Salvi%"</span>);
query = <span class="code-keyword">new</span> SelectQuery(Artist.class, template.expWithParameters(params));
values = dataContext.performQuery(query);
-...</pre>
+...
+</pre>
</div></div>
<h3><a name="BuildingExpressions-KeyPathExpressions"></a>Key Path Expressions</h3>
<p>A very powerful feature of Cayenne's expressions are the ability to specify relationships in the expression string as a "dotted" key path. Cayenne will automatically determine all the join information. For example, if basing a query off the Painting:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">final</span> Expression template = Expression.fromString(<span class="code-quote">"artist.artistName = $artist and gallery.galleryName = $gallery"</span>);
SelectQuery query;
List values;
@@ -168,12 +176,13 @@
params.put(<span class="code-quote">"gallery"</span>, <span class="code-quote">"Louvre"</span>);
query = <span class="code-keyword">new</span> SelectQuery(Artist.class, template.expWithParameters(params));
values = dataContext.performQuery(query);
-...</pre>
+...
+</pre>
</div></div>
<p>Note that the key path can contain multiple "dots" in the name – there is no predefined limit. Also, the parameter doesn't have to be a String (or Number/etc), it can also be a Cayenne DataObject if you already have one in memory:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">final</span> Expression template = Expression.fromString(<span class="code-quote">"artist.artistName = $artist and gallery = $gallery"</span>);
SelectQuery query;
List values;
@@ -183,14 +192,15 @@
params.put(<span class="code-quote">"gallery"</span>, gallery); <span class="code-comment">// gallery = instance of Gallery
</span>query = <span class="code-keyword">new</span> SelectQuery(Artist.class, template.expWithParameters(params));
values = dataContext.performQuery(query);
-...</pre>
+...
+</pre>
</div></div>
<h3><a name="BuildingExpressions-OptionalNamedParameterValues"></a>Optional Named Parameter Values</h3>
<p>Cayenne by default automatically omits parts of an expression which have no matching value. Using the expression from above:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">final</span> Expression template = Expression.fromString(<span class="code-quote">"artist.artistName = $artist and gallery.galleryName = $gallery"</span>);
SelectQuery query;
List values;
@@ -199,7 +209,8 @@
params.put(<span class="code-quote">"artist"</span>, <span class="code-quote">"Salvador Dali"</span>);
query = <span class="code-keyword">new</span> SelectQuery(Artist.class, template.expWithParameters(params));
values = dataContext.performQuery(query);
-...</pre>
+...
+</pre>
</div></div>
<p>Even though the specified expression has two named parameters, the "gallery" key has been omitted. Cayenne will automatically translate the expression into <tt>"artist.artistName = $artist"</tt> (which becomes <tt>"artist.artistName = 'Salvador Dali'"</tt>). This feature allows a restrictive search qualifier to be written and prompt the user for search criteria. If the user leaves values out, the expression can automatically widen to be a less restrictive search by omitting the keys for the map.</p></div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Expression Factory Utilities/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/Expression%20Factory%20Utilities/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Expression Factory Utilities/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Expression Factory Utilities/index.html Sun Oct 25 12:06:20 2009
@@ -57,7 +57,7 @@
<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
</ul>
</div>
-<div id="ConfluenceContent"><p>Sometimes there is a need to build an expression by combining other existing expressions. Also quiet often it is desirable to use strongly typed API instead of interpreted string expressions. The following sections describe <span class="nobr"><a href="http://incubator.apache.org/cayenne/2_0/api/cayenne/org/apache/cayenne/exp/ExpressionFactory.html" title="Visit page outside Confluence" rel="nofollow">ExpressionFactory<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> and <span class="nobr"><a href="http://incubator.apache.org/cayenne/2_0/api/cayenne/org/apache/cayenne/exp/Expression.html" title="Visit page outside Confluence" rel="nofollow">Expression<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> methods that allow to construct expressions step by step via API
calls.</p>
+<div id="ConfluenceContent"><p>Sometimes there is a need to build an expression by combining other existing expressions. Also quiet often it is desirable to use strongly typed API instead of interpreted string expressions. The following sections describe <a href="http://cayenne.apache.org/doc/api/org/apache/cayenne/exp/ExpressionFactory.html" rel="nofollow">ExpressionFactory</a> and <a href="http://cayenne.apache.org/doc/api/org/apache/cayenne/exp/Expression.html" rel="nofollow">Expression</a> methods that allow to construct expressions step by step via API calls.</p>
<h3><a name="ExpressionFactoryUtilities-Path%2FValueExpressions"></a>Path/Value Expressions</h3>
@@ -83,7 +83,7 @@
<p>As was mentioned <a href="../../../../Documentation/Cayenne Guide/Expressions/Path Expressions/index.html" title="Path Expressions">earlier</a>, the type of a second Object argument depends on the type of property path points to. It is important to mention that paths that end with a relationship name (both to-one and to-many) can be matched against DataObjects, thus removing the need to know PK or FK values when building expressions. This behavior is not specific to ExpressionFactory, it works the same way with Expression.fromString(..) as well.</p>
-<div class="code"><div class="codeContent">
+<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.exp.Expression;
<span class="code-keyword">import</span> org.apache.cayenne.exp.ExpressionFactory;
<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
@@ -93,7 +93,8 @@
</span>
Artist a = ...;
Expression qual = ExpressionFactory.matchExp(<span class="code-quote">"toArtist"</span>, a);
-SelectQuery select = <span class="code-keyword">new</span> SelectQuery(Painting.class, qual);</pre>
+SelectQuery select = <span class="code-keyword">new</span> SelectQuery(Painting.class, qual);
+</pre>
</div></div>
<h3><a name="ExpressionFactoryUtilities-ChainingExpressions"></a>Chaining Expressions</h3>
@@ -110,7 +111,7 @@
<p>Example of using chaining:</p>
-<div class="code"><div class="codeContent">
+<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.exp.Expression;
<span class="code-keyword">import</span> org.apache.cayenne.exp.ExpressionFactory;
<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
@@ -129,7 +130,8 @@
</span>qual =
qual.andExp(ExpressionFactory.likeIgnoreCaseExp(<span class="code-quote">"artistName"</span>, <span class="code-quote">"D%"</span>));
-SelectQuery select = <span class="code-keyword">new</span> SelectQuery(Artist.class, qual);</pre>
+SelectQuery select = <span class="code-keyword">new</span> SelectQuery(Artist.class, qual);
+</pre>
</div></div>
<h3><a name="ExpressionFactoryUtilities-CreatingComplexExpressions"></a>Creating Complex Expressions</h3>
@@ -150,14 +152,15 @@
<p>Example of creating complex expressions:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">HashMap map = <span class="code-keyword">new</span> HashMap();
map.put(<span class="code-quote">"login"</span>, <span class="code-quote">"joeuser"</span>);
map.put(<span class="code-quote">"password"</span>, <span class="code-quote">"secret"</span>);
<span class="code-comment">// the last parameter refers to the operation inside each key/value pair.
</span>
-Expression qual = ExpressionFactory.matchAllExp(map, Expression.EQUAL_TO);</pre>
+Expression qual = ExpressionFactory.matchAllExp(map, Expression.EQUAL_TO);
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/In-Memory Evaluation/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/In-Memory%20Evaluation/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/In-Memory Evaluation/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/In-Memory Evaluation/index.html Sun Oct 25 12:06:20 2009
@@ -70,11 +70,11 @@
</ul>
-<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Limitation of In-Memory Expressions</b><br />Current limitation of in-memory expressions is that no collections are permitted in the object property path. In case of DataObjects that means that path containing to-many relationships may not work for in-memory evaluation.</td></tr></table>
+<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><b>Limitation of In-Memory Expressions</b><br />Current limitation of in-memory expressions is that no collections are permitted in the object property path. In case of DataObjects that means that path containing to-many relationships may not work for in-memory evaluation.</td></tr></table></div>
<p>Here is an example of evaluating expression with a single object:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class User <span class="code-keyword">extends</span> CayenneDataObject {
<span class="code-keyword">public</span> <span class="code-object">String</span> getName() {
...
@@ -100,14 +100,16 @@
<span class="code-keyword">if</span>(exp.match(nonPersistentBean)) {
<span class="code-comment">// <span class="code-keyword">do</span> something <span class="code-keyword">else</span>
-</span>}</pre>
+</span>}
+</pre>
</div></div>
<p>Another example - using expression to filter a list objects:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">Expression exp = ExpressionFactory.likeExp(<span class="code-quote">"artistName"</span>, <span class="code-quote">"A%"</span>);
-List startWithA = exp.filterObjects(artists);</pre>
+List startWithA = exp.filterObjects(artists);
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/NULL Handling/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/NULL%20Handling/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/NULL Handling/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/NULL Handling/index.html Sun Oct 25 12:06:20 2009
@@ -61,15 +61,16 @@
<p>For example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// <span class="code-keyword">this</span> expression will be translated by Cayenne to the SQL like:
</span><span class="code-comment">// ...WHERE BIRTH_DATE IS NOT NULL
-</span>Expression exp = ExpressionFactory.noMatchExp(<span class="code-quote">"birthDate"</span>, <span class="code-keyword">null</span>);</pre>
+</span>Expression exp = ExpressionFactory.noMatchExp(<span class="code-quote">"birthDate"</span>, <span class="code-keyword">null</span>);
+</pre>
</div></div>
<p>When a query is executed with this qualifier, the a SQL String similar to the following will be generated:</p>
-<div class="preformatted"><div class="preformattedContent">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>... WHERE t0.BIRTH_DATE IS NOT NULL</pre>
</div></div></div>
</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Path Expressions/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Expressions/Path%20Expressions/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Path Expressions/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Expressions/Path Expressions/index.html Sun Oct 25 12:06:20 2009
@@ -59,7 +59,7 @@
</div>
<div id="ConfluenceContent"><p>Before we start discussing how to build expressions, it is important to understand one group of expressions widely used in Cayenne: <em>path expressions</em>. There are two types of path expressions: object path used to navigate graphs of Java objects that follow Java Bean property naming conventions and database path used to navigate the database schema. General form of path expressions is the following:</p>
-<div class="preformatted"><div class="preformattedContent">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>[db:]segment[+][.segment[+]...]</pre>
</div></div>
@@ -80,7 +80,7 @@
</ul>
-<table cellpadding='5' width='85%' cellspacing='8px' class='infoMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">What Does 'navigation' Means</b><br />The term "navigation" in the description above could mean different things depending on the context. For instance, when evaluating an expression in memory, "navigating" an object path would simply return the value of a corresponding object property. When the same expression is used in a select query qualifier, it resolves to the name of a table column used in a WHERE clause of a generated SQL statement.</td></tr></table>
+<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>What Does 'navigation' Means</b><br />The term "navigation" in the description above could mean different things depending on the context. For instance, when evaluating an expression in memory, "navigating" an object path would simply return the value of a corresponding object property. When the same expression is used in a select query qualifier, it resolves to the name of a table column used in a WHERE clause of a generated SQL statement.</td></tr></table></div>
<h3><a name="PathExpressions-DatabasePathExpressions"></a>Database Path Expressions</h3>
<p>Database Path Expressions provide an easy way to navigate through DB table joins. Instead of complex join semantics such expressions utilize the names of DbRelationships defined in Cayenne DataMap. Translating the above object path examples into the DB realm, database path expressions might look like this:</p>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Cayenne and Maven/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Installation/Cayenne%20and%20Maven/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Cayenne and Maven/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Cayenne and Maven/index.html Sun Oct 25 12:06:20 2009
@@ -60,7 +60,7 @@
<p>Cayenne publishes Maven2 artifacts to ibiblio repository, so they can be declared in the POM:</p>
-<div class="preformatted"><div class="preformattedContent">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-server</artifactId>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/JAR Files and Dependencies/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Installation/JAR%20Files%20and%20Dependencies/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/JAR Files and Dependencies/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/JAR Files and Dependencies/index.html Sun Oct 25 12:06:20 2009
@@ -67,6 +67,7 @@
<ul>
<li><tt>cayenne-client-x.x.jar</tt> - a subset of cayenne-server.jar trimmed for use on the client in an <a href="../../../../Documentation/Remote Object Persistence Guide/index.html" title="Remote Object Persistence Guide">ROP application</a>.</li>
+ <li><tt>cayenne-tools-x.x.jar</tt> - Ant tasks</li>
<li><tt>cayenne-agent-x.x.jar</tt> - a Java instrumentation agent that is used to enhance POJO persistent classes.</li>
<li><tt>cayenne-modeler-x.x.jar</tt> - CayenneModeler runtime library. Most applications won't ever use it. It is only needed for the <a href="../../../../Documentation/Cayenne Guide/Deployment/Using JNDI/index.html" title="Using JNDI">local JNDI hack</a>.</li>
</ul>
@@ -75,10 +76,10 @@
<p>When using <tt>cayenne-server-x.x.jar</tt> you'll need a few third party jars (all included in <tt>"lib/third-party"</tt> directory of the distribution):</p>
<ul>
- <li><span class="nobr"><a href="http://objectstyle.org/ashwood/" title="Visit page outside Confluence" rel="nofollow">ObjectStyle Ashwood Graph Library<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 2.0</li>
- <li><span class="nobr"><a href="http://jakarta.apache.org/velocity/" title="Visit page outside Confluence" rel="nofollow">Apache Velocity Template Engine<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 1.3 (and all its dependencies bundled with velocity-dep)</li>
- <li><span class="nobr"><a href="http://jakarta.apache.org/commons/collections" title="Visit page outside Confluence" rel="nofollow">Apache Commons Collections<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 3.1</li>
- <li><span class="nobr"><a href="http://jakarta.apache.org/commons/logging/" title="Visit page outside Confluence" rel="nofollow">Apache Commons Logging<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 1.1</li>
+ <li><a href="http://objectstyle.org/ashwood/" rel="nofollow">ObjectStyle Ashwood Graph Library</a>, version 2.0</li>
+ <li><a href="http://jakarta.apache.org/velocity/" rel="nofollow">Apache Velocity Template Engine</a>, version 1.3 (and all its dependencies bundled with velocity-dep)</li>
+ <li><a href="http://jakarta.apache.org/commons/collections" rel="nofollow">Apache Commons Collections</a>, version 3.1</li>
+ <li><a href="http://jakarta.apache.org/commons/logging/" rel="nofollow">Apache Commons Logging</a>, version 1.1</li>
</ul>
@@ -89,12 +90,12 @@
<p>One or more of the following libraries may be needed depending on how you use Cayenne:</p>
<ul>
- <li><span class="nobr"><a href="http://ant.apache.org/" title="Visit page outside Confluence" rel="nofollow">Apache Ant<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 1.6 or newer. Needed for <a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html" title="Ant Tasks">Cayenne Ant Tasks</a>.</li>
- <li><span class="nobr"><a href="http://jakarta.apache.org/commons/pool/" title="Visit page outside Confluence" rel="nofollow">Apache Commons Pool<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 1.2 and <span class="nobr"><a href="http://jakarta.apache.org/commons/dbcp/" title="Visit page outside Confluence" rel="nofollow">Apache Commons DBCP<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 1.2.1. Needed if you use DBCPDataSourceFactory for one of the DataNodes.</li>
- <li><span class="nobr"><a href="http://www.jgroups.org/" title="Visit page outside Confluence" rel="nofollow">JGroups<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 2.2.7 or newer. Needed if you plan to use remote notifications via JGroups transport.</li>
- <li><span class="nobr"><a href="http://java.sun.com/products/jms/" title="Visit page outside Confluence" rel="nofollow">Java Messaging Service (JMS)<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>. Needed if you plan to use remote notifications via JMS transport.</li>
- <li><span class="nobr"><a href="http://vpp.sourceforge.net/" title="Visit page outside Confluence" rel="nofollow">Foundry Logic VPP Library<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>, version 2.2.1. Needed for <a href="../../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">advanced class generation options</a> with Ant.</li>
- <li><span class="nobr"><a href="http://www.opensymphony.com/oscache/" title="Visit page outside Confluence" rel="nofollow">OSCache<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> version 2.3.2 or newer. Needed if you plan to use OSCache as your <a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html" title="Query Result Caching">query results cache provider</a>.</li>
+ <li><a href="http://ant.apache.org/" rel="nofollow">Apache Ant</a>, version 1.6 or newer. Needed for <a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html" title="Ant Tasks">Cayenne Ant Tasks</a>.</li>
+ <li><a href="http://jakarta.apache.org/commons/pool/" rel="nofollow">Apache Commons Pool</a>, version 1.2 and <a href="http://jakarta.apache.org/commons/dbcp/" rel="nofollow">Apache Commons DBCP</a>, version 1.2.1. Needed if you use DBCPDataSourceFactory for one of the DataNodes.</li>
+ <li><a href="http://www.jgroups.org/" rel="nofollow">JGroups</a>, version 2.2.7 or newer. Needed if you plan to use remote notifications via JGroups transport.</li>
+ <li><a href="http://java.sun.com/products/jms/" rel="nofollow">Java Messaging Service (JMS)</a>. Needed if you plan to use remote notifications via JMS transport.</li>
+ <li><a href="http://vpp.sourceforge.net/" rel="nofollow">Foundry Logic VPP Library</a>, version 2.2.1 (included in <tt>"lib/third-party"</tt> directory of the distribution). Needed for <a href="../../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">class generation options</a> with Ant.</li>
+ <li><a href="http://www.opensymphony.com/oscache/" rel="nofollow">OSCache</a> version 2.3.2 or newer. Needed if you plan to use OSCache as your <a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/Query Result Caching/index.html" title="Query Result Caching">query results cache provider</a>.</li>
</ul>
</div>
</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Upgrade/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Installation/Upgrade/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Upgrade/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/Upgrade/index.html Sun Oct 25 12:06:20 2009
@@ -71,7 +71,7 @@
</ul>
-<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Upgrading project XML files can make them unusable with earlier versions of Cayenne.</td></tr></table>
+<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>Upgrading project XML files can make them unusable with earlier versions of Cayenne.</td></tr></table></div>
<ul>
<li>Pay attention to CayenneModeler validation warnings.</li>
@@ -139,7 +139,7 @@
<ul>
- <li>DVModeler and DataViews are no longer shipped with Cayenne. See <span class="nobr"><a href="http://cwiki.apache.org/CAYDV/" title="Visit page outside Confluence" rel="nofollow">http://cwiki.apache.org/CAYDV/<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> for more details.</li>
+ <li>DVModeler and DataViews are no longer shipped with Cayenne. See <a href="http://cwiki.apache.org/CAYDV/" rel="nofollow">http://cwiki.apache.org/CAYDV/</a> for more details.</li>
</ul>
@@ -156,7 +156,7 @@
</ul>
- <div class="code"><div class="codeContent">
+ <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">ALTER TABLE AUTO_PK_SUPPORT CHANGE COLUMN NEXT_ID NEXT_ID BIGINT NOT NULL;</pre>
</div></div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Installation/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Installation/index.html Sun Oct 25 12:06:20 2009
@@ -60,7 +60,7 @@
<ul>
- <li><b>JDBC Driver:</b> You will need a JDBC driver to access the database. Information about various drivers and database-specific configuration is provided on the <span class="nobr"><a href="http://cwiki.apache.org/CAY/database-support.html" title="Visit page outside Confluence" rel="nofollow">Database Support<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> page.</li>
+ <li><b>JDBC Driver:</b> You will need a JDBC driver to access the database. Information about various drivers and database-specific configuration is provided on the <a href="http://cwiki.apache.org/CAY/database-support.html" rel="nofollow">Database Support</a> page.</li>
</ul>
@@ -72,7 +72,7 @@
<h3><a name="Installation-ObtainingCayenne"></a>Obtaining Cayenne</h3>
-<p>Installing Cayenne is simple - just download and unpack the distribution. Download page is located here: <span class="nobr"><a href="http://cayenne.apache.org/download.html" title="Visit page outside Confluence" rel="nofollow">http://cayenne.apache.org/download.html<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>. Select a distribution for your development platform (cross-platform version, as the name implies, works on any OS that has Java).</p>
+<p>Installing Cayenne is simple - just download and unpack the distribution. Download page is located here: <a href="http://cayenne.apache.org/download.html" rel="nofollow">http://cayenne.apache.org/download.html</a>. Select a distribution for your development platform (cross-platform version, as the name implies, works on any OS that has Java).</p>
<p>Once you've done that, you can <a href="../../../Documentation/Modeler Guide/Introduction to CayenneModeler/Running CayenneModeler/index.html" title="Running CayenneModeler">start the Modeler</a> and use appropriate jar files in your application. See <a href="../../../Documentation/Cayenne Guide/Installation/JAR Files and Dependencies/index.html" title="JAR Files and Dependencies">JAR Files and Dependencies</a> for more information. </p>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Lifecycle Callbacks/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Lifecycle%20Callbacks/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Lifecycle Callbacks/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Lifecycle Callbacks/index.html Sun Oct 25 12:06:20 2009
@@ -51,16 +51,15 @@
</div>
<div id="ConfluenceContent"><h2><a name="LifecycleCallbacks-LifecycleCallbacks"></a>Lifecycle Callbacks</h2>
-<p>Users can register callback methods that will be invoked during the lifecycle of persistent objects. Callback mechanism matches closely the one defined in the <a href="http://cwiki.apache.org/confluence/confluence/display/CAYJPA/JPA+Guide" title="JPA Guide">JPA Specification</a> (except that it works with JDK 1.4 and allows preconfigured listeners). There are seven lifecycle callbacks described below (PrePersist, PostPersist, PreUpdate, PostUpdate, PreRemove, PostRemove, PostLoad). There are two types of invocations for each one of them: <b>callback on a persistent object</b> itself or a <b>callback on an arbitrary listener object</b>.</p>
+<p>Users can register callback methods that will be invoked during the lifecycle of persistent objects. Callback mechanism is similar to the one defined in the <a href="http://cwiki.apache.org/confluence/confluence/display/CAYJPA/JPA+Guide" title="JPA Guide">JPA Specification</a>, however there are some noteable differences introduced to better follow the Cayenne object lifecycle. There are eight lifecycle callbacks described below (PostAdd, PrePersist, PostPersist, PreUpdate, PostUpdate, PreRemove, PostRemove, PostLoad). Each one cab be invoked as a <b>callback on a persistent object</b> itself or as a <b>callback on an arbitrary listener object</b>.</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">Callbacks feature supercedes the following 1.2/2.0 features:</b><br />
-<ul>
+<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>Callbacks feature supercedes the following 1.2/2.0 features:</b><br /><ul>
<li>Interception of object state transitions inside <tt>"Persistent.setPersistenceState()"</tt>.</li>
- <li>Event mechanism defined in <tt>"org.apache.cayenne.access.event"</tt> package. Scheduled for removal in 3.0.</li>
+ <li>Event mechanism defined in <tt>"org.apache.cayenne.access.event"</tt> package that was removed in 3.0.</li>
<li><tt>"DataObject.validateForX"</tt> - it is a good idea to use it strictly for validation; updating the state before commit should be done via callbacks.</li>
<li><tt>"DataObject.fetchFinished()"</tt> - scheduled for removal in 3.0</li>
</ul>
-</td></tr></table>
+</td></tr></table></div>
<h2><a name="LifecycleCallbacks-CallbackMethodSemantics"></a>Callback Method Semantics</h2>
@@ -70,14 +69,14 @@
<li>It looks like <tt>"void method(Type entityObject)"</tt> <em>for listener classes</em>.</li>
<li>A callback method can have an arbitrary name.</li>
<li>A callback method can use public, private, protected or default access.</li>
- <li>They must NOT be static.</li>
+ <li>It must NOT be static.</li>
<li>Callback methods are polymorphic - registering a callback on a superclass (even if the superclass does not map to an entity) will ensure the callback will be invoked on all entity subclasses, using the overriding subclass method if applicable.</li>
</ul>
<p>Callback on persistent object example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class Artist {
...
@@ -91,7 +90,7 @@
<p>Callback on a listener class example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyListener {
...
@@ -102,8 +101,9 @@
}</pre>
</div></div>
-<h2><a name="LifecycleCallbacks-TypesofCallbacks"></a>Types of Callbacks</h2>
+<p>Note that empty callback methods are generated as a part of persistent class generation (either with <a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html" title="maven2-cgen">Maven</a>, <a href="../../../Documentation/Cayenne Guide/Ant Tasks/cgen/index.html" title="cgen">Ant</a> or CayenneModeler).</p>
+<h2><a name="LifecycleCallbacks-TypesofCallbacks"></a>Types of Callbacks</h2>
<p>Valid callback types are defined as Java enumerated constants in the <tt>org.apache.cayenne.map.LifecycleEvent</tt> enumeration.</p>
@@ -113,10 +113,14 @@
<th class='confluenceTh'>Invoked...</th>
</tr>
<tr>
-<td class='confluenceTd'>PrePersist</td>
+<td class='confluenceTd'>PostAdd</td>
<td class='confluenceTd'>Within <tt>"ObjectContext.newObject()"</tt> after ObjectId and ObjectContext are set.</td>
</tr>
<tr>
+<td class='confluenceTd'>PrePersist</td>
+<td class='confluenceTd'>Prior to commit (and prior to "validateFor*") within <tt>"ObjectContext.commitChanges()"</tt> and <tt>"ObjectContext.commitChangesToParent()"</tt></td>
+</tr>
+<tr>
<td class='confluenceTd'>PreRemove</td>
<td class='confluenceTd'>Before an object is deleted inside <tt>"ObjectContext.deleteObject()"</tt>; also includes all objects that will be deleted as a result of CASCADE delete rule.</td>
</tr>
@@ -149,10 +153,10 @@
<h2><a name="LifecycleCallbacks-RegisteringCallbacks"></a>Registering Callbacks</h2>
-<p>Normally listeners and persistent object callbacks are mapped in the Modeler, but here we'll show how to do that in the code. Callbacks can be registered with <tt>LifecycleCallbackRegistry</tt>, which is shared by all contexts within DataDomain.</p>
+<p>Normally listeners and persistent object callbacks are mapped in the Modeler, but this can also be done in the code. Callbacks are registered with <tt>LifecycleCallbackRegistry</tt>, which is shared by all contexts within a DataDomain.</p>
<p>Obtaining the shared registry instance:</p>
-<div class="code"><div class="codeContent">
+<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.reflect.LifecycleCallbackRegistry;
...
DataDomain domain = ...
@@ -163,7 +167,7 @@
<p>Registry obtained this way already contains callbacks mapped in the DataMap. To add extra callbacks in runtimes, use various <tt>addListener(...)</tt> methods. </p>
<p>Adding a listener object that implements <tt>LifecycleListener</tt> interface:</p>
-<div class="code"><div class="codeContent">
+<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.LifecycleListener
<span class="code-keyword">public</span> class MyListener <span class="code-keyword">implements</span> LifecycleListener {
@@ -183,7 +187,7 @@
</div></div>
<p>Adding a listener of an arbitrary class</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyOtherListener {
<span class="code-comment">// note that callback method doesn't have to be
@@ -215,7 +219,7 @@
</div></div>
<p>Finally a persistent object can implement callbacks as well, being notified of its own events:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// <span class="code-quote">"<span class="code-keyword">extends</span> _Artist"</span> implies <span class="code-quote">"<span class="code-keyword">implements</span> Persistent"</span> via a superclass
</span><span class="code-keyword">public</span> class Artist <span class="code-keyword">extends</span> _Artist {
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/index.html Sun Oct 25 12:06:20 2009
@@ -61,7 +61,7 @@
<p>This plugin is imported into pom.xml as follows:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><build>
<plugins>
<plugin>
@@ -70,7 +70,8 @@
<version>3.0-SNAPSHOT</version>
</plugin>
</plugins>
-</build></pre>
+</build>
+</pre>
</div></div>
<p>It has the following goals:</p>
@@ -87,7 +88,7 @@
<p>This plugin is imported into pom.xml as follows:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><build>
<plugins>
<plugin>
@@ -96,7 +97,8 @@
<version>3.0-SNAPSHOT</version>
</plugin>
</plugins>
-</build></pre>
+</build>
+</pre>
</div></div>
<p>It has one goal:</p>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbgen/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/maven2-cdbgen/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbgen/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbgen/index.html Sun Oct 25 12:06:20 2009
@@ -55,7 +55,7 @@
<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
</ul>
</div>
-<div id="ConfluenceContent"><p><tt>cdbgen</tt> is an Maven 2 mojo that that uses Cayenne DataMap to drop and/or generate schema objects of a specified database. By default, it is bound to the <tt>pre-integration-test</tt> phase. Please see this <span class="nobr"><a href="http://docs.codehaus.org/display/MAVENUSER/Maven+and+Integration+Testing" title="Visit page outside Confluence" rel="nofollow">guide to integration testing with maven2<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> for ideas of how tie this in with your existing test infrastructure.</p>
+<div id="ConfluenceContent"><p><tt>cdbgen</tt> is an Maven 2 mojo that that uses Cayenne DataMap to drop and/or generate schema objects of a specified database. By default, it is bound to the <tt>pre-integration-test</tt> phase. Please see this <a href="http://docs.codehaus.org/display/MAVENUSER/Maven+and+Integration+Testing" rel="nofollow">guide to integration testing with maven2</a> for ideas of how tie this in with your existing test infrastructure.</p>
<h3><a name="maven2-cdbgen-Parameters%28asXMLelements%29"></a>Parameters (as XML elements)</h3>
<table class='confluenceTable'><tbody>
@@ -126,7 +126,7 @@
<p>Load the Maven 2 plugin and configure the <tt>cdbgen</tt> mojo: </p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -145,11 +145,12 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div>
<p>Here is an example of using <tt>cdbgen</tt> to create DB schema objects on a local HSQLDB database named "bookmarker" from a DataMap located in "main/resources/datamap.map.xml":</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -172,7 +173,8 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbimport/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/maven2-cdbimport/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbimport/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cdbimport/index.html Sun Oct 25 12:06:20 2009
@@ -136,7 +136,7 @@
<h3><a name="maven2-cdbimport-Examples"></a>Examples</h3>
<p>Load the Maven 2 plugin and configure the <tt>cdbimport</tt> mojo:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -155,10 +155,11 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div>
<p>Here is an example of using <tt>cdbimport</tt> to create DB schema objects on a local HSQLDB database named "bookmarker" from a DataMap located in "main/resources/datamap.map.xml":</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -181,7 +182,8 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/maven2-cgen/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-cgen/index.html Sun Oct 25 12:06:20 2009
@@ -162,7 +162,7 @@
<p>Load the Maven 2 plugin and configure the <tt>cgen</tt> mojo: </p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -181,11 +181,17 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div>
-<p>Here is an example of using CGen to generate Persistent subclass/superclass pairs from DataMap located in "main/resources/datamap.map.xml":</p>
-<div class="code"><div class="codeContent">
+<p>Here is an example of using CGen to generate Persistent subclass/superclass pairs from DataMap located in "main/resources/datamap.map.xml".</p>
+
+
+<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>There's an intermittent problem when using Maven/cgen in Eclipse with m2eclipse plugin that requires placing <configuration>..</configuration> at the plugin level, instead of execution level.</td></tr></table></div>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -205,13 +211,12 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div>
-<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The follow example includes the use of Velocity template overriding, which is not yet functional in the plugin.</td></tr></table>
-
<p>Here is an example of using CGen to generate html pages for all entities starting with "Artist" in the DataMap:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -236,7 +241,8 @@
<span class="code-tag"></executions></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-modeler/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Maven2%20Plugins/maven2-modeler/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-modeler/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Maven2 Plugins/maven2-modeler/index.html Sun Oct 25 12:06:20 2009
@@ -59,7 +59,7 @@
<p>There is no configuration of this plugin, but you do need to add to add the plugin to your POM:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag"><build></span>
<span class="code-tag"><plugins></span>
<span class="code-tag"><plugin></span>
@@ -67,13 +67,15 @@
<span class="code-tag"><artifactId></span>maven-cayenne-modeler-plugin<span class="code-tag"></artifactId></span>
<span class="code-tag"></plugin></span>
<span class="code-tag"></plugins></span>
-<span class="code-tag"></build></span></pre>
+<span class="code-tag"></build></span>
+</pre>
</div></div>
<p>It can be started from the root of your project by running:</p>
-<div class="code"><div class="codeContent">
-<pre class="code-java">$ mvn cayenne-modeler:run</pre>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">$ mvn cayenne-modeler:run
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Data%20Rows/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Data Rows/index.html Sun Oct 25 12:06:20 2009
@@ -73,7 +73,7 @@
<p>Data rows example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
<span class="code-keyword">import</span> java.util.Map;
<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
@@ -94,7 +94,8 @@
<span class="code-comment">// convert row to an artist
</span>Artist artist = (Artist)ctxt.objectFromDataRow(<span class="code-quote">"Artist"</span>, row);
-...</pre>
+...
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Iterating%20Through%20Data%20Rows/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Iterating Through Data Rows/index.html Sun Oct 25 12:06:20 2009
@@ -60,13 +60,13 @@
<div id="ConfluenceContent"><p>There are cases when the result sets are so large that even when fetching data rows, application can run out of memory. For instance, a user may be creating a report that requires in-memory processing of hundreds of thousands of database rows. In such cases normal Cayenne behavior of reading the whole java.sql.ResultSet in the memory before returning it to the user may result in an application exhausing all memory and crashing.</p>
<p>Cayenne solves this by allowing to obtain results in the form of ResultIterator. ResultIterator is connected to an open java.sql.ResultSet, therefore its methods may throw checked exceptions. ResultIterator returns data rows (not DataObjects) one at a time, reading them on demand from the open ResultSet. Each data row can be converted to a DataObject or accessed directly. Open ResultIterator locks the database connection, therefore <b>ResultIterator always requires explicit closing in the user code</b>.</p>
-<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>In web applications, programmers must ensure that no open ResultIterators are kept between HTTP requests. Failure to do so may result in too many database connections being locked, thus quickly exhausting connection pool. In general, an application with Web GUI is NOT a good candidate for implementation using ResultIterators.</td></tr></table>
+<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>In web applications, programmers must ensure that no open ResultIterators are kept between HTTP requests. Failure to do so may result in too many database connections being locked, thus quickly exhausting connection pool. In general, an application with Web GUI is NOT a good candidate for implementation using ResultIterators.</td></tr></table></div>
<p>When working with open ResultIterator, users still can perform any other database operations: select queries, traversing object relationships, etc. Any parallel data operation will internally check out an unused connection from the connection pool as it would normally do, while ResultIterator still locks its own connection.</p>
<p>ResultIterator annotated example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
<span class="code-keyword">import</span> java.util.Map;
<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
@@ -106,7 +106,8 @@
closeEx.printStackTrace();
}
}
-...</pre>
+...
+</pre>
</div></div></div>
</div>
<div class="clearer">.</div>
Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Paginated%20Queries/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Paginated Queries/index.html Sun Oct 25 12:06:20 2009
@@ -65,7 +65,7 @@
<p>Paged query example:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> java.util.List;
<span class="code-keyword">import</span> java.util.Map;
<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
@@ -94,10 +94,11 @@
<span class="code-comment">// This is safe and will NOT trigger a full fetch
</span><span class="code-object">int</span> size = artistRows.size();
-...</pre>
+...
+</pre>
</div></div>
-<table cellpadding='5' width='85%' cellspacing='8px' class='tipMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Combining data rows and paginated queries</b><br />Cayenne supports combining both performance optimizations in the same query - fetching data rows (see previous chapters) and paginated queries. So if users work with tabular data and don't care much about real objects, combining the two approaches would improve speed and memory use even more. </td></tr></table></div>
+<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Combining data rows and paginated queries</b><br />Cayenne supports combining both performance optimizations in the same query - fetching data rows (see previous chapters) and paginated queries. So if users work with tabular data and don't care much about real objects, combining the two approaches would improve speed and memory use even more. </td></tr></table></div></div>
</div>
<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/Performance Tuning/Prefetching/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Performance%20Tuning/Prefetching/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Performance Tuning/Prefetching/index.html Sun Oct 25 12:06:20 2009
@@ -61,7 +61,7 @@
<p>Prefetching is a performance optimization technique that allows to bring back more than one type of objects in a single query. Prefetches are configured in terms of relationship paths from the query root entity to the "prefetched" entity. E.g.:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// configure query with prefetches
</span>SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
query.addPrefetch(<span class="code-quote">"paintingArray"</span>);
@@ -72,7 +72,8 @@
<span class="code-keyword">while</span>(it.hasNext()) {
Artist a = (Artist) it.next();
<span class="code-object">System</span>.out.println(<span class="code-quote">"paintings: "</span> + a.getPaintingArray().size());
-}</pre>
+}
+</pre>
</div></div>
<p>When prefetching is set, corresponding relationships are "inflated" with database objects within a single <tt>performQuery</tt> run, leaving it up to Cayenne to optimize retrieval of multiple entities. For instance the example above results in just two SQL queries issued to the database internally, while running the same query without a prefetch and later iterating over artists will result in <tt>1 + N</tt> queries, where <tt>N</tt> is the number of artists returned. </p>
@@ -82,27 +83,17 @@
<ul>
<li>All types of relationships can be prefetched - to-one, to-many, flattened.</li>
<li>A prefetch can span more than one relationship:
-<div class="code"><div class="codeContent">
-<pre class="code-java">query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);</pre>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);
+</pre>
</div></div></li>
<li>A query can have more than one prefetch path at the same time:
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">query.addPrefetch(<span class="code-quote">"paintingArray"</span>);
-query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);</pre>
+query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);
+</pre>
</div></div></li>
- <li><font color="red">PREFETCH LIMITATION:</font> To-many relationships should not be prefetched if a query qualifier can potentially reduce a number of related objects, resulting in incorrect relationship list. E.g.:
-<div class="code"><div class="codeContent">
-<pre class="code-java">SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Artist.class);
-
-Expression exp = ExpressionFactory.matchExp(<span class="code-quote">"paintingArray.paintingTitle"</span>, <span class="code-quote">"Some Painting"</span>);
-
-<span class="code-comment">// INVALID!! since there can be more than one painting per artist, <span class="code-keyword">this</span> prefetch
-</span><span class="code-comment">// wouldn't work.
-</span>query.addPrefetch(<span class="code-quote">"paintingArray"</span>);</pre>
-</div></div>
-<p>In the future versions of Cayenne this will be addressed by using SQL subqueries. For now it is programmer's responsibility to avoid such prefetches.</p></li>
<li>If SelectQuery is fetching data rows, all default prefetches are ignored, though custom joint prefetches (see below) will be included.</li>
- <li>When you customize SelectQuery prefetches to use joint semantics (see below how customization can be done), be aware that joint prefetch adds an extra inner join to the main query. This may result in fewer objects returned than expected. If you are SQL-savvy it may be helpful to think of disjoint prefetches as analogous to SQL outer joins and joint prefetches - to SQL inner joins.</li>
</ul>
@@ -111,21 +102,19 @@
<h3><a name="Prefetching-PrefetchSemantics"></a>Prefetch Semantics</h3>
-<p><em>(semantics flavors were introduced in 1.2M3, with some changes in 1.2M8)</em></p>
-
<p>Queries store prefetching information as trees of <tt>PrefetchTreeNode</tt> objects:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">PrefetchTreeNode treeRoot = query.getPrefetchTree();
<span class="code-keyword">if</span>(treeRoot != <span class="code-keyword">null</span>) {
<span class="code-comment">// <span class="code-keyword">do</span> something with tree nodes
-</span>}</pre>
+</span>}
+</pre>
</div></div>
<p>Each node specifies the name of prefetch path segment and execution semantics. There are two flavors of prefetch semantics - <b>joint</b> and <b>disjoint</b>. Semantics of each node is initially determined by Cayenne when a new prefetch path is added, and can be later customized by the user (e.g., see joint example below).</p>
-<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>
-<p>In most cases prefetch semantics is of no concern to the users. Cayenne will do its best to configure the right semantics on the fly. Don't tweak semantics unless you understand the implications and have some proof that different semantics would result in better select performance on your database. </p></td></tr></table>
+<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><p>In most cases prefetch semantics is of no concern to the users. Cayenne will do its best to configure the right semantics on the fly. Don't tweak semantics unless you understand the implications and have some proof that different semantics would result in better select performance on your database. </p></td></tr></table></div>
<p>Some internal semantics rules:</p>
@@ -141,7 +130,7 @@
<p>"Disjoint" prefetches (aka "normal prefetches", as this is how Cayenne implemented prefetching since 1.0) internally result in a separate SQL statement per prefetch path.</p>
-<div class="code"><div class="codeContent">
+<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">// <span class="code-quote">"disjoint"</span> is <span class="code-keyword">default</span> semantics of SelectQuery
@@ -149,19 +138,21 @@
query.addPrefetch(<span class="code-quote">"paintingArray.toGallery"</span>);
<span class="code-comment">// <span class="code-keyword">this</span> will result in 1 main SQL query plus 2 extra prefetch queries
-</span>context.performQuery(query);</pre>
+</span>context.performQuery(query);
+</pre>
</div></div>
<h3><a name="Prefetching-JointPrefetches"></a>Joint Prefetches</h3>
<p>"Joint" is prefetch type that issues a single SQL statement for multiple prefetch paths. Cayenne processes in memory a cartesian product of the entities involved, converting it to an object tree. SQLTemplate and ProcedureQuery create joint prefetches by default. SelectQuery needs to be told to use joint prefetch:</p>
-<div class="code"><div class="codeContent">
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// after adding a <span class="code-keyword">new</span> prefetch, change its semantics to joint
</span>query.addPrefetch(<span class="code-quote">"paintingArray"</span>).setSemantics(
PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS);
-context.performQuery(query);</pre>
+context.performQuery(query);
+</pre>
</div></div>
<p>Code above will result in a single SQL statement issued. OUTER joins will be used for this type of prefetch. Specifics of the column naming when using prefetching with SQLTemplate are discussed <a href="../../../../Documentation/Cayenne Guide/Queries/SQLTemplate Query/Advanced SQLTemplate/index.html" title="Advanced SQLTemplate">here</a>.</p>