How to use AXgen  
  This guide covers the general workflow when using AXgen and explains how to configure an ANT build-file to generate files with AXgen.  
   
  The basic functioning of AXgen is illustrated in the figure above. The first step is to write a model with a CASE tool of your choice. Save or export the model as an XMI file or let ANT extract the XMI from the model.  
  In principle AXgen works with every CASE tool, as XMI is a standardized format for metamodel exchange. Unfortunately, a lot of different interpretations of this standard exist. AXgen tries to overcome this problem using it's own UML abstraction layer. Currently XMI produced by NetBeans MDR or the Nsuml library is supported. If your CASE tool produces compatible output, lucky you. If not, you may try to transform your XMI (using XSLT) to create a compatible format.  
  AXgen takes the XMI-file and Velocity template files as input and generates arbitrary code using putting model elements into the Velocity context. See the Writing Templates section and the Jakarta Velocity site for more details on velocity templates.  
  The AXgen ANT task  
  AXgen is implemented as an ANT task. If you are not familiar to ANT, we recommend having a look at the ANT project site. A good point to start from is the build.xml file in AXgen's example dir.  
  To enable AXgen, the first step is to register the AXgen ANT task in the build-file:  
  
<path id="axgen.path">
   <fileset dir="${axgen.lib.dir}">
      <include name="**/*.jar"/>
   </fileset>
</path>

<taskdef name="axgen" classname="de.armax.ax.devtools.generator.AXgen">
   <classpath>
      <path refid="axgen.path"/>
   </classpath>
</taskdef>
  
  This task is all you need to run AXgen. An AXgen task initializes the model and the generation context from a set of XMI files. It has any number of nested subtasks <check/> and <generate/> to check the model and generate different files based on the model. Nested tasks are executed in the order they appear in the build.xml file.  
 
AXgen properties
Attribute Description Required Default
xmiFilename The path to the XMI file containing the model. yes, unless xmiFilenames is set or nested xmiFileSet is present. -
xmiFilenames A comma-separated list of XMI filenames containing the model parts. yes, unless xmiFilename is set or nested xmiFileSet is present. -
referenceStereotype The stereotype name used to mark model elements in one model part as references to a real element in another model part. no reference
templatePath The path to the template location. AXgen looks for templates at the classpath, in the current directory and in the specified templatePath in this order. The property may be overridden by generate-subtasks. no -
destinationPath The target directory for generation output. This is the base directory for all output. Subdirectories may be created based on dymanic file names. This property may be overridden by generate-subtasks. no -
rootPackageName The package were generation starts. AXgen will iterate through all subpackages starting from the root package. This property may be overridden by generate-subtasks. no -
helperClass The class to be used as helper class in generate-subtasks.This property may be overridden by generate-subtasks. no -
modelClass The implementation class of the UML abstraction layer. May be one of de.armax.ax.devtools.uml.mdr.AXmodelMdrImpl or de.armax.ax.devtools.uml.nsuml.AXmodelNsumlImpl or any other class implementing de.armax.ax.devtools.uml.AXmodel no AXmodelMdrImpl
 
  You may use a nested xmiFileSet tag instead of the xmiFile or xmiFiles properties. The syntax of the xmiFileSet element is identic to the ANT fileset element (the ANT fileset element is actually used internally).  
  The <check/> subtask  
  The check subtask is intended to perform arbitrary model checking operation and produce warnings and errors. Its main purpose is to check whether presumption made in the templates are matched by the model.  
  To work properly, the check subtask needs a model checker class extending de.armax.ax.devtools.uml.AXmodelChecker. We provide such a checker class (de.armax.ax.devtools.generator.AXojbHelper) for our OJB related templates.  
 
check properties
Attribute Description Required Default
checkerClass The checker class (or a factory) to be used. This class may be any class with a static method getInstance() returning an de.armax.ax.devtools.uml.AXmodelChecker (typically a model checker singleton), of it must be a subclass of de.armax.ax.devtools.uml.AXmodelChecker with a public no argument constructor. no AXojbHelper
failOnWarning Configure whether the sourrounding AXgen task aborts on checker warnings. no false
failOnError Configure whether the sourrounding AXgen task aborts on checker errors. no true
 
  The <generate/> subtask  
  The generate subtask is where actual generation occurs. Add a generate subtask for each type of output you wish to generate. For each generate subtask, the whole model (starting from the root package) is scanned and output is generated for matching model elements (may be classes/interfaces and packages).  
  AXgen gives the user detailed control which elements are taken as input for generation through a nested element tag (similar to ANT's fileset tag) and some filtering attributes.  
 
generate properties
Attribute Description Required Default
templateFile The template file to be used. Must be located in current directory, in classpath or in directory specified as templatePath in surrounding AXgen task. This template is evaluated for each model element. yes -
startTemplateFile The start template file to be used. Must be located in current directory, in classpath or in directory specified as templatePath in surrounding AXgen task. This template must not depend on model elements. It is evaluated one time when a new file is created. no -
endTemplateFile The end template file to be used. Must be located in current directory, in classpath or in directory specified as templatePath in surrounding AXgen task. This template must not depend on model elements. It is evaluated one time when a new file is closed. no -
destinationPath The target directory for generation output. This is the base directory for all output. Subdirectories may be created based on dymanic file names. yes, unless it was set in surrounding AXgen task -
destinationFile The destination file for generation output (with the dynamic part of the path). The destination file may depend on the current model element/package. Any occurances of $element.[navigationString]() will be replaced by the result of calling the method represented by [navigationString] (separated by dots, no brackets) on the current element. Any occurences of points in the resulting String will be replaced by file separator chars. Any occurences of $package.[navigationString]() will be replaced by doing the same thing on the current package. E.g. $element.getName() will be replaced by the elements name. If the destinationFile is element dependant, a new file for each model element is generated. If it is not element dependant but package dependant, a new file per package is generated. If the destinationFile is neither element nor package dependant, one single output file is generated. yes -
rootPackageName The package were generation starts. AXgen will iterate through all subpackages starting from the root package. no the model package
elementTypes A comma separated list of element types to be used as generation input. Allowed elements are class, interface and package. no class, interface
instantiable Used to filter instantiable classes. If set to true, only instantiable classes are used as generation input. If set to false, only non instantiable classes/interfaces are used. If not set, do not filter instantiable classes. This property is ignored when generating output for packages. no -
abstract Used to filter abstract classes. If set to true, only abstract classes are used as generation input. If set to false, only non abstract classes/interfaces are used. If not set, do not filter abstract classes. This property is ignored when generating output for packages. no -
helperClass The helper class used. Can be any class with a static getInstance() method or a public no argument constructor. Put complex operations to the helper class to keep templates readable. The helper is accessible in the velocity context by the variable $helper. no -
 
  To control what elements are used as generation input, use a nested <elements/> tag. This tag works similar to the ANT fileset tag. It contains <include/> and <exclude/> tags to declare elements to include/exclude. If no include tag is specified, all elements are included that do not match any of the exclude tags, else elements that match at least one include tag and do not match any exclude tag are included. If the nested element tag is omitted, by default all elements are used except elements with stereotype transient.  
  The elements tag itself has one single attribute rootPackageName that works like for the AXgen and the generate task.  
 
include/exclude properties
Attribute Description Required Default
name A pattern to match. A single asterisk (*) stands for any sequence of characters except the package separation character (.). Two subsequent asterisks (**) stand for any sequence of characters including the package separation character (.). The pattern is evaluated relative to the rootPackageName property of the elements tag. If this property is omitted, all elements are used. no -
includeStereotypes A comma separated list of stereotype names. If this property is set, elements need at least one of the stereotypes in order to be used for generation input. no -
excludeStereotypes A comma separated list of stereotype names. If this property is set, elements must not have any of the stereotypes in order to be used for generation input. no -
 
  Example  
  
<axgen
  xmiFileNames="modelPartOne.xmi, modelPartTwo.xmi"
  templatePath="path/to/my/templates"
  destinationPath="where/to/put/output"
  rootPackageName="package.containg.model.elements">
  <check checkerClass="my.own.CheckerClass"/>
  <generate
    templateFile="MyInterfaceTemplate.vm"
    destinationFile="$package.getQualifiedName()/$element.getNameForMethod()Interface.java"
    elementTypes="interface, class">
    <elements>
      <include name="**.entity.*" excludeStereotypes="transient"/>
    </elements/>
  </generate>
  <generate
    templateFile="MyClassTemplate.vm"
    destinationFile="$package.getQualifiedName()/$element.getNameForMethod().java"
    elementTypes="class">
    <elements>
      <include name="**.entity.*" excludeStereotypes="transient"/>
      <exclude name="**.entity.api.*"/>
    </elements/>
  </generate>
</axgen>
  
  For more details on the AXgen tasks, please refer to the API doc.