cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1562136 - in /cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx: cayenne-mapping-structure.xml cayennemodeler-application.xml
Date Tue, 28 Jan 2014 18:13:03 GMT
Author: aadamchik
Date: Tue Jan 28 18:13:03 2014
New Revision: 1562136

user guide - mapping


Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
Tue Jan 28 18:13:03 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.
+            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
+        <para>Project descriptor can reference DataMap files, one per DataMap. DataMap
files are
+            normally called <code></code>, where "xyz" is the name
of the DataMap. For
+            legacy reasons this naming convention is different from the convention for the
+            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</programlisting></para>
+        <para>DataMap are referenced by name in the root
+            descriptor:<programlisting>&lt;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
+            representation. XML format details are really unimportant to the Cayenne users.</para>
     <section xml:id="datamap">
+        <para>DataMap is a container of persistent entities and other object-relational
+            DataMap provides developers with a scope to organize their entities, but it does
+            provide a namespace for entities. In fact all DataMaps present in runtime are
+            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 xml:id="datanode">
+        <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.
+            projects only have one DataNode, though there may be any number of nodes if
+            needed.</para>
     <section xml:id="dbentity">
+        <para>DbEntity is a model of a single DB table or view. DbEntity is made of
+            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 xml:id="objentity">
-        <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.
+            ObjAttributes represent "simple" properties (normally things like String, numbers,
+            dates, etc.), while ObjRelationships correspond to properties that have a type
+            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
+            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 xml:id="embeddable">
+        <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 xml:id="procedure">
+        <para>A model of a stored procedure in the database.</para>
     <section xml:id="query">
-    </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>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
Tue Jan 28 18:13:03 2014
@@ -51,6 +51,9 @@
             skip entities that are mapped to CayenneDataObject explicitly or have no class
+    <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>

View raw message