cgen is an Ant task that generates and maintains DataObjects source files based on Cayenne DataMap. 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

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 Java class generation. If omitted, default template is used. No
supertemplate Location of Velocity template file for Java 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 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.1") 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

Parameters specified as nested elements

Attribute Description Required
config CGen with version="1.2" also supports VPP config nested elements for configuring the velocity template engine and adding objects to the velocity template. You can also reference a vppconfig element declared outside of the CGen task, but you'll need to insure that both vppconfig and cgen have been loaded with the same classloader by using the same ant taskdef loaderRef value for both tasks. See the VPP VPPConfig Manual page for complete information. No

Examples

Load the Ant task (note: if you already loaded all Cayenne tasks via an antlib taskdef described before, this step is not needed): 

<taskdef name="cgen" classname="org.apache.cayenne.tools.CayenneGenerator">
    <classpath refid="classpath"/>
</taskdef>

Here is an example of using CGen to generate DataObject subclass/superclass pairs from DataMap located in "src/datamap.xml". All generated subclasses and superclasses will be saved in the same directory "src/java/dobj" regardless of their package names:

<cgen map="src/datamap.xml" destDir="src/java/dobj" usepkgpath="false"/>

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

<cgen map="src/datamap.xml" destDir="src/doc/web" makepairs="false" usepkgpath="false"
    template="EntityReport.vm" includeEntities="Artist*" outputPattern="*Report.html"/>

Here is an example of using CGen with a nested config element:

<cgen map="src/datamap.xml"
    destDir="src/doc/web"
    makepairs="false"
    usepkgpath="false"
    template="EntityReport.vm"
    includeEntities="Artist*"
    outputPattern="*Report.html">
    <config>
        <context>
            <property key="myPropertyName" value="myPropertyValue" />
            <tool key="myToolName" className="org.myDomain.MyTool" />
        </context>
    </config>
</cgen>

Here is an example of using CGen with vppconfig:

<typedef name="vppconfig"
    classname="foundrylogic.vpp.VPPConfig"
    loaderref="aclasspathloader">
    <classpath refid="aclasspath"/>
</typedef>

<vppconfig id="myconfig">
    <context>
        <property key="myPropertyName" value="myPropertyValue" />
        <tool key="myToolName" className="org.myDomain.MyTool" />
    </context>
</vppconfig>

<cgen map="src/datamap.xml"
    destDir="src/doc/web"
    makepairs="false"
    usepkgpath="false"
    template="EntityReport.vm"
    includeEntities="Artist*"
    outputPattern="*Report.html">
    <config refid="myconfig" />
</cgen>