Cayenne User Documentation
maven2-cgen

| This documentation is very much work-in-progress and subject to change.

`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 generator iteration target. "entity" performs one iteration for each selected entity. "datamap" performs one iteration per datamap (This is always one iteration since cgen currently supports specifying one-and-only-one datamap). (Default is "entity") | 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":

    <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>

| The follow example includes the use of Velocity template overriding, which is not yet functional in the plugin.

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>

.
Copyright ©2001-2008 Apache Software Foundation