AppFuse QuickStart

To start developing Java EE applications with AppFuse 2.x, please following the instructions below:

Table of Contents

1. Create a new project.
2. Run it.
3. Have Fun.

Create a project

1. Download and install JDK 5+.
2. Download and install MySQL 5.x.
3. Setup a local SMTP server or change mail.properties (in src/main/resources) to use a different host name - it defaults to "localhost".
4. Download and install Maven 2.0.6.

   If you'd prefer to create your project from Eclipse rather than from the command-line, checkout Candy for AppFuse.

5. AppFuse comes in a number of different flavors. To optimize and simplify your experience as a user, we've created a number of different archetypes (a.k.a. starter projects). There are currently two types of AppFuse Archetypes: basic and modular. The basic archetypes are ideal for creating projects that will serve as web applications. The modular archetypes contain "core" and "web" modules and are ideal for creating projects that have a re-usable backend. The list of commands to produce these projects is below. You should change the groupId to match your preferred package name and the artifactId to match your project's name.

   The warnings you see when creating an archetype are expected. If you see BUILD SUCCESSFUL at the end, your project was created successfully.

   Archetype	Command
   JSF Basic	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-jsf -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Spring MVC Basic	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-spring -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Struts 2 Basic	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-struts -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Tapestry Basic	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-basic-tapestry -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   JSF Modular	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-modular-jsf -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Spring MVC Modular	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-modular-spring -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Struts 2 Modular	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-modular-struts -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Tapestry Modular	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-modular-tapestry -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject
   Core (backend only)	mvn archetype:create -DarchetypeGroupId=org.appfuse.archetypes -DarchetypeArtifactId=appfuse-core -DremoteRepositories=http://static.appfuse.org/releases -DarchetypeVersion=2.0 -DgroupId=com.mycompany.app -DartifactId=myproject

   You should be able to run AppFuse immediately if you have a MySQL 5.x database installed and it's accessible to root using no password. If you'd prefer to use an embedded database, we've recently added Database Profiles for H2, HSQLDB, etc.

MySQL Security Running MySQL using root with no password is not the most secure thing to do. Once your database is created, you can change the root password using the command below: mysql --user=root --pass='' mysql -e "update user set password=password('newpw') where user='root'; flush privileges;" AppFuse uses the username "root" and a blank password by default. To change these values, modify the <jdbc.username> and <jdbc.password> properties in your project's pom.xml (at the bottom).

Run your application

Running AppFuse is easy now. Once the archetype project is created, Maven will create and populate your database using the hibernate3 and dbunit plugins, respectively. All you have to do is use Maven to run the Jetty container and view your application.

1. Check your new project into source control, unless you have a good reason not to. Google Code has free Subversion hosting, as do many others.
2. From the command line, cd into your new project's directory and run mvn to download JARs, Tomcat and run the integration tests in your project. Now is a good time to take a coffee break or grab a beer - downloading everything and running the tests can take 5-10 minutes.
3. To view your application run mvn jetty:run-war from your project's directory (for a modular project, you'll need to run mvn jetty:run-war from your project's web directory). Maven will start Jetty and you should be able to view your application in your browser at http://localhost:8080.

   The default username/password for an admin user is admin/admin. For a regular user, use user/user.

4. To override files from AppFuse, run mvn war:inplace. This will extract the dependent WARs into src/main/webapp, where you can change files to your heart's content. When you have the war expanded in your source tree, you can run mvn jetty:run. This will allow you to change files on-the-fly and Jetty will reload them as needed. The only problem with this approach is you end up with an "exploded AppFuse" in your project, which won't bode well for upgrading. We recommend you check your project into source control before running mvn war:inplace. That way, it'll be easier for you to decide what needs to be checked in (over written) and what can be deleted.

If you receive OutOfMemory errors when using jetty:run, see this mailing list thread.

You can change AppFuse from its "embedded mode" to full-source mode by running mvn appfuse:full-source from your project's root directory.

Development Environment See development environment for detailed instructions on how to setup your computer to develop AppFuse-based applications.

Changing database settings To change your MySQL database settings, simply change the <jdbc.*> properties at the bottom of your pom.xml. See Database Profiles to use a database other than MySQL.

Develop your application

You can develop your application using Eclipse, IDEA or NetBeans. For Eclipse, run mvn install eclipse:eclipse to generate project files. For IDEA, use mvn idea:idea. Further instructions can be found in the IDE Reference Guide.

The Tutorials should help you get started developing your application.