cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r488202 [11/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/Deployment/Web Applications/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Deployment/Web%20Applications/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Deployment/Web Applications/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Deployment/Web Applications/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,141 @@
+<!--
+   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 - Web Applications</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">Web Applications</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></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><ul>
+<li><a href="../../../../Documentation/User Guide/Deployment/Standalone Applications/index.html">Standalone Applications</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Web Applications/index.html">Web Applications</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Customizing Configuration/index.html">Customizing Configuration</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/DBCPDataSourceFactory/index.html">DBCPDataSourceFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Using JNDI/index.html">Using JNDI</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Deployment with Ant/index.html">Deployment with Ant</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Configuring Logging/index.html">Configuring Logging</a></li>
+</ul>
+</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="WebApplications-PuttingCayenneFilesinWebApplicationCLASSPATH"></a>Putting Cayenne Files in Web Application CLASSPATH</h3>
+
+<p>When deploying an application in a web container it is possible to follow the procedure for the standalone applications, i.e. put all XML files in the application CLASSPATH (e.g. in "mywebapp/WEB-INF/classes/", but DON'T put it in container shared locations!). Session DataContext can be obtained via ServletUtil:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">HttpSession session = ...;
+DataContext context = ServletUtil.getSessionContext(session);</pre>
+</div></div>
+
+<p>However you may consider a deployment procedure described below, as it provides more flexibility and a number of additional useful features.</p>
+
+<h3><a name="WebApplications-CayenneServletFilter"></a>Cayenne Servlet Filter</h3>
+
+<p>Adding the following filter to the <tt>web.xml</tt> would automate Cayenne setup in the web application:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>&lt;filter&gt;
+    &lt;filter-name&gt;CayenneFilter&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.apache.cayenne.conf.WebApplicationContextFilter&lt;/filter-class&gt;
+&lt;/filter&gt;
+&lt;filter-mapping&gt;
+    &lt;filter-name&gt;CayenneFilter&lt;/filter-name&gt;
+    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+&lt;/filter-mapping&gt;
+</pre>
+</div></div>
+
+<p>The filter will ensure that for each matching request a DataContext is bound to the request thread. So you can retrieve it anywhere in the application, even if you don't have a reference to the web environment:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = DataContext.getThreadDataContext();</pre>
+</div></div>
+
+<p>Filter can match a specific URL as shown above, or a specific servlet:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>&lt;servlet&gt;
+   &lt;servlet-name&gt;MyServlet&lt;/servlet-name&gt;
+   &lt;servlet-class&gt;org.example.MyServlet&lt;/servlet-class&gt;
+   &lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
+&lt;/servlet&gt;
+		
+&lt;filter&gt;
+    &lt;filter-name&gt;CayenneFilter&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.apache.cayenne.conf.WebApplicationContextFilter&lt;/filter-class&gt;
+&lt;/filter&gt;
+&lt;filter-mapping&gt;
+    &lt;filter-name&gt;CayenneFilter&lt;/filter-name&gt;
+    &lt;servlet-name&gt;MyServlet&lt;/servlet-name&gt;
+&lt;/filter-mapping&gt;</pre>
+</div></div>
+
+
+<p>Additionally the filter supports putting files in <tt>myapp/WEB-INF/</tt> directory instead of the CLASSPATH, so a .war file may look like this:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>index.jsp
+WEB-INF/cayenne.xml
+WEB-INF/xyz.map.xml
+WEB-INF/lib/...</pre>
+</div></div>
+
+<p>Actually, Cayenne files can be stored in any subdirectory of <tt>myapp/WEB-INF/</tt>. To specify a subdirectory, you'll need to add <tt>&lt;context-param&gt;</tt> named <tt>cayenne.configuration.path</tt> to your application descriptor:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>&lt;context-param&gt;
+    &lt;param-name&gt;cayenne.configuration.path&lt;/param-name&gt;
+    &lt;param-value&gt;/WEB-INF/config/cayenne-files&lt;/param-value&gt;
+&lt;/context-param&gt;</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/Deployment/Web Applications/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Deployment/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Deployment/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Deployment/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Deployment/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 - Deployment</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">Deployment</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></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><ul>
+<li><a href="../../../Documentation/User Guide/Deployment/Standalone Applications/index.html">Standalone Applications</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/Web Applications/index.html">Web Applications</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/Customizing Configuration/index.html">Customizing Configuration</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/DBCPDataSourceFactory/index.html">DBCPDataSourceFactory</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/Using JNDI/index.html">Using JNDI</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/Deployment with Ant/index.html">Deployment with Ant</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/Configuring Logging/index.html">Configuring Logging</a></li>
+</ul>
+</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 application deployment is about configuring the application so that at runtime it can find a main project file (cayenne.xml) and associated resources, such as DataMap and DataNode XML files.</p>
+
+<p>The central point in Cayenne deployment is the <span class="nobr"><a href="http://incubator.apache.org/cayenne/2_0/api/cayenne/org/apache/cayenne/conf/Configuration.html" title="Visit page outside Confluence" rel="nofollow">Configuration<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> class. It locates and loads all the mapping and configuration information required for Cayenne at runtime. By default Configuration uses a singleton model, i.e. normally there is only one instance of Configuration (or a subclass) that exists in the application. This shared instance can be accessed in the following way:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.conf.Configuration;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataDomain;
+...
+Configuration conf = Configuration.getSharedConfiguration();
+DataDomain domain = conf.getDomain();</pre>
+</div></div>
+<p>As discussed in the following chapters Configuration works behind the scenes and users rarely care about it. Application code is normally only concered with obtaining a DataContext.</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/Deployment/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Cayenne Contract/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Cayenne%20Contract/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Cayenne Contract/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Cayenne Contract/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,168 @@
+<!--
+   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 - Cayenne Contract</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">Cayenne Contract</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><ul>
+</ul>
+</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>There is an implied contract between persistent objects and Cayenne runtime. Cayenne expects persistent objects to follow certain conventions, while itself providing management of the various aspects of a persistent object graph.</p>
+
+<h2><a name="CayenneContract-PerstentObjectRequirements"></a>Perstent Object Requirements</h2>
+
+<h3><a name="CayenneContract-PersistentInterfaces"></a>Persistent Interfaces</h3>
+
+<p>Cayenne can persist Java objects that implement <tt>org.apache.cayenne.Persistent</tt> interface. The interface requires for an object to provide getters and setters for three bean properties: <tt>objectId</tt>, <a href="../../../../Documentation/User Guide/Design/Persistent Object Lifecycle/index.html" title="Persistent Object Lifecycle"><tt>persistenceState</tt></a> and <tt>objectContext</tt>:</p>
+
+<div class="code"><div class="codeHeader"><b>Persistent.java</b></div><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Persistent <span class="code-keyword">extends</span> Serializable {
+    ObjectId getObjectId();
+
+    void setObjectId(ObjectId id);
+
+    <span class="code-object">int</span> getPersistenceState();
+
+    void setPersistenceState(<span class="code-object">int</span> state);
+
+    ObjectContext getObjectContext();
+
+    void setObjectContext(ObjectContext objectContext);
+}</pre>
+</div></div>
+
+<p>Furthermore the most commonly used implementation of <a href="../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html" title="ObjectContext">ObjectContext</a> - <a href="../../../../Documentation/User Guide/DataContext/index.html" title="DataContext">DataContext</a> - requires a more complicated subinterface of Persistent - <tt>org.apache.cayenne.DataObject</tt>, that specifies generic methods for property access. The easiest way to satisfy these requirements is by using class generation mechanism provided by Cayenne (using <a href="../../../../Documentation/User Guide/Ant Tasks/cgen/index.html" title="cgen">cgen</a> Ant task or <a href="../../../../Documentation/Modeler Guide/Common Modeling Tasks/Generate Java Classes/index.html" title="Generate Java Classes">CayenneModeler UI</a>). </p>
+
+<p>It is worth noting that both requirements will likely become optional in the future releases, being substituted with reflection, bytecode enhancements and other such techniques. Still it is important to understand both benefits and shortcomings of the persistent interface requirement. </p>
+
+<p>The obvious (and only) shortcoming is that the users have to implement it, most often using a class generation template that relies on a framework superclass (such as <tt>org.apache.cayenne.CayenneDataObject</tt>). This may somewhat limit the flexibility of the application design.</p>
+
+<p>In returns users (and Cayenne framework internally) get extra capabilities:</p>
+
+<ul>
+	<li>Fast and consistent mechanism for the framework to inspect, cache, manipulate the objects.</li>
+	<li>Meaningless primary key doesn't have to be an object property.</li>
+	<li>An object always knows its context, and thus can access the database from its business logic methods without any external context.</li>
+	<li>An object always knows how its state compares to the state of the backing database row, and can implement logic based on that knowledge (e.g. objects that are modified, but not yet committed, can be shown in a different color in the user interface).</li>
+	<li>DataObject interface makes possible <a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html" title="Generic Persistent Class">generic persistent objects</a>, i.e. the same generic class can map to more than one entity, and persistent behavior can be defined dynamically in runtime.</li>
+</ul>
+
+
+<h3><a name="CayenneContract-PropertyAccessors"></a>Property Accessors</h3>
+
+<p>Another convention, that is not required strictly speaking, but is almost always implemented by persistent objects is invoking a callback method on their enclosing context before reading or setting their properties. Intercepting property accessors enables lazy on-demand resolution of objects and their relationships and also automatic bidirectional relationships, as discussed below. As with Persistent interface, property interception code is usually created via class generation.</p>
+
+
+<h2><a name="CayenneContract-HandlingPersistentObjects"></a>Handling Persistent Objects</h2>
+
+<p>Cayenne part of the "persistence contract" is the services it provides, including persistence per se and persistence-related object graph management capabilities.</p>
+
+<h3><a name="CayenneContract-QueryCapabilities"></a>Query Capabilities</h3>
+
+<p>Queries can be executed, bringing back objects matching certain criteria. As a part of this procedure, persistent objects are created and inflated with database values.</p>
+
+<h3><a name="CayenneContract-SingleMethodCallCommitandRollback"></a>Single Method Call Commit and Rollback</h3>
+
+<p>Multiple persistent object changes can be committed with a single method call (and in a single transaction). Similarly, object graph changes made since last commit can be discarded with a single method call.</p>
+
+<h3><a name="CayenneContract-MultipleLevelsofCommitandRollbackNesting"></a>Multiple Levels of Commit and Rollback Nesting</h3>
+
+<p>Commit and rollback functionality can have <a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html" title="Nested DataContexts">multiple levels of nesting</a> (i.e. a context can rollback its changes without affecting the parent context; or commit its changes to parent without committing them all the way to the database). </p>
+
+<h3><a name="CayenneContract-Relationships"></a>Relationships</h3>
+
+<p>Relationship support - objects related to the previously fetched objects can be accessed via a simple method call. Cayenne will do whatever is necessary to resolve related objects at the right moment behind the scenes. </p>
+
+<p>Unless the user <a href="../../../../Documentation/User Guide/Performance Tuning/Prefetching/index.html" title="Prefetching">specifies otherwise</a> in the query that fetched the initial objects, relationships are not fetched together with the objects. When a user requests a related object (or collection of objects), Cayenne ensures that the actual database query to read it is deferred as much as possible, so hopefully there won't be a need to do it at all. E.g. a to-many relationship is resolved only when a list is queried for its size, or a user tries to access one of the elements.</p>
+
+<h3><a name="CayenneContract-AutomaticBidirectionalRelationshipManagemenet"></a>Automatic Bi-directional Relationship Managemenet</h3>
+
+<p>If entity A has a relationship to entity B and entity B has a relationshop back to entity A, Cayenne would maintain consistency of the reverse relationship automatically. Consider this example of a many-to-one relationship, written in a form of a unit test:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">A a1;
+B b1;
+B b2;
+
+a1.setB(b1);
+assertTrue(b1.getListOfA().contains(a1));
+
+a1.setB(b2);
+assertTrue(b2.getListOfA().contains(a1));
+assertFalse(b1.getListOfA().contains(a1));</pre>
+</div></div>
+
+<p>This significantly simplifies coding and reduces possibility of errors in managing complex object graphs.</p>
+
+<h3><a name="CayenneContract-ContextInjection"></a>Context Injection</h3>
+
+<p>Cayenne framework injects all three properties defined in <tt>Persistent</tt> interface - <tt>objectId</tt>, <tt>persistenceState</tt> and <tt>objectContext</tt> - at the right moments in the lifecycle. It automatically maintans persistence state changes when an object undergoes state transformations.</p>
+
+<h3><a name="CayenneContract-Uniquing"></a>Uniquing</h3>
+
+<p>Cayenne ensures that each <a href="../../../../Documentation/User Guide/Design/Runtime Components/ObjectContext/index.html" title="ObjectContext">ObjectContext</a> contains at most one instance of each <b>unique</b> persistent object. In other words if two separate independent queries fetched a row with the same primary key, the same object instance will be used in both results. This behavior (not supported by some other frameworks), is extremely important in maintaining consistency of the object graph.</p>
+
+<h3><a name="CayenneContract-LazyObjectResolution"></a>Lazy Object Resolution</h3>
+
+<p>One of the object states is HOLLOW, corresponding to unresolved objects that only have their PK known. Most often HOLLOW objects are returned from to-one relationships. Whenever such object is "touched" by the user (i.e. a  setter or a getter is invoked), Cayenne automatically infaltes it with the database values.</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/Cayenne Contract/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

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

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/cache-level1.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

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

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/cache-level2.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

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

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/cache-level3.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Object%20Caching/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Object Caching/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,134 @@
+<!--
+   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 - Object Caching</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">Object 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/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><ul>
+</ul>
+</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 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="ObjectCaching-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="ObjectCaching-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="ObjectCaching-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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

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

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Persistent Object Lifecycle/fetched-persistent-object.png
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Persistent%20Object%20Lifecycle/fetched-persistent-object.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/Persistent Object Lifecycle/fetched-persistent-object.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Persistent Object Lifecycle/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Persistent%20Object%20Lifecycle/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Persistent Object Lifecycle/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Persistent Object Lifecycle/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,80 @@
+<!--
+   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 - Persistent Object Lifecycle</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">Persistent Object Lifecycle</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><ul>
+</ul>
+</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>A lifecycle of a persistent object can be represented as a number of states and transitions between them. These states are formally defined as "int" constants in <tt>org.apache.cayenne.PersistenceState</tt> class. Transitions between states (see the diagram below) occur in response to the application interacting with either persistent objects or Cayenne context. Whenever a transition occurs, Cayenne automatically updates "persistenceState" property of all affected objects by calling <tt>setPersistenceState()</tt>.</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
+<td class="confluenceTd"  valign="top">
+<p>A new object state transformations:<br/>
+<img src="new-persistent-object.png" align="absmiddle" border="0" /></p></td>
+
+<td class="confluenceTd"  valign="top">
+<p>A feteched or committed object state transformations:<br/>
+<img src="fetched-persistent-object.png" align="absmiddle" border="0" /></p></td></tr></tbody></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/Persistent Object Lifecycle/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Persistent Object Lifecycle/new-persistent-object.png
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Persistent%20Object%20Lifecycle/new-persistent-object.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/Persistent Object Lifecycle/new-persistent-object.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Primary%20Key%20Generation/Generated%20Columns/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,121 @@
+<!--
+   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 - Generated Columns</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">Generated Columns</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><ul>
+<li><a href="../../../../../Documentation/User Guide/Design/Primary Key Generation/Generated Columns/index.html">Generated Columns</a><ul>
+</ul>
+</li>
+</ul>
+</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">
+<h2><a name="GeneratedColumns-WhatIsa%22Generated%22Column"></a>What Is a "Generated" Column</h2>
+
+<p>Many databases allow users to define special columns with values that are automatically created by the the database to be unique for each inserted row. Main use if this feature is to generate a primary key. Such columns are often called <b>"autoincrement"</b> or <b>"identity"</b> columns. JDBC3 specification provides Java API to read values of such columns right after an insert is performed. JDBC calls such columns <b>"generated keys"</b>, and Cayenne follows JDBC in that. Namely DbAttribute has a <tt>"generated"</tt> boolean property to indicate that a given column value is provided by the database on insert.</p>
+
+<h2><a name="GeneratedColumns-GeneratedColumnsinCayenne"></a>Generated Columns in Cayenne </h2>
+
+<p>Primary key generation is the only use of generated columns in Cayenne.</p>
+
+<p>If a primary key column is marked as "generated" in CayenneModeler (see below), Cayenne will bypass its default PK generation mechanism and rely on the database to provide a key value. But only if the runtime DbAdapter is configured to allow that (see "Hints and Limitations" section for explanation). Currently only Derby, MySQL and SQLServer adapters allow generated columns by default. For the rest of the adapters, Cayenne will fall back to its default PK generation mechanism.</p>
+
+<p>If you know that your driver supports generated keys API, but Cayenne assumes it does not, you can change this setting manually:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataNode node = ...
+JdbcAdapter adapter = (JdbcAdapter) node.getAdapter();
+adapter.setSupportsGeneratedKeys(<span class="code-keyword">true</span>);</pre>
+</div></div>
+
+<p>Use of generated keys for PK is configured for each DbEntity individually in CayenneModeler:</p>
+
+<ul>
+	<li>Navigate to a DbEntity in question and select <tt>"PK Generation Strategy"</tt> to be <tt>"Database-Generated"</tt>:</li>
+</ul>
+
+
+<p><img src="select_db_key1.jpg" align="absmiddle" border="0" /></p>
+
+
+<ul>
+	<li>Select a PK column that will be auto-incremented by the database from the list of existing primary keys:</li>
+</ul>
+
+
+<p><img src="select_db_key2.jpg" align="absmiddle" border="0" /></p>
+
+<h2><a name="GeneratedColumns-HintsandLimitations"></a>Hints and Limitations</h2>
+
+<ul>
+	<li>Only a single DbAttribute can be marked as "generated" in a DbEntity. Most databases only allow a single generated column per table, and Cayenne consistently adheres to the same policy.</li>
+	<li>Generated attribute must also be a primary key.</li>
+	<li>Database must support this feature.</li>
+	<li>JDBC driver must support this feature. Even if database supports identity columns, the driver may not. By default Cayenne assumes that the following drivers support it: Derby, MySQL and SQLServer jTDS (but not the MS) driver.</li>
+</ul>
+
+
+<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">MS SQLServer Note</b><br /><br/>
+MS drivers prior to 2005 version do not support generated columns, while newer drivers and <span class="nobr"><a href="http://jtds.sourceforge.net" title="Visit page outside Confluence" rel="nofollow">jTDS<sup><img class="rendericon" src="../../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> support it just fine. Cayenne can automatically detect the driver type and configure SQLServerAdapter, but only when AutoAdapter is used. To make sure auto-detection works, clear the "Custom Adapter" field for the corresponding DataNode in the Modeler.</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/Primary Key Generation/Generated Columns/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/select_db_key1.jpg
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Primary%20Key%20Generation/Generated%20Columns/select_db_key1.jpg?view=auto&rev=488202
==============================================================================
Binary file - no diff available.

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/select_db_key1.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/select_db_key2.jpg
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Primary%20Key%20Generation/Generated%20Columns/select_db_key2.jpg?view=auto&rev=488202
==============================================================================
Binary file - no diff available.

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/Generated Columns/select_db_key2.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Primary%20Key%20Generation/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Primary Key Generation/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,137 @@
+<!--
+   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 - Primary Key Generation</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">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/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><ul>
+<li><a href="../../../../Documentation/User Guide/Design/Primary Key Generation/Generated Columns/index.html">Generated Columns</a></li>
+</ul>
+</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>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'>&nbsp;</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 &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

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

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataChannel/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/DataChannel/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataChannel/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataChannel/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,102 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - DataChannel</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">DataChannel</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><ul>
+</ul>
+</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.DataChannel"</tt> is an abstraction of Cayenne persistence stack. It is very simple - it defines only 4 methods, two for actually performing persistent operations, one to access metadata, and one - to access EventManager:</p>
+
+<div class="code"><div class="codeHeader"><b>DataChannel.java</b></div><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> DataChannel {
+
+    QueryResponse onQuery(ObjectContext originatingContext, Query query);
+
+    GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, <span class="code-object">int</span> syncType);
+
+    EventManager getEventManager();
+
+    EntityResolver getEntityResolver();
+}</pre>
+</div></div>
+
+<p>DataChannel is rarely used by the application directly. Instead ObjectContexts use it internally as an abstract persistent store. There are few kinds of DataChannels in Cayenne:</p>
+
+<ul>
+	<li>DataDomain (the most commonly used DataChannel) connects to one or more databases via DataNodes.</li>
+	<li>DataContext can serve as a DataChannel for other DataContexts</li>
+	<li>ClientChannel is a DataChannel that connects to a remote Cayenne service.</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/DataChannel/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataNode/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Design/Runtime%20Components/DataNode/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataNode/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Design/Runtime Components/DataNode/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 - DataNode</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">DataNode</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><ul>
+</ul>
+</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>DataNode is a Cayenne "driver" for a single physical data source, such as a relational database. In fact currently DataNode only handles JDBC sources (so maybe it should be renamed to JdbcDataNode?). </p>
+
+<p>DataNode doesn't do much work on its own, instead delegating most tasks to <tt>"org.apache.cayenne.action.SQLAction"</tt> instances returned by <a href="../../../../../Documentation/User Guide/Design/Runtime Components/DbAdapter/index.html" title="DbAdapter">DbAdapter</a>.</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/DataNode/index.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message