This article is written on top of the great work that Sébastien Arbogast has done. He has written 3 articles that showed you how to wire up Flex, BlazeDS, Spring, Hibernate and MySQL with Maven as build process. I have included his articles below as your reference.

1. The Flex, Spring, and BlazeDS full stack – Part 1: Creating a Flex module
2. The Flex, Spring and BlazeDS full stack – Part 2: Writing the to-do list server
3. The Flex, Spring and BlazeDS full stack – Part 3: Putting the application together

I have found Sebastien’s work as a good foundation for my own project. To contribute back to the community, I will write a series of articles to show you how can customize and extend the todolist sample.

What is in the Part 1 of the series…

1. Enhancements on the Maven build process
   • Leverage RSL to factor our the framework swc, so the size of the application swf will be reduced. Apart from that, I also take advantage of Flash Player Cache that is available after version 9 update 3 to cache the framework libraries.
   • Clean up the Flex and BlazeDS dependencies in POM as the latest version of the sdk is available and the BlazeDS dependencies are officially available.
   • Include some common reports for maven site generation
   • Embed Jetty web server in the build process for quick deployment and testing
2. Document how to get the sample up on Eclipse for development
   
3. Use Mate as Flex framework
   • Restructure ToDoList sample to leverage Mate framework
   • Factor out Mate as RSL and integrate it with Maven build process via Flex-mojo plugin.

What are in the coming articles…

1. In part 2 of this series, I will show you how to use flex-mojo to build a modular Flex application.
2. In part 3 of this series, I will show you how to test your flex app via FlexUnit (Unit test) and FlexMonkey (Functional test)
3. In part 4 or this series, I will work on server side. I am planning to add monitoring, caching and security to the server side.

Review “ToDoList” sample

Before I start my journey, let me highlight what Sebastien has done first:

1. Sebastien’s sample demonstrates how to use Maven as a build process. There are 3 parts or subprojects in his sample. They are:
   • todolist-config (configuration files shared by other subprojects)
   • todolist-ria (Flex frontend)
   • todolist-web (Server side that supports the Frontend)
2. All these subprojects are considered as modules of the main project (root POM). Finally, they are combined together into war artifact and ready to deploy to Tomcat or other J2EE webapp server.
3. Flex frontend and backend communicate through a binary RPC protocol – AMF. AMF is considered to be the simplest and fastest remoting approach available in Flex. Recently, Adobe has released BlazeDS as an open source implementation of AMF spec. In this sample, BlazeDS is used. To use BlazeDS, there are few things you need to do:
   • Externalize your POJO service via BlazeDS. This sample shows you how to integrate BlazeDS with Spring
   • Make BlazeDS endpoints availabe to the Net via Servlet.
   • Have frontend and backend shared the same BlazeDS configuration files.
4. In this sample, you can also find out how to use flex-mojo maven plugin to compile the Flex frontend code into swf. Apart from flex-mojo plugin, there are other two good plugins worth to mention:
   • maven-assembly-plugin - can be used to bundle all the files under a directory into a zip file. It is used by todolist-config to bundle all the configuration files (service-config.xml and remoting-config.xml) into a zip during the package phase.
   • maven-dependency-plugin – can be used to unpack the zip file and move to the place you want. It is used by todolist-web to unpack the config zip during the generate-resources phase.

Enhancements on maven POM

I have modified the sample’s maven pom as follows:

• Link to new repository “Sonatype Forge” in the root POM. So, I can use the new version of flex-mojo and simplify the todolist-ria adobe framework dependencies. Apart from that, I also take away the private repository from Sebastein because BlazeDS libraries are available in official maven repository (Note: The BlazeDS libraries available in official maven repo are in version 3.0 instead of 3.0.0.544. So, you need to modify the webapp pom correspondingly).

    <repositories>
        <repository>
            <id>flex-mojos-repository</id>
            <url>http://svn.sonatype.org/flexmojos/repository/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

    <pluginRepositories>
        <pluginRepository>
            <id>flex-mojos-repository</id>
            <url>http://svn.sonatype.org/flexmojos/repository/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

• Because I link to Sonatype repository, I can have my todolist-ria depends on one flex-framework pom dependency instead of all the swc dependencies. Note that the pom dependency is a way to factor out all the adobe swc dependencies that makes your pom easier to maintain.

        <dependency>
            <groupId>com.adobe.flex.framework</groupId>
            <artifactId>flex-framework</artifactId>
            <version>3.1.0.2710</version>
            <type>pom</type>
        </dependency>

• I include mysql driver as dependency in my webapp pom. I think it is cleaner to bundle it in war. I have also added jetty plugin in the POM so you have a web server embedded in the build process. With this, you can run this sample application right after you check it out from svn (assume you have maven 2 installed). To start jetty, you can issue the following maven command under your webapp project.

project_root> mvn clean install
project_root/jp-web> mvn jetty:run-war

• I have included some reports that will be shown after site generation. You may not be able to do mvn site-deploy because it is linked to my web hosting site. However, you can modify it for your own sake.

Get the sample up on Eclipse

To develop on Eclipse, you can follow the steps below:

1. Create Eclipse project file via running the command below at the project root. This will create 2 eclipse projects. One for todolist-ria and one for the webapp. You noticed that I use the -Declipse.downloadSource=true to include the source files of my dependencies in my eclipse project. Therefore, I can get to the source code if needed.

mvn -Declipse.downloadSource=true eclipse:eclipse

1. Import the projects into Eclipse
2. Add new variable M2_REPO and set it equals to [home]/.m2/repository
3. If you have installed Flex Builder plugin to your Eclipse, you can Add Flex Project Nature to the todolist-ria project.
   • Select Application Server Type: J2EE
   • Put check on “Use remote object access service” with LiveCycle Data Service selected.
   • Set up the path. I have my tomcat installed under C:\tools with default 8080 as port. You should make the changes if you installed it differently.
   • 
   • Remove the generated main.mxml under the src folder.
   • Set index.mxml under src folder as default Flex application file to run.
   • Use Default Flex SDK in Flex Compiler Configuration instead of Server Flex SDK
   • Right click and select Recreate HTML Template if you see error.
   • After all these, you have configured your Flex application pointing to the webapp server and sharing the BlazeDS configuration files. You can verify in Flex Compiler Configuration’s Additional Compiler Parameters. See whether you see this: -services “C:\tools\tomcat-6.0.16\webapps\jp\WEB-INF\flex\services-config.xml” -locale en_US
   • Move the war to your tomcat’s webapp folder and start it under remote debugging setting. If you are using window, set DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8787,suspend=n under your bin/catalina.bat.
   • Start your webapp via bin/startup.bat
   • Put breakpoint under TodoServiceImpl save method and start remote debugger on localhost:8787
   • Right click the index.mxml and Run As Flex Application.
   • Add a new entry and save it on the flex app. You should see your remote debugger halt at the breakpoint for you to debug.
   • Now you can change your flex code and test it out without leaving your Eclipse. However, if you modify the service in webapp, you need to run “mvn clean install” and deploy the war to the tomcat before your flex code can call your server-side code via AMF.

Use Mate as Framework

If you are not familiar with Mate, click the image below that moves you to a nice presentation.

What did I do to restructure the todolist sample to make it Mate app?

Download

I have made my work available at: www.solutionhacker.com/wp-content/uploads/todolist-jp-modified.zip

Reference

Below are the references I used for the article:

1. Flex mojo compiler user guide
2. Flex mojo dependency scope rules
3. Flex 3 feature introduction: Flex 3 RSL
4. Improving Flex application performance using Flash Player Cache
5. FNA archetype projects 

POM lets you to tell maven the “what” and maven knows the “how”. Put it in another way, POM gives you an abstraction layer over your build process to make things more explicit, more standard and easier to follow. There are several key elements in POM that I want to talk about. Below is a nice diagram I borrowed and it shows you what information the POM captures.

1. Identifier (artifactId-version.[packaging])
   • groupId – directory structure layout
   • artifactId
   • version
   • packaging type
2. Project relationship (Inheritance vs aggregation)
   • Inheritance – If you have several Maven projects, and they all have similar configurations, you can refactor your projects by pulling out those similar configurations and making a parent project. Thus, all you have to do is to let your Maven projects inherit that parent project, and those configurations would then be applied to all of them. (Goal: simplify the pom). Syntax: Parent POM has <packaging>pom</packaging> and Children POM specify <parent> element. However, parent has no knowledge of its children.
   • aggregation - if you have a group of projects that are built or processed together, you can create a aggregator project and have that declares modules and sets packaging type to pom. By doing so, you’d only have to build the aggregator and the rest will follow. (Goal: simplify the build). Syntax: Aggregator POM has <packaging>pom</packaging> and <module>xyz</module> specified. However, module has no knowledge of the aggregator.
     
   • You can use inheritance together with aggregation.
3. Choose packaging type
   • Defines what goals your project will be executed during the build process and what artifact type of your output.
   • pom (package > install > deploy) and package is using site:attach-descriptor goal.
   • jar and war (see Lifecycle below)
4. Path management
   • All directories not beginning with “/” or some other absolute path delimiter are relative to ${baseDir}—the directory where the POM lives.
5. Lifecycle is composed of build phases and a phase is made up of 0 to many goals (ie tasks).  A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. There are three built-in build lifecycles: default, clean and site. These build phases below (plus the other build phases not shown here) are executed sequentially to complete the default lifecycle.
   • validate – validate the project is correct and all necessary information is available
   • process-resource
   • compile – compile the source code of the project
   • process-test-resource
   • test-compile
   • test – test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
   • package – take the compiled code and package it in its distributable format, such as a JAR.
   • integration-test – process and deploy the package if necessary into an environment where integration tests can be run
   • verify – run any checks to verify the package is valid and meets quality criteria
   • install – install the package into the local repository, for use as a dependency in other projects locally
   • deploy – done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
   • If you want the full lifecycle reference, check this out.

   • 

6. Maven extension points
   • plugins (contains 1 or more goals) can be used to plugin goal to the phase. And plugins can be seen as libraries to the build like dependencies to your projects. Note that adding the plugin on its own is not enough information – you must also specify the goals you want to run as part of your build. The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed first, followed by those configured in the POM. Note that you can use the <executions> element to gain more control over the order of particular goals. (For details, see Customize Your Build Process below)
7. Dependencies Management
   • Transitive dependency – You just tell Maven which libraries you need, and Maven will take care of the libraries that your libraries need (and so on).
   • Dependency scope: compile (default), provided (use it compile but will not be deployed), runtime (not needed in compilation but execution like JDBC driver), test (only need for test compilation and run tests)
   • Create your own repository
   • Concept of Snapshot - depends on snapshot means depends on the latest version of the dependency as it gets download every time you run the build process.
8. Create your own archetype
9. Configuration Management
   • Configure the configuration via setting properties as variable that can be referenced via ${name} throughout your pom. There are many other ways to set properties—through the (1) command line, through the Maven (2) settings.xml files, through (3) filters. For example, if your box is behind a firewall, you may nee to go through a proxy to download the dependencies. To set this up, you can do it in settings.xml <proxies> element.
   • There is a super pom that all your projects are inherited from. So, you can taste the power of configuration via convention. 

Customize Your Build Process

Associate goals to the standard lifecycle

<build>
   <pluginManagement>
     <plugins>
          <plugin>
            <groupId>com.mycompany.example</groupId>
            <artifactId>maven-touch-plugin</artifactId>
            <version>1.0</version>
            <executions>
               <execution>
                   <phase>process-test-resources</phase>
                   <goals>
                      <goal>timestamp</goal>
                   </goals>
              </execution>
            </executions>
          </plugin>
      </plugins>
  </pluginManagement>
</build>

The above setting tells maven that you have a goal “timestamp” under maven-touch-plugin that you want to associate it to “process-test-resources” phase during the build process. You do this goal-phase association under <execution> element. You put this setting under <pluginManagment> because you want this to be inherited to all the children POMs. Otherwise, you can have <plugins> without <pluginManagement> and the setting will only apply to single POM.

Just simply associate an plugin to the project

     <build>
       <finalName>maven2example_webapp</finalName>
         <plugins>
             <plugin>
                  <groupId>org.mortbay.jetty</groupId>
                  <artifactId>maven-jetty-plugin</artifactId>
             </plugin>
         </plugins>
     </build>

OK. This allow you to run your project in jetty web container. You notice that simply adding a few lines to a pom.xml file will automatically download and launch Jetty (a lightweight servlet/JSP container), seamlessly installing and running the WAR file by issuing a command as below.


    C:\[project path]>mvn jetty:run

You can also configure your plugin

For example, if  you wish to force compilation on Java 5, simply pass in the following option under the build configuration in the pom.xml file. The maven-compiler-plugin has already been used behind the scene. Here you just need to configure it. So, you don’t need to put other information here. Each plugin listed on the Maven 2 site includes documentation on the various configuration options available.


      <build>
         <plugins>
           <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              <configuration>
                   <source>1.5</source>
                   <target>1.5</target>
              </configuration>
           </plugin>
         </plugins>
       </build>

If you want to extend maven via ant tasks, you can do that via plugin as well

  <build>
    …
    <plugins>
       <plugin>
          <artifactId>maven-antrun-plugin</artifactId>
          <executions>
            <execution>
              <phase>generate-sources</phase>
              <goals>
                <goal>run</goal>
              </goals>
              <configuration>            
                <tasks>
                  <!– Ant tasks go here –>
                </tasks>
              </configuration>
            </execution>
          </executions>
        </plugin>
     </plugins>   
  </build>

Useful commands

To list out what goals a plugin contains:

mvn help:describe -Dplugin=org.apache.maven.plugins:maven-archetype-plugin -Dfull=true

To run archetype creation from the template installed locally: (You can delete local templates via removing the file in your user home directory)

mvn archetype:generate -DartifactId=jp -DarchetypeCatalog=local

Reference

This references below helps me to write this article:

1. Introduction to Maven 2 – javaworld
2. Building Web Application Using Maven 2 – java.net
3. Maven 2 POM demystified (build section) – javaworld