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 2014/01/28 19:12:25 UTC
svn commit: r1562135 - in
/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx:
cayenne-mapping-structure.xml cayennemodeler-application.xml
Author: aadamchik
Date: Tue Jan 28 18:12:24 2014
New Revision: 1562135
URL: http://svn.apache.org/r1562135
Log:
user guide - mapping
(cherry picked from commit aa5349811cd9efdc999b11534ec320ac4100cc3a)
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml?rev=1562135&r1=1562134&r2=1562135&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml Tue Jan 28 18:12:24 2014
@@ -19,32 +19,77 @@
<title>Cayenne Mapping Structure</title>
<section xml:id="cayenne-project">
<title>Cayenne Project</title>
+ <para>A Cayenne project is an XML representation of a model connecting database schema with
+ Java classes. A project is normally created and manipulated via CayenneModeler GUI and
+ then used to initialize Cayenne runtime. A project is made of one or more files. There's
+ always a root project descriptor file in any valid project. It is normally called
+ <code>cayenne-xyz.xml</code>, where "xyz" is the name of the project.</para>
+ <para>Project descriptor can reference DataMap files, one per DataMap. DataMap files are
+ normally called <code>xyz.map.xml</code>, where "xyz" is the name of the DataMap. For
+ legacy reasons this naming convention is different from the convention for the root
+ project descriptor above, and we may align it in the future versions. Here is how a
+ typical project might look on the file
+ system:<programlisting>~: ls -l
+total 24
+-rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
+-rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</programlisting></para>
+ <para>DataMap are referenced by name in the root
+ descriptor:<programlisting><map name="datamap"/></programlisting></para>
+ <para>Map files are resolved by Cayenne by appending <code>.map.xml</code>" extension to the
+ map name, and resolving the resulting string relative to the root descriptor URI. The
+ following sections discuss varios ORM model objects, without regards to their XML
+ representation. XML format details are really unimportant to the Cayenne users.</para>
</section>
<section xml:id="datamap">
<title>DataMap</title>
+ <para>DataMap is a container of persistent entities and other object-relational metadata.
+ DataMap provides developers with a scope to organize their entities, but it does not
+ provide a namespace for entities. In fact all DataMaps present in runtime are combined
+ in a single namespace. Each DataMap must be associated with a DataNode. This is how
+ Cayenne knows which database to use when running a query.</para>
</section>
<section xml:id="datanode">
<title>DataNode</title>
+ <para>DataNode is model of a database. It is actually pretty simple. It has an arbitrary
+ user-provided name and information needed to create or locate a JDBC DataSource. Most
+ projects only have one DataNode, though there may be any number of nodes if
+ needed.</para>
</section>
<section xml:id="dbentity">
<title>DbEntity</title>
+ <para>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes
+ that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships
+ are not strictly tied to FK constraints in DB, and should be mapped for all logical
+ "relationships" between the tables.</para>
</section>
<section xml:id="objentity">
<title>ObjEntity</title>
- <section xml:id="mapping-objattributes-to-custom-classes">
- <title>Mapping ObjAttributes to Custom Classes</title>
- </section>
+ <para>ObjEntity is a model of a single persistent Java class. ObjEntity is made of
+ ObjAttributes and ObjRelationships. Both correspond to entity class properties. However
+ ObjAttributes represent "simple" properties (normally things like String, numbers,
+ dates, etc.), while ObjRelationships correspond to properties that have a type of
+ another entity. </para>
+ <para>ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each
+ ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped
+ DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from
+ another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called
+ "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a
+ chain of DbRelationships ("flattened" ObjRelationship).</para>
+ <para>ObjEntities may also contain mapping of their lifecycle callback methods.</para>
</section>
<section xml:id="embeddable">
<title>Embeddable</title>
+ <para>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity,
+ but maps to multiple columns in the database.</para>
</section>
<section xml:id="procedure">
<title>Procedure</title>
+ <para>A model of a stored procedure in the database.</para>
</section>
<section xml:id="query">
<title>Query</title>
- </section>
- <section xml:id="listeners-and-callbacks">
- <title>Listeners and Callbacks</title>
+ <para>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created
+ in the code. Depending on the circumstances the users may take one or the other
+ approach.</para>
</section>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml?rev=1562135&r1=1562134&r2=1562135&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml Tue Jan 28 18:12:24 2014
@@ -51,6 +51,9 @@
skip entities that are mapped to CayenneDataObject explicitly or have no class
mapping.</para>
</section>
+ <section xml:id="mapping-objattributes-to-custom-classes">
+ <title>Mapping ObjAttributes to Custom Classes</title>
+ </section>
<section xml:id="modeling-pk-generation-strategy">
<title>Modeling Primary Key Generation Strategy</title>
</section>