Getting started with AndroMDA

In this section we'll cover the steps needed to successfully get your first project using AndroMDA up and running. A few third-party tools and software are needed to get started, let's begin with listing them and briefly describing the requirement.

The impatient may feel free to skip this section and directly head over to the step-by-step section; if you are a seasoned Java developer and have Java and Maven already up and running then feel free to jump to this section: My first AndroMDA project.

On this page you will learn:

  • what software is needed to run AndroMDA,
  • how to configure environment variables for these software components,
  • and how to make AndroMDA setup a template J2EE project for you


This section lists and describes the necessary software you need to have installed to get AndroMDA running.


You will need the developer release of the Java 2 Virtual Machine (Java 2 SDK). You will need at least version 1.5.

A distribution can be downloaded from this site:

Maven or Ant

You can start AndroMDA from either Maven or Ant, depending on your preference you are free to choose either one. We strongly recommend using Maven because most of the AndroMDA tools come with a Maven plugin. Don't worry if you are not familiar with Maven, you will not need to write your own Maven specific files, AndroMDA will do all of that for you out-of-the-box.

This getting started guide will assume you followed our recommendation and chose Maven. The Ant users may follow this link for more information: AndroMDA Ant Task.

Using AndroMDA in combination with Maven (instead of Ant) will save you a considerable amount of time and effort if you've never used AndroMDA before. Just make sure you are using the latest version, Maven 2.2.1 is recommended, earlier versions are less performant and contain critical bugs.

The AndroMDA team puts out updates to their library components on a regular basis, in order for Maven to pick them up automatically you will need to do a very minor configuration to the Maven setup after installation.

JBoss or Tomcat

AndroMDA in no way depends on JBoss or Tomcat in order to properly function, it is just that the generated code by default will run in either the free JBoss container or free Tomcat container. You will see later what is needed to have generated code deployed on other application servers.

Note: not only the generated code may change, but also the way you include libraries in your application's distributions.

You may go here to download a copy of JBoss:, or here to download a copy of Tomcat:

MagicDraw or Poseidon

None of these tools are required to use AndroMDA; it just happens to be that they are able to import and export UML models in a version of XMI that is compatible with AndroMDA and they provide a set of features that make it suitable for AndroMDA users, most other tools that we have tried do not seem to provide adequate support for a serious UML/MDA developer. Both of these tools are commercial and have a free Community Edition that can be downloaded at no cost, please note that these editions are not open-source.

For use with AndroMDA we recommend MagicDraw, it is fast, relatively light-weight and provides the best support for almost any UML feature. We aren't affiliated with any of these products in any way... if you find another tool that can be listed here please let us know.


What follows is a step-by-step guide to setting up a configuration so that you can quickly start modeling. In this guide we will assume you are a Windows user and we will be using Maven. Anyway, if you're using a Unix based platform you should be smart enough to get the job done too by reading this section.


Depending on your platform you install the Java 2 SDK 1.5 (or a later version), you may go here to download a stable release.


It's possible you have this environment variable already set, but just to make sure here's where you can set them under Windows.

  1. Go to the control panel and double-click on System, if you are a Windows XP user it's possible you have to open Performance and Maintenance before you will see the System icon.
  2. Go to the Advanced tab and click on Environment Variables
  3. Make sure you have set the properties listed below (if not already present)

In the dialog that you just opened you should add/edit the variable JAVA_HOME and set it the Java SDK installation directory, eg. C:\j2sdk1.5.


Next we will install Maven and configure it to download dependencies from the AndroMDA server whenever it needs to.

  1. Download Maven from this site:
  2. Install the downloaded binary. (We will assume you installed it in C:\apps\maven)
  3. If the installation would complain that the JAVA_HOME environment is not set then make sure you have correctly set it and close Windows Explorer or Total Commander, whatever it is you are using and start it again.


This step is optional but will allow you to automatically deploy your generated applications to JBoss or Tomcat.


The JBoss application server can be used to deploy your generated EAR applications, follow these simple steps to install and configure:

  1. Download JBoss from this site: Version 4.0.x should do the job.
  2. Unzip the downloaded binary into a directory of your choice, eg. C:\apps\jboss-4.0.1sp1


The Tomcat servlet container can be used to deploy your generated WAR applications, follow these simple steps to install and configure:

  1. Download Tomcat from this site: Version 5.x should do the job.
  2. Unzip the downloaded binary into a directory of your choice, eg. C:\apps\jakarta-tomcat-5.5.9


Download at least one of these tools, they will allow you to model your application in UML and export it into a format that AndroMDA understands (UML 1.4).

Environment variables

We have seen earlier how to set environment variables such as JAVA_HOME, it is strongly recommended to set the following variables before continuing. We repeat JAVA_HOME here just for completeness.

Property Value Required?
JAVA_HOME Java installation directory, eg. C:\j2sdk1.4.2_08. Yes
M2_HOME Maven installation directory, eg. C:\apps\maven, this might have already been set by the Maven installer. Yes
JBOSS_HOME JBoss installation directory, eg. C:\apps\jboss-4.0.1sp1. No (unless you're deploying to Jboss)
CATALINA_HOME Tomcat installation directory, eg. C:\apps\jakarta-tomcat-5.5.9. No (unless you're deploying to Tomcat)
PATH This makes sure the system will search for console commands in the directories listed here. If this property already exists you should simply add %JAVA_HOME%\bin;%M2_HOME%\bin. Yes

My first AndroMDA project

So your system is properly configured to run Java and Maven, we are now ready to use AndroMDA.

At this point we have not downloaded any AndroMDA components yet, and we will not need to since Maven will make sure everything is downloaded for us. What we are going to do now is ask Maven to download and install an AndroMDA plugin so that we can create our first project.

Open up a console and type the following at the command prompt (the version property at the end of that line may vary depending on the version you wish to use, the SNAPSHOT suffix denotes it is a nightly-build, stable releases could be: 3.0, 3.1, 3.2, 3.3, 3.4, at the time of this writing 3.4 was the most recent release (meaning 3.4 final).

The documentation for this specific plugin can be found by clicking on the Maven Plugins on the left, or by directly going to its page by clicking here.

maven plugin:download -DgroupId=andromda -DartifactId=maven-andromdapp-plugin -Dversion=3.3

|  \/  |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \  ~ intelligent projects ~
|_|  |_\__,_|\_/\___|_||_|  v. 1.0.2

Plugin cache will be regenerated
Directory C:\Documents and Settings\foo\.maven\repository does not exist. Attempting to create.
Attempting to download commons-io-20030203.000550.jar.
59K downloaded
Attempting to download commons-net-1.1.0.jar.
139K downloaded
Attempting to download commons-httpclient-2.0.jar.
217K downloaded
Attempting to download commons-lang-2.0.jar.
165K downloaded
Attempting to download commons-logging-1.0.3.jar.
30K downloaded
Attempting to download jsch-0.1.5.jar.
79K downloaded
Attempting to download commons-jelly-20030902.160215.jar.
150K downloaded
Attempting to download commons-jelly-tags-velocity-20030303.205659.jar.
7K downloaded
Attempting to download velocity-1.4-dev.jar.
351K downloaded
Attempting to download commons-jelly-tags-xml-20030211.142705.jar.
31K downloaded
Attempting to download commons-jelly-tags-interaction-20030211.143817.jar.
4K downloaded
Plugin 'maven-deploy-plugin' in project 'null' is not available

    [mkdir] Created dir: C:\Documents and Settings\foo\.maven\repository\andromda\plugins
    [echo] repo is ''
    [echo] trying to download
    [echo] repo is ''
    [echo] trying to download
40K downloaded

    [delete] C:\Documents and Settings\foo\.maven\plugins not found.
    [copy] Copying 1 file to C:\Program Files\Apache Software Foundation\Maven 1.0\plugins

Now you have installed the andromdapp AndroMDA plugin, it can create a directory structure for a J2EE project. The build process for that project will use Maven too. Type the following at the command prompt and answer the questions.

Please note, that this example below assumes you're generating an EAR, however a standalone WAR can be generated as well, by answering 'war' to the question about whether you would like an ear or standalone war):

maven andromdapp:generate

 __  __
|  \/  |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \  ~ intelligent projects ~
|_|  |_\__,_|\_/\___|_||_|  v. 1.0.2

Attempting to download velocity-1.4.jar.
352K downloaded
Please enter your first and last name (i.e. Chad Brandon):
Wouter Zoons
Please enter the name of your J2EE project (i.e. Animal Quiz):
AndroMDA Example
Please enter the id for your J2EE project (i.e. animalquiz):
Please enter a version for your project (i.e. 1.0-SNAPSHOT):
Please enter the base package name for your J2EE project (i.e. org.andromda.samples):
Would you like an EAR or standalone WAR (enter 'ear' or 'war')?
Please enter the type of transactional/persistence cartridge to use ('hibernate', 'ejb', or 'spring'):
Would you like a web application? (enter 'yes' or 'no'):
Would you like to be able to expose your services as web services? (enter 'yes' or 'no'):

Answering the last question will yield the following output from the plugin



    [echo] +---------------------------------------------------------------------+
    [echo] |   G E N E R A T I N G   A n d r o M D A   J 2 E E   P R O J E C T   |
    [echo] +---------------------------------------------------------------------+
    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample
    [copy] Copying 1 file to E:\temp\andromda-example\andromdaexample
    [copy] Copying 1 file to E:\temp\andromda-example\andromdaexample

    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\app
    [copy] Copying 2 files to E:\temp\andromda-example\andromdaexample\app

    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\app\src\META-INF


    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\core
    [copy] Copying 2 files to E:\temp\andromda-example\andromdaexample\core

    [copy] Copying 6 files to E:\temp\andromda-example\andromdaexample\core
    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\core\src\java
    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\core\target\src


    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\common

    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\common\src\java
    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\common\target\src


    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\mda\src\uml
    [copy] Copying 1 file to E:\temp\andromda-example\andromdaexample\mda\src\uml
    [copy] Copying 1 file to E:\temp\andromda-example\andromdaexample\mda


    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\web

    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\web\src\java
    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\web\target\src


    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\webservice
    [copy] Copying 1 file to E:\temp\andromda-example\andromdaexample\webservice

    [mkdir] Created dir: E:\temp\andromda-example\andromdaexample\webservice\target\src

    [echo] New J2EE project generated to: 'E:\temp\andromda-example/andromdaexample'

Congratulations, just now you have created your first AndroMDA project and you are ready to start modeling. The generated project in this example allows you to model entities and services, the services can be accessed via webservices which in turn can be used by a Struts front-end. The generated code is J2EE compliant and will by default deploy in a JBoss container compatible with the generated J2EE implementation (at the time of this writing that would be J2EE 1.3 or above on JBoss 3.2.7 or above).

Make sure to read the /readme.txt file generated in the root of the project, it explains the directory structure and the files contained therein.

Here are some pointers on how to proceed from here (please note there will be slight differences if you generated a standalone war):

  1. Go into the created andromdaexample subdirectory
  2. Call maven here, it will download all dependencies and build your project. Here are a few commands you can call:
    • maven (runs the default goal: 'install')
    • maven install (builds all components, an .ear bundle can be found in /app/target)
    • maven mda (runs AndroMDA on the UML model)
    • maven mda -Dfilter=spring,java (runs AndroMDA, only using the spring and java cartridges, in that order)
    • maven core (builds the core component, usually hibernate,ejb or spring)
    • maven web (builds the web component)
    • maven core web (builds the core and web components, in that order)
    • maven mda -Dfilter=spring core deploy (regenerates the spring code, rebuilds the core component, bundles the .ear and deploys)
    For more goals take a look in /maven.xml.
  3. All components will build an artifact, check out the /target directory in each separate component.
  4. All required J2EE and other dependencies will be downloaded, after a while the build should successfully end. This process might take a while to complete, 3-4 minutes if you have a fast internet connection.
  5. Subsequent calls to maven may specify the -o flag, denoting you want to build offline because you are sure all dependencies are already downloaded. Building offline with Maven will be much faster, approximately 30 secs.
  6. Start your favorite UML tool and open the empty UML model that has been created for you, you can find it in the mda/src/uml subdirectory, in our example it is called AndroMDAExampleModel.xmi.
  7. MagicDraw will prompt you for a file with a name starting with andromda-profile and extension, it will have been downloaded by Maven during the build process and stored in your local Maven repository, eg. C:\Documents and Settings\foo\.maven\repository\andromda\xml.zips. This file contains all datatypes, stereotypes and tagged values that are known to work with any of the AndroMDA cartridges. If this confuses you then just think of it as a free addon-package that will make it significantly easier for you to model your application. It is completely optional though, but not using it will mean more work for you.
  8. You are now ready to start modeling, depending on which AndroMDA cartridges you are using you might need to know a few things in order to properly model, for that you will need to learn how each cartridge works. Read the howto guides to quickly get up to speed modeling with AndroMDA, they will explain you what to do with the UML model in order to have your components generated for you.
  9. Good luck, questions can be posted on the AndroMDA Forums, please make sure to pick the right forum for your question.

Where to go from here ?

In this guide we have made sure we have everything installed to start writing MDA projects using AndroMDA, but that's just the start .. there are several different cartridges you can use, or maybe, if you can't find one you like, you can write one yourself and contribute to the AndroMDA project.

In any case you will need to learn about UML, MDA and modeling techniques and best practices. Perhaps a good idea would be to take a look at the samples included in the binary distribution, each one of them includes a model. Such a distribution is found here: AndroMDA project page. Please note that the samples in the distribution still need to be built if you want to see the generated sources or ant to deploy it (just go into a sample and invoke maven, nothing more to it).