Prepare the Development Environment

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.

Recommended Path Purpose
C:\Programs\m2repo Maven local repository M2_REPO
C:\Programs\maven3 Maven3 program M2_HOME
C:\Programs\Java\jdk\6 Java Development Kit JAVA_HOME
C:\Programs\Java\jdk\6\jre6 Java Runtime Engine
C:\Programs\MySQL MySQL database server 5.6
C:\Programs\JetBrains\IntelliJ IDEA 9.0.2 IntelliJ IDEA IDE (optional)
C:\Programs\Eclipse Eclipse IDE (optional)
C:\Programs\JBoss\7 JBoss v7 Application Server JBOSS_HOME

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, or Computer > Properties > 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.

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.

Property Value Required?
JAVA_HOME Java installation directory, e.g. C:\Programs\Java\jdk\6 Yes
M2_HOME Maven installation directory, e.g. C:\Programs\maven3 (this may have already been set by the Maven installer) Yes
M2_REPO Maven local repository, e.g. C:\Programs\m2repo Yes
MAVEN_OPTS Parameters to pass to the Java VM when running Maven. Set this value to: -XX:MaxPermSize=128m -Xmx512m (required to build large maven projects such as AndroMDA itself) No
JBOSS_HOME JBoss installation directory, if running jboss server e.g. C:\Programs\JBoss\7 No
ANT_HOME Ant installation directory, if running ant scripts from maven e.g. C:\Programs\Ant. Can set to eclipse\plugins\org.apache.ant directory. No
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;%ANT_HOME%\bin Yes

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:
Plugin Repository or Download Location (* = Manual install) Notes
Sonatype M2E http://download.eclipse.org/technology/m2e/releases Import maven projects, run maven from Eclipse. See http://wiki.eclipse.org/M2E_FAQ
SpringSource Tool Suite http://dist.springsource.com/release/TOOLS/update/e3.7

http://dist.springsource.com/release/TOOLS/composite/e3.7

Install instructions at http://download.springsource.com/release/STS/doc/STS-installation_instructions.pdf
JBoss Tools http://download.jboss.org/jbosstools/updates/development/ If using JBoss server or Hibernate ORM. Only Dev releases are available for Eclipse 3.7. Install instructions at https://www.jboss.org/tools/download/dev.html
PMD http://pmd.sourceforge.net/eclipse Code quality checker
CheckStyle http://eclipse-cs.sourceforge.net/update Code quality checker
FindBugs http://findbugs.cs.umd.edu/eclipse-candidate Code quality checker
Cobertura http://ecobertura.johoop.de/update Code unit test coverage
SVN http://eclipse.svnkit.com/1.3.x If using SVN repositories, integrate with Eclipse Subversive
Velocity http://veloedit.sourceforge.net/updates If editing Velocity templates

What's Next?

Now that the development environment is set up, we are ready to try out the TimeTracker application. Click here to get started.