Mind the Flex

Setting up a Java and Flex Project in Maven 2 for Beginners

Maven is a tool that provides an uniform and easy build process for your projects. In real life this means generally that you describe your project in one xml file and Maven reads this information to compile and package your project. The pros of this approach are that the project can be set up quickly in new environment, you can quite transparently add new features, and you have all the time clear overview of libraries that are used in your project.

Why this entry was written: to give an hands on overview of how to develop a Flex and Java in one project with Maven 2
Who should read it: Java developers who have no experience with Maven and Flex

We'll start using a multiple module project in this example (a tutorial how to set up Maven can be found here). This means that you'll split the application to different logical units and the project would consist of one Java, one Flex, and one parent project. The project means in current context simply a directory, which contains a file named pom.xml and other project specific stuff like source code, properties etc. The pom.xml stands for Project Object Module and describes usually the contents of the project like where the source code is located, what kind of module it is and so on. This file is freely editable and you can open it with any text editor to change the values in it. When you open a pom.xml file then in case of a minimum pom you can see there following code:

<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>multiModuleProjectId </groupId>
  <artifactId>multiModuleProjectArtifactId </artifactId>
  <version>1.0</version>
</project>

The modelVersion tag contains the version number of the pom, which is currently 4.0.0 and is used by Maven itself to ensure compatibility with different pom versions. The groupId, artifactId and version are explained later as we start to create a project by ourselves. The projects are generally independent units and a modification in one should not affect usually other projects. This allows to share the development between different persons and it is useful also if you decide to replace one module with some other like trying out JavaFx or SilverLight with your Java module.

In the end of this tutorial the structure of the directory of the project will look similar to the following picture:

We'll start creating the projects using archetypes. Archetype is a term for a template, which allows to create Maven projects (directory structure with initial contents) automatically. The archetype can be written by yourself but the most common ones are already predefined and can be used easily without digging too deep into the Maven world in the beginning.

Creating a Parent Project
Create a directory to your disk where you want to put the project stuff we'll start creating now. Open command prompt, go to this directory and execute the command below. This command will create the parent project to the directory you are in at the moment. Don't be scared of all the stuff that is downloaded after the execution in the first time and later on as it is normal behavior. (In case the mvn tries to unsuccessfully contact the remote server, you should check the settings.xml file in the directory you installed Maven to. It could be the case that you are behind a proxy and therefore you would have to uncomment the proxy entry and update the proxy settings in this file).

mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=multiModuleProjectId -DartifactId=multiModuleProjectArtifactId -DpackageName=com.mypackage -Dversion=1.0

As you can see the command line has multiple parameters and let's take a closer look to them now. The first two (archetypeGroupId and archetypeArtifactId) mean that you want to use Maven's own archetype and to be more specific "maven-archetype-quickstart". The list of available archetypes can be found here and by just replacing this value in the command you can create skeletons for different type of projects.

The following parameters are your project specific and are meant to be changed by you:

-DartifactId=multiModuleProjectArtifactId
-DgroupId=multiModuleProjectId
-DpackageName=com.mypackage
-Dversion=1.0

On directory level they would look as following:

As you can see the artifactId determines the name of your project and this name is used later as the title of the project when you package it. In the future you would access your module from the following Maven repository path multiModuleProjectId\multiModuleProjectArtifactId\1.0 which would contain a file multiModuleProjectArtifactId-1.0.jar. The 1.0 in the filename is taken from the parameter version and marks the version of your project.

Creating a Java Web Application
Next we'll create a web application as in the end we want to package the Flex and web application together to deploy it to the server. For this purpose we will have to change the archetypeArtifactId to maven-archetype-webapp. We would also have to change the archetypeArtifactId as otherwise it would conflict with the project id we created previously. The groupId can stay the same as these two projects belong to one logical entity. After executing the following command:

mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-webapp -DgroupId=multiModuleProjectId -DartifactId=multiModuleProjectArtifactIdWeb -DpackageName=com.test -Dversion=1.0

we should see in our project folder a new folder, which contains following contents that describe the web application:

Creating a Flex Module
Flex project structure is quite similar to the parent project we created earlier but as there is an existing archetype available, we will use this one. Let's execute the command with a new archetype id but as this is not an "official" archetype we will have to change the archetypeGroupId also. Let's execute the following command:

mvn archetype:create -DarchetypeArtifactId=maven-archetype-flex -DarchetypeVersion=1.0 -DarchetypeGroupId=dk.jacobve.maven.archetypes  -DgroupId=multiModuleProjectId -DartifactId=multiModuleProjectArtifactIdFlex -DpackageName=

This will create a new folder with name multiModuleProjectArtifactFlex and the skeleton of the multimodule project is ready now.

Configuring the Parent project (pom.xml)
If everything went well then your project tree should look following:

As the next step we will have to modify the pom.xml in the multiproject since at the moment this project has no idea of being a parent to the Java and Flex project. Open the pom.xml and

1. change

   <packaging>jar</packaging>

   to

   <packaging>pom</packaging>

2. add after

   dependencies

   tag following code

   <modules>
     <module>../multiModuleProjectArtifactIdFlex</module>
     <module>../multiModuleProjectArtifactIdWeb</module>
   </modules>

   This means that this project has two modules (multiModuleProjectArtifactIdFlex and multiModuleProjectArtifactIdWeb), which are located in the same directory.

Configuring the Flex project (pom.xml)
As we used the predefined archetype, which did the most of the job for us, we only have to take care that the property flex.home in Flex projects pom.xml refers to the correct path like C:\Program Files\Adobe\Flex Builder 3 Plug-in\sdks\3.0.0. In the pom.xml you can see also definition of the Maven Flex plugin. The plugin by itself includes some kind of functionality that can be applied to your project. In our case this plugin is meant to take the flex sourcecode and compile it.

<plugin>
 <groupId>net.israfil.mojo</groupId>
 <artifactId>maven-flex2-plugin</artifactId>
 <extensions>true</extensions>
 <configuration>
   <flexhome>${flex.home}</flexhome>
   <usenetwork>true</usenetwork>
   <main>Main.mxml</main>
 </configuration>
</plugin>

As you can see, the definition of plugin is quite self-explanatory. The tag extensions, which is set to true means that you don't have to worry when the plugin is executed as it has own lifecycle.  In addition to that the configuration tag includes the parameters, which are needed by the plugin to get a picture of what and where it has to do something.

Configuring the Webapp project (pom.xml)
In configuring the web application you'll have to also add the dependencies. The dependencies tag is used to describe the resources that are needed for building the project. In the pom.xml in the web application project we need to refer to our flex project as it has to go to our web application war file we want to deploy later on. This is done using the depenencies tag that can include multiple dependency tags, which in our case would look as following:

 <dependencies>
  <dependency>
    <groupId>multiModuleProjectId</groupId>
    <artifactId>multiModuleProjectArtifactIdFlex</artifactId>
    <version>1.0-SNAPSHOT</version>
    <type>swf</type>
  </dependency>
</dependencies>

As the last step in configuring the Maven we need to define two plugins, which would take the compiled flex project and copy it to the web application project so it could be put to the war file and in addition to that we need a plugin, which would create index.html for displaying compiled swf. For compiling the Flex application we would use again the plugin maven-flex2-plugin we used earlier to compile the flex source. As you can see below, we have added the executions tag because we don't want to execute the default goal of the plugin but the copy-flex-applications goal, which would take the already compiled swf module from defined path and would put it to the path where the Maven war plugin could access it and put into the war file. To add plugins to the pom, you should add plugins tag after the finalName tag and put the following plugins between these tags.

<plugin>
  <groupId>net.israfil.mojo</groupId>
   <artifactId>maven-flex2-plugin</artifactId>
   <executions>
     <execution>
       <phase>compile</phase>
       <id>copy-flex</id>
       <goals>
         <goal>copy-flex-applications</goal>
       </goals>
       <configuration>
         <modules>
          <swfModule>
            <groupId>multiModuleProjectId</groupId>
            <artifactId>multiModuleProjectArtifactIdFlex</artifactId>
            <targetPath>target/multiModuleProjectArtifactIdWeb/</targetPath>
          </swfModule>
         </modules>
        </configuration>
      </execution>
   </executions>
</plugin>

In addition to this plugin we have to create a html wrapper for the swf file we just copied to the webapp. Since there is no suitable plugin for this purpose we have to use a workaround. As Adobe has created an Ant task for generating such wrappers and Maven has an Ant plugin, we will put these two together.

<plugin>
  <artifactId>maven-antrun-plugin</artifactId>
  <executions>
    <execution>
        <phase>compile</phase>
        <configuration>
            <tasks>
               <taskdef
                   className="flex.ant.HtmlWrapperTask" name="html-wrapper"
                   classpath="${flex.home}\ant\lib\flexTasks.jar" />
               <property name="FLEX_HOME" value="${flex.home}" />
               <property name="APP_ROOT" value="target/multiModuleProjectArtifactIdWeb" />
               <html-wrapper
                      title="Welcome to My Flex App"
                      file="index.html"
                      height="300"
                      width="400"
                      bgcolor="red"
                      application="app"
                      swf="multiModuleProjectArtifactIdFlex-1.0-SNAPSHOT"
                      version-major="9"
                      version-minor="0"
                      version-revision="0"
                      history="true"
                      template="express-installation"
                      output="${APP_ROOT}" />
           </tasks>
         </configuration>
         <goals>
           <goal>run</goal>
         </goals>
      </execution>
   </executions>
</plugin>

You should also add a property tag with correct flex home to this pom.xml. You could copy it from the pom.xml from flex module or copy-paste it from here after the url tag

<properties><flex.home>C:\Program Files\Adobe\Flex Builder 3 Plug-in\sdks\3.0.0</flex.home></properties>

This plugin will take care of the wrapper generation and copy it to the correct target directory from where the war plugin will pick it up and put into the war file.

Building and deploying the application
Now you should go on the command prompt to the folder where the pom.xml of parent project is located. In this folder you should execute the command mvn clean install. The result of plugin executions is put to the project subfolder named target, which is created by Maven during the command execution. To clean up previous results of execution you should add clean goal to the mvn command as was done previously. After executing this command you should find a file named multiModuleProjectArtifactIdWeb.war in your web application project target directory. This file can be deployed directly to the Tomcat webapps directory and you should be able to access the application on the following url http://localhost:8080/multiModuleProjectArtifactIdWeb/