This section provides a step-by-step guide to set up your development environment for AndroMDA. We assume that you are working on a Windows platform.

Throughout this section you will install various programs. The recommended installation paths for these programs and other required directories are listed below. Please feel free to change the installation paths depending on your configuration and personal preferences. For example, you may choose to install programs on the D: drive instead of the C: drive. However, note that some programs don't work well if there are spaces in their pathname. So, try to stick to the suggestions below as much as possible.

You will also be asked to set up several environment variables. Please set these as SYSTEM variables using the Control Panel (Control Panel > System > Advanced > Environment Variables). Note that if you change the installation path of any program then you must make sure that the associated environment variable is changed accordingly.

Prepare the Development Environment

To start developing with AndroMDA, prepare your development environment by following the steps shown below.

Install Java

Install J2SE Development Kit 6 (JDK 6) from here. This is the preferred version of the JDK for AndroMDA. We also support JDK version 1.5. We don't support JDK version 1.4 anymore!

Make sure that the JAVA_HOME environment variable is pointing to the directory where you installed the JDK. It is possible you have this variable set already, but just to make sure here's how to check.

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 JAVA_HOME variable and that it is pointing to the directory where you installed the JDK. If not, add/edit the variable and set it to the correct value (e.g. C:\Program Files\Java\jdk1.6.0_06).

Install Maven

Maven is our preferred tool for building and deploying applications generated by AndroMDA. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting, and documentation from a central piece of information. If you are familiar with Ant, Maven is very similar except that it contains additional functionality:

1. A hierarchical build environment, where properties configured in a POM file (pom.xml) flow down to POM files of all child projects.
2. Standardized build tasks (clean, build, install, deploy, etc.)
3. Dependency specifications for build and deploy tasks - for all internal and external libraries; tied to a specific released versions of dependent libraries
4. A repository containing all versioned dependencies. This repository is used during the build and deploy processes (very similar to the .NET Global Assembly Cache concept).

Install Maven 2.0.8 by following the steps below. 

1. Click here to download Maven 2.0.8.
2. Unzip this file at C:\Program Files\Apache Software Foundation. A directory called maven-2.0.8 will be created which contains the Maven program.

Note: If you are behind a proxy server, you will have to configure Maven to use the proxy. The details can be found here.

Install JBoss Application Server

JBoss Application Server is a widely used open source Java application server. Install JBoss 4.0.5 by following the steps below.

1. Click here to point your browser to the JBoss download page.
2. Click the Download button on the row that lists JBoss Application Server version 4.0.5. This should take you to the download page on the SourceForge site.
3. Click on the link named "jboss-4.0.5.GA.zip" to download this file.
4. Unzip this file at C:\. A directory called jboss-4.0.5.GA will be created which contains the JBoss application server. Rename this directory to jboss-4.0.5 (just to make the name a little shorter).
5. If you are planning to install the Oracle database on your machine, then you must change the JBoss HTTP port, which defaults to 8080. The reason is that Oracle also defaults to this port and it is not easy to change Oracle's configuration. In order to change JBoss' HTTP port, edit the file called server.xml under the directory C:\jboss-4.0.5\server\default\deploy\jbossweb-tomcat55.sar and change all occurences of the number "8080" to something else, say "9090". This will resolve the conflict between JBoss and Oracle. If you have followed this step then you must use port 9090 whenever you are instructed to use port 8080 in this tutorial.

Setup 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.

Test Maven and create a local repository

Maven is based on the concept of a central, local repository located on your machine, where it stores artifacts such as 3rd party libraries as well as components created by you. When you create a new project, you must specify a Project Object Model (POM) in a file named pom.xml. In this file, you can tell Maven about the various 3rd party libraries and components your application depends on. When Maven starts to build the application, it will first fetch these dependencies from one or more remote repositories (generally located on the Internet) and store them in your local repository. This allows future builds to happen entirely locally. By default, the local repository is located at C:\Documents and Settings\your user name\.m2\repository. Note that so far we have installed only the Maven application, we have not created a local repository. Follow the steps below to test your Maven installation and force the creation of a local repository. We will use a standard Maven plugin to create a temporary project which we will delete later.

1. Open a Command Prompt and change the current directory to any temporary directory, such as C:\temp.
2. Execute the following command to make sure you can run Maven:
   mvn --version
3. Maven should display the following output:
   Maven version: 2.0.8.
4. Now execute the following command to create a temporary project:
   mvn archetype:create -DgroupId=testapp -DartifactId=testapp
   Make sure that you get a BUILD SUCCESSFUL message at the end. Sometimes due to bad Internet connectivity, Maven may not be able to download all dependencies. If your build fails due to this reason, try to issue the command again until you get a successful build.
5. Verify that Maven created a temporary project called testapp in the current directory and also a local repository at the default location mentioned above. If both these results are achieved successfully, you can delete the temporary project that was just created.

Install AndroMDA Application plugin

Next we will download and install the AndroMDA Application plugin into your Maven repository. This plugin allows creation of Java starter applications that use AndroMDA. This is the only AndroMDA artifact that we will install explicitly. All other artifacts, such as AndroMDA cartridges, will be automatically downloaded by the Maven scripts generated by the plugin. Install the plugin by following the steps below.

1. Click here to download the the AndroMDA plugin installer.
2. Unzip the contents of the installer into your Maven repository at C:\Documents and Settings\your user name\.m2\repository.
3. Verify that the following directory was created:
   C:\Documents and Settings\your user name\.m2\repository\org\andromda\maven\plugins\andromdapp-maven-plugin
4. Create a temporary directory, e.g. C:\andromda-temp.
5. Create a file called pom.xml in this directory with the following content.
   

   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <groupId>samples.test</groupId>
       <artifactId>test</artifactId>
       <version>1.0</version>
       <packaging>jar</packaging>
       <name>test</name>
   
       <build>
           <defaultGoal>compile</defaultGoal>
           <plugins>
               <plugin>
                   <groupId>org.andromda.maven.plugins</groupId>
                   <artifactId>andromdapp-maven-plugin</artifactId>
                   <version>3.3</version>
               </plugin>
           </plugins>
       </build>
   
       <repositories>
           <repository>
               <id>andromda</id>
               <name>AndroMDA Repository</name>
               <url>http://team.andromda.org/maven2</url>
           </repository>
       </repositories>
   
       <pluginRepositories>
           <pluginRepository>
               <id>andromda</id>
               <name>AndroMDA Repository</name>
               <url>http://team.andromda.org/maven2</url>
           </pluginRepository>
       </pluginRepositories>
   </project>
   

6. Open a Command Prompt in the directory where you created this pom.xml and run the command mvn without any arguments. Make sure the command completes successfully by displaying the BUILD SUCCESSFUL message.
7. You can now delete the temporary directory you created in step 1.

Install a UML tool

Install a tool that will allow you to model your applications in UML and export these models into a format that AndroMDA can understand. AndroMDA currently supports UML 1.4/XMI 1.2 as well as UML 2/EMF. Please follow one of the links below to install the UML tool of your choice. Even if you have one of these tools installed, take a look at the appropriate page for important configuration information. (We invite UML tool vendors and open-source projects to test their tools with AndroMDA and supply installation instructions for inclusion in this section.)

• ArgoUML (UML 1.4/XMI 1.2)
• MagicDraw 9.x (UML 1.4/XMI 1.2)
• MagicDraw 15.5 (UML 2/EMF)
• RSM 6 (Rational Software Modeler/Architect) (UML 2/EMF)

Install a database

Install a database that is supported by Hibernate. Click here to see the list of supported databases. For the purpose of this tutorial we will use MySQL 5.0, an open source database. If you install another database, then you will have to change JBoss and Hibernate configurations accordingly. Follow the steps below to install MySQL.

1. Click here to go to the MySQL download page.
2. Download the full Windows installation, specified as "Windows (x86)" (not just the "Essentials"). Install it at C:\Program Files\MySQL\MySQL Server 5.0. Record the database port, userid, and password for future use. You will need it each time you connect through the console, and when configuring the database connections in the tutorial.
3. Download MySQL GUI Tools Bundle for GUI based administration and querying of your database. Install it at C:\Program Files\MySQL\MySQL Tools for 5.0\
4. Download MySQL Connector/J version 5.0.4, the MySQL JDBC driver. Unzip it at C:\Program Files\MySQL.
5. Copy the MySQL driver from C:\Program Files\MySQL\mysql-connector-java-5.0.4\mysql-connector-java-5.0.4-bin.jar to the JBoss lib directory located at C:\jboss-4.0.5\server\default\lib. Rename the copied file to mysql-connector-java-5.0.4.jar, removing the "-bin" to make it consistent with Maven naming conventions. (Recheck the target directory - JBoss has multiple lib directories under its root directory.) This allows JBoss to access your database.

Install Eclipse (Optional)

Eclipse is a popular open source IDE useful for developing Java applications. AndroMDA does not require Eclipse, but we recommend its use to increase your productivity. Eclipse users will glad to know that AndroMDA generates fully usable .project and .classpath files. Simply import the .project file and start editing your code in Eclipse.

You can download Eclipse from here. We recommend downloading the Eclipse Europa Package called "Eclipse IDE for Java EE Developers". Follow the steps below to install and configure Eclipse:

1. Unzip the downloaded archive to a suitable location on your hard drive. The recommended location is C:\eclipse.
2. Edit the file eclipse.ini under C:\eclipse to increase the memory available for Eclipse. Here are the suggested contents for this file:

   	-vmargs
   	-Xms256m
   	-Xmx512m
   	-XX:PermSize=64m
   	-XX:MaxPermSize=128m
   	

3. Start Eclipse by double-clicking on eclipse.exe.
4. Eclipse asks for a folder where it can store your projects. This folder is called the Eclipse workspace. Set the workspace to a location where you generally creates projects, such as C:\Projects.
5. Choose Preferences from the Window Menu.
6. In the left pane, select Java > Build Path > Classpath Variables.
7. Click New.
8. Add M2_REPO in the Name field and the path of your M2 repository in the Path field (for example, C:\Documents and Settings\your user name\.m2\repository). This value is needed in order to import Maven generated project configurations.
9. Click OK twice to close the dialog boxes.

What's Next?

Now that the development environment is set up, we are ready to try out the TimeTracker application. Click the Next link below to take a test drive.