Cayenne Mapping Structure

Reply-To: dev@cayenne.apache.org Delivered-To: mailing list commits@cayenne.apache.org Received: (qmail 65563 invoked by uid 99); 28 Jan 2014 18:13:28 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Jan 2014 18:13:28 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Jan 2014 18:13:25 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id B04722388A02; Tue, 28 Jan 2014 18:13:03 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@cayenne.apache.org From: aadamchik@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20140128181303.B04722388A02@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: aadamchik Date: Tue Jan 28 18:13:03 2014 New Revision: 1562136 URL: http://svn.apache.org/r1562136 Log: 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/cayennemodeler-application.xml Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml?rev=1562136&r1=1562135&r2=1562136&view=diff ============================================================================== --- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml (original) +++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml Tue Jan 28 18:13:03 2014 @@ -19,32 +19,77 @@ Cayenne Mapping Structure

Cayenne Project + 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 + cayenne-xyz.xml, where "xyz" is the name of the project. + Project descriptor can reference DataMap files, one per DataMap. DataMap files are + normally called xyz.map.xml, 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:~: 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 + DataMap are referenced by name in the root + descriptor:<map name="datamap"/> + Map files are resolved by Cayenne by appending .map.xml" 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.

DataMap + 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.

DataNode + 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.

DbEntity + 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.

ObjEntity -

- Mapping ObjAttributes to Custom Classes -

+ 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. + 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). + ObjEntities may also contain mapping of their lifecycle callback methods.

Embeddable + 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.

Procedure + A model of a stored procedure in the database.

Query -

- Listeners and Callbacks + 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.

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml?rev=1562136&r1=1562135&r2=1562136&view=diff ============================================================================== --- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml (original) +++ 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 mapping. +

+ Mapping ObjAttributes to Custom Classes +

Modeling Primary Key Generation Strategy