cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r554413 [3/17] - in /cayenne/main/trunk/docs/doc/src/main/resources/doc: ./ Documentation/ Documentation/Cayenne Guide/ Documentation/Cayenne Guide/Ant Tasks/ Documentation/Cayenne Guide/Ant Tasks/cdataport/ Documentation/Cayenne Guide/Ant ...
Date Sun, 08 Jul 2007 19:11:53 GMT
Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/ObjectContext%20Memory%20Management/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,104 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+ 
+     http://www.apache.org/licenses/LICENSE-2.0
+ 
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+-->
+<html>
+  <head>
+    <title>Apache Cayenne Documentation - ObjectContext Memory Management</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+    <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+    <span class="pagetitle">ObjectContext Memory Management</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="ObjectContextMemoryManagement-OldMemoryManagementStrategy"></a>Old Memory Management Strategy</h2>
+
+<p>Prior to 3.0 release, all implementations of ObjectContext (specifically DataContext) retained hard references to all registered objects on a premise that the context itself would eventually go out of scope and release all those objects. In certain situations such as a context used for processing large data sets and/or a context staying around for a long time (e.g application-scoped context), memory would grow indefinitely, resulting in a leak. </p>
+
+<p>Also there was a little-advertised workaround based on users explicitly calling <tt>ObjectStore.startTrackingNewObjects()</tt> and <tt>ObjectStore.unregisterNewObjects()</tt>.</p>
+
+<h2><a name="ObjectContextMemoryManagement-NewMemoryManagementStrategy"></a>New Memory Management Strategy</h2>
+
+<p>In release 3.0, by default DataContext uses weak references to store registered objects. So objects are allowed to be garbage collected by the VM if they are not referenced elsewhere in the application. "Elsewhere" usually means one of the following:</p>
+
+<ul>
+	<li>An object is directly or indirectly referenced by the application.</li>
+	<li>An object is a part of the cached query result stored by Cayenne.</li>
+	<li>An object is "dirty" (i.e. new, modified or deleted). In this case Cayenne ensures that such object is retained at least until commit or rollback.</li>
+</ul>
+
+
+<p>In addition to saving memory, another positive side effect of this feature is that DataContext retains fewer objects at any given time and hence internal object lookups work somewhat faster on select and commit.</p>
+
+<h2><a name="ObjectContextMemoryManagement-WhentoAvoidWeakReferences"></a>When to Avoid Weak References</h2>
+
+<p>In some cases automatic cleaning of registered objects may result in extra DB trips later on. Depending on a situation, this may or may not be critical, so users will need to weigh the choices of fewer queries vs. smaller memory footprint. In addition to the "dirty objects" scenario described above (and taken care by Cayenne behind the scenes), here are a few more scenarios where a user may choose a different strategy:</p>
+
+<ul>
+	<li>Nested DataContexts: When a child nested DataContext commits to parent, parent using weak references may have already deallocated some of the objects being committed and will have to refetch them.</li>
+	<li>ROP: When an ROP client commits to the server, parent server DataContext using weak references may have already deallocated some of the objects being committed and will have to refetch them.</li>
+</ul>
+
+
+<p>To ensure that weak references are not used, create a DataContext manually, passing a regular <tt>HashMap</tt> to the <tt>ObjectStore</tt> constructor.</p>
+
+<p><em>TODO: an example, and figure out how to make it a parameter in the Modeler</em></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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/Obtaining%20DataContext/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,146 @@
+<!--
+   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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne 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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Running Queries/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/Running%20Queries/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Running Queries/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Running Queries/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,139 @@
+<!--
+   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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne 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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/Running Queries/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataContext/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,88 @@
+<!--
+   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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a><ul>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html">Obtaining DataContext</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html">Running Queries</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html">DataObject State Management</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html">Moving Objects Between Contexts</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html">DataContextDelegate</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html">DataContextFactory</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html">Nested DataContexts</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html">ObjectContext Memory Management</a></li>
+</ul>
+</li>
+<li><a href="../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h2><a name="DataContext-DataContext"></a>DataContext</h2>
+<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>
+
+<h3><a name="DataContext-Sections"></a>Sections</h3>
+
+<ol>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/Obtaining DataContext/index.html" title="Obtaining DataContext">Obtaining DataContext</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/Running Queries/index.html" title="Running Queries">Running Queries</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataObject State Management/index.html" title="DataObject State Management">DataObject State Management</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/Moving Objects Between Contexts/index.html" title="Moving Objects Between Contexts">Moving Objects Between Contexts</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataContextDelegate/index.html" title="DataContextDelegate">DataContextDelegate</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/DataContextFactory/index.html" title="DataContextFactory">DataContextFactory</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/Nested DataContexts/index.html" title="Nested DataContexts">Nested DataContexts</a></li>
+	<li><a href="../../../Documentation/Cayenne Guide/DataContext/ObjectContext Memory Management/index.html" title="ObjectContext Memory Management">ObjectContext Memory Management</a></li>
+</ol>
+</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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataContext/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Accessing%20PK%20and%20FK%20Values/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html Sun Jul  8 12:11:31 2007
@@ -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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html">Accessing PK and FK Values</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne 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, the generated 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 an easier way to obtain an object primary key or to find an object from a known PK, skip to the chapter on the <a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html" title="DataObjectUtils">DataObjectUtils</a> class.</td></tr></table>
+
+<p>Cayenne provides a generic way to 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 generate 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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObject%20Validation/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html Sun Jul  8 12:11:31 2007
@@ -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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html">Accessing PK and FK Values</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne 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, the 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/Cayenne 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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObjectUtils/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,96 @@
+<!--
+   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://cayenne.apache.org/"><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/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html">Accessing PK and FK Values</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne 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 okay 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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObjects%20Example/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,132 @@
+<!--
+   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 - DataObjects Example</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><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">DataObjects Example</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html">Accessing PK and FK Values</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>As discussed in <a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html" title="DataObjects">DataContext</a> chapter, any changes made to the DataObjects via "set*" methods are synchronized with the database by calling <tt>DataContext.commitChanges</tt>. Here is an example showing how the <tt>Painting</tt> object is fetched, modified and saved back. The following modifications are performed: the price of the first retrieved painting is doubled, a new painting is added that belongs to the same artist as the painting fetched before:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> java.math.BigDecimal;
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
+<span class="code-keyword">import</span> org.apache.cayenne.query.SelectQuery;
+<span class="code-keyword">import</span> org.apache.cayenne.exp.Expression;
+<span class="code-keyword">import</span> org.apache.cayenne.exp.ExpressionFactory;
+<span class="code-keyword">import</span> org.apache.art.Painting;
+<span class="code-keyword">import</span> org.apache.art.Artist;
+...
+
+<span class="code-comment">// assume <span class="code-keyword">this</span> exists and initialized
+</span>DataContext ctxt;
+...
+Expression e =
+  ExpressionFactory.greaterExp(<span class="code-quote">"estimatedPrice"</span>,
+                        <span class="code-keyword">new</span> BigDecimal(100000.0));
+SelectQuery q = <span class="code-keyword">new</span> SelectQuery(Painting.class, e);
+List realExpensiveArt = ctxt.performQuery(q);
+
+<span class="code-keyword">if</span>(realExpensiveArt.size() &gt; 0) {
+  Painting firstPainting = (Painting)realExpensiveArt.get(0);
+
+  <span class="code-comment">// <span class="code-object">double</span> the price
+</span>  <span class="code-object">double</span> oldPrice = firstPainting.getEstimatedPrice().doubleValue();
+  firstPainting.setEstimatedPrice(<span class="code-keyword">new</span> BigDecimal(oldPrice * 2.00));
+
+  <span class="code-comment">// create <span class="code-keyword">new</span> painting and register it with DataContext
+</span>  <span class="code-comment">// <span class="code-quote">"Painting"</span> string is a name of ObjEntity in the DataMap
+</span>  Painting newPainting = (Painting)ctxt.newObject(Painting.class);
+  newPainting.setPaintingTitle(<span class="code-quote">"Sunset as it is"</span>);
+
+  <span class="code-comment">// price it as unreasonable as other paintings
+</span>  newPainting.setEstimatedPrice(<span class="code-keyword">new</span> BigDecimal(5000000.0));
+
+  <span class="code-comment">// get artist via relationship
+</span>  Artist artist = firstPainting.getToArtist();
+
+  <span class="code-comment">// assign <span class="code-keyword">new</span> painting to an artist
+</span>  artist.addToPaintingArray(newPainting);
+
+  <span class="code-comment">// save all the changes we've made so far
+</span>  ctxt.commitChanges();
+}
+...</pre>
+</div></div>
+<p>If SQL tracing is turned on, and depending on the preexisting data in the database, the following SQL statements might be printed to console during the commit phase:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>[main 12-22 15:50:19] QueryLogger: --- will run 2 queries.
+[main 12-22 15:50:19] QueryLogger: INSERT INTO PAINTING (PAINTING_ID, PAINTING_TITLE, ESTIMATED_PRICE,
+ ARTIST_ID) VALUES (?, ?, ?, ?) [params: 200, 'Sunset as it is', 5000000, 10]
+[main 12-22 15:50:19] QueryLogger: === updated 1 row.
+[main 12-22 15:50:19] QueryLogger: UPDATE PAINTING SET ESTIMATED_PRICE = ? WHERE PAINTING_ID = ? 
+ [params: 2000000, 34]
+[main 12-22 15:50:19] QueryLogger: === updated 1 row.
+[main 12-22 15:50:19] QueryLogger: +++ transaction committed.
+</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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Deleting%20Objects/index.html?view=auto&rev=554413
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html (added)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html Sun Jul  8 12:11:31 2007
@@ -0,0 +1,110 @@
+<!--
+   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 - Deleting Objects</title>
+    <style type="text/css">@import "../../../../style.css";</style>
+  </head>
+<body>
+  <div class="header">
+    <div style="float: left;"><a href="http://cayenne.apache.org/"><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">Deleting Objects</span>
+  </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/Cayenne Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/index.html">DataObjects</a><ul>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Relationships/index.html">Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Accessing PK and FK Values/index.html">Accessing PK and FK Values</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/Cayenne Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Lifecycle Callbacks/index.html">Lifecycle Callbacks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Caching and Fresh Data/index.html">Caching and Fresh Data</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Maven2 Plugins/index.html">Maven2 Plugins</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/Customization/index.html">Customization</a></li>
+<li><a href="../../../../Documentation/Cayenne Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>As discussed before, an object must be deleted in the DataContext to trigger a removal of the corresponding row from the database on commit. There are few simple ways to delete individual objects and collections of objects. Quite naturally, a delete operation changes the object state to PersistenceState.DELETED. However there maybe other consequences of such operation for the overall object graph. Such consequences are controlled via <a href="../../../../Documentation/Modeler Guide/Modeling Object Layer/Delete Rules/index.html" title="Delete Rules">delete rules</a> configured for object relationships. Properly configuring delete rules will simplify the application code, as you no longer need to track related objects and do the right thing with them. Other delete rule effects are discussed for each DataContext deletion method individually.</p>
+
+<h5><a name="DeletingObjects-Deletingasingleobject"></a>Deleting a single object</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = ...;
+Artist artist = ....;
+
+<span class="code-comment">// <span class="code-keyword">this</span> will trigger delete rules <span class="code-keyword">for</span> artist, <span class="code-keyword">if</span> any
+</span>context.deleteObject(artist);</pre>
+</div></div>
+<h5><a name="DeletingObjects-Deletingacollectionofobjects"></a>Deleting a collection of objects</h5>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = ...;
+Artist artist = ....;
+
+context.deleteObjects(artist.getPaintings());</pre>
+</div></div>
+<h5><a name="DeletingObjects-DeletinginanIterator"></a>Deleting in an Iterator</h5>
+<p>This case can be complicated if an iteration is performed over a relationship list and an object being deleted has a nullify delete rule. Such combination may result in ConcurrencyModificationExceptions as collection underlying the iterator is being modified. If ALL objects in the collection have to be deleted, use "deleteObjects()" method shown above - it will do the right thing. If only a subset of collection objects has to be deleted, you can use the following technique:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context = ...;
+Artist artist = ....;
+
+Iterator it = artist.getPaintings().iterator();
+<span class="code-keyword">while</span>(it.hasNext()) {
+   DataObject object = it.next();
+   
+   <span class="code-keyword">if</span>(some_condition) {
+      <span class="code-comment">// jump ahead of the delete rule and unset the relationship
+</span>      it.remove();
+   
+      <span class="code-comment">// now <span class="code-keyword">do</span> the actual delete
+</span>      context.deleteObject(object); 
+   }
+}</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-2007 Apache Software Foundation
+  </div>
+
+</body>
+</html>

Propchange: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message