Install Java

Install J2SE Development Kit 6 (JDK 6) or newer from http://www.oracle.com/technetwork/java/javase/downloads/index.html. This is the preferred version of the JDK for AndroMDA. We also support JDK version 1.5. Support for version 1.4 requires a specific code generation configuration overriding the default settings, and changing to an earlier maven version and changing compiler settings.

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. From a command prompt type echo %JAVA_HOME%. - OR -
2. 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.
3. Go to the Advanced tab and click on Environment Variables
4. Make sure you have set the JAVA_HOME variable and 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:\Programs\Java\6. You may add the variable to the list of user variables or system variables.

Install Maven

Maven3 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 for all referencing projects.

Install Maven 3.0.3 by following the steps below.

1. Click http://maven.apache.org/download.html and download Maven 3.0.3 or newer.
2. Unzip this file at C:\Programs\. A directory called apache-maven-3.0.3 will be created which contains the Maven program. Rename to 'maven3'.

Note: If you are behind a proxy server, you will have to configure Maven to use the proxy. The details can be found below. Maven 2.2.1 or later will also work with AndroMDA.

Install JBoss Application Server

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

1. Download the desired version from http://www.jboss.org/jbossas/downloads.html. The TimeTracker sample works with the latest current version 7.0.2.
2. Timetracker is also compatibile with JBoss 6.1, 5.1, Tomcat7, and GlassFish, with minor changes to be described later.
3. Click on the download link for "7.0.2.Final" Everything Profile to download this file.
4. Unzip this file at C:\Programs. A directory called jboss-as-7.0.2.Final will be created which contains the JBoss application server. Rename this directory to JBoss\7 (just to make the name a little shorter and to allow for multiple versions).
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 files called standalone\configuration\standalone.xml (on JBoss 6.1 or earlier \default\conf\bindingservice.beans\META-INF\bindings-jboss-beans.xml and server\default\deploy\jbossweb.sar\server.xml) and change all occurrences 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. If you are using JBoss5.1, use a utility such as WinGrep to search and replace all instances of 8080 with the new port, under server\default, for *.xml and *.properties (about 4 places).
6. Test start the JBoss application server: cd %JBOSS_HOME%\bin and standalone.bat. If using JBoss 6.1 or earlier, use run.bat. Make sure the default server starts without errors. JDK6 is required for JBoss7. If you see the error java.lang.NoSuchMethodError: javax.annotation.Resource.lookup()Ljava/lang/String; there is a JDK version conflict in the JSR250 jar, add the following to the JBoss command line: -Djava.endorsed.dirs=$JBOSS_HOME/lib/endorsed as explained in http://community.jboss.org/wiki/EJB31Embeddable
7. Verify the JBoss Administration Console after starting JBoss: Open http://localhost:8080. Select the 'Administrative Console' link. Login with 'admin/admin'. The console will be used for adding/configuring databases other than the default H2 DB ExampleDS.

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.

Configure and Test Maven and create a local repository

Maven is based on the concept of a single local repository located on your machine, where it automatically downloads 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. Maven3 and Maven2 share the same M2 environment variables.

• Edit %M2_HOME%\conf\settings.xml to use the Sonatype and JBoss repositories, and to download the andromda plugins. Include proxy settings if behind a firewall. This is described at Configuring Maven and Maven Settings

  ...
    <!-- localRepository
     | The path to the local repository maven will use to store artifacts. Always set to M2_REPO environment variable.
     |
     | Default: ~/.m2/repository
     | Note: This value overrides the M2_REPO environment variable, if different!
    -->
    <localRepository>${env.M2_REPO}</localRepository>
  ...
    <!-- pluginGroups
     | This is a list of additional group identifiers that will be searched when resolving plugins by their prefix, i.e.
     | when invoking a command line like "mvn prefix:goal". Maven will automatically add the group identifiers
     | "org.apache.maven.plugins" and "org.codehaus.mojo" if these are not already contained in the list.
     |-->
    <pluginGroups>
      <!-- Specifies a further group identifier to use for plugin lookup. Causes all to be searched for updates.-->
        <pluginGroup>org.andromda.maven.plugins</pluginGroup>
     </pluginGroups>
  ...
    <!-- proxies
     | This is a list of proxies which can be used on this machine to connect to the network.
     | Unless otherwise specified (by system property or command-line switch), the first proxy
     | specification in this list marked as active will be used.
     |-->
    <proxies>
      <!-- proxy
       | Specification for one proxy, to be used in connecting to the network.
       |
      -->
      <proxy>
        <id>your-proxy</id>
        <active>true</active>
        <protocol>http</protocol>
        <host>your-proxy.company.com</host>
        <port>8080</port>
        <nonProxyHosts>*.company.com|127.0.0.1|localhost</nonProxyHosts>
      </proxy>
    </proxies>
  ...
    <repositories>
      <repository>
          <id>sonatype</id>
          <name>Sonatype Repository</name>
          <url>http://oss.sonatype.org/content/groups/public</url>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </repository>
      <repository>
          <id>jboss</id>
          <name>JBoss Repository</name>
          <url>http://repository.jboss.org/nexus/content/groups/public-jboss/</url>
      </repository>
    </repositories>
    <pluginRepositories>
      <pluginRepository>
          <id>sonatype</id>
          <name>Sonatype Repository</name>
          <url>http://oss.sonatype.org/content/groups/public</url>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </pluginRepository>
    </pluginRepositories>
  ...
                          

• Open a Command Prompt and change the current directory to any temporary directory, such as C:\andromda-temp.

• Execute the following command to make sure you can run Maven: mvn -v

• Maven should display the following output:

  Apache Maven 3.0.3 (r1075438; 2011-02-28 12:31:09-0500)
  Java version: 1.6.0_21
  Java home: C:\Program Files\JDK\16\jre

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

• Verify that Maven created a temporary project called testapp in the current directory and also a local repository at the %M2_REPO% location mentioned above.

Install AndroMDA Application plugin

Next we will download and install the AndroMDA Application plugin. This plugin allows creation of Java starter applications that use AndroMDA. All artifacts, such as AndroMDA cartridges, will be automatically downloaded by the Maven scripts generated by the plugin.

• Change to the temporary directory, e.g. C:\andromda-temp.
• Edit pom.xml in this directory to add the following content:

  ...
  <build>
      <defaultGoal>compile</defaultGoal>
      <plugins>
          <plugin>
              <groupId>org.andromda.maven.plugins</groupId>
              <artifactId>andromdapp-maven-plugin</artifactId>
              <version>3.5-SNAPSHOT</version>
          </plugin>
      </plugins>
  </build>
                          

• Open a Command Prompt in the directory where you edited this pom.xml and run the command mvn without any arguments. Make sure the command completes successfully by displaying the BUILD SUCCESSFUL message.
• 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 UML2 3.x/EMF/XMI2. Please follow one of the links below to install the UML tool of your choice. (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.5 (UML 1.4/XMI 1.2)
MagicDraw 11.5 through 17 (EMF-UML2 3.x)
RSM 7, 7.5, 8 (Rational Software Modeler/Architect) (EMF-UML2 3.x)
Eclipse Papyrus (EMF-UML2 3.x)

Install a database

Install or download a database that is supported by Hibernate. Click http://www.hibernate.org/260.html to see the list of supported databases. For the purpose of this tutorial we assume that the H2 database will be downloaded automatically and configured by maven as part of the build process. If you have installed another database then you will have to change the AndroMDA Hibernate configuration accordingly in the completed application pom.xml.

• H2: H2 is an open source in-memory java database, the successor version of HSQL. You can download it from http://www.h2database.com or automatically through maven. This database ships with JBoss 7 and is often used for unit testing. It features compatibility modes with most major DBMSs such as mySQL, Oracle, DB2, SqlServer.
• Hypersonic SQL 2.0: HSQL is an open source java database. You can download it from http://hsqldb.org. This database ships with JBoss 6.1 and earlier.
• MySQL 5.6: MySQL is an open source database, owned and supported by Oracle. You can download it from http://dev.mysql.com/downloads/mysql. We recommend downloading the full Windows installation - not just the "Essentials". In addition, download and install MySQL Workbench, a GUI based tool that will make your development much easier. Finally, download and unzip MySQL Connector/J (the MySQL JDBC driver) in a convenient directory. For the purpose of this tutorial we will assume that you have installed the driver at C:\Programs\MySQL\mysql-connector-java-5.1.18. Or - you can wait until running mvn after creating the timetracker project, which has a dependency on mysql connector. Copy the MySQL driver from C:\Programs\m2repo\mysql\mysql-connector-java\5.1.18\mysql-connector-java-5.1.18.jar to the JBoss lib directory located at C:\Programs\jboss\7\server\default\lib. This allows JBoss to access your database.
• PostgreSQL 8.1: PostgreSQL is an open source database. You can download it from http://www.enterprisedb.com/products/pgbindownload.do. The Postgres installation contains a GUI based administrative tool called pgAdmin III. JDBC drivers are also included as part of the installation.
• Oracle: Oracle 11g is an commercial database sold by Oracle. We assume that you have the necessary distribution media to install it. Oracle 11g includes a GUI based administrative tool called Enterprise Manager. JDBC drivers are also included as part of the installation, or as a separate download. The Express edition is free to use.

Install Eclipse (Optional)

Eclipse is a popular open source IDE that is useful in developing Java applications. AndroMDA does not require the use of Eclipse. However we do recommend using it for development as it helps increase your productivity. Eclipse users will glad to know that AndroMDA generates fully usable .project and .classpath files, or you can use the Sonatype M2E Eclipse plugin to manage your maven projects. You can download Eclipse from http://www.eclipse.org/downloads. We recommend downloading the Eclipse Indigo (v3.7) Package called "Eclipse IDE for Java EE Developers". Follow the steps below to install and configure Eclipse:

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

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

• Start Eclipse by double-clicking on eclipse.exe.
• 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:\Workspaces.
• Choose Preferences from the Window Menu.
• In the left pane, select Java > Installed JREs
• Add the JDK6 from the JAVA_HOME directory, and make it the Workspace default.
• In the left pane, select Java > Build Path > Classpath Variables.
• Click New.
• Add M2_REPO in the Name field and the path of your M2 repository in the Path field (for example, C:\Programs\m2repo). This value is needed in order to import Maven generated project configurations.
• In the left pane, select Server > Runtime Environments > Add > Jboss v7
• Click OK twice to close the dialog boxes.
• Create a new JBoss server instance (Window > Show View > Other > Servers > Server) and start the instance from Eclipse.
• We recommend the following plugins also be installed: