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

Requirements

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

Step-by-step

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.

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
build:start:

plugin:download-artifact:
    [mkdir] Created dir: C:\Documents and Settings\foo\.maven\repository\andromda\plugins
    [echo] repo is 'http://www.ibiblio.org/maven'
    [echo] trying to download http://www.ibiblio.org/maven/andromda/plugins/maven-andromdapp-plugin-3.2.jar
    [echo] repo is 'http://andromda.sourceforge.net/maven'
    [echo] trying to download http://andromda.sourceforge.net/maven/andromda/plugins/maven-andromdapp-plugin-3.2.jar
40K downloaded

plugin:download:
    [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
BUILD SUCCESSFUL
            

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):
andromdaexample
Please enter a version for your project (i.e. 1.0-SNAPSHOT):
1.0-demo
Please enter the base package name for your J2EE project (i.e. org.andromda.samples):
org.andromda.demo
Would you like an EAR or standalone WAR (enter 'ear' or 'war')?
ear
Please enter the type of transactional/persistence cartridge to use ('hibernate', 'ejb', or 'spring'):
spring
Would you like a web application? (enter 'yes' or 'no'):
yes
Would you like to be able to expose your services as web services? (enter 'yes' or 'no'):
yes
            

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

build:start:

andromdapp:init:

andromdapp:generate:
    [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
andromdapp:init:

andromdapp:generate-app-subproject:
andromdapp:generate-module:
    [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

andromdapp:generate-hibernate-subproject:
andromdapp:init:

andromdapp:generate-core-subproject:
andromdapp:generate-module:
    [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


andromdapp:init:

andromdapp:generate-common-subproject:
andromdapp:generate-module:
    [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

andromdapp:init:

andromdapp:generate-mda-subproject:
    [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

andromdapp:init:

andromdapp:generate-web-subproject:
andromdapp:generate-module:
    [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

andromdapp:init:

andromdapp:generate-webservice-subproject:
andromdapp:generate-module:
    [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'
BUILD SUCCESSFUL
            

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 .xml.zip, 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).