Chapter 4. Including Cayenne in a Project

Table of Contents

Jar Files and Dependencies
Maven Projects
Ant Projects

Jar Files and Dependencies

Cayenne distribution contains the following core runtime jars in the distribution lib directory:

  • cayenne-server-x.x.jar - contains full Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications will use only this file.

  • cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on the client in an ROP application.

  • Other cayenne-* jars - various Cayenne extensions.

When using cayenne-server-x.x.jar you'll need a few third party jars (all included in lib/third-party directory of the distribution):

Cayenne integrates with various caching, clustering and other frameworks. These optional integrations will require other third-party jars that the users will need to obtain on their own.

Maven Projects

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:

<dependency>
   <groupId>org.apache.cayenne</groupId>
   <artifactId>cayenne-server</artifactId>
   <version>X.Y.Z</version>
</dependency>

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 org.apache.cayenne.plugins:maven-cayenne-plugin.

cgen

cgen is a maven-cayenne-plugin 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.

By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.

Table 4.1. cgen required parameters
Name Type Description
map File DataMap XML file which serves as a source of metadata for class generation. E.g. ${project.basedir}/src/main/resources/my.map.xml
destDir File Root destination directory for Java classes (ignoring their package names).

Table 4.2. cgen optional parameters
Name Type Description
additionalMaps File 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.
client boolean Whether we are generating classes for the client tier in a Remote Object Persistence application. "False" by default.
embeddableTemplate String Location of a custom Velocity template file for Embeddable class generation. If omitted, default template is used.
embeddableSuperTemplate String Location of a custom Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.
encoding String 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.
excludeEntities String 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.
includeEntities String A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to include from template generation. By default all DataMap entities are included.
makePairs boolean If "true" (a recommended default), will generate subclass/superclass pairs, with all generated code placed in superclass.
mode String 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.
overwrite boolean Only has effect when "makePairs" is set to "false". If "overwrite" os "true", will overwrite older versions of generated classes.
superPkg String Java package name of generated superclasses. Only has effect if "makepairs" and "usePkgPath" are set to "true" (both are true by default). Defines a common package for all generated Java classes. If omitted, each superclass will be placed in the same package as subclass.
superTemplate String 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.
template String Location of a custom Velocity template file for ObjEntity class generation. If omitted, default template is used.
usePkgPath boolean 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.

Example - a typical class generation scenario, where pairs of classes are generated, and superclasses are placed in a separate package:

<plugin>
    <groupId>org.apache.cayenne.plugins</groupId>
    <artifactId>maven-cayenne-plugin</artifactId>
    <version>X.Y.Z</version>

    <!--
    There's an intermittent problem when using Maven/cgen in Eclipse with  m2eclipse plugin that
    requires placing "configuration" section at the plugin level, instead of execution
    level.
    -->
    <configuration>
        <map>${project.basedir}/src/main/resources/my.map.xml</map>
        <destDir>${project.basedir}/src/main/java</destDir>
        <superPkg>org.example.model.auto</superPkg>
    </configuration>

    <executions>
        <execution>
            <goals>
                <goal>cgen</goal>
            </goals>
        </execution>
    </executions>
</plugin>

cdbgen

cdbgen is a maven-cayenne-plugin goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.

Table 4.3. cdbgen required parameters
Name Type Description
map File DataMap XML file which serves as a source of metadata for DB schema generation. E.g. ${project.basedir}/src/main/resources/my.map.xml
driver String A class of JDBC driver to use for the target database.
url String JDBC connection URL of a target database.

Table 4.4. cdbgen optional parameters
Name Type Description
adapter String 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.
createFK boolean Indicates whether cdbgen should create foreign key constraints. Default is "true".
createPK boolean Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".
createTables boolean Indicates whether cdbgen should create new tables. Default is "true".
dropPK boolean Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".
dropTables boolean Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".
password String Database user password.
username String Database user name.

Example - creating a DB schema on a local HSQLDB database:

<plugin>
    <groupId>org.apache.cayenne.plugins</groupId>
    <artifactId>maven-cayenne-plugin</artifactId>
    <version>X.Y.Z</version>

    <executions>
        <execution>
            <configuration>
                <map>${project.basedir}/src/main/resources/my.map.xml</map>
                <url>jdbc:hsqldb:hsql://localhost/testdb</url>
                <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
                <driver>org.hsqldb.jdbcDriver</driver>
                <username>sa</username>
            </configuration>
            <goals>
                <goal>cdbgen</goal>
            </goals>
        </execution>
    </executions>
</plugin>

cdbimport

cdbimport is a maven-cayenne-plugin 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, which may be necessary if you are also using the cgen task.

Table 4.5. cdbimport required parameters
Name Type Description
map File DataMap XML file which is the destination of the schema import. Maybe an existing file. If this file does not exist, it is created when cdbimport is executed. E.g. ${project.basedir}/src/main/resources/my.map.xml
driver String A class of JDBC driver to use for the target database.
url String JDBC connection URL of a target database.

Table 4.6. cdbimport optional parameters
Name Type Description
adapter String 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.
importProcedures boolean Indicates whether stored procedures should be imported from the database. Default is false.
meaningfulPk boolean Indicates whether primary keys should be mapped as attributes of the ObjEntity. Default is false.
namingStrategy String The naming strategy used for mapping database names to object entity names. Default is org.apache.cayenne.map.naming.SmartNamingStrategy.
overwriteExisting boolean Indicates whether existing DB and object entities should be overwritten. This is an all-or-nothing setting. If you need finer granularity, use the CayenneModeler. Default is "true".
password String Database user password.
procedurePattern String Pattern to match stored procedure names against for import. Default is to match all stored procedures. This value is only meaningful if importProcedures is true.
schemaName String Database schema to import tables/stored procedures from.
tablePattern String Pattern to match table names against for import. Default is to match all tables.
username String Database user name.

Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) :

<plugin>
    <groupId>org.apache.cayenne.plugins</groupId>
    <artifactId>maven-cayenne-plugin</artifactId>
    <version>X.Y.Z</version>

    <executions>
        <execution>
            <configuration>
                <map>${project.basedir}/src/main/resources/my.map.xml</map>
                <url>jdbc:mysql://127.0.0.1/mydb</url>
                <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
                <driver>com.mysql.jdbc.Driver</driver>
                <username>sa</username>
            </configuration>
            <goals>
                <goal>cdbimport</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Ant Projects

cgen

cdbgen

cdbimport

This is an Ant counterpart of "cdbimport" goal of maven-cayenne-plugin described above. It has exactly the same properties. Here is a usage example:

 <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
    driver="com.mysql.jdbc.Driver" 
    url="jdbc:mysql://127.0.0.1/mydb" 
    username="sa"/> 

cdataport