The AndroMDA Ant Task

One of the ways to use AndroMDA, is as a custom task for the famous Apache Ant build tool. This page documents the attributes and elements of the <andromda> task.

<andromda>

andromda is the task that generates Java source (or other) files from templates and a metamodel that it loads from a text file (i.e. an XMI file).

To configure your cartridges you'll will use nested <namespace> elements.

To customize andromda's default behavior and to point to shared modules or profiles then you will possibly use a nested <repository> element.

Attributes

Attribute Description Required
basedir Specifies the path to the directory location of your case tool's model file(s). NOTE: if this is NOT specified, you'll need to specify the modelURL property to give the URL of a single model to load. Yes (unless modelURL is used).
includes This is the standard Ant includes attribute. Specify any files or directories with XMI files that you do want AndroMDA to try to process. This is used in conjunction with the basedir property. Yes (unless modelURL is used).
excludes This is the standard Ant excludes attribute. Specify any files or directories with XMI files that you do not want AndroMDA to try to process. This is used in conjunction with the basedir property. No.
lastModifiedCheck This turns on or off the ability to check the last modified date on files in order to determine whether or not they need to be re-rendered or not. The value of this attribute can be "true, false, yes, no". By default, it is true, meaning that the last modified date should be checked and if the original .xml file has not changed, then don't process the output file. This accelerates processing because files that have not changed will not get reprocessed. No, defaults to true.
processAllModelPackages Specifies whether or not to process/generate from all packages in the model, used in combination with the <modelPackage> element. No, defaults to true.
modelValidation Specifies whether or not models loaded by AndroMDA will be validated. By default models WILL be validated, however sometimes its nice to turn off validation for performance reasons (i.e. you have very large model(s) being processed). No, defaults to true.
xmlValidation Specifies whether or not XML resources loaded by AndroMDA will be validated (such as XML plugin descriptors). Sometimes underlying XML parsers don't support XML Schema validation and in that case, we want to be able to turn it off. No, defaults to true.

<model>

The <model/> element is used to tell AndroMDA to process a model. It can be used instead of the include and exclude attributes to point directly at the location of an XMI file. It is useful if the model file is in a JAR and you do not want to unzip the jar. Unlike include it can only be used to process one XMI file (however you can define as many <model/> elements as you would like).

The model is optional if basedir and includes is defined.

Attribute Description Required
url The URL to the model to be processed. (i.e. jar:file:/path/to/my/model.xml.zip!/model.xmi) Yes

Example

This example call to the andromda task, tells AndroMDA to load the model from jar:file:/path/to/my/model.zuml!/model.xmi and generate code using the hibernate, the ejb and bpm4struts cartridges. Notice how we configure each cartridge through the <namespace> elements.

<taskdef name="andromda"
         classname="org.andromda.core.anttasks.AndroMDAGenTask"
         classpathref="class.path"/>
<andromda>
    <model url="jar:file:/path/to/my/model.zuml!/model.xmi"/>
    <!-- defines the location of the mapping files -->
    <mappingsSearchPath>
        <pathelement location="${basedir}/src/mappings"/>
    </mappingsSearchPath>
    <!-- This example package will not be processed -->
    <modelPackage name="my.package.foo" shouldProcess="false"/>
    <!-- This file tells AndroMDA how to map abstract datatypes to classes -->
    <namespace name="default" ignore="false">
        <property name="languageMappingsUri" value="file:${basedir}/JavaMappings.xml"/>
    </namespace>
    <!-- This will generate the Hibernate code -->
    <namespace name="hibernate" ignore="false">
        <property name="jdbcMappingsUri" value="JDBC"/>
        <property name="sqlMappingsUri" value="HypersonicSql"/>
        <property name="foreignKeySuffix" value="_FK"/>
        <property name="maxSqlNameLength" value="30"/>
        <property name="entities"      value="${gen.src.dir}" ignore="false"/>
        <property name="entity-impls"  value="${gen.src.dir}" ignore="false"/>
        <property name="session-beans" value="${gen.src.dir}" ignore="false"/>
        <property name="session-impls" value="${gen.src.dir}" ignore="false"/>
    </namespace>
    <!-- This will generate the EJB code -->
    <namespace name="ejb" ignore="false">
        <property name="entities"      value="${gen.src.dir}" ignore="false"/>
        <property name="entity-impls"  value="${gen.src.dir}" ignore="false"/>
        <property name="session-beans" value="${gen.src.dir}" ignore="false"/>
        <property name="session-impls" value="${gen.src.dir}" ignore="false"/>
    </namespace>
    <!-- This will generate the Bpm4Struts code -->
    <namespace name="bpm4struts" ignore="false">
        <property name="securityEnabled" value="false"/>
        <property name="securityRealm" value="other"/>
        <property name="pages" value="${gen.src.dir}"/>
        <property name="forms" value="${gen.src.dir}"/>
        <property name="actions" value="${gen.src.dir}"/>
        <property name="controllers" value="${gen.src.dir}"/>
        <property name="controller-impls" value="${gen.src.dir}"/>
        <property name="messages" value="${gen.src.dir}"/>
        <property name="configuration" value="${gen.src.dir}"/>
        <property name="xdoclet-merge" value="${merge.src.dir}"/>
    </namespace>
</andromda>
            

<modelPackage>

The <modelPackage> is used in conjunction with the processAllModelPackages attribute of the <andromda> task. By default all packages are processed. Therefore it is recommended to turn off the packages which should be not processed. In other words, if you don't want to generate code from a certain package of a model, then you can create a modelPackage for that package, set the shouldProcess attribute to false, and any model elements in that package will not be processed.

The modelPackage element is optional.

Attribute Description Required
name The fully qualified name of the UML namespace/package. Yes.
shouldProcess True or false depending on whether or not the package should be processed. No. Defaults to true.

Example

The below example demonstrates the correct use of the <modelPackage> element:

<andromda ...>
    <modelPackage name="my.package.foo" shouldProcess="true"/>
    <modelPackage name="my.package.bar" shouldProcess="false"/>
  ...
</andromda>
                

The above is equivalent to:

<andromda ...>
    <modelPackage name="my.package.bar" shouldProcess="false"/>
    ...
</andromda>
                

<namespace>

The <andromda> task takes a nested <namespace> element in order to customize the properties of a cartridge. These properties are used to define the location of where generated files are written, what language mapping files to use (i.e. JavaMappings.xml, DotNetMappings.xml, etc.) and any other properties that a cartridge and its metafacades might support.

Attributes

Attribute Description Required
name The name of the cartridge you want to use. It must match the name in a cartridge descriptor (i.e. /META-INF/andromda-cartridge.xml). Yes.
ignore This is useful if you have a cartridge on your classpath (since cartridge's are loaded when on your classpath) and you do not want to generate any output from this cartridge, in other words, you want it to be ignored. If you want to ignore a cartridge, then set this attribute with value of true, otherwise don't set it at all. No. Defaults to false.

See the example above for the correct use of namespace elements.

<repository>

The <andromda> task supports a nested <repository> tag to use to define any extra repository options (i.e. moduleSearchPath).

<moduleSearchPath>

The <repository> element takes a nested <moduleSearchPath> element in order to define the location of external modules or profiles that a model being processed is using. The <moduleSearchPath> takes any valid Ant path element structures. See Path-like Structures for more information on how to define these paths.

Example

The BPM4Struts cartridge metafacade model extends from the base metafacade model, so we define a <moduleSearchPath> element pointing to the location for which to find the base metafacade model.

<andromda lastModifiedCheck="false">
    <model url="jar:file:${src.dir}/uml/BPM4StrutsMetafacadeModel.xml.zip!/BPM4StrutsMetafacadeModel.xml"/>
    <repository>
        <moduleSearchPath>
            <pathelement location="${basedir}/lib"/>
        </moduleSearchPath>
    </repository>
    ...
</andromda>
            

<mappingsSearchPath>

The <andromda> element takes a nested <mappingsSearchPath> element in order to define the location of AndroMDA mapping files. This allows us to use the logical names for the location of mapping files (instead of the complete path). The <mappingsSearchPath> takes any valid Ant path element structures. See Path-like Structures for more information on how to define these paths.

Example

We want to define the location of the mapping files so that we use the logical name of mapping, files therefore we create a <mappingsSearchPath> element pointing to the location for which to find all AndroMDA mapping files we'll be using. Note how we are able to use logical names such as JDBC and HypersonicSql instead of the complete paths.

<andromda lastModifiedCheck="false">
    <model url="jar:file:/path/to/my/model.zuml!/model.xmi"/>
    <mappingsSearchPath>
        <pathelement location="${basedir}/src/mappings"/>
    </mappingsSearchPath>
    ...
    <!-- This will generate the Hibernate code -->
    <namespace name="hibernate" ignore="false">
        <property name="jdbcMappingsUri" value="JDBC"/>
        <property name="sqlMappingsUri" value="HypersonicSql"/>
        ...
    </namespace>
    ...
</andromda>