| Title: cgen |
| |
| <P><TT>cgen</TT> 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.</P> |
| |
| <P>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.</P> |
| |
| <H3><A name="cgen-Parameters"></A>Parameters</H3> |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Attribute</TH> |
| <TH class="confluenceTh">Description</TH> |
| <TH class="confluenceTh">Required</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">map</TD> |
| <TD class="confluenceTd">DataMap XML file to use as a base for class generation.</TD> |
| <TD class="confluenceTd">Yes</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">additionalMaps</TD> |
| <TD class="confluenceTd">Path to additional DataMap XML files to use for class generation.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">destDir</TD> |
| <TD class="confluenceTd">Destination directory for Java classes (ignoring their package names).</TD> |
| <TD class="confluenceTd">Yes</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">overwrite</TD> |
| <TD class="confluenceTd">If set to "true", will overwrite older versions of generated classes. Ignored unless makepairs is set to "false".</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">makepairs</TD> |
| <TD class="confluenceTd">If set to "true", will generate subclass/superclass pairs, with all generated code included in superclass (default is "true").</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">template</TD> |
| <TD class="confluenceTd">Location of Velocity template file for Entity class generation. If omitted, default template is used.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">supertemplate</TD> |
| <TD class="confluenceTd">Location of Velocity template file for Entity superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">embeddabletemplate</TD> |
| <TD class="confluenceTd"><EM>(added in 3.0)</EM> Location of Velocity template file for Embeddable class generation. If omitted, default template is used.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">embeddablesupertemplate</TD> |
| <TD class="confluenceTd"><EM>(added in 3.0)</EM> Location of Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">superpkg</TD> |
| <TD class="confluenceTd">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.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">usepkgpath</TD> |
| <TD class="confluenceTd">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> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">encoding</TD> |
| <TD class="confluenceTd">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.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd"><EM>version</EM> </TD> |
| <TD class="confluenceTd"><EM><B>(deprecated)</B></EM> Specifies template location and generator behavior. Can either be empty (default) or "1.1" - the old behavior, with templates located in "dotemplates" and "classgen" as the only velocity context attribute. The default behavior, with templates located in "dotemplates/v1.2" and "objEntity", "entityUtils", "stringUtils", and "importUtils" in the velocity context.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">excludeEntities</TD> |
| <TD class="confluenceTd">Entities and Embeddables (expressed as a perl5 regex) to exclude from template generation. Default is to include all entities and embeddables that exist in the DataMap)</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">includeEntities</TD> |
| <TD class="confluenceTd">Entities and Embeddables (expressed as a perl5 regex) to include in template generation. (Default is to include all entities and embeddables that exist in the DataMap</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">outputPattern</TD> |
| <TD class="confluenceTd">Name of file for generated output. (Default is "*.java")</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">mode</TD> |
| <TD class="confluenceTd">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</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">client</TD> |
| <TD class="confluenceTd">Whether we are generating classes for the client tier in a <A href="remote-object-persistence-guide.html" title="Remote Object Persistence Guide">Remote Object Persistence</A> application. Default is "false"</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
| |
| <H3><A name="cgen-Parametersspecifiedasnestedelements"></A>Parameters specified as nested elements</H3> |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Attribute</TH> |
| <TH class="confluenceTh">Description</TH> |
| <TH class="confluenceTh">Required</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">config</TD> |
| <TD class="confluenceTd">CGen with version="1.2" also supports <A href="http://vpp.sourceforge.net/" class="external-link" rel="nofollow">VPP</A> 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 <TT>vppconfig</TT> and <TT>cgen</TT> have been loaded with the same classloader by using the same ant taskdef loaderRef value for both tasks. See the <A href="http://vpp.sourceforge.net/manual/vppconfig.html" class="external-link" rel="nofollow">VPP VPPConfig Manual</A> page for complete information.</TD> |
| <TD class="confluenceTd">No</TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
| |
| <H3><A name="cgen-Examples"></A>Examples</H3> |
| |
| <P>Here is an example of using CGen to generate 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:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-xml"><SPAN class="code-tag"><cgen map=<SPAN class="code-quote">"src/datamap.xml"</SPAN> destDir=<SPAN class="code-quote">"src/java/dobj"</SPAN> usepkgpath=<SPAN class="code-quote">"false"</SPAN>/></SPAN> |
| </PRE> |
| </DIV></DIV> |
| <P>Here is an example of using CGen to generate html pages for all entities starting with "Artist" in the DataMap:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-xml"> |
| <cgen map=<SPAN class="code-quote">"src/datamap.xml"</SPAN> destDir=<SPAN class="code-quote">"src/doc/web"</SPAN> makepairs=<SPAN class="code-quote">"false"</SPAN> usepkgpath=<SPAN class="code-quote">"false"</SPAN> |
| template=<SPAN class="code-quote">"EntityReport.vm"</SPAN> includeEntities=<SPAN class="code-quote">"Artist*"</SPAN> outputPattern=<SPAN class="code-quote">"*Report.html"</SPAN>/> |
| </PRE> |
| </DIV></DIV> |
| |
| <P>Here is an example of using CGen with a nested config element:</P> |
| |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-xml"> |
| <cgen map=<SPAN class="code-quote">"src/datamap.xml"</SPAN> |
| destDir=<SPAN class="code-quote">"src/doc/web"</SPAN> |
| makepairs=<SPAN class="code-quote">"false"</SPAN> |
| usepkgpath=<SPAN class="code-quote">"false"</SPAN> |
| template=<SPAN class="code-quote">"EntityReport.vm"</SPAN> |
| includeEntities=<SPAN class="code-quote">"Artist*"</SPAN> |
| outputPattern=<SPAN class="code-quote">"*Report.html"</SPAN>> |
| <SPAN class="code-tag"><config></SPAN> |
| <SPAN class="code-tag"><context></SPAN> |
| <SPAN class="code-tag"><property key=<SPAN class="code-quote">"myPropertyName"</SPAN> value=<SPAN class="code-quote">"myPropertyValue"</SPAN> /></SPAN> |
| <SPAN class="code-tag"><tool key=<SPAN class="code-quote">"myToolName"</SPAN> className=<SPAN class="code-quote">"org.myDomain.MyTool"</SPAN> /></SPAN> |
| <SPAN class="code-tag"></context></SPAN> |
| <SPAN class="code-tag"></config></SPAN> |
| <SPAN class="code-tag"></cgen></SPAN> |
| </PRE> |
| </DIV></DIV> |
| |
| <P>Here is an example of using CGen with vppconfig:</P> |
| |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-xml"><typedef name=<SPAN class="code-quote">"vppconfig"</SPAN> |
| classname=<SPAN class="code-quote">"foundrylogic.vpp.VPPConfig"</SPAN> |
| loaderref=<SPAN class="code-quote">"aclasspathloader"</SPAN>> |
| <SPAN class="code-tag"><classpath refid=<SPAN class="code-quote">"aclasspath"</SPAN>/></SPAN> |
| <SPAN class="code-tag"></typedef></SPAN> |
| |
| <SPAN class="code-tag"><vppconfig id=<SPAN class="code-quote">"myconfig"</SPAN>></SPAN> |
| <SPAN class="code-tag"><context></SPAN> |
| <SPAN class="code-tag"><property key=<SPAN class="code-quote">"myPropertyName"</SPAN> value=<SPAN class="code-quote">"myPropertyValue"</SPAN> /></SPAN> |
| <SPAN class="code-tag"><tool key=<SPAN class="code-quote">"myToolName"</SPAN> className=<SPAN class="code-quote">"org.myDomain.MyTool"</SPAN> /></SPAN> |
| <SPAN class="code-tag"></context></SPAN> |
| <SPAN class="code-tag"></vppconfig></SPAN> |
| |
| <cgen map=<SPAN class="code-quote">"src/datamap.xml"</SPAN> |
| destDir=<SPAN class="code-quote">"src/doc/web"</SPAN> |
| makepairs=<SPAN class="code-quote">"false"</SPAN> |
| usepkgpath=<SPAN class="code-quote">"false"</SPAN> |
| template=<SPAN class="code-quote">"EntityReport.vm"</SPAN> |
| includeEntities=<SPAN class="code-quote">"Artist*"</SPAN> |
| outputPattern=<SPAN class="code-quote">"*Report.html"</SPAN>> |
| <SPAN class="code-tag"><config refid=<SPAN class="code-quote">"myconfig"</SPAN> /></SPAN> |
| <SPAN class="code-tag"></cgen></SPAN> |
| </PRE> |
| </DIV></DIV> |
