---
#  Licensed to the Apache Software Foundation (ASF) under one
#  or more contributor license agreements.  See the NOTICE file
#  distributed with this work for additional information
#  regarding copyright ownership.  The ASF licenses this file
#  to you under the Apache License, Version 2.0 (the
#  "License"); you may not use this file except in compliance
#  with the License.  You may obtain a copy of the License at
#
#    https://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing,
#  software distributed under the License is distributed on an
#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#  KIND, either express or implied.  See the License for the
#  specific language governing permissions and limitations
#  under the License.

title: "Cayenne Guide 5.0 · Cayenne Mapping Structure"
description: "Cayenne Guide 5.0, Cayenne Mapping Structure"
cayenneVersion: "5.0"
cayenneNoToc: true
---
<div class="sect2">
 <h3 id="cayenne-mapping-structure"><a class="anchor" href="#cayenne-mapping-structure"></a>1.2. Cayenne Mapping Structure</h3>
 <div class="sect3">
  <h4 id="cayenne-project"><a class="anchor" href="#cayenne-project"></a>1.2.1. Cayenne Project</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
  <div class="paragraph">
   <p>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:</p>
  </div>
  <div class="listingblock">
   <div class="content">
    <pre>$ 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</pre>
   </div>
  </div>
  <div class="paragraph">
   <p>DataMap are referenced by name in the root descriptor:</p>
  </div>
  <div class="listingblock">
   <div class="content">
    <pre class="highlight"><code class="language-xml xml" data-lang="xml">&lt;map name="datamap"/&gt;</code></pre>
   </div>
  </div>
  <div class="paragraph">
   <p>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 various ORM model objects, without regards to their XML representation. XML format details are really unimportant to the Cayenne users.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="datamap"><a class="anchor" href="#datamap"></a>1.2.2. DataMap</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="datanode"><a class="anchor" href="#datanode"></a>1.2.3. DataNode</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="dbentity"><a class="anchor" href="#dbentity"></a>1.2.4. DbEntity</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="objentity"><a class="anchor" href="#objentity"></a>1.2.5. ObjEntity</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
  <div class="paragraph">
   <p>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).</p>
  </div>
  <div class="paragraph">
   <p>ObjEntities may also contain mapping of their lifecycle callback methods.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="embeddable"><a class="anchor" href="#embeddable"></a>1.2.6. Embeddable</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="procedure"><a class="anchor" href="#procedure"></a>1.2.7. Procedure</h4>
  <div class="paragraph">
   <p>A model of a stored procedure in the database.</p>
  </div>
 </div>
 <div class="sect3">
  <h4 id="query"><a class="anchor" href="#query"></a>1.2.8. Query</h4>
  <div class="paragraph">
   <p>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.</p>
  </div>
 </div>
</div>