| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title xmlns:d="http://docbook.org/ns/docbook">Chapter 4. Including Cayenne in a Project</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 4.0 documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 4.0"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="prev" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="next" href="starting-cayenne.html" title="Chapter 5. Starting Cayenne"><script xmlns:d="http://docbook.org/ns/docbook" type="text/javascript"> |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-7036673-1']); |
| _gaq.push(['_trackPageview']); |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header"><tr><th class="versioninfo">v.4.0 (4.0.M5)</th><th align="center">Chapter 4. Including Cayenne in a Project</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Part II. Cayenne Framework</a></th><td width="20%" align="right"> <a accesskey="n" href="starting-cayenne.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="including-cayenne-in-project"></a>Chapter 4. Including Cayenne in a Project</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="including-cayenne-in-project.html#jar-files-and-depdendencies">Jar Files</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#d0e387">Dependencies</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#maven-projects">Maven Projects</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#ant-projects">Ant Projects</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="jar-files-and-depdendencies"></a>Jar Files</h2></div></div></div><p>This is an overview of Cayenne jars that is agnostic of the build tool used. The |
| following are the important libraries:</p><p> |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="italic">cayenne-di-4.0.M5.jar</span> - Cayenne |
| dependency injection (DI) container library. All applications will require |
| this file.</p></li><li class="listitem"><p><span class="italic">cayenne-server-4.0.M5.jar</span> - contains |
| main Cayenne runtime (adapters, DB access classes, etc.). Most applications |
| will require this file.</p></li><li class="listitem"><p><span class="emphasis"><em>cayenne-client-4.0.M5.jar</em></span> - a |
| client-side runtime for <a class="link" href="introduction-to-rop.html" title="Chapter 13. Introduction to ROP">ROP |
| applications</a>.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne tools extensions.</p></li></ul></div><p> |
| </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="d0e387"></a>Dependencies</h2></div></div></div><p>With modern build tools like Maven and Gradle, you should not worry about tracking |
| dependencies. If you have one of those, you can skip this section and go straight to the |
| Maven section below. However if your environment requires manual dependency resolution |
| (like Ant), the distribution provides all of Cayenne jars plus a minimal set of |
| third-party dependencies to get you started in a default configuration. Check |
| <code class="code">lib</code> and <code class="code">lib/third-party</code> folders for those.</p><p>Dependencies for non-standard configurations will need to be figured out by the users |
| on their own. Check <code class="code">pom.xml</code> files of the corresponding Cayenne modules in |
| one of the searchable Maven archives out there to get an idea of those dependencies |
| (e.g. <a class="link" href="http://search.maven.org" target="_top">http://search.maven.org</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><p>If you are using Maven, you won't have to deal with figuring out the dependencies. You |
| can simply include cayenne-server artifact in your |
| POM:</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><dependency></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><groupId></span>org.apache.cayenne<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></groupId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><artifactId></span>cayenne-server<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></artifactId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><version></span>4.0.M5<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></version></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></dependency></span></pre><p>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project |
| tasks, such as synching generated Java classes with the mapping, described in the |
| following subsection. The full plugin name is |
| <code class="code">org.apache.cayenne.plugins:cayenne-maven-plugin</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">cayenne-maven-plugin</code> goal that generates and maintains |
| source (.java) files of persistent objects based on a DataMap. By default, it is |
| bound to the generate-sources phase. If "makePairs" is set to "true" (which is the |
| recommended default), this task will generate a pair of classes |
| (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be |
| changed manually, since they are always overwritten. Subclasses are never |
| overwritten and may be later customized by the user. If "makePairs" is set to |
| "false", a single class will be generated for each ObjEntity. </p><p>By creating custom templates, you can use cgen to generate other output (such as |
| web pages, reports, specialized code templates) based on DataMap information.</p><p> |
| </p><div class="table"><a name="d0e432"></a><p class="title"><b>Table 4.1. cgen required parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="79%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">map</code> |
| </td> |
| <td>File</td> |
| <td>DataMap XML file which serves as a source of metadata for class |
| generation. E.g. |
| <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><div class="table"><a name="d0e467"></a><p class="title"><b>Table 4.2. cgen optional parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="79%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">additionalMaps</code> |
| </td> |
| <td>File</td> |
| <td>A directory that contains additional DataMap XML files that may be |
| needed to resolve cross-DataMap relationships for the the main |
| DataMap, for which class generation occurs.</td> |
| </tr><tr> |
| <td><code class="code">client</code></td> |
| <td>boolean</td> |
| <td>Whether we are generating classes for the client tier in a Remote |
| Object Persistence application. "False" by default.</td> |
| </tr><tr> |
| <td><code class="code">destDir</code></td> |
| <td>File</td> |
| <td>Root destination directory for Java classes (ignoring their package |
| names). The default is "src/main/java".</td> |
| </tr><tr> |
| <td><code class="code">embeddableTemplate</code></td> |
| <td>String</td> |
| <td>Location of a custom Velocity template file for Embeddable class |
| generation. If omitted, default template is used.</td> |
| </tr><tr> |
| <td><code class="code">embeddableSuperTemplate</code></td> |
| <td>String</td> |
| <td>Location of a custom Velocity template file for Embeddable |
| superclass generation. Ignored unless "makepairs" set to "true". If |
| omitted, default template is used.</td> |
| </tr><tr> |
| <td><code class="code">encoding</code></td> |
| <td>String</td> |
| <td>Generated files encoding if different from the default on current |
| platform. Target encoding must be supported by the JVM running the |
| build. Standard encodings supported by Java on all platforms are |
| US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See |
| javadocs for java.nio.charset.Charset for more information.</td> |
| </tr><tr> |
| <td><code class="code">excludeEntities</code></td> |
| <td>String</td> |
| <td>A comma-separated list of ObjEntity patterns (expressed as a perl5 |
| regex) to exclude from template generation. By default none of the |
| DataMap entities are excluded.</td> |
| </tr><tr> |
| <td><code class="code">includeEntities</code></td> |
| <td>String</td> |
| <td>A comma-separated list of ObjEntity patterns (expressed as a perl5 |
| regex) to include from template generation. By default all DataMap |
| entities are included.</td> |
| </tr><tr> |
| <td><code class="code">makePairs</code></td> |
| <td>boolean</td> |
| <td>If "true" (a recommended default), will generate subclass/superclass |
| pairs, with all generated code placed in superclass.</td> |
| </tr><tr> |
| <td><code class="code">mode</code></td> |
| <td>String</td> |
| <td>Specifies class generator iteration target. There are three possible |
| values: "entity" (default), "datamap", "all". "entity" performs one |
| generator iteration for each included ObjEntity, applying either |
| standard to custom entity templates. "datamap" performs a single |
| iteration, applying DataMap templates. "All" is a combination of |
| entity and datamap.</td> |
| </tr><tr> |
| <td><code class="code">overwrite</code></td> |
| <td>boolean</td> |
| <td>Only has effect when "makePairs" is set to "false". If "overwrite" |
| is "true", will overwrite older versions of generated classes.</td> |
| </tr><tr> |
| <td><code class="code">superPkg</code></td> |
| <td>String</td> |
| <td>Java package name of all generated superclasses. If omitted, each |
| superclass will be placed in the subpackage of its subclass called |
| "auto". Doesn't have any effect if either "makepairs" or |
| "usePkgPath" are false (both are true by default). </td> |
| </tr><tr> |
| <td><code class="code">superTemplate</code></td> |
| <td>String</td> |
| <td>Location of a custom Velocity template file for ObjEntity superclass |
| generation. Only has effect if "makepairs" set to "true". If |
| omitted, default template is used.</td> |
| </tr><tr> |
| <td><code class="code">template</code></td> |
| <td>String</td> |
| <td>Location of a custom Velocity template file for ObjEntity class |
| generation. If omitted, default template is used.</td> |
| </tr><tr> |
| <td><code class="code">usePkgPath</code></td> |
| <td>boolean</td> |
| <td>If set to "true" (default), a directory tree will be generated in |
| "destDir" corresponding to the class package structure, if set to |
| "false", classes will be generated in "destDir" ignoring their |
| package.</td> |
| </tr><tr> |
| <td><code class="code">createPropertyNames</code></td> |
| <td>boolean</td> |
| <td>If set to "true", will generate String Property names. |
| Default is "false"</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> Example - a typical class generation scenario, where pairs of classes are |
| generated with default Maven source destination and superclass |
| package:</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><plugin></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><groupId></span>org.apache.cayenne.plugins<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></groupId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><artifactId></span>cayenne-maven-plugin<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></artifactId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><version></span>4.0.M5<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></version></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><configuration></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><map></span>${project.basedir}/src/main/resources/my.map.xml<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></map></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></configuration></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goal></span>cgen<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goal></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></plugin></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbgen"></a>cdbgen</h3></div></div></div><p><code class="code">cdbgen</code> is a <code class="code">cayenne-maven-plugin</code> goal that drops and/or generates |
| tables in a database on Cayenne DataMap. By default, it is bound to the |
| pre-integration-test phase. |
| </p><div class="table"><a name="d0e692"></a><p class="title"><b>Table 4.3. cdbgen required parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="79%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">map</code> |
| </td> |
| <td>File</td> |
| <td>DataMap XML file which serves as a source of metadata for DB schema |
| generation. E.g. |
| <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td> |
| </tr><tr> |
| <td><code class="code">dataSource</code> |
| </td> |
| <td>XML</td> |
| <td>An object that contains Data Source parameters</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p> |
| </p><div class="table"><a name="d0e742"></a><p class="title"><b>Table 4.4. <dataSource> parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="7%"><col width="72%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Required</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">driver</code></td> |
| <td>String</td> |
| <td>Yes</td> |
| <td>A class of JDBC driver to use for the target database.</td> |
| </tr><tr> |
| <td><code class="code">url</code></td> |
| <td>String</td> |
| <td>Yes</td> |
| <td>JDBC URL of a target database.</td> |
| </tr><tr> |
| <td><code class="code">username</code></td> |
| <td>String</td> |
| <td>No</td> |
| <td>Database user name.</td> |
| </tr><tr> |
| <td><code class="code">password</code></td> |
| <td>String</td> |
| <td>No</td> |
| <td>Database user password.</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p> |
| </p><div class="table"><a name="d0e828"></a><p class="title"><b>Table 4.5. cdbgen optional parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="79%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">adapter</code> |
| </td> |
| <td>String</td> |
| <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While |
| this attribute is optional (a generic JdbcAdapter is used if not |
| set), it is highly recommended to specify correct target |
| adapter.</td> |
| </tr><tr> |
| <td><code class="code">createFK</code></td> |
| <td>boolean</td> |
| <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td> |
| </tr><tr> |
| <td><code class="code">createPK</code></td> |
| <td>boolean</td> |
| <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is |
| "true".</td> |
| </tr><tr> |
| <td><code class="code">createTables</code></td> |
| <td>boolean</td> |
| <td>Indicates whether cdbgen should create new tables. Default is "true".</td> |
| </tr><tr> |
| <td><code class="code">dropPK</code></td> |
| <td>boolean</td> |
| <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is |
| "false".</td> |
| </tr><tr> |
| <td><code class="code">dropTables</code></td> |
| <td>boolean</td> |
| <td>Indicates whether cdbgen should drop the tables before attempting to create new ones. |
| Default is "false".</td> |
| </tr><tr> |
| <td><code class="code">password</code></td> |
| <td>String</td> |
| <td>Database user password.</td> |
| </tr><tr> |
| <td><code class="code">username</code></td> |
| <td>String</td> |
| <td>Database user name.</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p>Example - creating a DB schema on a local HSQLDB |
| database:</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><plugin></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><groupId></span>org.apache.cayenne.plugins<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></groupId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><artifactId></span>cayenne-maven-plugin<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></artifactId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><version></span>4.0.M5<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></version></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><configuration></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><map></span>${project.basedir}/src/main/resources/my.map.xml<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></map></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><adapter></span>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></adapter></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><dataSource></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><url></span>jdbc:hsqldb:hsql://localhost/testdb<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></url></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><driver></span>org.hsqldb.jdbcDriver<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></driver></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><username></span>sa<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></username></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></dataSource></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></configuration></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goal></span>cdbgen<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goal></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></plugin></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbimport"></a>cdbimport</h3></div></div></div><p><code class="code">cdbimport</code> is a <code class="code">cayenne-maven-plugin</code> goal that generates a DataMap |
| based on an existing database schema. By default, it is bound to the |
| generate-sources phase. This allows you to generate your DataMap prior to building |
| your project, possibly followed by "cgen" execution to generate the classes. |
| CDBImport plugin described in details in chapter <a class="link" href="re-introduction.html" title="Chapter 19. Introduction">"DB-First Flow"</a> |
| </p><div class="table"><a name="d0e962"></a><p class="title"><b>Table 4.6. cdbimport parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="7%"><col width="72%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Required</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">map</code> |
| </td> |
| <td>File</td> |
| <td>Yes</td> |
| <td>DataMap XML file which is the destination of the schema import. Can |
| be an existing file. If this file does not exist, it is created when |
| cdbimport is executed. E.g. |
| <code class="code">${project.basedir}/src/main/resources/my.map.xml</code>. |
| If "overwrite" is true (the default), an existing DataMap will be |
| used as a template for the new imported DataMap, i.e. all its |
| entities will be cleared and recreated, but its common settings, |
| such as default Java package, will be preserved (unless changed |
| explicitly in the plugin configuration).</td> |
| </tr><tr> |
| <td><code class="code">adapter</code> |
| </td> |
| <td>String</td> |
| <td>No</td> |
| <td>A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is |
| optional. If not specified, AutoAdapter is used, which will attempt |
| to guess the DB type.</td> |
| </tr><tr> |
| <td><code class="code">dataSource</code> |
| </td> |
| <td>XML</td> |
| <td>Yes</td> |
| <td>An object that contains Data Source parameters</td> |
| </tr><tr> |
| <td><code class="code">dbimport</code> |
| </td> |
| <td>XML</td> |
| <td>No</td> |
| <td>An object that contains detailed reverse engineering rules about what DB objects should |
| be processed. For full information about this parameter see <a class="link" href="re-introduction.html" title="Chapter 19. Introduction">"DB-First Flow"</a> chapter.</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p> |
| </p><div class="table"><a name="d0e1058"></a><p class="title"><b>Table 4.7. <dataSource> parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="7%"><col width="72%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Required</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">driver</code></td> |
| <td>String</td> |
| <td>Yes</td> |
| <td>A class of JDBC driver to use for the target database.</td> |
| </tr><tr> |
| <td><code class="code">url</code></td> |
| <td>String</td> |
| <td>Yes</td> |
| <td>JDBC URL of a target database.</td> |
| </tr><tr> |
| <td><code class="code">username</code></td> |
| <td>String</td> |
| <td>No</td> |
| <td>Database user name.</td> |
| </tr><tr> |
| <td><code class="code">password</code></td> |
| <td>String</td> |
| <td>No</td> |
| <td>Database user password.</td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p> |
| </p><div class="table"><a name="d0e1144"></a><p class="title"><b>Table 4.8. <dbimport> parameters</b></p><div class="table-contents"><table frame="void"><col width="14%"><col width="7%"><col width="79%"><thead><tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr></thead><tbody><tr> |
| <td><code class="code">defaultPackage</code></td> |
| <td>String</td> |
| <td>A Java package that will be set as the imported DataMap default and |
| a package of all the persistent Java classes. This is a required |
| attribute if the "map" itself does not already contain a default |
| package, as otherwise all the persistent classes will be mapped with |
| no package, and will not compile.</td> |
| </tr><tr> |
| <td><code class="code">forceDataMapCatalog</code></td> |
| <td>boolean</td> |
| <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) |
| may sometimes be undesirable. If this is the case then setting |
| <code class="code">forceDataMapCatalog</code> to <code class="code">true</code> will set |
| DbEntity catalog to one in the DataMap. Default value is |
| <code class="code">false</code>. </td> |
| </tr><tr> |
| <td><code class="code">forceDataMapSchema</code></td> |
| <td>boolean</td> |
| <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) |
| may sometimes be undesirable. If this is the case then setting |
| <code class="code">forceDataMapSchema</code> to <code class="code">true</code> will set |
| DbEntity schema to one in the DataMap. Default value is |
| <code class="code">false</code>. </td> |
| </tr><tr> |
| <td><code class="code">meaningfulPkTables</code></td> |
| <td>String</td> |
| <td>A comma-separated list of Perl5 patterns that defines which imported tables should have |
| their primary key columns mapped as ObjAttributes. "*" would |
| indicate all tables.</td> |
| </tr><tr> |
| <td><code class="code">namingStrategy</code></td> |
| <td>String</td> |
| <td> |
| The naming strategy used for mapping database names to object entity |
| names. Default is <code class="code">org.apache.cayenne.dbsync.naming.DefaultObjectNameGenerator</code>. |
| </td> |
| </tr><tr> |
| <td><code class="code">skipPrimaryKeyLoading</code></td> |
| <td>boolean</td> |
| <td>Whether to load primary keys. Default "false".</td> |
| </tr><tr> |
| <td><code class="code">skipRelationshipsLoading</code></td> |
| <td>boolean</td> |
| <td>Whether to load relationships. Default "false".</td> |
| </tr><tr> |
| <td><code class="code">stripFromTableNames</code></td> |
| <td>String</td> |
| <td>Regex that matches the part of the table name that needs to be stripped off when |
| generating ObjEntity name. Here are some examples: <pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment"><!-- Strip prefix --></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><stripFromTableNames></span>^myt_<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></stripFromTableNames></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment"><!-- Strip suffix --></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><stripFromTableNames></span>_s$<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></stripFromTableNames></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment"><!-- Strip multiple occurrences in the middle --></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><stripFromTableNames></span>_abc<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></stripFromTableNames></span></pre> |
| </td> |
| </tr><tr> |
| <td><code class="code">usePrimitives</code></td> |
| <td>boolean</td> |
| <td>Whether numeric and boolean data types should be mapped as Java primitives or Java |
| classes. Default is "true", i.e. primitives will be used.</td> |
| </tr><tr> |
| <td><code class="code">useJava7Types</code></td> |
| <td>boolean</td> |
| <td>Whether <code class="code">DATE</code>, <code class="code">TIME</code> and <code class="code">TIMESTAMP</code> data types should be mapped |
| as <code class="code">java.util.Date</code> or <code class="code">java.time.*</code> classes. |
| Default is "false", i.e. <code class="code">java.time.*</code> will be used.</td> |
| </tr><tr xml:id="cdbimport-rr-parameter"> |
| <td>filters configuration</td> |
| <td>XML</td> |
| <td>Detailed reverse engineering rules about what DB objects should be processed. |
| For full information about this parameter see <a class="link" href="re-introduction.html" title="Chapter 19. Introduction">"DB-First Flow"</a> chapter. |
| Here is some simple example: |
| <pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><dbimport></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><catalog</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"test_catalog"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag">></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><schema</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"test_schema"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag">></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><includeTable></span>.*<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></includeTable></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><excludeTable></span>test_table<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></excludeTable></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></schema></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></catalog></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><includeProcedure</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">pattern</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">".*"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag">/></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></dbimport></span></pre> |
| </td> |
| </tr></tbody></table></div></div><p><br class="table-break"> |
| </p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation |
| compared to the <code class="code">cdbgen</code> example above) |
| :</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><plugin></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><groupId></span>org.apache.cayenne.plugins<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></groupId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><artifactId></span>cayenne-maven-plugin<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></artifactId></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><version></span>4.0.M5<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></version></span> |
| |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><configuration></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><map></span>${project.basedir}/src/main/resources/my.map.xml<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></map></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><dataSource></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><url></span>jdbc:mysql://127.0.0.1/mydb<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></url></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><driver></span>com.mysql.jdbc.Driver<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></driver></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><username></span>sa<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></username></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></dataSource></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><dbimport></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><defaultPackage></span>com.example.cayenne<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></defaultPackage></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></dbimport></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></configuration></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><goal></span>cdbimport<span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goal></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></goals></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></execution></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></executions></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></plugin></span></pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><p>Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen", |
| "cdbimport". Configuration parameters are also similar (except Maven can guess many |
| defaults that Ant can't). To include Ant tasks in the project, use the following |
| Antlib:</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><typedef</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">resource</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"org/apache/cayenne/tools/antlib.xml"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag">></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><classpath></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><fileset</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">dir</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"lib"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> ></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-ant-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-cgen-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-dbsync-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-di-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-project-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"cayenne-server-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"commons-collections-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"commons-lang-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"commons-logging-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"velocity-*.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><include</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">name</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"vpp-2.2.1.jar"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"> /></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></fileset></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></classpath></span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"></typedef></span></pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div><p>This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described |
| above. It has exactly the same properties. Here is a usage |
| example:</p><pre class="programlisting"> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag"><cdbimport</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">map</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"${context.dir}/WEB-INF/my.map.xml"</span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">driver</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"com.mysql.jdbc.Driver"</span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">url</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"jdbc:mysql://127.0.0.1/mydb"</span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">username</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"sa"</span> |
| <span xmlns="http://www.w3.org/1999/xhtml" class="hl-attribute">defaultPackage</span>=<span xmlns="http://www.w3.org/1999/xhtml" class="hl-value">"com.example.cayenne"</span><span xmlns="http://www.w3.org/1999/xhtml" class="hl-tag">/></span> </pre><p> |
| </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. Cayenne Framework </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Starting Cayenne</td></tr></table></div></body></html> |
