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 2006/05/10 03:11:01 UTC
svn commit: r405581 [9/14] - in
/incubator/cayenne/main/trunk/cayenne/cayenne-other: docs/ docs/images/
wiki-docs/ wiki-docs/Documentation/ wiki-docs/Documentation/Modeler Guide/
wiki-docs/Documentation/Modeler Guide/Cayenne Project Structure/ wiki-doc...
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Graph/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Object%20Graph/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Graph/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Graph/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,76 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Object Graph</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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">Object Graph</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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</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/Understanding Caching/index.html">Understanding Caching</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Mapping discussed in the previous chapter is used to translate data coming from the database into a bunch of DataObjects. DataObjects interconnected with each other using relationships form an object graph. Object graph is a useful abstraction when thinking about interactions between persistent objects in Cayenne application.</p>
+<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>There is no "ObjectGraph" class in Cayenne - this is a pure logical concept transparent to the user. Other terms describing the same concept as object graph are "business objects layer", "persistent objects", etc. Object graph is stored in memory and manipulated by the ObjectStore instance.</td></tr></table>
+
+<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>While relationships between objects are represented as ObjRelationship instances in the DataMap, objects themselves implement relationships as simple List or DataObject properties.</td></tr></table>
+
+<p>Cayenne object graph has the following principal properties that make it useful and easy to use in the application:</p>
+
+<ul>
+ <li><em>All operations on the object graph are controllable by the application.</em><br/>
+ Developers can add/remove/modify objects related to a given object via corresponding method calls.</li>
+ <li><em>Initial set of objects is obtained by running a select query, or creating new DataObjects.</em></li>
+ <li><em>Most objects related to the initial objects can be obtained via simple method calls on initial objects.</em></li>
+ <li><em>Object identity and uniquing in a certain context.</em><br/>
+ Cayenne ensures that there will be no more than one object in any given DataContext that corresponds to a given database row. For instance if an object is obtained via a relationship method call, and later another object is obtained via a query interface for the same database row (think same primary key), only one object will be created in Cayenne. For the later case an object will not be created, but rather an already existing object will be reused.</li>
+ <li><em>Synchronization with the database.</em><br/>
+ Object graph changes can be synchronized with the database in a single method call. This greatly simplifies management of changes and solves transactional issues.</li>
+ <li><em>Discarding changes.</em><br/>
+ Object graph changes made since last commit can be discarded using a single method call.</li>
+</ul>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Graph/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/entities.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Object%20Relational%20Mapping/entities.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/entities.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Object%20Relational%20Mapping/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,78 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Object Relational Mapping</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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">Object Relational Mapping</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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</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/Understanding Caching/index.html">Understanding Caching</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Normally mapping is done between a Java class and a database table or view. Instances of such class will correspond to single rows in the database. Persistent properties of such object (properties in a "JavaBeans" sense) would map either to table columns or to database primary-foreign key relationships. Summarizing possible mappings, the most common cases are:</p>
+
+<ul>
+ <li>Java class -> database table or view</li>
+ <li>"simple" class property -> table column</li>
+ <li>"complex" class property -> related table via a database relationship</li>
+</ul>
+
+
+<ul>
+ <li>Java object -> row in a table</li>
+ <li>"simple" object property value -> value of column in a row</li>
+ <li>"complex" object property value -> another object or list of objects</li>
+</ul>
+
+
+<p>The following diagram shows how mapping is organized in Cayenne:<br/>
+<img src="entities.gif" align="absmiddle" border="0" /></p>
+
+<p>Cayenne mapping is implemented as 2 layers: database layer and Java layer. Java layer uses database layer to tie Java classes to the database tables. Main benefit of using 2 mapping layers is loose coupling of database metadata information and Java class information. For instance, database layer may describe the full structure of the database to allow database schema generation, while Java layer would only map to a subset of tables. Another case is when a relationship between Java classes spans a chain of relationships between database tables. This mapping scenario will be supported by Cayenne in the future.</p>
+
+<p>Cayenne organizes mapping information into DataMap's. Normally a DataMap is saved in XML format. Other formats are also possible. For instance Cayenne can create DataMaps using WebObjects EOModel format. Normally DataMaps are created and maintained using CayenneModeler GUI tool. </p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Object Relational Mapping/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Primary Key Generation/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Primary%20Key%20Generation/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Primary Key Generation/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Primary Key Generation/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,120 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Primary Key Generation</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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">Primary Key Generation</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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Primary Key Generation/index.html">Primary Key Generation</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Caching/index.html">Understanding Caching</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Depending on the type of persistent objects and the database design, primary key values can be handled in a few different ways. A decision to use one or another technique will affect how the mapping is done. Here is a summary of possible scenarios. Each one is described below in details.</p>
+<table class='confluenceTable'><tbody>
+<tr>
+<th class='confluenceTh'> </th>
+<th class='confluenceTh'>PK Has DbAttribute</th>
+<th class='confluenceTh'>PK Has ObjAttribute</th>
+<th class='confluenceTh'>PK is a DataObject property</th>
+</tr>
+<tr>
+<td class='confluenceTd'>Meaningful Primary Key</td>
+<td class='confluenceTd'>Yes</td>
+<td class='confluenceTd'>Yes</td>
+<td class='confluenceTd'>Yes</td>
+</tr>
+<tr>
+<td class='confluenceTd'>Primary Key Derived From Relationship</td>
+<td class='confluenceTd'>Yes</td>
+<td class='confluenceTd'>No</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>Database-Generated Primary Key</td>
+<td class='confluenceTd'>Yes</td>
+<td class='confluenceTd'>No</td>
+<td class='confluenceTd'>No</td>
+</tr>
+<tr>
+<td class='confluenceTd'>Cayenne-Generated Primary Key</td>
+<td class='confluenceTd'>Yes</td>
+<td class='confluenceTd'>No</td>
+<td class='confluenceTd'>No</td>
+</tr>
+</tbody></table>
+
+<h3><a name="PrimaryKeyGeneration-MeaningfulPrimaryKey"></a>Meaningful Primary Key</h3>
+
+<p>DataObjects can provide their own values for the primary key columns. Sometimes this makes sense, for example if a primary key column contains meaningful data like a Social Security Number. In such cases primary key handling is no different from handling any other persistent attributes. Each primary key column (DbAttribute) will have an ObjAttribute mapped to it. The Java class implementing DataObject will contain a property described by this ObjAttribute. The value of this property will be saved to the database.</p>
+
+<h3><a name="PrimaryKeyGeneration-PrimaryKeyDerivedFromRelationship"></a>Primary Key Derived From Relationship</h3>
+
+<p>A primary key column of a table may depend on a primary key column of another table. This is normally the case with "join" tables used to resolve many-to-many relationships. In such cases DataObject normally does not contain a property mapped to a PK column. Instead the value is automatically derived by Cayenne from a primary key of a related object using a relationship.</p>
+
+<h3><a name="PrimaryKeyGeneration-PrimaryKeyProvidedbyDatabaseonINSERT"></a>Primary Key Provided by Database on INSERT</h3>
+
+<p>Sometimes databases have their own proprietary mechanism to generate a primary key when a new row is inserted. This feature is called "auto increment" or "identity column". Cayenne supports such primary keys out of the box. For this mechanism to be invoked, PK DbAttributes must be marked as "generated" in the Modeler. Currently MySQL and SQLServer adapters have this feature turned on by default.</p>
+
+<h3><a name="PrimaryKeyGeneration-CayenneGeneratedPrimaryKey"></a>Cayenne Generated Primary Key</h3>
+
+<p>In most cases, the database primary key is a purely relational concept that has no correspondence in the object model. Normally this is a unique sequential number that identifies a row in the database. This means that creating a property in a persistent object that corresponds to a primary key is an artificial step. To avoid doing that Cayenne assigns each object an ObjectId that internally handles the details of primary key handling.</p>
+
+<p>When a new DataObject is saved, and its properties and relationships do not contain primary key values, Cayenne will attempt to automatically generate a key value. Generation mechanism depends on the DbAdapter used and can be customized by users by subclassing one of the included adapters. Adapters shipped with Cayenne use the following default PK generation strategies:</p>
+
+<ul>
+ <li>MySQL, PostgreSQL, HSQL Adapters: use select/update from a special AUTO_PK_TABLE lookup table.</li>
+ <li>Oracle Adapter: uses Oracle sequences.</li>
+ <li>DB2 Adapter: uses DB2 sequences.</li>
+ <li>SQLServer , Sybase Adapters: use a strored procedure tied to AUTO_PK_TABLE lookup table.</li>
+ <li>OpenBase Adapter: uses OpenBase specific NEWID mechanism.</li>
+</ul>
+
+
+<p>To generate the necessary database objects for the primary key autogeneration, use CayenneModeler and follow the instructions given <a href="../../../../Documentation/Modeler Guide/Common Modeling Tasks/Generate Primary Key Support/index.html" title="Generate Primary Key Support">here</a>.</p>
+
+<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>Cayenne only supports automatic PK generation for a single column per table.</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 ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Primary Key Generation/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level1.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Caching/cache-level1.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level1.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level2.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Caching/cache-level2.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level2.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level3.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Caching/cache-level3.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/cache-level3.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Caching/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,119 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Understanding Caching</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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 Caching</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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</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/Understanding Caching/index.html">Understanding Caching</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne implements an advanced caching mechanism that has a goal of improving application performance and ensuring data consistency both across Java applications and sessions within the same application. The following classes participate in the caching mechanism:</p>
+
+<ul>
+ <li><b>DataObject</b><br/>
+ Any persistent object; tracks the version of snapshot it was last updated with.</li>
+ <li><b>DataRow</b><br/>
+ Immutable snapshot of a database row. Has a VM-unique version identifier.</li>
+ <li><b>ObjectStore</b><br/>
+ Stores DataObjects using ObjectIds as keys.</li>
+ <li><b>DataRowStore</b><br/>
+ Stores snapshots as DataRows using ObjectIds as keys.</li>
+</ul>
+
+
+
+<h3><a name="UnderstandingCaching-LevelsofCaching"></a>Levels of Caching</h3>
+
+<p>Cayenne implements the following levels of caching:</p>
+
+<ul>
+ <li><b>Level 1 - No Cache Sharing</b><br/>
+ The DataContext keeps its own cache - data fetched from the database via a given DataContext is never shared with other local or remote DataContexts. Changes made on commit are not propagated to other DataContexts.<br/>
+ <img src="cache-level1.gif" align="absmiddle" border="0" /></li>
+ <li><b>Level 2 - Local VM Cache Sharing</b><br/>
+ Each DataDomain keeps the cache shared by all DataContexts in the same VM. Changes made via one of the DataContexts are propagated via a SnapshotEvent to other DataContexts in the same VM.<br/>
+ <img src="cache-level2.gif" align="absmiddle" border="0" /></li>
+ <li><b>Level 3 - Cross-VM Cache Sharing</b><br/>
+ Behaves just like Level 2, but also synchronizes caches across JVMs. SnapshotEvents are sent remotely via a preconfigured transport mechanism. Notification channels use the DataDomain name to identify which remote domains should receive the event.<br/>
+ <img src="cache-level3.gif" align="absmiddle" border="0" /></li>
+</ul>
+
+
+<p>Caching properties are configured using CayenneModeler for each application DataDomain. Application code is normally independent from a chosen level, i.e., it does not have to be changed when caching is reconfigured. Details on caching configuration are provided in the <a href="../../../../Documentation/Modeler Guide/Configuring Deployment Settings/Configuring Caching Behavior/index.html" title="Configuring Caching Behavior">Modeler Guide</a>.</p>
+
+<h3><a name="UnderstandingCaching-SynchronizingObjectStoresusingSnapshotEvents."></a>Synchronizing ObjectStores using SnapshotEvents.</h3>
+
+<p>DataRowStore posts SnapshotEvents for any changes made to the cache. ObjectStore(s) using a given DataRowStore are automatically registered as listeners for SnapshotEvents and update their state accordingly. Application objects can also take advantage of the events by implementing SnapshotEventListener interface and registering with EventManager</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">SnapshotEventListener customListener = ...
+
+DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+DataRowStore cache = domain.getSharedSnapshotCache();
+domain.getEventManager().addListener(
+ customListener,
+ <span class="code-quote">"snapshotsChanged"</span>,
+ SnapshotEvent.class,
+ cache.getSnapshotEventSubject());</pre>
+</div></div>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='noteMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Upgrading to Cayenne 1.2 and Newer</b><br /> Cayenne 1.1 used a singleton EventManager accessible via <tt>EventManager.getDefaultManager()</tt>. Note that now EventManager is obtained from DataDomain or DataContext. Make sure that you register your listeners with an appropriate EventManager.</td></tr></table>
+
+
+<h3><a name="UnderstandingCaching-ConcurrentUpdatesoftheSameDataObject."></a>Concurrent Updates of the Same DataObject.</h3>
+
+<p>If two or more users update their local copies of the same object, Cayenne implements the following behavior:</p>
+
+<ul>
+ <li>Whenever a local modification of an object is detected, its snapshot is "retained" by ObjectStore, so that any changes to the underlying DataRowStore could not affect modification process of this object.</li>
+ <li>On commit, an UPDATE query is built based on retained snapshot, not the one currently cached in DataRowStore (this may or may not be the same DataRow). If the changes were made to a different set of attributes, this allows concurrent modification of the same object by different users without overwriting each other's changes.</li>
+ <li>Due to concurrency issues discussed above, if a snapshot version conflict occurs, DataRowStore removes a given snapshot from the cache to avoid dealing with concurrency effects on merging.</li>
+</ul>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Caching/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Transactions/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,187 @@
+<html>
+ <head>
+ <title>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://objectstyle.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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</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/Understanding Caching/index.html">Understanding Caching</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</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.objectstyle.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.jpg" 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.objectstyle.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.objectstyle.cayenne.DataChannel</tt>.</li>
+ <li>The request travels the chain of DataChannels until it reaches one that is a <tt>org.objectstyle.cayenne.access.DataDomain</tt>.</li>
+ <li>DataDomain analyzes context request and dispatches data queries to one or more <tt>org.objectstyle.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.objectstyle.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.objectstyle.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 ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/transactions-types.jpg
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/Understanding%20Transactions/transactions-types.jpg?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/Understanding Transactions/transactions-types.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Design/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,55 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Design</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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/Access Classes/index.html">Access Classes</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Cayenne DataSource/index.html">Cayenne DataSource</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Cross-Database Issues/index.html">Cross-Database Issues</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Data Objects/index.html">Data Objects</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Event Package/index.html">Event Package</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Generated Columns/index.html">Generated Columns</a></li>
+<li><a href="../../../Documentation/User Guide/Design/How Information Is Stored in Cayenne/index.html">How Information Is Stored in Cayenne</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Object Graph/index.html">Object Graph</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Object Relational Mapping/index.html">Object Relational Mapping</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/Understanding Caching/index.html">Understanding Caching</a></li>
+<li><a href="../../../Documentation/User Guide/Design/Understanding Transactions/index.html">Understanding Transactions</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</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></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>This chapter describes design ideas and the architecture of Cayenne. It is not required to start using Cayenne and there is no hands-on information here, so new users can skip it initially and come back later to gain better understanding of how Cayenne operates under the hood.</p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Design/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Building Expressions/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Expressions/Building%20Expressions/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Building Expressions/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Building Expressions/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,195 @@
+<html>
+ <head>
+ <title>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://objectstyle.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/Generating Classes/index.html">Generating Classes</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/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/In-Memory Evaluation/index.html">In-Memory Evaluation</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/NULL Handling/index.html">NULL Handling</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Path Expressions/index.html">Path Expressions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</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.objectstyle.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://www.objectstyle.org/cayenne/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 < 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 – 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 ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Building Expressions/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Expression Factory Utilities/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Expressions/Expression%20Factory%20Utilities/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Expression Factory Utilities/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Expression Factory Utilities/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,140 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Expression Factory Utilities</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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">Expression Factory Utilities</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/Generating Classes/index.html">Generating Classes</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/Building Expressions/index.html">Building Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Expression Factory Utilities/index.html">Expression Factory Utilities</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Expressions/In-Memory Evaluation/index.html">In-Memory Evaluation</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/NULL Handling/index.html">NULL Handling</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Path Expressions/index.html">Path Expressions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</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://objectstyle.org/cayenne/api/cayenne/org/objectstyle/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://objectstyle.org/cayenne/api/cayenne/org/objectstyle/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>
+
+<h3><a name="ExpressionFactoryUtilities-Path%2FValueExpressions"></a>Path/Value Expressions</h3>
+
+<p>The most simple expressions are the ones that match an object property path with a value or a list of values. ExpressionFactory provides a set of methods to build such "path/value" expressions:</p>
+<ul>
+ <li>public static Expression <b>matchExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>noMatchExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>matchDbExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>lessExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>lessOrEqualExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>greaterExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>greaterOrEqualExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>inExp</b>(String pathSpec, Object[] values)</li>
+ <li>public static Expression <b>inExp</b>(String pathSpec, java.util.List values)</li>
+ <li>public static Expression <b>betweenExp</b>(String pathSpec, Object value1, Object value2)</li>
+ <li>public static Expression <b>likeExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>likeIgnoreCaseExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>notInExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>notBetweenExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>notLikeExp</b>(String pathSpec, Object value)</li>
+ <li>public static Expression <b>notLikeIgnoreCaseExp</b>(String pathSpec, Object value)</li>
+</ul>
+
+
+<p>As was mentioned <a href="../../../../Documentation/User 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">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.exp.Expression;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.exp.ExpressionFactory;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.query.SelectQuery;
+...
+
+<span class="code-comment">// find artist paintings (<span class="code-keyword">if</span> we don't want to use relationship <span class="code-keyword">for</span> whatever reason)
+</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>
+</div></div>
+
+<h3><a name="ExpressionFactoryUtilities-ChainingExpressions"></a>Chaining Expressions</h3>
+
+<p>Expression class itself provides a set of convenience methods to chain expressions as they are built from smaller parts. Note that each of these methods does not modify the original expression, rather it builds and returns a new instance of the expression.</p>
+<ul>
+ <li>public Expression <b>joinExp</b>(int type, Expression exp)<br/>
+ Creates and returns a new expression that joins this object with another expression, using specified join type. This is a shorter equivalent of ExpressionFactory.binaryExpression(type, this, exp).</li>
+ <li>public Expression <b>andExp</b>(Expression exp)<br/>
+ A shorter equivalent for joinExp(Expression.AND, exp).</li>
+ <li>public Expression <b>orExp</b>(Expression exp)<br/>
+ A shorter equivalent for joinExp(Expression.OR, exp).</li>
+</ul>
+
+
+<p>Example of using chaining:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.exp.Expression;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.exp.ExpressionFactory;
+<span class="code-keyword">import</span> org.objectstyle.cayenne.query.SelectQuery;
+...
+
+<span class="code-comment">// find artists whose name starts with <span class="code-quote">"D"</span>
+</span><span class="code-comment">// with invalid or <span class="code-keyword">null</span> date of birth
+</span>
+Expression qual = ExpressionFactory.greaterOrEqualExp(<span class="code-quote">"dateOfBirth"</span>, <span class="code-keyword">new</span> Date());
+
+<span class="code-comment">// 1. chain expressions, note the assignment back to <span class="code-quote">"qual"</span>,
+</span><span class="code-comment">// since a <span class="code-keyword">new</span> instance is created
+</span>qual = qual.orExp(ExpressionFactory.matchExp(<span class="code-quote">"dateOfBirth"</span>, <span class="code-keyword">null</span>));
+
+<span class="code-comment">// 2. <span class="code-quote">"AND"</span> applies to a combined earlier criteria
+</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>
+</div></div>
+
+<h3><a name="ExpressionFactoryUtilities-CreatingComplexExpressions"></a>Creating Complex Expressions</h3>
+
+<p>There is a way to create complex expressions either from the Lists of expressions or from the Maps containing values using "path" Strings as keys. This approach significantly simplifies connecting Cayenne queries to the UI, and reduces the number of steps needed to create expressions in other cases. ExpressionFactory provides the following methods:</p>
+<ul>
+ <li>public static Expression <b>joinExp</b>(int type, java.util.List expressions)<br/>
+ Joins all expressions into a single expression. type is used as an expression type for expressions joining each one of the items on the list. type is normally AND or OR.</li>
+ <li>public static Expression <b>matchAllExp</b>(java.util.Map map, int type)<br/>
+ Creates an expression that matches all path/value pairs in map. Path is OBJ_PATH.</li>
+ <li>public static Expression <b>matchAllDbExp</b>(java.util.Map map, int type)<br/>
+ Same as above, but path is interpreted to be DB_PATH.</li>
+ <li>public static Expression <b>matchAnyExp</b>(java.util.Map map, int type)<br/>
+ Creates an expression that matches any of the path/value pairs in map. Path is OBJ_PATH.</li>
+ <li>public static Expression <b>matchAnyDbExp</b>(java.util.Map map, int type)<br/>
+ Same as above, but path is interpreted to be DB_PATH.</li>
+</ul>
+</div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/Expression Factory Utilities/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/In-Memory Evaluation/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Expressions/In-Memory%20Evaluation/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/In-Memory Evaluation/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/In-Memory Evaluation/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,100 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - In-Memory Evaluation</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.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">In-Memory Evaluation</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/Generating Classes/index.html">Generating Classes</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/Building Expressions/index.html">Building Expressions</a></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/In-Memory Evaluation/index.html">In-Memory Evaluation</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Expressions/NULL Handling/index.html">NULL Handling</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/Path Expressions/index.html">Path Expressions</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</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/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>In additions to providing a database-independent WHERE clause for SQL queries, expressions support in-memory evaluation. An expressions can be evaluated with any type of objects that follow Java Beans method naming convention. Of course this includes DataObjects. The following API is used for expressions evaluation:</p>
+
+<ul>
+ <li>public Object <b>evaluate</b>(Object object)<br/>
+ Evaluates expression with object, returning the result.</li>
+ <li>public boolean <b>match</b>(Object object)<br/>
+ Returns true if an object "matches" expression criteria.</li>
+ <li>public java.util.List <b>filterObjects</b>(java.util.List objects)<br/>
+ Returns a list of objects from the original list that match expression criteria.</li>
+</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>
+
+<p>Here is an example of evaluating expression with a single object:</p>
+
+<div class="code"><div class="codeContent">
+<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() {
+ ...
+ }
+}
+...
+<span class="code-keyword">public</span> class NonPersistentUser <span class="code-keyword">extends</span> <span class="code-object">Object</span> {
+ <span class="code-keyword">protected</span> <span class="code-object">String</span> name;
+ <span class="code-keyword">public</span> <span class="code-object">String</span> getName() {
+ <span class="code-keyword">return</span> name;
+ }
+ ...
+}
+...
+Expression exp = ExpressionFactory.inExp(<span class="code-quote">"name"</span>, <span class="code-keyword">new</span> <span class="code-object">Object</span>[] {<span class="code-quote">"John"</span>, <span class="code-quote">"Bob"</span>});
+User persistentObject;
+NonPersistentUser nonPersistentBean;
+...
+<span class="code-comment">// evaluate with DataObject
+</span><span class="code-keyword">if</span>(exp.match(persistentObject)) {
+ <span class="code-comment">// <span class="code-keyword">do</span> something
+</span>}
+
+<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>
+</div></div>
+
+<p>Another example - using expression to filter a list objects:</p>
+
+<div class="code"><div class="codeContent">
+<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>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Expressions/In-Memory Evaluation/index.html
------------------------------------------------------------------------------
svn:eol-style = native