Tuesday, June 24, 2008

Creating Modular Struts2 Applications with AppFuse and Netbeans – A Tutorial

Introduction

I am not in the habit of writing tutorials but I found that there was a very small niche that I couldn't find adequate documentation for so I decided to write this tutorial. I recently created a new application in which I used the excellent Struts 2 framework. I used Hibernate for persistence and Spring for dependency injection. I used Sitemesh to decorate the user interface and Freemarker to create the forms.


At first the list of technologies was overwhelming and I spent more than a month trying to figure out how to get all these to work well with each other. When I came across Matt Raible's most excellent framework AppFuse it was a Godsend. AppFuse can get you up and running in a few minutes with a large number of configurations.


I found that I was able to create projects without worrying about the configuration and then customize to suit my own needs. The documentation for AppFuse is very good and most of what I write here is covered. Its just that in using Netbeans there are a few points that I had to look in the mailing list for. So its only a very small bit I have to add. You will find appfuse quickstart at http://appfuse.org/display/APF/AppFuse+QuickStart.


Setting Up the Environment

First, lets make sure that we have everything installed and configured. You will need:

  1. Netbeans 6.1 – http://www.netbeans.org

  2. MySQL 5 - http://www.sun.com/software/products/mysql/getit.jsp

  3. Java 6 – http://java.sun.com

  4. Maven 2.0.7 at least - http://maven.apache.org/



On the respective websites there are installation instructions so I will not repeat them here. However there are a few things that I would mention.

Netbeans

After Netbeans has been installed you may install the Maven plugin.

Start by opening the Plugins window. Click Tools > Plugins. In the plugins window you can update existing plugins or install new plugins. Click on the Available Plugins tab. You will see the list of plugins that are available for download. See Figure 1.

Figure 1: Available Plugins in Netbeans

Search for the Maven pluigin and select it then click Install.

After the installation Netbeans is now Maven Aware.

Maven Local Repository

Create a local repository for Maven so that the project could be built even without an Internet connection. Select a location on the hard drive and set the following in the M2_HOME/conf/settings.xml file:


<localrepository>path/to/your /local/repository</localrepository>



Creating the Application

Now its time to create a new application, and this is where the magic of AppFuse happens. As the title implies this project is using Struts2 Modular architecture. AppFuse allows many different configurations so you should visit the website and see for yourself.

1. Open a command window and run the following command.


mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-modular-struts -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0.2 -DgroupId=com.mycompany.app -DartifactId=myproject


Make sure you change com.mycompany.app to your own package structure and myproject to the name of your project. Maven creates a directory with your project name.


2. CD into the newly created project directory

In here you will find a file called pom.xml. This file is the main configuration file for Maven. Open it and edit the Database Settings. You will find these near the bottom of the file. Add the user name and password necessary for your database.


3. Run mvn

This downloads all the files and dependencies from the internet for you. It may take a long time to run. The database will be created in MySQL at this point.


4. Run mvn war:inplace

This will copy the source code from the appfuse wars into your src directory and give you a chance to make changes to them.


5. Run mvn appfuse:full-source -DrenamePackages=false

This is necessary for Netbeans to find the dependent classes. It basically installs all the source code into your application. The rename packages option is necessary if you want to keep the appfuse packages separate from your packages.


6. Now lets test your project and make sure its working. CD to the web directory of your project. Run mvn jetty:run-war.

This builds your website and starts the Jetty server. You can now open your browser and visit http://localhost:8080 to see your application. The default user name and password is admin/admin.


7. Now you can open Netbeans and click File > Open Project. Browse to the location of your new project and click on it. Make sure that you select the Open Required Projects checkbox. Click Open Project button.

Now edit your project to your hearts content.