Saturday, April 10, 2010

Quick web app prototyping with AppFuse

Quick web app prototyping with AppFuse


Sometimes we just need to put together a quick web app for prototyping, discuss screen flows, design layouts, create web services etc. I found AppFuse to be a pretty good option for this purpose.

You can follow the steps in this article to setup your environment and create a new web application with AppFuse. The best thing is that once your environment has all the requirements setup it is super quick to create as many new web apps whenever you need. Even if you aren't very familiar with things like AppFuse, Maven, Spring, Hibernate etc but still want to be able to generate new web apps, just try to endure the first steps - once you see the web app up and running on your computer I am sure you will be more motivated to learn it all through AppFuse.

Click on the "Read more" link below to get started with AppFuse and build a working web application in no time.




I used AppFuse 2.1.0 M1 on my examples for this article since this is what I would use if I had to start a new project today. If you prefer to use the last full release of AppFuse 2.0.2 or the snapshot release for M2 check out the additional sections at the end of this article.

Prerequisites


1. Java Development Kit 1.5.x or newer
You can download the latest one here:
http://java.sun.com/javase/downloads/widget/jdk6.jsp

2. Apache Maven 2.0.x (AppFuse 2.0.2) or Maven 2.2.x (AppFuse 2.1.0+)
You can download both versions here:
http://maven.apache.org/download.html

3. Any email server
You can download an open source implementation here:
Java Apache Mail Enterprise Server (JAMES) - http://james.apache.org/download.cgi#Apache_James_Server

An email server is not exactly required for you to use AppFuse but it is used by the standard automated tests. If this is your first time using AppFuse it is a good idea to start James just to avoid having to disable or modify jUnit tests.

No database is required (how cool is that?) if you can use one of the supported embedded database such as H2 or HSQLDB. Sure, you can easily configure AppFuse to use other databases such as MySQL or Oracle, but while this is a good idea for a real enterprise application it is out of the scope for this quick guide.

Eclipse (or any other Java IDE) isn't actually required if you just want to run AppFuse's starter web application - however, if you are planning on customizing it, play with changing configuration and properties files etc you really want to use it. I included instructions to setup the project in Eclipse but if you use some other IDE you might want to check AppFuse's website or forum for more information.

Environment setup


You will need to execute the steps in this section only once. After you set up all requirements on your development environment you will be able to create and start new web applications with just 4 or 5 commands, without even touching code or configuration files!

For this example I will install the JDK, Maven and James in "C:\Users\Pedro\Env\Java" and create my AppFuse-based projects in "C:\Users\Pedro\Projects" - but you can use whatever paths you want – especially if your name isn't "Pedro"! From now on I will refer to "C:\Users\Pedro\Projects" just as PROJECT_ROOT.

1. I always create a batch file (in Windows) or shell script (in Unix) to set up my environment variables. Usually this is a better practice than set environment variables only in the system configuration since it is easier to clone on other machines and make the project less coupled with the underlying environment. If you want to do the same, on PROJECT_ROOT create a file called setenv.bat with the content below:

set JAVA_HOME=C:\Users\Pedro\Env\Java\jdk1.6.0_17
set PATH=%JAVA_HOME%\bin;%PATH%
set M2_HOME=C:\Users\Pedro\Env\Java\apache-maven-2.2.1
set MAVEN_HOME=C:\Users\Pedro\Env\Java\apache-maven-2.2.1
set PATH=%MAVEN_HOME%\bin;%PATH%
set MAVEN_OPTS=-Xms256m -Xmx512m

Remember to replace the paths in setenv.bat described above with the ones you use on your environment.

Let's create a new web project!


1. Start your mail server:


Execute C:\Users\Pedro\Env\Java\james-2.3.2\bin\run.bat




2. Open a command prompt, go to PROJECT_ROOT and execute setenv.bat




3. Create a new AppFuse project:


AppFuse supports different combinations of various frameworks - in the example below uses Spring, Hibernate and JSF. If you want to use other frameworks you can check out AppFuse's official site for the appropriate Maven commands.

Also, note that the first time you create an application with AppFuse it will take Maven several minutes to download all the dependencies from the internet into your local Maven repository. However, the next times since it will already have the JARs the build will finish much faster.

[AppFuse 2.1.0 M1]


On the same command prompt window copy and paste the commands below to generate the web application:

I am using simple names in the example below, but for a real project you might want to replace "com.mycompany" with a more meaningful Java package, and "appfusem1" with your project name.

mvn archetype:generate -B -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-jsf-archetype -DarchetypeVersion=2.1.0-M1 -DgroupId=com.mycompany -DartifactId=appfusem1
cd appfusem1
mvn appfuse:full-source
mvn -P hsqldb
mvn -P hsqldb install

Because of the many tests being executed as part of the build process it is normal for warning and error messages to popup in the command prompt, just give it some time and wait for it to complete.

If you got a SUCCESS message like the one shown below your web application was generated correctly and it is ready to run.



Build, test and run:

mvn -e -P hsqldb jetty:run-war


Wait for the message highlighted above.

Open your internet browser and go to URL "http://localhost:8080/".
You can login as username "admin" password "admin" or username "user" password "user".



Disable database rebuild, unit and UI tests


Database rebuild, unit and web tests are enabled by default, which means that even with the JARs the builds will take some time to complete. It is a good idea to run and keep these tests in sync with the code so you can avoid surprises, but for times when we just want a quick build we just need to add property "-DskipTests=true" in the command line to disable it all.

For example:
mvn -e -P hsqldb jetty:run-war -DskipTests=true

Import project in Eclipse:


You can use Maven to generate Eclipse's .project file:
mvn -P hsqldb org.apache.maven.plugins:maven-eclipse-plugin:2.5.1:eclipse

Open Eclipse with PROJECT_ROOT as the workspace. If Eclipse does not ask you for the workspace when it starts, go to File / Switch Workspace / Other and enter the path to your PROJECT_ROOT

In Eclipse, select File / Import, expand General and select Existing Project into Workspace



Click Next and for the root directory just click Browse and Ok to select the current workspace, make sure your new project is listed and checked, and click Finish.

Once the import is finished you will see many dependency issues – to correct this you must add a variable classpath in Eclipse named "M2_REPO" pointing to your Maven repository
eg. M2_REPO=C:\env\.m2\repository

You can do that via Eclipse: right-click the project root node, select Java Build Path, Libraries, Add Variable, New, and create M2_REPO pointing to your Maven repository.

You can also do that using Maven: in the command prompt window just execute the command below:
mvn -Declipse.workspace=C:\Users\Pedro\Projects eclipse:add-maven-repo

Instructions for different versions of AppFuse


[AppFuse 2.0.2]

mvn archetype:generate -B -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-jsf -DarchetypeVersion=2.0.2 -DgroupId=com.mycompany -DartifactId=appfuse202
cd appfuse202
mvn appfuse:full-source

To correct a minor bug with AppFuse + embedded databases in Windows, edit and replace in pom.xml:
<jdbc.url><![CDATA[jdbc:hsqldb:${java.io.tmpdir}/appfuse202;shutdown=true]]></jdbc.url>
with:
<jdbc.url><![CDATA[jdbc:hsqldb:tmp/appfuse202;shutdown=true]]></jdbc.url>

mvn -e -P hsqldb
mvn -e -P hsqldb install eclipse:eclipse

How to disable database rebuild, unit and UI tests in 2.0.2: add "-Dmaven.test.skip=true". For example:
mvn -e -P hsqldb jetty:run-war -Dmaven.test.skip=true

[AppFuse 2.1.0 M2 SNAPSHOT]

mvn archetype:generate -B -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-jsf-archetype -DarchetypeVersion=2.1.0-M2-SNAPSHOT -DgroupId=com.mycompany -DartifactId=appfusem2
cd appfusem2
mvn appfuse:full-source
mvn -P hsqldb
mvn -P hsqldb install eclipse:eclipse

No comments:

Post a Comment