| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1.3"> |
| <link rel="apple-touch-icon" sizes="180x180" href="/img/favicon/apple-touch-icon-04cb17e028.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/img/favicon/favicon-32x32-12431ee8eb.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/img/favicon/favicon-16x16-4f316e4d55.png"> |
| <link rel="manifest" href="/img/favicon/manifest-65e6aaa49e.json"> |
| <link rel="mask-icon" href="/img/favicon/safari-pinned-tab-558c1991b1.svg" color="#dc5656"> |
| <link rel="shortcut icon" href="/img/favicon/favicon-6cef91375b.ico"> |
| <meta name="msapplication-TileColor" content="#ffffff"> |
| <meta name="msapplication-TileImage" content="/img/favicon/mstile-144x144-34e7696278.png"> |
| <meta name="msapplication-config" content="/img/favicon/browserconfig-82ff158058.xml"> |
| <meta name="theme-color" content="#ffffff"> |
| <link rel="stylesheet" href="https://cayenne.apache.org/css/styles-9ee2e6e330.css"/> |
| <script src="https://cayenne.apache.org/js/bundle-c0e6356367.js"></script> |
| <title>Cayenne Guide 5.0 · Cayenne Mapping Structure · Apache Cayenne</title> |
| </head> |
| <body class="cd-head"> |
| <header class="page-header"> |
| <nav id="topbar" class="bg-dark" aria-label="breadcrumb" role="navigation"> |
| <ul class="breadcrumb breadcrumb-sm breadcrumb-dark container mb-0"> |
| <li class="breadcrumb-item dropdown"> |
| <a class="dropdown-toggle text-nowrap pr-1" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| <img class="mw-15px mr-1" src="/img/feather-641aa69d09.svg" />Apache Software Foundation</a> |
| <div class="dropdown-menu rounded-0" aria-labelledby="navbarDropdown"> |
| <a class="dropdown-item" href="https://www.apache.org">Apache Homepage</a> |
| <a class="dropdown-item" href="https://www.apache.org/licenses/">License</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <a class="dropdown-item" href="https://www.apache.org/security/">Security</a> |
| <a class="dropdown-item" href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy</a> |
| <a class="ml-1 mt-1 acevent" data-format="wide" data-mode="dark" data-width="120"></a> |
| </div> |
| </li> |
| </ul> |
| </nav> |
| <nav class="navbar navbar-expand-lg navbar-dark bg-primary"> |
| <div class="container"> |
| <a class="navbar-brand" href="https://cayenne.apache.org/"> |
| <img src="/img/logo_mono_full-d7a19eef61.svg" alt="Apache Cayenne" /> |
| </a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#mainMenu" aria-controls="mainMenu" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| |
| <div class="collapse navbar-collapse" id="mainMenu"> |
| <ul class="navbar-nav mt-3 mt-lg-0 mr-auto"> |
| |
| <li class="nav-item"> |
| <a class="nav-link" href="/download/">DOWNLOAD</a> |
| </li> |
| |
| <li class="nav-item"> |
| <a class="nav-link" href="/docs/4.2/getting-started-guide/">DOCUMENTATION</a> |
| </li> |
| |
| <li class="nav-item"> |
| <a class="nav-link" href="/about/support/">SUPPORT</a> |
| </li> |
| |
| </ul> |
| <ul class="navbar-nav flex-row justify-content-center mt-2 mt-lg-0 mb-2 mb-lg-0 " id="social-links-menu"> |
| <li class="nav-item d-flex"> |
| <a class="nav-link d-flex justify-content-center align-items-center" href="https://github.com/apache/cayenne"> |
| <img src="/img/icon_octocat_stars-c24dac94b8.svg" alt="GitHub" /> |
| </a> |
| </li> |
| <li class="nav-item d-flex"> |
| <a class="nav-link d-flex justify-content-center align-items-center" href="https://twitter.com/ApacheCayenne"> |
| <img src="/img/icon_twitter-220a129d14.svg" alt="Twitter" /> |
| </a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| </header> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <main> |
| <div class="cd-top-sidebar bb"> |
| <div class="container"> |
| <div class="row no-gutters"> |
| |
| <div class="col-12 col-lg-4 col-xl-3 br cd-sidebar1"> |
| <ul class="nav" role="tablist"> |
| <li class="nav-item dropdown mw-100"> |
| <a class="nav-link dropdown-toggle text-truncate" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false"> |
| Cayenne Version 5.0 |
| </a> |
| <div class="dropdown-menu"> |
| <a class="dropdown-item" href="/docs/5.0/cayenne-guide/">Version 5.0 (Alpha)</a><a class="dropdown-item" href="/docs/4.2/getting-started-guide/">Version 4.2 (Stable)</a><a class="dropdown-item" href="/docs/4.1/getting-started-guide/">Version 4.1 (Stable)</a><a class="dropdown-item" href="/docs/4.0/getting-started-guide/">Version 4.0 (Aging)</a><a class="dropdown-item" href="/docs/3.1/getting-started-guide/">Version 3.1 (Legacy)</a> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="col-12 col-lg-8 col-xl-9"> </div> |
| </div> |
| </div> |
| </div> |
| <div class="container"> |
| <div class="row no-gutters "> |
| <div class="col-12 col-lg-4 col-xl-3 br py-2 bg-gray-100 cd-sidebar"> |
| <div class="tab-content" id="cd-docs-nav"> |
| |
| <div class="cd-toc-item"> |
| |
| <span class="cd-toc-link active">Cayenne Guide 5.0</span><div id="toc" class="toc toc-side"> |
| <div id="toctitle"> |
| Table of Contents |
| </div> |
| <ul class="sectlevel1 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/object-relational-mapping-with-cayenne" class="nav-link" id="object-relational-mapping-with-cayenne">1. Object Relational Mapping with Cayenne</a> |
| <ul class="sectlevel2 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/setup" class="nav-link" id="setup">1.1. Setup</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/cayenne-mapping-structure" class="nav-link" id="cayenne-mapping-structure">1.2. Cayenne Mapping Structure</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/cayenne-modeler" class="nav-link" id="cayenne-modeler">1.3. CayenneModeler Application</a></li> |
| </ul></li> |
| <li><a href="/docs/5.0/cayenne-guide/cayenne-framework" class="nav-link" id="cayenne-framework">2. Cayenne Framework</a> |
| <ul class="sectlevel2 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/including-cayenne-in-project" class="nav-link" id="including-cayenne-in-project">2.1. Including Cayenne in a Project</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/starting-cayenne" class="nav-link" id="starting-cayenne">2.2. Starting Cayenne</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/persistent-objects-objectcontext" class="nav-link" id="persistent-objects-objectcontext">2.3. Persistent Objects and ObjectContext</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/expressions" class="nav-link" id="expressions">2.4. Expressions</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/orderings" class="nav-link" id="orderings">2.5. Orderings</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/queries" class="nav-link" id="queries">2.6. Queries</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/lifecycle-events" class="nav-link" id="lifecycle-events">2.7. Lifecycle Events</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/performance-tuning" class="nav-link" id="performance-tuning">2.8. Performance Tuning</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/customizing-cayenne-runtime" class="nav-link" id="customizing-cayenne-runtime">2.9. Customizing Cayenne Runtime</a></li> |
| </ul></li> |
| <li><a href="/docs/5.0/cayenne-guide/db-first-flow" class="nav-link" id="db-first-flow">3. DB-First Flow</a> |
| <ul class="sectlevel2 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/re-introduction" class="nav-link" id="re-introduction">3.1. Introduction</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/re-filtering" class="nav-link" id="re-filtering">3.2. Filtering</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/re-relationships-loading-control" class="nav-link" id="re-relationships-loading-control">3.3. Other Settings</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/re-modeler" class="nav-link" id="re-modeler">3.4. Reverse Engineering in Cayenne Modeler</a></li> |
| </ul></li> |
| <li><a href="/docs/5.0/cayenne-guide/additional-modules" class="nav-link" id="additional-modules">4. Additional Modules</a> |
| <ul class="sectlevel2 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/ext-cache-invalidation" class="nav-link" id="ext-cache-invalidation">4.1. Cache Invalidation Extension</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-commit-log" class="nav-link" id="ext-commit-log">4.2. Commit log extension</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-crypto" class="nav-link" id="ext-crypto">4.3. Crypto extension</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-jcache" class="nav-link" id="ext-jcache">4.4. JCache integration</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-project-compatibility" class="nav-link" id="ext-project-compatibility">4.5. Project compatibility extension</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-velocity" class="nav-link" id="ext-velocity">4.6. Apache Velocity Extension</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ext-osgi" class="nav-link" id="ext-osgi">4.7. Cayenne OSGI extension</a></li> |
| </ul></li> |
| <li><a href="/docs/5.0/cayenne-guide/build_tools" class="nav-link" id="build_tools">5. Build Tools</a> |
| <ul class="sectlevel2 nav"> |
| <li><a href="/docs/5.0/cayenne-guide/maven_plugin" class="nav-link" id="maven_plugin">5.1. Maven Plugin</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/gradle_plugin" class="nav-link" id="gradle_plugin">5.2. Gradle Plugin</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/ant_tasks" class="nav-link" id="ant_tasks">5.3. Ant Tasks</a></li> |
| </ul></li> |
| <li><a href="/docs/5.0/cayenne-guide/appendix-a-configuration-properties" class="nav-link" id="appendix-a-configuration-properties">6. Appendix A. Configuration Properties</a></li> |
| <li><a href="/docs/5.0/cayenne-guide/appendix-b-service-collections" class="nav-link" id="appendix-b-service-collections">7. Appendix B. Service Collections</a></li> |
| </ul> |
| </div> |
| </div> |
| |
| <div class="cd-toc-item"> |
| </div> |
| </div> |
| </div> |
| |
| <div class="col-12 col-lg-8 col-xl-9 py-3 pl-lg-5 cd-content"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <article> |
| <header> |
| </header> |
| <section> |
| <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"><map name="datamap"/></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> |
| </section> |
| <footer> |
| <div class="row"> |
| <div class="col-6 col-md-3 text-center text-md-left"> |
| |
| </div> |
| <div class="col-18 col-md-9 text-center text-md-right"> |
| |
| <a class="btn btn-link" href='/docs/5.0/cayenne-guide/cayenne-modeler/'> |
| <span class="d-block d-md-none text-muted">Next: </span> |
| Next: Cayenne Guide 5.0 · CayenneModeler Application |
| <i class="small fa fa-chevron-right ml-3l2 d-none d-md-inline"></i> |
| </a> |
| |
| </div> |
| </div> |
| </footer> |
| </article> |
| |
| |
| <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=5c836e39-be6b-4a21-a946-a97b5b69f172" /> |
| </div> |
| </div> |
| </div> |
| </main> |
| |
| <footer class="bg-dark"> |
| <div class="footer-nav container text-center text-lg-left pb-3"> |
| <div class="row pt-5 pb-3"> |
| |
| <div class="col-sm-6 col-lg-3"> |
| <h4>About</h4> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a href="/why-cayenne.html">Why Cayenne?</a> |
| </li> |
| |
| <li> |
| <a href="/download/">Download</a> |
| </li> |
| |
| <li> |
| <a href="/success-stories.html">Success Stories</a> |
| </li> |
| |
| <li> |
| <a href="/about/support/">Support</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="col-sm-6 col-lg-3"> |
| <h4>Documentation</h4> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a href="/docs/4.0/getting-started-guide/">Getting Started (4.0)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.1/getting-started-guide/">Getting Started (4.1)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.2/getting-started-guide/">Getting Started (4.2)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.0/cayenne-guide/">Cayenne Guide (4.0)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.1/cayenne-guide/">Cayenne Guide (4.1)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.2/cayenne-guide/">Cayenne Guide (4.2)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.1/getting-started-db-first/">Database First tutorial (4.1)</a> |
| </li> |
| |
| <li> |
| <a href="/docs/4.2/getting-started-db-first/">Database First tutorial (4.2)</a> |
| </li> |
| |
| <li> |
| <a href="/legacy/legacy-docs/">Legacy Documentation</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="col-sm-6 col-lg-3"> |
| <h4>Collaboration</h4> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a href="https://issues.apache.org/jira/browse/CAY">Bug/Feature Tracker</a> |
| </li> |
| |
| <li> |
| <a href="/mailing-lists.html">Mailing Lists</a> |
| </li> |
| |
| <li> |
| <a href="/dev/code-repository.html">Code Repository</a> |
| </li> |
| |
| <li> |
| <a href="/dev/">Developer Guide</a> |
| </li> |
| |
| <li> |
| <a href="/how-can-i-help.html">How can I help?</a> |
| </li> |
| |
| <li> |
| <a href="/contributors.html">Contributors</a> |
| </li> |
| |
| <li> |
| <a href="/thanks.html">Thanks</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="col-sm-6 col-lg-3"> |
| <h4>News</h4> |
| <ul class="list-multiline-items list-unstyled mb-0"> |
| |
| <li> |
| <time datetime="2023-05-25 18:00:00 +0300 +0300" class="xsmall d-block">May 25, 2023</time> |
| <a href="/2023/05/cayenne-42-final-released/">Cayenne 4.2 Final Released</a> |
| </li> |
| |
| <li> |
| <time datetime="2023-03-02 12:00:00 +0300 +0300" class="xsmall d-block">Mar 02, 2023</time> |
| <a href="/2023/03/cayenne-403-released/">Cayenne 4.0.3 Released</a> |
| </li> |
| |
| <li> |
| <time datetime="2022-12-05 12:00:00 +0300 +0300" class="xsmall d-block">Dec 05, 2022</time> |
| <a href="/2022/12/cayenne-42rc2-released/">Cayenne 4.2 Release Candidate 2 Released</a> |
| </li> |
| |
| </ul> |
| <a class="btn-link text-uppercase xsmall" href="https://cayenne.apache.org/news"> |
| More news |
| <i class="fa fa-lg fa-long-arrow-right" aria-hidden="true"></i> |
| </a> |
| </div> |
| </div> |
| <hr class="mt-0 mb-3" /> |
| <p class="copy xsmall text-center mw-75 mx-auto mb-0"> |
| Copyright © 2001-2024 Apache Software Foundation. Apache Cayenne, Cayenne, Apache, the Apache feather logo, and the Apache Cayenne project logo are trademarks of The Apache Software Foundation. |
| <a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a>. |
| <img class="d-block mx-auto mt-2" src="/img/logo_mono-3302daa3cf.svg" alt="Apache Cayenne" /> |
| </p> |
| </div> |
| </footer> |
| </body> |
| </html> |
