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:
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: http://java.sun.com.
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.
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.
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.
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.
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:
The Tomcat servlet container can be used to deploy your generated WAR applications, follow these simple steps to install and configure:
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).
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.
|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|
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).
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):
__ __ | \/ |__ _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):
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).