cgen is an Maven 2 mojo that generates and maintains DataObjects source files based on Cayenne DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (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, cgen can also be used to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.

Parameters (as XML elements)

Attribute Description Required
map DataMap XML file to use as a base for class generation. Yes
additionalMaps Path to additional DataMap XML files to use for class generation. No
destDir Destination directory for Java classes (ignoring their package names). Yes
overwrite If set to "true", will overwrite older versions of generated classes. Ignored unless makepairs is set to "false". No
makePairs If set to "true", will generate subclass/superclass pairs, with all generated code included in superclass (default is "true"). No
template Location of Velocity template file for Entity class generation. If omitted, default template is used. No
superTemplate Location of Velocity template file for Entity superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used. No
embeddableTemplate Location of Velocity template file for Embeddable class generation. If omitted, default template is used. No
embeddableSuperTemplate Location of Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used. No
superPkg Java package name of generated superclasses. Ignored unless "makepairs" set to "true". If omitted, each superclass will be assigned the same package as subclass. Note that having superclass in a different package would only make sense when "usepkgpath" is set to "true". Otherwise classes from different packages will end up in the same directory. No
usePkgPath 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. No
encoding Specify generated file encoding if different from the default on current platform. Target encoding must be supported by the JVM running Ant build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See Sun Java Docs for java.nio.charset.Charset for more information. No
version (deprecated)) Specifies template location and generator behavior. "1.1" is the old behavior, with templates located in "dotemplates" and "classgen" as the only velocity context attribute. "1.2" is the new behavior, with templates located in "dotemplates/v1.2" and "objEntity", "entityUtils", "stringUtils", and "importUtils" in the velocity context. (Default is "1.2") No
excludeEntities Entities (expressed as a perl5 regex) to exclude from template generation. (Default is to include all entities in the DataMap) No
includeEntities Entities (expressed as a perl5 regex) to include in template generation. (Default is to include all entities in the DataMap) No
outputPattern Name of file for generated output. (Default is "*.java") No
mode Specifies class generator iteration target. There are three possible values: "entity" (default), "datamap", "all". "entity" performs one generator iteration for each selected entity, applying standard entity templates (templates can of course be overridden with user defined ones). "datamap" performs a single iteration, applying standard DataMap templates. "All" is a combination of entity and datamap No
client Whether we are generating classes for the client tier in a Remote Object Persistence application. Default is "false" No

Examples

Load the Maven 2 plugin and configure the cgen mojo: 

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.cayenne.plugins</groupId>
      	    <artifactId>maven-cayenne-plugin</artifactId>
      	    <executions>
                <execution>
      		    <id>cgen</id>
      		    <configuration>
      			<!-- Configuration items go in here.  See table, above. -->
      		    </configuration>
      		    <goals>
      			<goal>cgen</goal>
      		    </goals>
      		</execution>
      	    </executions>
        </plugin>
    </plugins>
</build>

Here is an example of using CGen to generate Persistent subclass/superclass pairs from DataMap located in "main/resources/datamap.map.xml".

There's an intermittent problem when using Maven/cgen in Eclipse with m2eclipse plugin that requires placing <configuration>..</configuration> at the plugin level, instead of execution level.
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.cayenne.plugins</groupId>
      	    <artifactId>maven-cayenne-plugin</artifactId>
      	    <executions>
                <execution>
      		    <id>cgen</id>
      		    <configuration>
      			<map>${project.build.sourceDirectory}/../resources/datamap.map.xml</map>
                        <destDir>${project.build.sourceDirectory}</destDir>
      		    </configuration>
      		    <goals>
      			<goal>cgen</goal>
      		    </goals>
      		</execution>
      	    </executions>
        </plugin>
    </plugins>
</build>

Here is an example of using CGen to generate html pages for all entities starting with "Artist" in the DataMap:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.cayenne.plugins</groupId>
      	    <artifactId>maven-cayenne-plugin</artifactId>
      	    <executions>
                <execution>
      		    <id>cgen</id>
      		    <configuration>
      			<map>${project.build.sourceDirectory}/datamap.xml</map>
                        <destDir>${project.build.sourceDirectory}/doc/web</destDir>
                        <makePairs>false</makePairs>
                        <usePkgPath>false</usePkgPath>
                        <template>EntityReport.vm</template>
                        <includeEntities>Artist*</includeEntities>
                        <outputPattern>*Report.html</outputPattern>
      		    </configuration>
      		    <goals>
      			<goal>cgen</goal>
      		    </goals>
      		</execution>
      	    </executions>
        </plugin>
    </plugins>
</build>