You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2006/05/10 03:11:01 UTC
svn commit: r405581 [7/14] - in
/incubator/cayenne/main/trunk/cayenne/cayenne-other: docs/ docs/images/
wiki-docs/ wiki-docs/Documentation/ wiki-docs/Documentation/Modeler Guide/
wiki-docs/Documentation/Modeler Guide/Cayenne Project Structure/ wiki-doc...
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataObjects/Handling%20Inheritance/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,138 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Handling Inheritance</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Handling Inheritance</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a><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/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</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/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>"Inheritance" is an Object Oriented concept absent in traditional RDBMS. Cayenne however allows to map a hierarchical class tree to a single base table (so called "single table inheritance"). Such mapping is described in detail in the <a href="../../../../Documentation/Modeler Guide/Modeling Object Layer/Modeling Inheritance/index.html" title="Modeling Inheritance">Modeler Guide</a>. The idea of single table inheritance is that a "class" of a database row is determined from the values in one or more columns of the base table. These columns are called "class designator columns".</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><b class="strong">Initial Values of the Classs Designator Columns</b><br />Assigning correct values to the "class designator columns" mentioned above is one task that is not yet automated in Cayenne and requires user code in the DataObject, as discussed in the next subsection. In the future versions this will likely be handled in the mapping and completely outside of the Java classes, so the advise below will become obsolete.</td></tr></table>
+
+<h3><a name="HandlingInheritance-InheritanceandnewDataObjects"></a>Inheritance and new DataObjects</h3>
+<p>Consider the following class hierarchy (also used in the Modeler Guide example):<br/>
+<img src="inheritance-diagram.jpg" align="absmiddle" border="0" /></p>
+
+<p>If a class designator column is "PERSON_TYPE", AbstractPerson class should define an attribute (for instance called "personType") that maps to PERSON_TYPE. This attribute is redundant and meanigless in Java, since person type is defined already by the Java class of the object, however we still have to keep it around so that when the new objects are saved, correct PERSON_TYPE data is stored in the database. Currently it is a developer responsibility to set "personType" value (or values of any other attributes that map to "class designator columns") when the new object is registered with DataContext. One way to take care of this is to override "setPersistenceState(..)" method on each DataObject class in the inheritance hierarchy to catch when the object is registered with DataContext:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> class Employee <span class="code-keyword">extends</span> _Employee {
+ <span class="code-keyword">public</span> void setPersistenceState(<span class="code-object">int</span> state) {
+ <span class="code-keyword">super</span>.setPersistenceState(state);
+
+ <span class="code-comment">// <span class="code-keyword">if</span> object was just created
+</span> <span class="code-keyword">if</span>(state == PersistenceState.NEW) {
+ setPersonType(<span class="code-quote">"EMPLOYEE"</span>);
+ }
+ }
+...
+}
+
+<span class="code-keyword">public</span> class Manager <span class="code-keyword">extends</span> _Manager {
+ <span class="code-keyword">public</span> void setPersistenceState(<span class="code-object">int</span> state) {
+ <span class="code-keyword">super</span>.setPersistenceState(state);
+
+ <span class="code-comment">// <span class="code-keyword">if</span> object was just created
+</span> <span class="code-keyword">if</span>(state == PersistenceState.NEW) {
+ setPersonType(<span class="code-quote">"MANAGER"</span>);
+ }
+ }
+...
+}
+
+<span class="code-keyword">public</span> class CustomerContact <span class="code-keyword">extends</span> _CustomerContact {
+ <span class="code-keyword">public</span> void setPersistenceState(<span class="code-object">int</span> state) {
+ <span class="code-keyword">super</span>.setPersistenceState(state);
+
+ <span class="code-comment">// <span class="code-keyword">if</span> object was just created
+</span> <span class="code-keyword">if</span>(state == PersistenceState.NEW) {
+ setPersonType(<span class="code-quote">"CUSTOMER"</span>);
+ }
+ }
+...
+}</pre>
+</div></div>
+
+<h3><a name="HandlingInheritance-InheritanceandSelectQueries"></a>Inheritance and SelectQueries</h3>
+<p>When performing SelectQuery on a table that maps to inheritance hierarchy, Cayenne will only return rows that belong to root class of the query and all its subclasses. No superclasses or objects from parallel inheritance branches will be returned. For example executing a SelectQuery with Employee class as root will potentially return a mix of Employees and Managers (who are also Employees of course), but no CustomerContact objects:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context;
+...
+SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Employee.class);
+List employees = context.performQuery(query);
+
+<span class="code-comment">// employees list will contain <span class="code-quote">"regular"</span> employees and managers
+</span>Iterator it = employees.iterator();
+<span class="code-keyword">while</span>(it.hasNext()) {
+ Employee e = (Employee) it.next();
+ <span class="code-keyword">if</span>(e <span class="code-keyword">instanceof</span> Manager) {
+ <span class="code-comment">// <span class="code-keyword">do</span> something with manager...
+</span> }
+}</pre>
+</div></div>
+
+<p>The need to determine the correct class for each fetched database row makes queries on entities that use inheritance less efficient than the regular queries. If an application doesn't care about the query root class subclasses, the query can be optimized by explicitly turning off inheritance resolution. If this is done, the example above will return all Managers as instances of Employee class, not Manager class:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataContext context;
+...
+SelectQuery query = <span class="code-keyword">new</span> SelectQuery(Employee.class);
+
+<span class="code-comment">// *** explicitly turn off inheritance resolution
+</span>query.setResolvingInherited(<span class="code-keyword">false</span>);
+
+List employees = context.performQuery(query);
+
+<span class="code-comment">// employees list will contain no Manager instances...
+</span><span class="code-comment">// all Managers will be returned as regular Employees</span></pre>
+</div></div>
+
+<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>Whenever an object is obtained via a relationship, it is always fully resolved to the lowest possible subclass in an entity inheritance tree.</td></tr></table>
+
+<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>Use <tt>setResolvingInherited(false)</tt> with caution, and only if you never plan to work with subclasses. The downside of it is that the DataContext may end up with two objects pointing to the same database row, thus violating uniquing principle. With the above example, this may happen if at a later time user decides to fetch Managers directly, or if a Manager object is obtained via a relationship.</td></tr></table></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/inheritance-diagram.jpg
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataObjects/Handling%20Inheritance/inheritance-diagram.jpg?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Handling Inheritance/inheritance-diagram.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Relationships/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataObjects/Relationships/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Relationships/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Relationships/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,95 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Relationships</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Relationships</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a><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/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</a><ul>
+</ul>
+</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/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Relationships are special <span class="nobr"><a href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/DataObject.html" title="Visit page outside Confluence" rel="nofollow">DataObject<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> properties that reference other "related" objects. Semantically there are two types of relationships - to-one pointing to just a single DataObjects (e.g. Painting.toArtist), and to-many pointing to a collection of DataObjects of the same base type (e.g. Artist.paintingArray).</p>
+
+<h3><a name="Relationships-ToOneRelationships"></a>To-One Relationships</h3>
+
+<p>"Get" methods for to-one relationships return the target DataObject. If the object is not in memory yet, it will be fetched on demand. Modifying to-one relationships is no different from modifying attributes - just a simple call to a "set" method:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">Painting painting;
+
+<span class="code-comment">// obtain artist <span class="code-keyword">for</span> a given painting
+</span>Artist originalArtist = painting.getToArtist();
+
+<span class="code-comment">// replace with a <span class="code-keyword">new</span> artist
+</span>Artist newArtist = (Artist)context.createAndRegisterNewObject(Artist.class);
+painting.setToArtist(newArtist);
+
+<span class="code-comment">// or remove Artist at all...
+</span><span class="code-comment">// painting.setToArtist(<span class="code-keyword">null</span>);</span></pre>
+</div></div>
+<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>
+<p>When adding or removing an object from any kind of relationship, Cayenne will locate and modify an existing reverse relationship as appropriate.</p></td></tr></table>
+
+<h3><a name="Relationships-ToManyRelationships"></a>To-Many Relationships</h3>
+
+<p>"Get" methods for to-many relationships return Lists of DataObjects. Just like individual DataObjects, such lists are also resolved on demand (e.g. when a user tries to read an element from the list). For modification there are special "addTo..." and "removeFrom..." methods:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java">Artist artist;
+
+<span class="code-comment">// obtain a list of paintings
+</span>List paintings = artist.getPaintingArray();
+
+<span class="code-comment">// remove the first painting
+</span><span class="code-keyword">if</span>(paintings.size() > 0) {
+ Painting firstPainting = (Painting)paintings.get(0);
+ artist.removeFromPaintingArray(firstPainting);
+}
+
+<span class="code-comment">// add a <span class="code-keyword">new</span> painting
+</span>Painting newPainting = (Painting)context.createAndRegisterNewObject(Painting.class);
+artist.addToPaintingArray(newPainting);</pre>
+</div></div>
+<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>
+<p>While to-many relationships in Cayenne are represented by Lists, they are really ordered Sets, as they are not allowed to contain the same object more than once.</p></td></tr></table></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/Relationships/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataObjects/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,56 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - DataObjects</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">DataObjects</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a><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/DataObject Validation/index.html">DataObject Validation</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/DataObjectUtils/index.html">DataObjectUtils</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/DataObjects Example/index.html">DataObjects Example</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/Deleting Objects/index.html">Deleting Objects</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/Flattened Relationships/index.html">Flattened Relationships</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/Generic Persistent Class/index.html">Generic Persistent Class</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/Handling Inheritance/index.html">Handling Inheritance</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/Relationships/index.html">Relationships</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/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p><span class="nobr"><a href="http://objectstyle.org/cayenne/api/cayenne/org/objectstyle/cayenne/DataObject.html" title="Visit page outside Confluence" rel="nofollow">DataObjects<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span> (Cayenne persistent objects) are composed of attributes and relationships. Attributes are the simplest object properties (as in "java bean properties") that can be stored in the columns in the database. Those are usually string, numeric, binary or date values. Another type of properties is relationships. They represent related DataObjects (to-one relationships) or collections of DataObjects (to-many relationships). To read and modify attributes and relationships, application code would simply invoke corresponding get or set methods. In case of to-many relationships represented by collections there are also add and remove methods.</p>
+
+<p>Queries discussed in the previous chapter are used to obtain the initial sets of DataObjects. After that a graph of persistent objects is navigated and modified via relationship methods, thus hiding the underlying relational storage complexity and giving application a nice object view of the relevant subset of the database data.</p>
+
+<p>Examples of working with attributes and relationships are given later in this chapter.</p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataObjects/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DVModeler%20GUI%20Tool/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,62 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - DVModeler GUI Tool</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">DVModeler GUI Tool</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a><ul>
+<li><a href="../../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html">DVModeler GUI Tool</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataView Concepts/index.html">DataView Concepts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataViews in Action/index.html">DataViews in Action</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/Swing Applications/index.html">Swing Applications</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>DVModeler is a Java GUI tool to work with DataViews configuration included in Cayenne projects. Steps needed to start DVModeler are similar to that of CayenneModeler. Main class is <tt>org.objectstyle.cayenne.dataview.dvmodeler.Main</tt>. For convenience Cayenne distribution provides run scripts to start DVModeler on Windows and UNIX platforms. To take advantage of these scripts, user must set CAYENNE_HOME (optional) and JAVA_HOME environment variables as described in <a href="../../../../Documentation/User Guide/Installation/index.html" title="Installation">Installation</a>.</p>
+
+<p>To run DVModeler, simply doubleclick the appropriate script. Alternatively it can be run from the command line.</p>
+
+<p>Windows:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>%CAYENNE_HOME%\bin\dvmodeler.bat
+</pre>
+</div></div>
+<p>UNIX:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>$CAYENNE_HOME/bin/dvmodeler.sh
+</pre>
+</div></div></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/cell-editors1.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/cell-editors1.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/cell-editors1.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/cell-renderers.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/cell-renderers.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/cell-renderers.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/dataview-structure.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/dataview-structure.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/dataview-structure.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/dataview-usecases.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/dataview-usecases.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/dataview-usecases.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/domodels.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/domodels.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/domodels.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/format-factory.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/format-factory.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/format-factory.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataView%20Concepts/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,94 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - DataView Concepts</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">DataView Concepts</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a><ul>
+<li><a href="../../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html">DVModeler GUI Tool</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataView Concepts/index.html">DataView Concepts</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataViews in Action/index.html">DataViews in Action</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/Swing Applications/index.html">Swing Applications</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div id="ConfluenceContent"><h3><a name="DataViewConcepts-DataViewHierarchy"></a>DataView Hierarchy</h3>
+
+<p>The class diagram on the figure below captures the structure of Data Views and how they rely on the classes in the Cayenne subpackages. Single DataView object is the root of the hierarchy. It serves as a container for ObjEntityViews from one or more DataView configuration files. Just like entities in the DataMaps, ObjEntityViews can freely refer to each other whether they are defined in the same configuration file or different ones. The recommended practice is to store closely related ObjEntityViews in the same XML "module" and define several "modules" based on the criterion of such closeness. When you load the list of XML files into the DataView, all the relationships are resolved automatically and the ObjEntityViews share the same namespace (so they must have different names even if they are located in different XML files).</p>
+
+<p>The diagram also shows that DataView is associated with several classes such as EntityResolver, DataTypeSpec, FormatFactory. The instances of these classes participate in the process of loading actual Data View files.</p>
+
+<p>The main unit of any Data View is ObjEntityView. It always refers to an ObjEntity defined in one of the used DataMaps and defines various presentation rules for this entity. There can be several ObjEntityViews for an ObjEntity, each of them utilized by an application when appropriate. EntityResolver finds the corresponding ObjEntities by the names as the Data View is being loaded. Every ObjEntityView must have a name unique in the DataView context.</p>
+
+<p>ObjEntityViews contain fields called ObjEntityViewFields. They must be named uniquely within an ObjEntityView. The fields can be of two sorts. The regular "nocalc" fields reference ObjAttributes in the ObjEntity referred by the parent ObjEntityView. There may be several fields for a given ObjAttribute in the ObjEntityView. A field describes the following view parameters:</p>
+
+<ul>
+ <li>How the related ObjAttribute should be rendered and edited.</li>
+ <li>The data type and the formats to use in the presentation layer.</li>
+ <li>The caption that is usually used to name a table column or to label an input control in a form.</li>
+ <li>Editability and visibility of the attribute</li>
+ <li>An order in which the fields appear as columns in a JTable or in a form with the preferred index.</li>
+</ul>
+
+
+<p>The other type of ObjEntityViewFields is "lookup" fields. They point to the fields defined in other ObjEntityViews so the actual values to display, edit, or select from come from those referenced fields. Such a lookup field corresponds to an ObjRelationship with the ObjEntity referred by this its ObjEntityView as a source and the ObjEntity referred by the lookup ObjEntityView as a target instead of an ObjAttribute. Next the field identifies which lookup ObjEntityView and which particular field it wants to use as a lookup. These dependencies are resolved when the data views are loaded into memory. Class LookupCache helps maintain and map to data objects lists of values used in lookup combo boxes and lists. Thus you can describe the rules of visual editing the relationships or make aggregated views base on the related entities.<br/>
+<img src="format-factory.gif" align="absmiddle" border="0" /></p>
+
+
+<h3><a name="DataViewConcepts-FieldDataTypes"></a>Field Data Types</h3>
+<p>Cayenne defines the mapping between several Java Class types and JDBC types. It is convenient to use and sufficient in many cases but there are all sorts of situations when one would like to define more specific data types to make use of, especially for the presentation purposes. In many cases when Integer is used as a flag you would like to map it to Boolean. Or you may have a Money type or Date type that holds only year, month, and day values, and so forth.</p>
+
+<p>ObjEntityViewFields address that by providing an easily extensible system of data types often used in the business applications. This system takes care of converting values back and forth between Cayenne data types and application specific data types. It relies on two classes DataTypeEnum and DataTypeSpec, both of them can be extended to define new types of any sorts. While the entire thing may seem redundant at the first glance, actually, it is a powerful concept that can save a lot of time spent on the manual conversions.</p>
+
+<h3><a name="DataViewConcepts-FormatFactory"></a>FormatFactory</h3>
+<p>FormatFactory shown on the next figure provides the means to create instances of the edit and display formats used by ObjEntityViewFields. There are several formats defined in the java.text package. In addition the dataview library defines convenient MapFormat somewhat similar to java.text.ChoiceFormat. instead of formatting doubles by inclusion in range criterion as ChoiceFormat does it maps a set of objects of any type to string values. For example you can map Booleans to "Sure" and "No way" strings or you can map String keys to some descriptive String values, etc. It is easy for users to add custom formats of their own. They should subclass FormatFactory and create new Builders for their formats. That done, all they need is to configure the display and edit formats in ObjEntityViewFields with the class names of their Format classes and the patterns (and, maybe, some other properties).<br/>
+<img src="format-factory.gif" align="absmiddle" border="0" /></p>
+
+
+<h3><a name="DataViewConcepts-CellRenderersandCellEditors"></a>CellRenderers and CellEditors</h3>
+<p>The following figure presents the utility class CellRenderers and several ready-to-use cell renderers for different types of ObjEntityViewFields. They are used in JTables, JLists, and JComboBoxes. The methods defined in the CellRenderers class will save your time when configuring a JTable to render values of the types available for use with ObjEntityViewFields<br/>
+<img src="cell-renderers.gif" align="absmiddle" border="0" /></p>
+
+<p>The purpose of CellEditors is the same as that of CellRenderers. The editors are used when there is a need to edit data in JTables and such.<br/>
+<img src="cell-editors1.gif" align="absmiddle" border="0" /></p>
+
+<p>The convenient notion of DataObjectList is defined in the library. It is a specialized container to store Cayenne DataObjects (usually of the same type). It fires events when modified and DOTableModel, DOListModel, DOComboBoxModel wrap it and being configured with an ObjEntityView / Field are handy to provide access to these data objects with JTables, JLists, and JComboBoxes. In fact, they make the visual components data aware.<br/>
+<img src="domodels.gif" align="absmiddle" border="0" /></p>
+
+
+<h3><a name="DataViewConcepts-MiscellaneousFeatures"></a>Miscellaneous Features</h3>
+<p>One more useful feature is a centralized EventDispatcher within the DataView class. It is used by the fields to fire the events whenever their values are changed. Thus the ObjAttribute/ObjRelationship modifications can be easily propagated to all the listening components. </p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataView Concepts/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataViews in Action/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/DataViews%20in%20Action/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataViews in Action/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataViews in Action/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,98 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - DataViews in Action</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">DataViews in Action</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a><ul>
+<li><a href="../../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html">DVModeler GUI Tool</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataView Concepts/index.html">DataView Concepts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataViews in Action/index.html">DataViews in Action</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/DataViews/Swing Applications/index.html">Swing Applications</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Here we illustrate the discussion of DataViews with configuration samples and code snippets. Cayenne project DTD file supports references to data view configuration files. This information is loaded into the Cayenne Configuration instance along with the DataDomain, DataNode, and DataMap entries. Since the DataView functionality is optional and would not be very useful in some deployment scenarios (server-side applications) the DataView configiuration itself is not loaded at the time of initialization. Neither DataView instances are created by the configuration process. A DataView can be created in a Swing application with the code similar to the following:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">//Assume, <span class="code-keyword">this</span> is your Cayenne Configuration instance.
+</span>Configuration cayenneConfiguration = ...;
+
+<span class="code-comment">//You will need to setup a Cayenne EntityResolver in your DataView
+</span><span class="code-comment">//For example you can retrieve it from the DataContext in use
+</span><span class="code-comment">//with dataContext.getEntityResolver();
+</span><span class="code-comment">//or construct your own composite one, spanning several Data Domains.
+</span>EntityResolver entityResolver = ...;
+
+<span class="code-comment">//Create <span class="code-keyword">new</span> DataView instance, and set its entityResolver
+</span><span class="code-comment">//*before* loading the actual configuration
+</span>DataView dataView = <span class="code-keyword">new</span> DataView();
+dataView.setEntityResolver(entityResolver);
+
+<span class="code-comment">//Load the configuration
+</span>cayenneConfiguration.loadDataView(dataView);
+
+<span class="code-comment">//Here we go. Our Data View is ready to be used in the application
+</span><span class="code-comment">//This way you can create several of them, completely separated <span class="code-keyword">if</span> needed.</span></pre>
+</div></div>
+
+<p>It is worth mentioning one instance of DataView serves to incorporate several Data View configurations saved in different files. Therefore it defines single namespace and easily resolves inter-configuration references among the ObjEntityViews</p>
+
+<p>Next, let us see how a Swing table model and JTable can be configured with our Data View to display and edit a list of data objects.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">DataView dataView = ...;
+
+JTable featureTable = ...;
+ObjEntityView featureView = dataView.getObjEntityView(<span class="code-quote">"ProductFeatureView"</span>);
+
+<span class="code-comment">// This is a descendant of javax.swing.table.AbstractTableModel
+</span>DOTableModel tableModel = <span class="code-keyword">new</span> DOTableModel();
+tableModel.setView(featureView);
+
+<span class="code-comment">// Retrieve a list of data objects (with SelectQuery, say)
+</span><span class="code-comment">// and initialize the model with it
+</span>DataObjectList featureDataObjects = ...;
+tableModel.setDataObjects(matrixEntries);
+
+featureTable.setModel(tableModel);
+
+<span class="code-comment">// set the apropriate TableCellRenderers and Editors
+</span><span class="code-keyword">new</span> CellRenderers().installRenderers(featureTable);
+<span class="code-keyword">new</span> CellEditors().installEditors(featureTable);</pre>
+</div></div>
+
+<p>In fact, there is many more cool things you could do with DataViews to build your Cayenne enabled Swing rich client faster and cleaner, and separate the GUI related stuff from your domain logic defining the clear declarative rules telling the framework how to interprete, render, and edit the ObjEntities and DataObjects your application relies upon. </p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/DataViews in Action/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/dataview-usecases.gif
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/Swing%20Applications/dataview-usecases.gif?rev=405581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/dataview-usecases.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/Swing%20Applications/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,56 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Swing Applications</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Swing Applications</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a><ul>
+<li><a href="../../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html">DVModeler GUI Tool</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataView Concepts/index.html">DataView Concepts</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/DataViews in Action/index.html">DataViews in Action</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/Swing Applications/index.html">Swing Applications</a><ul>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Those who have experience of Swing GUI development knows how much time it takes to work out all the minutest details of formatting, in-place input validation, handling the interactive data modification, enforcing naming, order, and formatting consistensy, etc. Whenever the domain or requirements change (e.g. new attributes are added to an ObjEntity, formats or captions of data are modified, or relationships change their meaning) developers are faced with the necessity to go through the number of Swing data models, panels, various helpers fishing out the bits of code to be corrected.</p>
+
+<p>Another problem is the need for quick and easy prototyping of data aware GUIs. Those who, at one time or another, worked with Borland VCL for C++ or Delphi or DataExpress/dbSwing for Java and similar frameworks can recall how painless it was to create a rough prototype of the GUI working with the relational database and bind it to the actual data. That was possible due to the layer of easily configured data aware classes and components. And once the working prototype had been ready, refinining it used to be a very simple task.</p>
+
+<p>Cayenne DataViews solve these problems. Data Views act as a bridge between the domain defined in terms of Cayenne DataObjects and a presentation layer built with Swing. Potentially they can be used in the Web environment as well, but Swing integration is the main direction. Conceptually, Data Views are close to the application facades described, for instance, by <span class="nobr"><a href="http://www.martinfowler.com/apsupp/appfacades.pdf" title="Visit page outside Confluence" rel="nofollow">Martin Fowler<sup><img class="rendericon" src="../../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>. The following figure shows the area where Data Views can be applied.<br/>
+<img src="dataview-usecases.gif" align="absmiddle" border="0" /></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><b class="strong">Validation</b><br />The validation rules mentioned in the Use Cases are meant to be "lightweght", i.e. it is generally agreed the validation related code to enforce the business rules should be located in the domain area but, still, there are various checks one could prefer to perform right in the presentation layer like inclusion in a predefined range of values, correct input format, sometimes, even preliminary credit card number validity check with the well known Luhn algorithm, the other kinds of sanity checks. Presently the validation is on the list of the features to be added.</td></tr></table></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/Swing Applications/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/DataViews/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,53 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - DataViews</title>
+ <style type="text/css">@import "../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">DataViews</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../Documentation/User Guide/Deployment/index.html">Deployment</a></li>
+<li><a href="../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/index.html">DataViews</a><ul>
+<li><a href="../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html">DVModeler GUI Tool</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/DataView Concepts/index.html">DataView Concepts</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/DataViews in Action/index.html">DataViews in Action</a></li>
+<li><a href="../../../Documentation/User Guide/DataViews/Swing Applications/index.html">Swing Applications</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne takes care of managing persistence layer for all types of applications - web, rich client, command line, etc. With DataViews Cayenne extends into the area of integrating such persistent layer with Swing GUI.</p>
+
+<p>DataViews define various presentation parameters of the DataObjects in an XML format. Just like DataMaps are edited using CayenneModeler, DataViews are edited with <a href="../../../Documentation/User Guide/DataViews/DVModeler GUI Tool/index.html" title="DVModeler GUI Tool">DVModeler GUI tool</a>. Runtime DataView classes are a part of the main Cayenne JAR file.</p>
+
+<p>For manual editing of the DataViews, DataView DTD is included in the distribution. It is pretty small and the names are self-explanatory once you become familiar with the Data View structure described in this chapter.</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><b class="strong">JDOM Note</b><br />DataViews use JDOM, so in addition to the jar files required by a regular Cayenne application, DataViews-based application must have access to JDOM jars. JDOM can be downloaded from <span class="nobr"><a href="http://www.jdom.org/" title="Visit page outside Confluence" rel="nofollow">http://www.jdom.org/<sup><img class="rendericon" src="../../../images/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"/></sup></a></span>.</td></tr></table></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/DataViews/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Configuring Logging/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Deployment/Configuring%20Logging/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Configuring Logging/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Configuring Logging/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,114 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Configuring Logging</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Configuring Logging</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a><ul>
+<li><a href="../../../../Documentation/User Guide/Deployment/Configuring Logging/index.html">Configuring Logging</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Customizing Configuration/index.html">Customizing Configuration</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Deployment with Ant/index.html">Deployment with Ant</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Standalone Applications/index.html">Standalone Applications</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Using JNDI/index.html">Using JNDI</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Web Applications/index.html">Web Applications</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>Cayenne logging is based on Log4J package from Jakarta Apache Project. This is the most powerful and flexible logging framework available in Java. Log4J configuration is normally done using a property file. Later in this chapter we explain how Cayenne loads configuration files and how to customize this process. Format of the entries in this file is described in the Log4j documentation. Here is a sample configuration file contents:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre># General Log4J stuff
+log4j.rootLogger=WARN, A1
+log4j.appender.A1=org.apache.log4j.ConsoleAppender
+log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+log4j.appender.A1.layout.ConversionPattern=cayenne %-5p [%t %d{MM-dd HH:mm:ss}] %c{1}: %m%n
+
+# indiv. packages configuration - turning on the packages that we care about
+#log4j.logger.org.objectstyle.cayenne = INFO
+
+# This is the logger that controls SQL output
+# Setting the level to INFO or DEBUG will turn the logs on
+log4j.logger.org.objectstyle.cayenne.access.QueryLogger = INFO
+</pre>
+</div></div>
+
+<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><b class="strong">Users of Other Logging Frameworks</b><br />If your application uses another package for its own logging purposes (like JDK 1.4 java.util.logging, or commons-logging from Jakarta), Cayenne Log4J-based logging will not interfere with your other logging configurations.</td></tr></table>
+
+<table cellpadding='5' width='85%' cellspacing='8px' class='tipMacro' border="0" align='center'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="../../../../images/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b class="strong">Log4J Users</b><br />If your application already uses Log4J, Cayenne will simply use your existing configuration.</td></tr></table>
+
+<h3><a name="ConfiguringLogging-EssentialLoggers"></a>Essential Loggers</h3>
+<p>SQL Tracing. Very important logging feature of Cayenne is tracing the execution of SQL statements. If configured appropriately, Cayenne will log opened connections, executed queries, and DDL statements. This is extremely important in understanding what is going on in the application, tracing bugs, etc. Logger that is responsible for SQL logging is "org.objectstyle.cayenne.access.QueryLogger". Its default logging level is INFO, so the following lines in the configuration file will turn it on or off:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre># Turn SQL tracing on
+log4j.logger.org.objectstyle.cayenne.access.QueryLogger = INFO
+
+# Turn SQL tracing off, e.g. to increase performance
+log4j.logger.org.objectstyle.cayenne.access.QueryLogger = WARN
+</pre>
+</div></div>
+
+<p>When SQL tracing is turned off, it is possible to log the execution of only certain queries or commits by manually increasing the logging level of just a specific query above the level configured for the QueryLogger. This is a very convenient feature for debugging the code, since it reduces the level of noise in the logs, focusing attention on the queries that are important. This API is discussed in the FAQ.</p>
+
+<p>Tracing Configuration Loading. Cayenne XML files may contain errors, or maybe missing or inaccessible by the application; there maybe lots of other reasons why Cayenne fails to startup, from missing JDBC drivers to misspelled database URLs. To trace configuration loading process, you will need to turn on the following loggers:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>log4j.logger.org.objectstyle.cayenne.conf = DEBUG
+log4j.logger.org.objectstyle.cayenne.util = DEBUG
+</pre>
+</div></div>
+
+<h3><a name="ConfiguringLogging-DefaultConfiguration"></a>Default Configuration</h3>
+<p>Default behaviour of Cayenne is to look for a file called cayenne-log.properties, first in the directory $HOME/.cayenne/, then in the CLASSPATH (i.e. a file called .cayenne/cayenne-log.properties at the root of one of the locations accessible by the ClassLoader). $HOME is a system specific home directory of a user running the application. If you don't know what it is, try printing it from Java like this: System.out.println(System.getProperty("user.home")).</p>
+
+<p>If you don't explicitly create this file, Cayenne will use the one included in cayenne.jar (and therefore guaranteed to be in the CLASSPATH). This means - no special logging configuration is required, Cayenne will just work out of the box.</p>
+
+<h3><a name="ConfiguringLogging-CustomConfigurationFile"></a>Custom Configuration File</h3>
+<p>If you are not satisfied with the default location or default file name of the logging configuration, you can supply your own:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-comment">// Obtain the URL of the custom configuration file
+</span>java.net.URL url = ....;
+
+<span class="code-comment">// configure cayenne logging
+</span><span class="code-comment">// note that URL can be <span class="code-keyword">null</span>, resulting in <span class="code-keyword">default</span> settings
+</span>org.objectstyle.cayenne.conf.Configuration.configureCommonLogging(url);</pre>
+</div></div>
+<p>It is important to execute this code before any calls to Cayenne are made in the application, or otherwise it will have no effect on logging.</p>
+
+<h3><a name="ConfiguringLogging-ConfiguringLog4JoutsideofCayenne"></a>Configuring Log4J outside of Cayenne</h3>
+
+<p>Finally, if your application already uses Log4J and implements its own logic to configure logging, it would be undesirable for Cayenne to use its default behavior and override any application settings. Also it is convenient to use a single logging configuration file per application. Cayenne detects if Log4J has already been started and will stop any attempts to configure logging. This means that Log4J services must be configured prior to any calls to Cayenne. </p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Configuring Logging/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Customizing Configuration/index.html
URL: http://svn.apache.org/viewcvs/incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User%20Guide/Deployment/Customizing%20Configuration/index.html?rev=405581&view=auto
==============================================================================
--- incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Customizing Configuration/index.html (added)
+++ incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Customizing Configuration/index.html Tue May 9 18:10:42 2006
@@ -0,0 +1,101 @@
+<html>
+ <head>
+ <title>Cayenne Documentation - Customizing Configuration</title>
+ <style type="text/css">@import "../../../../style.css";</style>
+ </head>
+<body>
+ <div class="header">
+ <div style="float: left;"><a href="http://objectstyle.org/cayenne/"><img src="../../../../images/logo.gif" align="absmiddle" border="0"></a></div>
+ <span class="logoSpaceLink"><a href="../../../../index.html">Cayenne User Documentation</a></span><br />
+ <span class="pagetitle">Customizing Configuration</span>
+ </div>
+<div id="cayenne_toc">
+<ul>
+<li><a href="../../../../Documentation/User Guide/Introduction/index.html">Introduction</a></li>
+<li><a href="../../../../Documentation/User Guide/Installation/index.html">Installation</a></li>
+<li><a href="../../../../Documentation/User Guide/Quick Start/index.html">Quick Start</a></li>
+<li><a href="../../../../Documentation/User Guide/Design/index.html">Design</a></li>
+<li><a href="../../../../Documentation/User Guide/Generating Classes/index.html">Generating Classes</a></li>
+<li><a href="../../../../Documentation/User Guide/DataContext/index.html">DataContext</a></li>
+<li><a href="../../../../Documentation/User Guide/Queries/index.html">Queries</a></li>
+<li><a href="../../../../Documentation/User Guide/DataObjects/index.html">DataObjects</a></li>
+<li><a href="../../../../Documentation/User Guide/Stored Procedures/index.html">Stored Procedures</a></li>
+<li><a href="../../../../Documentation/User Guide/Expressions/index.html">Expressions</a></li>
+<li><a href="../../../../Documentation/User Guide/Performance Tuning/index.html">Performance Tuning</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/index.html">Deployment</a><ul>
+<li><a href="../../../../Documentation/User Guide/Deployment/Configuring Logging/index.html">Configuring Logging</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Customizing Configuration/index.html">Customizing Configuration</a><ul>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Deployment with Ant/index.html">Deployment with Ant</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Standalone Applications/index.html">Standalone Applications</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Using JNDI/index.html">Using JNDI</a></li>
+<li><a href="../../../../Documentation/User Guide/Deployment/Web Applications/index.html">Web Applications</a></li>
+</ul>
+</li>
+<li><a href="../../../../Documentation/User Guide/Ant Tasks/index.html">Ant Tasks</a></li>
+<li><a href="../../../../Documentation/User Guide/Access Stack Internals/index.html">Access Stack Internals</a></li>
+<li><a href="../../../../Documentation/User Guide/DataViews/index.html">DataViews</a></li>
+</ul>
+</div>
+<div id="ConfluenceContent"><p>A user can create her own subclass of Configuration and use it instead of the classes provided by Cayenne. Custom subclasses are usually created to load configuration files from non-standard locations, to automatically configure Cayenne during certain events that happen in deployment containers, etc. Cayenne provides a few implementations of Configuration discussed later in this chapter.</p>
+
+<p>To ensure that Cayenne uses the correct Configuration class, it must be initialized properly before any calls to Configuration are made:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.conf.Configuration
+...
+<span class="code-object">Class</span> myConfigSubclass = my.<span class="code-keyword">package</span>.ConfigSubclass.class;
+Configuration.initializeSharedConfiguration(myConfigSubclass);</pre>
+</div></div>
+<p>After this code is executed, any subsequent calls to <tt>Configuration.getSharedConfiguration()</tt> will return an instance of the custom class instead of <tt>DefaultConfiguration</tt>.</p>
+
+<p>Another useful feature is the customization of the resource lookup strategy implemented by the existing classes. Currently, both <tt>DefaultConfiguration</tt> and <tt>FileConfiguration</tt> offer the possibility to add additional paths which will be searched for resources.</p>
+
+<h3><a name="CustomizingConfiguration-DefaultConfiguration"></a>DefaultConfiguration</h3>
+
+<p><tt>DefaultConfiguration</tt> uses the application's class path for locating configuration files; this works for both "expanded" class paths and JAR files. "Out of the box" only resources on the top level of the class path are found; very often it is convenient to have a subdirectory ('package') with configuration files. There are two ways to make Configuration find these files:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.conf.DefaultConfiguration;
+...
+DefaultConfiguration conf = <span class="code-keyword">new</span> DefaultConfiguration();
+conf.addClassPath(<span class="code-quote">"my/<span class="code-keyword">package</span>/conf"</span>);
+Configuration.initializeSharedConfiguration(conf);</pre>
+</div></div>
+<p>Alternatively you can place an empty subclass of DefaultConfiguration into your package and use that class directly:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> my.<span class="code-keyword">package</span>.conf.MyPackageConfiguration;
+...
+Configuration.initializeSharedConfiguration(<span class="code-keyword">new</span> MyPackageConfiguration());</pre>
+</div></div>
+
+<h3><a name="CustomizingConfiguration-FileConfiguration"></a>FileConfiguration</h3>
+
+<p><tt>FileConfiguration</tt> uses the regular file system to load its files, and works very silimar to <tt>DefaultConfiguration</tt>:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.conf.FileConfiguration;
+...
+<span class="code-object">String</span> fileName = <span class="code-quote">"/some/path/to/my-cayenne.xml"</span>;
+FileConfiguration conf = <span class="code-keyword">new</span> FileConfiguration(<span class="code-keyword">new</span> File(fileName));
+Configuration.initializeSharedConfiguration(conf);</pre>
+</div></div>
+<p>The fileName argument can be absolute or relative to the application's working directory, and is checked for accessibility. A more flexible lookup can be done by using the name without any path and adding search paths:</p>
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">import</span> org.objectstyle.cayenne.conf.FileConfiguration;
+...
+FileConfiguration conf = <span class="code-keyword">new</span> FileConfiguration(<span class="code-quote">"my-cayenne.xml"</span>);
+conf.addFilesystemPath(<span class="code-quote">"a/relative/path"</span>);
+conf.addFilesystemPath(<span class="code-quote">"/another/absolute/path"</span>);
+conf.addFilesystemPath(<span class="code-keyword">new</span> File(<span class="code-quote">"/some/path/that/must/exist/"</span>));
+Configuration.initializeSharedConfiguration(conf);</pre>
+</div></div>
+<p>The difference between the String and File arguments is that the latter are checked for existence. Both variants can be absolute or relative, and are evaluated in the order in which they are added to the Configuration.</p></div>
+</div>
+ <div class="clearer">.</div>
+ <div style="height: 12px; background-image: url('../../../../images/border_bottom.gif'); background-repeat: repeat-x;"></div>
+
+ <div class="smalltext copyright">
+ Copyright ©2001-2006 ObjectStyle Group and content authors
+ </div>
+
+</body>
+</html>
Propchange: incubator/cayenne/main/trunk/cayenne/cayenne-other/wiki-docs/Documentation/User Guide/Deployment/Customizing Configuration/index.html
------------------------------------------------------------------------------
svn:eol-style = native