cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r488202 [8/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/DataContext/DataObject State Management/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/DataObject%20State%20Management/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataObject State Management/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataObject State Management/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,196 @@
+<!--
+   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 - DataObject State Management</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">DataObject State Management</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+</ul>
+</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>Arguably the second most important function of DataContext (first is performing queries) is keeping track of changes made to the registered DataObjects. "Registered" is a keyword here - registering an object with DataContext is what gives this object its persistent qualities.</p>
+
+<h3><a name="DataObjectStateManagement-HowtoRegisteraDataObject"></a>How to Register a DataObject</h3>
+
+<p>Behind the scenes "registering an object" results in storing this object in a map using its ObjectId as a key, setting "dataContext" property of a DataObject to the current DataContext, and taking a snapshot of all persistent properties to be able to track later modifications. Objects can become "registered" in two ways:</p>
+
+<ul>
+	<li>automatically when they are fetched via query API</li>
+	<li>explicitly for the newly created objects</li>
+</ul>
+
+
+<p>Whenever a selecting query is executed by a DataContext, all fetched objects are automatically registered with this DataContext. On the other hand, newly created objects must be registered explicitly:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+Artist artist = <span class="code-keyword">new</span> Artist();
+context.registerNewObject(artist);
+
+<span class="code-comment">// after the line above is executed, artist object acquired <span class="code-quote">"persistent"</span> behavior
+</span><span class="code-comment">// and is said to be <span class="code-quote">"managed"</span> by DataContext</span></pre>
+</div></div>
+
+<p>This code can be simplified - object creation and registrations steps can be combined in one method call:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+Artist artist = (Artist) context.newObject(Artist.class);</pre>
+</div></div>
+
+<p>This method relies on the presence of a no-argument constructor in the DataObject class.</p>
+
+<h3><a name="DataObjectStateManagement-CheckingtheStateofRegisteredDataObjects"></a>Checking the State of Registered DataObjects</h3>
+
+<p>State transitions of DataObjects from persistence point of view are discussed in the "Design" chapter. State of each individual object is described by an integer constant obtained via a call to DataObject.getPeristenceState(). Allowed states are defined as static variables in PersistenceState class.</p>
+
+<p>When a new object is inserted to the DataContext as described above, it becomes "NEW":</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// artist will become PersistenceState.NEW
+</span>Artist artist = (Artist) context.newObject(Artist.class);</pre>
+</div></div>
+
+<p>When a DataContext is committed, such object becomes "COMMITTED":</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// artist will become PersistenceState.COMMITTED
+</span>context.commitChanges();</pre>
+</div></div>
+
+<p>When any of the attributes or relationships of the fetched or committed object are changed, such an object becomes MODIFIED:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// <span class="code-keyword">this</span> will change the object state to PersistenceState.MODIFIED
+</span>artist.setName(<span class="code-quote">"NewName"</span>);</pre>
+</div></div>
+
+<p>When a fetched or committed object is explicitly deleted from the DataContext, object becomes DELETED:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// <span class="code-keyword">this</span> will change the object state to PersistenceState.DELETED
+</span>context.deleteObject(artist);</pre>
+</div></div>
+
+<p>DataContext is said to have changes if it has one or more registered objects in a state PersistenceState.MODIFIED, PersistenceState.NEW or PersistenceState.DELETED. DataContext provides the following method to check if it has any changed objects:</p>
+
+<ul>
+	<li><tt>public boolean hasChanges()</tt></li>
+</ul>
+
+
+<p>There is also a way to obtain a list of changed objects in each one of the above states:</p>
+
+<ul>
+	<li><tt>public java.util.Collection newObjects()</tt></li>
+	<li><tt>public java.util.Collection deletedObjects()</tt></li>
+	<li><tt>public java.util.Collection modifiedObjects()</tt></li>
+</ul>
+
+
+<h3><a name="DataObjectStateManagement-SavingAllUncommittedDataObjects"></a>Saving All Uncommitted DataObjects</h3>
+
+<p>All of the uncommitted objects ("uncommitted" means "new", "modified" or "deleted") are saved ("committed") to the database with a single method call on the DataContext:</p>
+
+<ul>
+	<li><tt>public void commitChanges()</tt></li>
+</ul>
+
+
+<p>Method commitChanges takes care of building correct SQL statements, generating primary keys and transactional behaviour. It roughly follows this scenario:</p>
+
+<ul>
+	<li>Checks if there are any changed objects (also detecting "phantom" modifications, e.g. if an object property was "updated" with the equivalent value).</li>
+	<li>Validates "dirty" objects (for more information on validation see <a href="../../../../Documentation/User Guide/DataObjects/DataObject Validation/index.html" title="DataObject Validation">this page</a>).</li>
+	<li>Generates primary keys for any NEW objects that require autogenerated key.</li>
+	<li>Builds any needed INSERT, UPDATE, DELETE queries.</li>
+	<li>Starts the database transaction.</li>
+	<li>Runs the queries.</li>
+	<li>Commits transaction.</li>
+	<li>Changes all committed objects state to PersistenceState.COMMITTED.</li>
+	<li>Updates internally stored snapshots of the recently saved objects.</li>
+</ul>
+
+
+
+<h3><a name="DataObjectStateManagement-UndoingAllUncommittedChanges"></a>Undoing All Uncommitted Changes</h3>
+
+<p>There is a way for the DataContext to undo all uncommitted changes:</p>
+
+<ul>
+	<li><tt>public void rollbackChanges()</tt></li>
+</ul>
+
+
+<p>This will restore the persistence state and the values of all registered objects to the values that objects had when they were fetched or the last commitChanges was executed. This effectively restores previously committed state of the object graph. Note that any NEW objects are unregistered from the context.</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/DataContext/DataObject State Management/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/Moving%20Objects%20Between%20Contexts/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,92 @@
+<!--
+   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 - Moving Objects Between Contexts</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">Moving Objects Between Contexts</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+</ul>
+</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>Each instance of a DataObject belongs to only one DataContext for the duration of the object lifecycle. Sometimes there maybe a need to transfer a list of objects from one DataContext to another. The goal of this operation is to be able to use such objects in relationships with objects of the target DataContext. Most common use for this feature is the following. An application may have a "shared" DataContext that is used to fetch "static" read only lookup data. To avoid fetching the same data over and over again for each session, objects from the shared DataContext can be transferred to a session DataContext by calling <tt>DataContext.localObject()</tt>:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext sessionContext = DataContext.getThreadDataContext();
+
+HttpSession session; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// assume that ServletContext contains a list of UserType DataObjects
+</span><span class="code-comment">// fetched via some global DataContext
+</span>List sharedUserTypes = (List) session.getServletContext().getAttribute("userTypes);
+UserType sharedType = (UserType) sharedUserTypes.get(0);
+
+UserType localType = (UserType) sessionContext.localObject(sharedType.getObjectId(), sharedType);
+User user; <span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>
+<span class="code-comment">// now it is safe to use the UserType in relationships with other
+</span><span class="code-comment">// session objects
+</span>user.setUserType(localType);
+...</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/DataContext/Moving Objects Between Contexts/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Nested DataContexts/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/Nested%20DataContexts/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Nested DataContexts/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Nested DataContexts/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,115 @@
+<!--
+   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 - Nested DataContexts</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">Nested DataContexts</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a><ul>
+</ul>
+</li>
+</ul>
+</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>One of the goals of the DataContext is to provide an isolated area where local object changes can be performed without affecting other similar areas or the underlying storage. At some point in time users would either commit changes to the underlying storage or undo them (roll them back). </p>
+
+<p>If a DataContext is directly attached to the DataDomain, a call to <tt>DataContext.commitChanges()</tt> results in changes written to the database. On the other hand if DataContext's direct parent in the access stack is not a DataDomain, but another DataContext, changes can be saved to the parent without saving them to the database. Such child context is often called "nested".</p>
+
+<p>Nested contexts are useful in many situations, such as nested UI dialogs, complicated workflows, etc.</p>
+
+<h3><a name="NestedDataContexts-CreatingNestedDataContext"></a>Creating Nested DataContext</h3>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext parent = ...
+DataContext child = context.createChildDataContext();</pre>
+</div></div>
+
+<p>Note that if there was a DataContextFactory configured for the DataDomain at the top of the context hierarchy, such factory will be used internally by <tt>createChildDataContext</tt> method. Also child DataContext inherits parent's <tt>"ValidatingObjectsOnCommit"</tt> property.</p>
+
+<h3><a name="NestedDataContexts-UsingNestedDataContext"></a>Using Nested DataContext</h3>
+
+<p>A nested DataContext does everything a regular DataContext can do, i.e. perform queries, register new objects, delete objects, etc. A specific behavior is the ability to choose between a cascading or one-level commit or rollback.</p>
+
+<p>Regular <tt>"commitChanges"</tt> call does a cascading commit through the stack of parents all the way to the database:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.commitChanges();</pre>
+</div></div>
+
+<p>However it is possible to commit to parent, without triggering a DB commit:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.commitChangesToParent();</pre>
+</div></div>
+
+<p>Same thing with rollback, <tt>"rollbackChanges"</tt> does a cascading rollback:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.rollbackChanges();</pre>
+</div></div>
+
+<p>While <tt>"rollbackChangesLocally"</tt> only affects the nested context, and not even sent to the parent:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">child.rollbackChangesLocally();</pre>
+</div></div>
+
+
+<h3><a name="NestedDataContexts-NestedDataContextsPerformance"></a>Nested DataContexts Performance</h3>
+
+<p>All cascading operations (such as a select query or a cascading update) initiated by a nested DataContext will have to travel through the stack of parent contexts, incurring certain delay at each stack level. The delay is due to the fact that each DataContext has to update its own objects during most operations. So nesting should only be used when application specifics require to do so. Also nesting of more than a few levels should be avoided.</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/DataContext/Nested DataContexts/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Obtaining DataContext/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/Obtaining%20DataContext/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Obtaining DataContext/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Obtaining DataContext/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,145 @@
+<!--
+   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 - Obtaining DataContext</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">Obtaining DataContext</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+</ul>
+</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 deployment environment and application needs, Cayenne can be configured in a few different ways to make DataContext instances available. This is discussed in detail in deployment chapter. In this chapter we assume a properly deployed application and will concentrate on how to obtain a DataContext for the database access. The following are the most common ways to achieve that:</p>
+
+<h3><a name="ObtainingDataContext-CreatingDataContextontheSpot"></a>Creating DataContext on the Spot</h3>
+
+<p>A new DataContext instance normally can be created using the following code:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+DataContext context = DataContext.createDataContext();</pre>
+</div></div>
+
+<p>This approach may be used in standalone applications, where the notion of a "session" is user-defined. In web applications the correct instance of DataContext is usually bound to a session or a request thread externally, and all that is needed is to retrieve it, as discussed below. Creating a new DataContext for each request is not a recommended practice.</p>
+
+<h3><a name="ObtainingDataContext-RetrievingSessionBoundDataContextinWebApplications"></a>Retrieving Session-Bound DataContext in Web Applications</h3>
+
+<p>A web application can be configured to automatically create a new instance of DataContext for each new HttpSession, and set it as a session attribute. Retrieving it from a session is done with the following code:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.conf.ServletUtil;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+
+<span class="code-comment">// assume <span class="code-keyword">this</span> exists
+</span>HttpSession session;
+DataContext context = ServletUtil.getSessionContext(session);</pre>
+</div></div>
+
+
+<h3><a name="ObtainingDataContext-RetrievingThreadBoundDataContext."></a>Retrieving Thread-Bound DataContext.</h3>
+
+<p>An application can bind a DataContext to a current execution thread. Later on the code that needs DB access can retrieve this DataContext without making any assumptions about the environment. This approach is universal and works in all types of applications (web, standalone, etc.). Previously bound DataContext can be retrieved by calling <tt>DataContext.getThreadDataContext()</tt> static method. If no DataContext was bound to the current thread, this method throws IllegalStateException:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+<span class="code-comment">// we are positive there is DataContext in the current thread, and <span class="code-keyword">do</span> not want
+</span><span class="code-comment">// to handle possible exception...
+</span>DataContext context = DataContext.getThreadDataContext();</pre>
+</div></div>
+
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+<span class="code-comment">// we want to handle the condition of no thread context...
+</span><span class="code-keyword">try</span> {
+    DataContext context = DataContext.getThreadDataContext();
+}
+<span class="code-keyword">catch</span>(IllegalStateException ex) {
+    <span class="code-comment">// handle failure
+</span>    ....
+}</pre>
+</div></div>
+
+
+<h3><a name="ObtainingDataContext-MultipleDataDomains%28Advanced%29"></a>Multiple DataDomains (Advanced)</h3>
+
+<p>Cayenne can be configured to support mass database hosting. This is a so-called Application Service Provider (ASP) scenario. Basic architecture of such setup is a single application supporting multiple databases (or more generally - data sources), each one with same or similar schema. Each data source corresponds to an individual ASP "customer" using the system. Each customer has a number of users that will log in to the system and are only allowed to view data from their data source.</p>
+
+<p>This approach, though not required for most normal applications, could be quiet common and powerful in some enterprise systems. To implement it, each DataContext must be limited to access only a relevant subset of datasources.</p>
+
+<p>Considering that behind the scenes a source of DataContext instances is an object called DataDomain, Cayenne allows creation of multiple DataDomains per project. Each DataDomain would support a single "customer". Creation of DataContext in this case is done using DataDomain name as a parameter:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+...
+
+<span class="code-comment">// domain name string is initialized depending on
+</span><span class="code-comment">// the application logic. For instance it can be based
+</span><span class="code-comment">// on the logged in user's company, etc.
+</span><span class="code-object">String</span> domainName = ...;
+DataContext context = DataContext.createDataContext(domainName);</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/DataContext/Obtaining DataContext/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Running Queries/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/Running%20Queries/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Running Queries/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/Running Queries/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,138 @@
+<!--
+   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 - Running Queries</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">Running Queries</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+</ul>
+</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 Query API is discussed in the following chapters. This chapter concentrates on how to execute an existing query via a DataContext. Still we'd like to point to a few aspects of the query API here, as they are important for the query execution discussion:</p>
+
+<ul>
+	<li>There are selecting and non-selecting queries. Selecting queries return objects back to the caller, while non-selecting just perform some DB operation (such as INSERT, DELETE, UPDATE, etc.) without returning anything back.</li>
+	<li>Queries can be created in two ways - either by instantiating and configuring a Query object directly, or by mapping a query in CayenneModeler, and then referring to it by name. Mapped named queries are generally easier to create and maintain.</li>
+</ul>
+
+
+<p>Being an instance of QueryEngine, DataContext has generic API to execute any type of queries, however it is rarely used directly. Instead DataContext provides a number of overriden convenience methods to run the types of queries mentioned above.</p>
+
+<h3><a name="RunningQueries-RunningQueryInstances"></a>Running Query Instances</h3>
+
+<p>The following methods are used for running selecting and non-selecting Query objects built in the code:</p>
+
+<ul>
+	<li><tt>public java.util.List performQuery(Query query)</tt><br/>
+This is the most commonly used method for any selecting query.</li>
+</ul>
+
+
+<ul>
+	<li><tt>public ResultIterator performIteratedQuery(Query query) throws CayenneException</tt><br/>
+Performs a selecting query, returning an iterator over the result backed by an open JDBC ResultSet. Benefits and shortcomings of using result iterators are discussed in "Performance Tuning" chapter. This is the only query method that throws checked exceptions. Also returned ResultIterator requires explicit cleanup via calling close().</li>
+</ul>
+
+
+<ul>
+	<li><tt>public int[] performNonSelectingQuery(Query query)</tt><br/>
+Executes a non-selecting query, returning update counts.</li>
+</ul>
+
+
+<ul>
+	<li><tt>public QueryResponse performGenericQuery(Query query)</tt><br/>
+A generic query execution method. Used for queries with complex results. For example queries based on stored procedures can have more than one result set, do multiple updates, and return values as OUT parameters.</li>
+</ul>
+
+
+
+<h3><a name="RunningQueries-RunningMappedQueries"></a>Running Mapped Queries</h3>
+
+<p>The following methods are used to run named selecting and non-selecting queries mapped using CayenneModeler and stored in the DataMap XML file:</p>
+
+<ul>
+	<li><tt>public java.util.List performQuery(String name, boolean expireCachedLists)</tt><br/>
+Runs a named selecting query stored in the DataMap.</li>
+</ul>
+
+
+<ul>
+	<li><tt>public java.util.List performQuery(String name, Map parameters, boolean expireCachedLists)</tt><br/>
+Runs a named selecting query stored in the DataMap, using a map of named parameters.</li>
+</ul>
+
+
+<ul>
+	<li><tt>public int[] performNonSelectingQuery(String name)</tt><br/>
+Runs a named non-selecting query stored in the DataMap.</li>
+</ul>
+
+
+<ul>
+	<li><tt>public int[] performNonSelectingQuery(String name, Map parameters)</tt><br/>
+Runs a named non-selecting query stored in the DataMap, using a map of named parameters.</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/DataContext/Running Queries/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,74 @@
+<!--
+   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 - DataContext</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">DataContext</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><ul>
+<li><a href="../../../Documentation/User Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/User Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/User Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../Documentation/User Guide/Customizing/index.html">Customizing</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>In most applications <tt>org.apache.cayenne.access.DataContext</tt> is the main user access point to all Cayenne functionality. It provides query execution facilities as well as object state management functions. Applications rarely directly deal with access or mapping objects beyond DataContext.</p>
+
+<p>One of the important features of DataContext is that it isolates changes made in a user session from other users. With this in mind, DataContext normally has a session scope. "Session" can have different meanings in different types of applications. Good example is an HttpSession in a web application. Each one of HttpSessions will normally need a single instance of 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/DataContext/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataObjects/Accessing%20PK%20and%20FK%20values/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,147 @@
+<!--
+   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 - Accessing PK and FK values</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">Accessing PK and FK values</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html">Accessing PK and FK values</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</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>Normally it is not advisable to map primary and foreign key columns (PK and FK) as Java class properties (ObjAttributes). When reverse engineering of the database is done using CayenneModeler, produced mapping will reflect that - PKs and FKs will not be included in the Java class. However sometimes an application requires access to these values.</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>For generic and easy API to obtain an object primary key or to find an object from a known PK, skip to the next chapter on DataObjectUtils class.</td></tr></table>
+
+<p>Cayenne provides a generic way to do access primary and foreign keys by creating custom get* methods in the DataObject subclass. Lets take a Painting class as an example. The following code is generated by CayenneModeler:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> org.apache.art;
+
+<span class="code-keyword">public</span> class Painting <span class="code-keyword">extends</span> org.apache.art.auto._Painting {
+
+}</pre>
+</div></div>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> org.apache.art.auto;
+
+/** <span class="code-object">Class</span> _Painting was generated by Cayenne.
+  * It is probably a good idea to avoid changing <span class="code-keyword">this</span> class manually, 
+  * since it may be overwritten next time code is regenerated. 
+  * If you need to make any customizations, please use subclass. 
+  */
+<span class="code-keyword">public</span> class _Painting <span class="code-keyword">extends</span> org.apache.art.ArtDataObject {
+
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> ESTIMATED_PRICE_PROPERTY = <span class="code-quote">"estimatedPrice"</span>;
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> PAINTING_TITLE_PROPERTY = <span class="code-quote">"paintingTitle"</span>;
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> TO_ARTIST_PROPERTY = <span class="code-quote">"toArtist"</span>;
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> TO_GALLERY_PROPERTY = <span class="code-quote">"toGallery"</span>;
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> TO_PAINTING_INFO_PROPERTY = <span class="code-quote">"toPaintingInfo"</span>;
+
+    <span class="code-keyword">public</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-object">String</span> PAINTING_ID_PK_COLUMN = <span class="code-quote">"PAINTING_ID"</span>;
+
+    <span class="code-keyword">public</span> void setEstimatedPrice(java.math.BigDecimal estimatedPrice) {
+        writeProperty(<span class="code-quote">"estimatedPrice"</span>, estimatedPrice);
+    }
+    <span class="code-keyword">public</span> java.math.BigDecimal getEstimatedPrice() {
+        <span class="code-keyword">return</span> (java.math.BigDecimal)readProperty(<span class="code-quote">"estimatedPrice"</span>);
+    }
+    
+    
+    <span class="code-keyword">public</span> void setPaintingTitle(<span class="code-object">String</span> paintingTitle) {
+        writeProperty(<span class="code-quote">"paintingTitle"</span>, paintingTitle);
+    }
+    <span class="code-keyword">public</span> <span class="code-object">String</span> getPaintingTitle() {
+        <span class="code-keyword">return</span> (<span class="code-object">String</span>)readProperty(<span class="code-quote">"paintingTitle"</span>);
+    }
+...
+}</pre>
+</div></div>
+
+<p>The following custom methods should be added to the Painting class to access the values of ARTIST_ID and PAINTING_ID:</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>If you perform class generation using Ant, you can customize class generation templates to generte these methods for you. Eventually CayenneModeler will support this too as optional functionality.</td></tr></table>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> org.apache.art;
+
+<span class="code-keyword">public</span> class Painting <span class="code-keyword">extends</span> org.apache.art.auto._Painting {
+   /** Read-only access to PK */
+   <span class="code-keyword">public</span> <span class="code-object">Integer</span> getPaintingId() {
+      <span class="code-keyword">return</span> (getObjectId() != <span class="code-keyword">null</span> &amp;&amp; !getObjectId().isTemporary()) 
+               ? (<span class="code-object">Integer</span>)getObjectId().getIdSnapshot().get(PAINTING_ID_PK_COLUMN) 
+               : <span class="code-keyword">null</span>;
+   }
+   
+   /** Read-only access to FK */
+   <span class="code-keyword">public</span> <span class="code-object">Integer</span> getArtistId() {
+      Artist artist = getArtist();
+      <span class="code-keyword">return</span> (artist != <span class="code-keyword">null</span>) 
+               ? (<span class="code-object">Integer</span>)artist.getObjectId().getIdSnapshot().get(Artist.ARTIST_ID_PK_COLUMN) 
+               : <span class="code-keyword">null</span>;
+   }
+}</pre>
+</div></div></div>
+</div>
+  <div class="clearer">.</div>
+  <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+  <div class="smalltext copyright">
+    Copyright &copy;2001-2006 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObject Validation/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataObjects/DataObject%20Validation/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObject Validation/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObject Validation/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,133 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - DataObject Validation</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">DataObject Validation</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html">Accessing PK and FK values</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</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>DataObject implements a set of methods to validate its state. DataContext calls these methods before performing a commit. If validation fails, commit is aborted with ValidationException. There are a few clear benefits of validating DataObjects at the application level before committing them to the database:</p>
+
+<ul>
+	<li>Cayenne can leverage ORM metadata (DataMap) to check for many standard error conditions.</li>
+	<li>Custom validation can be easily integrated into the business objects by overriding standard validation methods.</li>
+	<li>Validation failures can be tracked down to the individual objects and their properties, allowing creation of user-friendly, internationalized validation messages.</li>
+	<li>Relying on database validation for things like mandatory properties, etc., would result in errors that are meaningless or extremely hard to decode in the application context.</li>
+	<li>Application validation partially addresses shortcomings of databases that do not support real transactions (e.g. older MySQL). Validation would trap the whole class of errors that would otherwise result in failure halfway through the commit, leaving database in inconsistent state.</li>
+	<li>Automating of the business objects validation takes away some burden from the UI that now has fewer things to track.</li>
+</ul>
+
+
+
+<h2><a name="DataObjectValidation-ValidationAPI"></a>Validation API</h2>
+<p>Each DataObject participating in commit operation (i.e. those in state NEW, DELETED or MODIFIED , in other words "non-committed") will be validated by DataContext's ObjectStore during commit processing. Depending on the non-committed object state, ObjectStore calls one of the methods described below (description of method behavior is provided for CayenneDataObject implementation):</p>
+
+<ul>
+	<li>public void <b>validateForInsert</b>(ValidationResult validationResult)<br/>
+      public void <b>validateForUpdate</b>(ValidationResult validationResult)<br/>
+      Implementation internally calls <tt>validateForSave(..)</tt>. When overriding, in most cases developers should invoke "super".</li>
+	<li>public void <b>validateForDelete</b>(ValidationResult validationResult)<br/>
+      This method does nothing by default and exists merely for overriding.</li>
+	<li>protected void <b>validateForSave</b>(ValidationResult validationResult)<br/>
+      This method only exists in CayenneDataObject (and not in DataObject). It is invoked internally from <tt>validateForInsert(..)</tt> and <tt>validateForUpdate(..)</tt>, performing some generic validation based on the DataMap information. This includes checking for nulls and for values that exceed their database size limitations. When overriding this method to include custom validation, developers should call "super" in most cases.</li>
+</ul>
+
+
+<p>Custom validation method implementation would normally append any failures to the provided ValidationResult instance. After validating all non-committed objects, DataContext (or rather its ObjectStore) will check if the ValidationResult is not empty, and throw an exception if there is at least one failure. Typical custom validation method would look like that:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class Painting <span class="code-keyword">extends</span> _Painting {
+   ...
+   <span class="code-keyword">protected</span> void validateForSave(ValidationResult validationResult) {
+      <span class="code-keyword">super</span>.validateForSave(validationResult);
+     
+      <span class="code-comment">// check business rules
+</span>      <span class="code-keyword">if</span>(getEstimatedPrice().doubleValue() &lt;= 0.0) {
+         validationResult.addFailure(
+                <span class="code-keyword">this</span>, <span class="code-comment">// source object of the failure
+</span>                Painting.ESTIMATED_PRICE_PROPERTY, <span class="code-comment">// failed property name
+</span>                <span class="code-quote">"Painting price must be greater than zero."</span>)); <span class="code-comment">// error message  
+</span>      }
+   }
+   ...
+}</pre>
+</div></div>
+
+<h2><a name="DataObjectValidation-ValidationMethodswithSideEffects"></a>Validation Methods with Side Effects</h2>
+
+<p>Often validation methods are implemented to modify an object being validated and/or other persistent objects. Cayenne supports such behavior, however a few things should be taken into consideration:</p>
+
+<ul>
+	<li>Since version 3.0 Cayenne supports <a href="../../../../Documentation/User Guide/Lifecycle Callbacks/index.html" title="Lifecycle Callbacks">lifecycle callbacks</a> that may be a better alternative.</li>
+	<li>If a previously "clean" object becomes "dirty" as a result of the user logic in the "validate" method, such object is not validated.</li>
+	<li>There is no guarantee of a specific order in which dirty objects are validated.</li>
+</ul>
+
+
+<h2><a name="DataObjectValidation-TurningValidationOn%2FOff"></a>Turning Validation On/Off</h2>
+<p>Whether DataContext performs validation at all depends on the value of its property <tt>validatingObjectsOnCommit</tt>. Calling <tt>isValidatingObjectsOnCommit()</tt> returns currently configured value. Default value (usually "true") is propagated from the parent DataDomain when DataContext is created. This default value can be configured using CayenneModeler as described in <a href="../../../../Documentation/Modeler Guide/Configuring Deployment Settings/Configuring Object Validation/index.html" title="Configuring Object Validation">Configuring Object Validation</a> section.</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/DataObjects/DataObject Validation/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObjectUtils/index.html
URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataObjects/DataObjectUtils/index.html?view=auto&rev=488202
==============================================================================
--- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObjectUtils/index.html (added)
+++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataObjects/DataObjectUtils/index.html Mon Dec 18 02:24:19 2006
@@ -0,0 +1,95 @@
+<!--
+   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 - DataObjectUtils</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">DataObjectUtils</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><ul>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Accessing PK and FK values/index.html">Accessing PK and FK values</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</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>DataObjectUtils class provides an important and easy to use facility to obtain a primary key value from a DataObject and to locate a DataObject in the database for a known primary key. Both operations work in a generic fashion and do not require primary key to be an object property.</p>
+<table cellpadding='5' width='85%' cellspacing='8px' class='warningMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Security Warning</b><br />DataObjectUtils make it very easy to use a primary key value as a universal "code" for an object in web forms and URLs. This opens a potential security hole in the interface. If application code is not careful enough, a malicious user can gain access to the information she is not allowed to see (e.g. other people's accounts) simply by trying a series of sequential numbers. So for example it is probably ok to use product PK to build a bookmarkable link to a catalog product, but it may not be appropriate to do that for a private user profile record.</td></tr></table>
+<p>DataObjectUtils API is really straightforward and self-explanatory. It supports the most common case of a single column integer primary key, but also a more generic case of an arbitrary PK (that can also be compound, i.e. consist of more than one column). Here is an example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// obtain PK to build a bookmarkable artist page URL
+</span>Artist artist = ...;
+<span class="code-object">int</span> artistID = DataObjectUtils.intPKForObject(artist);
+<span class="code-object">String</span> artistURL = <span class="code-quote">"http:<span class="code-comment">//www.example.org/catalogapp/artists?a="</span> + artistID;</span></pre>
+</div></div>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// find an artist from URL parameters
+</span>HttpServletRequest request = ...;
+DataContext context = ...;
+<span class="code-object">String</span> idString = request.getParameter(<span class="code-quote">"a"</span>);
+
+<span class="code-keyword">if</span>(idString != <span class="code-keyword">null</span>) {
+  Artist artist = DataObjectUtils.objectForPK(context, Artist.class, <span class="code-object">Integer</span>.parseInt(idString));
+}</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/DataObjects/DataObjectUtils/index.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message