cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r488202 [12/19] - in /incubator/cayenne/main/trunk/assembly/cayenne-generic: ./ src/doc/ src/doc/confluence/ src/doc/confluence/Documentation/ src/doc/confluence/Documentation/JPA Guide/ src/doc/confluence/Documentation/JPA Guide/JPA Agent/...
Date Mon, 18 Dec 2006 10:24:42 GMT
Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataSource/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/DataSource/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataSource/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataSource/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,83 @@
+<!--
+   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 - DataSource</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">DataSource</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html" title="DataNode">DataNode</a> obtains connections via a <tt>javax.sql.DataSource</tt>. If an application is deployed in a J2EE container, DataSource is normally provided by container <a href="../../../../../Documentation/User Guide/Deployment/Using JNDI/index.html" title="Using JNDI">via JNDI</a>. For standalone applications (or if you don't want to use JNDI) Cayenne provides its own DataSource that includes connection pooling features. Whenever you select <tt>org.apache.cayenne.conf.DriverDataSourceFactory</tt> in the Modeler, you are choosing to use Cayenne DataSource. </p>
+
+<p>Cayenne DataSource implementation is located in the <tt>org.apache.cayenne.conn</tt> package and is fully independent from the rest of the framework. Since Cayenne DataSource is chosen automatically, users rarely need to know more details. One notable exception are applications requiring users to interactively <span class="nobr"><a href="http://cwiki.apache.org/CAY/setting-database-connection.html" title="Visit page outside Confluence" rel="nofollow">enter database login information<sup><img class="rendericon" src="../../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>. In this case you can write your own DataSource wrapper, and internally instantiate Cayenne DataSource (<tt>org.apache.cayenne.conn.PoolManager</tt>) after the user provides login and password.</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataSource/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/DbAdapter/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,99 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - DbAdapter</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">DbAdapter</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h3><a name="DbAdapter-PortabilityAcrossDatabases"></a>Portability Across Databases</h3>
+
+<p>The JDBC specification provides a great abstraction for relational database work. Still in practice some cross-database portability issues remain:</p>
+
+<ul>
+	<li>Certain standard SQL features may not be implemented in some RDBMS.</li>
+	<li>Certain standard JDBC features may not be supported by some drivers (batch updates, auto incremented columns, etc.)</li>
+	<li>SQL syntax may vary across RDBMS.</li>
+	<li>BLOBs and CLOBs are handled differently by different vendors.</li>
+	<li>Data type definitions vary across RDBMS. Data types may have different names, size and precision.</li>
+	<li>Vendors provide their own extensions of SQL and JDBC functionality. Taking advantage of these extensions and creating portable code at the same time is not a trivial task.</li>
+</ul>
+
+
+<p><tt>org.apache.cayenne.dba.DbAdapter</tt> interface is used in Cayenne for an additional portability layer sitting on top of JDBC. There is one generic implementation of DbAdapter provided with Cayenne (JdbcAdapter) and also a subclass of JdbcAdapter for each database that is officially supported by Cayenne. Users can create their own adapter implementations as well (some hints are given <a href="http://cwiki.apache.org/confluence/confluence/display/CAY/Custom+DbAdapter" title="Custom DbAdapter">here</a>).</p>
+
+<h3><a name="DbAdapter-DbAdapterAutomaticDetection"></a>DbAdapter Automatic Detection</h3>
+
+<p>Usually Cayenne detects the type of the database dynamically and installs the right adapter in runtime. However a user can enforce a specific adapter class by entering its name using "Adapter" tab in the DataNode Editor panel in CayenneModeler. Alternatively an adapter can be set on a DataNode via a method call.</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/EntityResolver/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html Mon Dec 18 02:24:19 2006
@@ -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 - EntityResolver</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">EntityResolver</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>In runtime the mapping metadata is accessed via a <a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html" title="DataChannel">DataChannel</a> in a form of <tt>org.apache.cayenne.map.EntityResolver</tt> (EntityResolver available via ObjectContext is usually obtained from the channel behind the scenes). EntityResolver provides a single namespace for multiple DataMaps. </p>
+
+<p>Another important function of the EntityResolver is providing access to the <tt>org.apache.cayenne.property.ClassDescriptor</tt> instances for each persistent entity. Those a compiled by Cayenne on the fly using EntityResolver's <tt>org.apache.cayenne.property.ClassDescriptorFactory</tt>.</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/Event Package/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/Event%20Package/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/Event Package/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/Event Package/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,93 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Event Package</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Event Package</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent">
+<p>Cayenne includes a full-featured events mechanism. It allows creation of local and distributed event queues. It is very powerful and generic; it is not tied to Cayenne persistence features in any way and can be used in any application. The most important features are:</p>
+
+<ul>
+	<li>Event senders do not have to deal with event dispatching details - listener handling and dispatches are done via instances of EventManager.</li>
+	<li>Any types of listeners can be registered. Listeners do not have to implement a specific interface.</li>
+	<li>No explicit unregistering of listeners is required. Listeners are cleaned up when they go out of scope, or when the event subject goes out of scope.</li>
+	<li>Supports local and remote dispatches. Remote dispatches can be done via arbitrary transport by implementing transport-specific EventBridge. There are two existing EventBridge implementations - using JMS and using JavaGroups.</li>
+	<li>Dispatches can be done both synchronously (sender waits till all listeners finish) or asyncronously (sender posts an event to the queue, and returns without waiting for the processing to complete).</li>
+	<li>In a similar manner individual listeners can register as blocking or non-blocking.</li>
+</ul>
+
+
+<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>The most common error when using EventSubject is not storing a reference to it. This may result in a premature cleanup of a given subject, and automatic unregistering of all listeners. Good practice is to make subject a "public static final" variable of the event sender class if a subject is common for all instances of senders; or make it an ivar of a sender instance if subject is only related to this instance.</td></tr></table></div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/Event Package/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/ObjectContext/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html Mon Dec 18 02:24:19 2006
@@ -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 - ObjectContext</title>
+    <style type="text/css">@import "../../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">ObjectContext</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a><ul>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p><tt>org.apache.cayenne.ObjectContext</tt> is an interface that defines API for the application interaction with Cayenne. Two most notable implementors are <a href="../../../../../Documentation/User Guide/DataContext/index.html" title="DataContext">DataContext</a>, used in most Cayenne applications, and <tt>CayenneContext</tt> used on the <a href="../../../../../Documentation/Remote Object Persistence Guide/Remote Object Persistence Coding Client/index.html" title="Remote Object Persistence Coding Client">remote client</a>. </p>
+
+<p>ObjectContext accesses the underlying persistence stack via a parent <a href="../../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html" title="DataChannel">DataChannel</a>. ObjectContexts that support multiple levels of nesting (such as DataContext) themselves implement a <tt>org.apache.cayenne.DataChannel</tt> interface.</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/cayenne-runtime.png
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/cayenne-runtime.png?view=auto&rev=488202
==============================================================================
Binary file - no diff available.

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/cayenne-runtime.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,105 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - Runtime Components</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Runtime Components</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a><ul>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html">ObjectContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html">EntityResolver</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html">DataChannel</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html">DataNode</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html">DbAdapter</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html">DataSource</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne runtime framework is an intermediary between a Java application and a relational database. The picture below shows the main components of the framework:</p>
+
+<p><img src="cayenne-runtime.png" align="absmiddle" border="0" /></p>
+
+<h3><a name="RuntimeComponents-VerticalStructureCayennePersistenceStack"></a>Vertical Structure - Cayenne Persistence Stack</h3>
+
+<p>Vertically this structure reflects the runtime organization of the Cayenne persistence stack. Cayenne instantiates and configures the stack (shown in yellow above) using the XML descriptors provided by the user (usually these are the XML files created by CayenneModeler). Alternatively <b>persistence stack can be assembled via the API</b> and/or using Spring or any similar approach. Moreover Cayenne stack is fully dynamic and <b>can be altered at runtime</b>, since currently (as of version 1.2) Cayenne does not rely on bytecode enhancement.</p>
+
+<h3><a name="RuntimeComponents-HorizontalStructureCayenneLayers"></a>Horizontal Structure - Cayenne Layers</h3>
+
+<p>The top Cayenne layer (ObjectContext, Query API, Expression API) is what the application needs to work with persistent objects. This layer implements Cayenne part of the <a href="../../../../Documentation/User Guide/Design/Cayenne Contract/index.html" title="Cayenne Contract">persistence contract</a> between the application and the framework, while underlying layers deal with details of the object-to-relational translation and data source interaction. Access to the mapping metadata and the stack objects residing in the lower layers is possible via the API.</p>
+
+<h3><a name="RuntimeComponents-RuntimeComponents"></a>Runtime Components</h3>
+
+<p>Many individual components of the framework are discussed in the following chapters:</p>
+
+<ul>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html" title="ObjectContext">ObjectContext</a></li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/EntityResolver/index.html" title="EntityResolver">Mapping Metadata</a></li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataChannel/index.html" title="DataChannel">DataChannel</a></li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataNode/index.html" title="DataNode">DataNode</a></li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html" title="DbAdapter">DbAdapter</a></li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/Event Package/index.html" title="Event Package"><tt>org.apache.cayenne.event</tt></a> - event support package.</li>
+	<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/DataSource/index.html" title="DataSource"><tt>org.apache.cayenne.conn</tt></a> - DataSource package.</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Understanding%20Transactions/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,201 @@
+<!--
+   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 - Understanding Transactions</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Understanding Transactions</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne has its own simple transaction API centered around <tt>org.apache.cayenne.access.Transaction</tt> class. Its goal is to ensure consistency of the DataContext database operations. It works either as a standalone mechanism, or in conjunction with another transaction framework, such as JTA or Spring. To switch between the two modes of operation, use "Container-Managed Transactions" checkbox in the DataDomain editing panel in CayenneModeler:</p>
+
+<p><img src="transactions-types.png" align="absmiddle" border="0" /></p>
+
+<p>If this box is unchecked (default), standalone mode is used and Cayenne will take care of transactional resources management on its own. If it is checked, Cayenne won't commit or rollback transactional resources, relying on the external transaction manager to do that.</p>
+
+<p>In both cases Transaction API works implicitly behind the scenes, so the application doesn't need to interact with it directly. In that Cayenne Transactions are fully declarative.</p>
+
+<h3><a name="UnderstandingTransactions-HowTransactionsWork"></a>How Transactions Work</h3>
+
+<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">
+<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>
+</div></div>
+
+<p>When a Transaction is created inside Cayenne, it is immediately bound to the thread:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">Transaction tx = ...;
+Transaction.bindThreadTransaction(tx);</pre>
+</div></div>
+
+<p>Now let's revisit the flow of a typical operation that requires a transaction:</p>
+<ol>
+	<li>A DataContext sends a query or a commit request to the underlying <tt>org.apache.cayenne.DataChannel</tt>.</li>
+	<li>The request travels the chain of DataChannels until it reaches one that is a <tt>org.apache.cayenne.access.DataDomain</tt>.</li>
+	<li>DataDomain analyzes context request and dispatches data queries to one or more <tt>org.apache.cayenne.access.DataNodes</tt>.</li>
+	<li>Each DataNode opens a JDBC Connection and executes queries.</li>
+</ol>
+
+
+<p>Transactions come into play in <b>step 3</b>. DataDomain checks whether there is an existing Transaction in process and if not - creates and starts a new one (standalone or container, depending on the preconfigured type). In that Cayenne transaction policy is similar to Java EE <tt>"REQUIRE"</tt> policy.</p>
+
+<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">
+<pre class="code-java"><span class="code-keyword">import</span> java.sql.Connection;
+...
+Connection connection = ...
+currentTx.addConnection(<span class="code-quote">"someKey"</span>, connection);</pre>
+</div></div>
+
+<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">
+<pre class="code-java">ublic class MyTxCallback <span class="code-keyword">implements</span> TransactionDelegate {
+
+    <span class="code-keyword">public</span> <span class="code-object">boolean</span> willCommit(Transaction transaction) {
+        <span class="code-comment">// run extra query before transaction is committed
+</span>
+        <span class="code-comment">// The results of it will be committed or rolled back together with the current Transaction. 
+</span>
+        DataContext context = DataContext.getThreadDataContext();
+        context.performGenericQuery(<span class="code-keyword">new</span> SQLTemplate(X.class, <span class="code-quote">"..."</span>));
+
+        <span class="code-comment">// <span class="code-keyword">return</span> <span class="code-keyword">true</span>, letting Cayenne know it should <span class="code-keyword">continue</span> with commit
+</span>        <span class="code-keyword">return</span> <span class="code-keyword">true</span>;
+    }
+
+    <span class="code-keyword">public</span> <span class="code-object">boolean</span> willMarkAsRollbackOnly(Transaction transaction) {
+        <span class="code-keyword">return</span> <span class="code-keyword">true</span>;
+    }
+
+    <span class="code-keyword">public</span> <span class="code-object">boolean</span> willRollback(Transaction transaction) {
+        <span class="code-keyword">return</span> <span class="code-keyword">true</span>;
+    }
+
+    <span class="code-keyword">public</span> void didCommit(Transaction transaction) {
+    }
+
+    <span class="code-keyword">public</span> void didRollback(Transaction transaction) {
+    }
+
+    <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>
+</div></div>
+
+<p>Then an instance can be registered with the DataDomain. </p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+domain.setTransactionDelegate(<span class="code-keyword">new</span> MyTxCallback());</pre>
+</div></div>
+
+<p>The delegate is shared by all DataContexts.</p>
+
+<h3><a name="UnderstandingTransactions-UserDefinedTransactionScope"></a>User-Defined Transaction Scope</h3>
+
+<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>
+
+<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">
+<pre class="code-java">DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+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">
+<pre class="code-java">Transaction.bindThreadTransaction(tx);
+
+<span class="code-keyword">try</span> {
+    <span class="code-comment">// <span class="code-keyword">do</span> something...
+</span>    ....
+    <span class="code-comment">// <span class="code-keyword">if</span> no failures, commit
+</span>    tx.commit();
+}
+<span class="code-keyword">catch</span> (Exception ex) {
+    tx.setRollbackOnly();
+}
+<span class="code-keyword">finally</span> {
+    Transaction.bindThreadTransaction(<span class="code-keyword">null</span>);
+ 
+    <span class="code-keyword">if</span> (tx.getStatus() == Transaction.STATUS_MARKED_ROLLEDBACK) {
+        <span class="code-keyword">try</span> {
+           tx.rollback();
+        }
+        <span class="code-keyword">catch</span> (Exception rollbackEx) {
+        }
+    }
+}</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/transactions-types.png
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Understanding%20Transactions/transactions-types.png?view=auto&rev=488202
==============================================================================
Binary file - no diff available.

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Understanding Transactions/transactions-types.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,83 @@
+<!--
+   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 - Design</title>
+    <style type="text/css">@import "../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Design</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/User Guide/Design/index.html">Design</a><ul>
+<li><a href="../../../Documentation/User Guide/Design/Cayenne Contract/index.html">Cayenne Contract</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html">Persistent Object Lifecycle</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Runtime Components/index.html">Runtime Components</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Object Caching/index.html">Object Caching</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent">
+<p>This chapter discusses the architecture of the core Cayenne framework. It only deals with the runtime operation of the object-relational persistence layer. <a href="../../../Documentation/Modeler Guide/index.html" title="Modeler Guide">Mapping procedures</a> and <a href="../../../Documentation/Remote Object Persistence Guide/index.html" title="Remote Object Persistence Guide">remote object persistence</a> are discussed elsewhere. The information below is not strictly required to start using Cayenne, so new users can skip it initially and come back later to gain better understanding of how Cayenne operates under the hood.</p>
+
+<p>The following topics are discssued:</p>
+
+<ul>
+	<li><a href="../../../Documentation/User Guide/Design/Cayenne Contract/index.html" title="Cayenne Contract">Contract between persistent objects and Cayenne</a></li>
+	<li><a href="../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html" title="Persistent Object Lifecycle">Persistent object lifecycle</a></li>
+	<li><a href="../../../Documentation/User Guide/Design/Runtime Components/index.html" title="Runtime Components">Runtime Components</a></li>
+	<li><a href="../../../Documentation/User Guide/Design/Understanding Transactions/index.html" title="Understanding Transactions">Transactions</a></li>
+	<li><a href="../../../Documentation/User Guide/Design/Primary Key Generation/index.html" title="Primary Key Generation">Primary Key generation strategies</a></li>
+	<li><a href="../../../Documentation/User Guide/Design/Object Caching/index.html" title="Object Caching">Object caching mechanism</a></li>
+</ul>
+
+</div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Expressions/Building Expressions/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Expressions/Building%20Expressions/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Expressions/Building Expressions/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Expressions/Building Expressions/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,215 @@
+<!--
+   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 - Building Expressions</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://incubator.apache.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">Building Expressions</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a><ul>
+<li><a href="../../../../Documentation/User Guide/Expressions/Path Expressions/index.html">Path Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Building Expressions/index.html">Building Expressions</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Expression Factory Utilities/index.html">Expression Factory Utilities</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/NULL Handling/index.html">NULL Handling</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/In-Memory Evaluation/index.html">In-Memory Evaluation</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</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 class="code"><div class="codeContent">
+<pre class="code-java">Expression e = Expression.fromString(<span class="code-quote">"paintingTitle like 'A%' and estimatedPrice &lt; 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>
+
+<h3><a name="BuildingExpressions-BinaryOperators"></a>Binary Operators</h3>
+
+<p>Expressions used as query qualifiers must use binary operators:</p>
+
+<div class="code"><div class="codeContent">
+<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>
+</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">
+<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>
+</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">
+<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>
+</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></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">
+<pre class="code-java"><span class="code-comment">// object path
+</span>Expression e1 = Expression.fromString(<span class="code-quote">"artistName = 'Salvador Dali'"</span>);
+
+<span class="code-comment">// same object path
+</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>
+</div></div>
+
+<p>Please note that "obj:" and "db:" are case sensitive.</p>
+
+
+<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">
+<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;
+...
+Map params = <span class="code-keyword">new</span> HashMap();
+params.put(<span class="code-quote">"name"</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);
+...
+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>
+</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">
+<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;
+...
+Map params = <span class="code-keyword">new</span> HashMap();
+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>
+</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">
+<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;
+...
+Map params = <span class="code-keyword">new</span> HashMap();
+params.put(<span class="code-quote">"artist"</span>, <span class="code-quote">"Salvador Dali"</span>);
+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>
+</div></div>
+
+<p>Note that the key path can contain multiple "dots" in the name &#8211; 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">
+<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;
+...
+Map params = <span class="code-keyword">new</span> HashMap();
+params.put(<span class="code-quote">"artist"</span>, <span class="code-quote">"Salvador Dali"</span>);
+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>
+</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">
+<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;
+...
+Map params = <span class="code-keyword">new</span> HashMap();
+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>
+</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>
+</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Expressions/Building Expressions/index.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message