What is AppFuse?

AppFuse is an open source project and application that uses open source tools built on the Java platform to help you develop Web applications quickly and efficiently. It was originally developed to eliminate the ramp-up time found when building new web applications for customers. At its core, AppFuse is a project skeleton, similar to the one that's created by your IDE when you click through a wizard to create a new web project.

AppFuse 1.x uses Ant to create your project, as well as build/test/deploy it. AppFuse 2.x uses Maven 2 to create your project as well as build/test/deploy it. IDE support is much better in 2.x because you can generate the IDE project files with Maven plugins. AppFuse 1.x uses XDoclet and JDK 1.4+. AppFuse 2.x uses annotations and JDK 5+.

What are AppFuse's conventions for package naming?

It's recommended you start with com.companyname if you're commercial or org.organizationname if you're non-profit. Most folks match their internet domain name. From there, use your application name.

From there, AppFuse expects you to use the following conventions:

What is the difference between AppFuse 1.x and 2.x?

AppFuse 2.0 works rather differently from AppFuse 1.x - Maven keeps the AppFuse core classes as dependencies. You add your code, and Maven will merge in the code from AppFuse. This should make it much easier for you to upgrade to future releases of AppFuse.

If you run mvn jetty:run-war and point your browser to http://localhost:8080/ you will see that you have a fully fledged AppFuse project present. If you need to change any of the files in the web project, simply run mvn war:inplace in the web project to populate the src/main/webapp source directory. You will need to delete WEB-INF/lib and WEB-INF/classes/struts.xml (if you're using Struts) after doing this.

Where are the Java source files and JSPs in 2.x?

AppFuse 2.x is a fair amount different from 1.x in that you don't get all the source to start your project with. The main reason for this is to make it possible for you to upgrade your application to a newer version of AppFuse. For a more detailed explanation, please see this mailing list thread.

If you'd like to modify modify AppFuse's core entity classes, see how to modify core classes. If you'd like to convert your project so it doesn't rely on AppFuse dependencies and includes AppFuse's source instead, run mvn appfuse:full-source.

Can I use Ant instead of Maven in 2.x?

If you create a project using one of the basic archetypes in M5 and then run mvn appfuse:full-source, you can use a modified version of AppFuse Light's build.xml to build/test/deploy your project. Below are the steps needed to add Ant support to a basic archetype:

• Run mvn appfuse:full-source from your project's directory
• Download build.xml into your project.
• Edit build.xml to replace occurrences of "appfuse-light" with your project's name.
• Download maven-artifact-ant-2.0.4-dep.jar and copy it to a "lib" directory in your project. You will need to create this directory if it doesn't already exist.

We don't plan on supporting Ant for modular archetypes. If someone wants to contribute Ant support for them and support it, we'll be happy to add it.

Can I run AppFuse 2.x using Java SE 1.4?

AppFuse 2.x requires Java 5 for development, but not for deployment. You should be able to use the Retrotranslator Plugin to convert your WAR to be 1.4-compliant.

How do I customize the header and footer messages in 2.x?

If you would like change the following heading:

AppFuse
Providing integration and style to open source Java

Change src/main/resources/ApplicationResources.properties and change values for the webapp.name and webapp.tagline keys. To modify the "Your Company Here" text and its URL in the footer, you'll need to modify the company.name and company.url in this same file.

How do I customize Login and Error Pages in 2.x

If you would like change the any of the pages that appear in the root directory of your application, for example:

login.jsp, error.jsp, 404.jsp, logout.jsp

Put copies of your modified jsp files into src/main/webapp.

If you want to copy existing versions of these files and modify them, look for them in your target/YOUR_APP_NAME/ directory.

Why don't I have to install Tomcat with 2.x?

If you run mvn integration-test, the Maven Cargo plugin will download and install Tomcat and run the integration tests against it. If you want to see your project running in a server, you have two options:

1. Run mvn jetty:run-war - this will fire up a Jetty instance and it will be available at http://localhost:8080.
2. Run mvn cargo:start -Dcargo.wait=true and your application will be deployed to Tomcat and available at http://localhost:8081/applicationname-version.

You can also add the Maven 2 Tomcat Plugin to your pom.xml and use mvn tomcat:run and mvn tomcat:run-war.

    org.codehaus.mojo
    tomcat-maven-plugin
    
        /
    

What if I already have Tomcat installed and I'd like to use it?

If you want to change Cargo to point to an existing instance of Tomcat, you should be able to change the bottom of pom.xml from:

    ${cargo.container}
    ${cargo.container.home}
        ${cargo.container.url}
        ${installDir}
    

To:

    ${cargo.container}
    ${cargo.container.home}

You can also deploy to a running instance of Tomcat with Cargo.

What does "basic" and "modular" mean when it comes to AppFuse 2.x archetypes?

Basic archetypes are meant for developing web applications with no re-usable backend. This is the recommended archetype to use with AppFuse 2.x. The tutorials assume you're using this archetype.

Unlike Ant, Maven requires you to have a different "module" for each artifact you want to produce (i.e. JAR or WAR). This is what the modular archetypes are for. If you're an experienced Maven 2 user, you might consider this archetype. It's also useful if you need a backend that can be used by multiple clients.

How do I tell IDEA to ignore deployment descriptors when compiling?

Right-click on the file in the messages window and choose "Exclude From Compile".

How can I export my database using DbUnit?

Running mvn dbunit:export will export your database to target/dbunit/export.xml. You can override the destination location by passing in a -Ddest parameter:

mvn dbunit:export -Ddest=sample-data.xml

How can I change my AppFuse-generated project to use iBATIS or JPA?

As of AppFuse 2.0 M5+, it's as easy as changing your changing the property in your root pom.xml to ibatis or jpa (jpa-hibernate in 2.0 M5). For further instructions, please see the JPA and iBATIS tutorials.

Is there any documentation that describes what all the filters do in web.xml?

See the Web Filters Reference Guide for a list of what each filter in web.xml is used for.

How do I configure LDAP Authentication?

See the LDAP Authentication page for a sample configuration.

How do I debug my application when it's running in Jetty?

Dan Allen has a nice writeup of how to do remoting debugging with Jetty.

How do I make Jetty start on a specific port?

There are two easy methods depending on whether you want the change to be permanent (i.e. each time you run 'mvn jetty:run-war' or a manual port change.

Permanent: In your project pom.xml look for the plugin with the artifactid 'maven-jetty-plugin' and add the elements to it:

    org.mortbay.jetty
    maven-jetty-plugin
    6.1.5
    
        ...
        
	    "org.mortbay.jetty.nio.SelectChannelConnector">
		8081
	    
	
    

Manual: run 'mvn jetty:run-war -Djetty.port=8081'

When saving Chinese or Japanese characters in a form, I'm getting java.sql.SQLException: Incorrect string value. How do I solve this?

To solve this problem, you'll need to drop and recreate your database with UTF-8 enabled. The following example shows how to do this with a database named myproject:

mysqladmin -u root -p drop myproject
mysqladmin -u root -p create myproject
mysql -u root -p

mysql> ALTER DATABASE myproject CHARACTER SET utf8 DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci DEFAULT COLLATE utf8_general_ci;
mysql> exit

You can also configure MySQL to use UTF-8 by default by adding the following to your c:Windowsmy.ini or /etc/my.cnf (on Unix) file:

[mysqld]
default-character-set=utf8

When using jetty:run, CSS and JavaScript files are locked - how can I fix this?

Jetty buffers static content for webapps such as html files, css files, images etc and uses memory mapped files to do this if the NIO connectors are being used. The problem is that on Windows, memory mapping a file causes the file to be locked, so that the file cannot be updated or replaced. This means that effectively you have to stop Jetty in order to update a file.

The problem is explained more in Jetty's documentation. To fix this, add a line with to your maven-jetty-plugin configuration:

org.mortbay.jetty
maven-jetty-plugin
6.1.5

    ...
    src/main/resources/webdefault.xml

The default webdefault.xml file is found in the lib/jetty.jar at org/mortbay/jetty/webapp/webdefault.xml. Extract it to a convenient disk location and edit it to change useFileMappedBuffer to false:

    useFileMappedBuffer
    false

Using Struts, how can I dynamically add columns to a Table using a list of beans nested in my table row data?

This is the scenario. You are presenting a list of your data on a standard mymodelList.jsp form, using the Display tag library. Your data bean has an attribute that is a list of related data beans. In this scenario, you wish to display that related data in extra columns in your table. Here is one way to achieve this.

The following code example assumes that your Action class has generated a list of parentBean objects and exposes that with a getParentBeans() method that returns a List. The ParentBean object includes an attribute that is a list of ChildBean objects.
Our simple beans have the following structure:

... and the markup goes something like this...

for brevity --->
"parentBeans" class="table" requestURI="" id="parentBeans" export="true" pagesize="25">
    this is a normal column displaying the "ParentBean.title" attribute --->
    "title" sortable="true" href="editParentBean.html"
        media="html" paramId="id" paramProperty="id" titleKey="parentBean.title"/>
    "title" media="csv excel xml pdf" titleKey="parentBean.title"/>

    if present and display a name and lastUpdated column for each --->
    
    if test="#attr.parentBeans.childBeans != null && #attr.parentBeans.childBeans.size() > 0">
        this example, the List is actually implemented by a TreeMap (to facilitate sorting) so the
          reference is to the list's "values()" method, otherwise the iterator will return a Map object (containing
          a key and your bean) rather than just the bean.  If your childBeans list is a normal List (eg ArrayList)
          you'd simply put 'value="#attr.parentBeans.childBeans"' in the next line --->
        "childBean" value="#attr.parentBeans.childBeans.values()" status="col">
            
            "false" titleKey="childbean.name">
                this example, we edit a childBean by going to the
                     editor for its ParentBean --->
                "editParentBean.html?id=${parentBeans.id/|">
                    ${childBean.name/|
                
            
            "false" titleKey="childbean.lastUpdated">
                "${lastUpdated/|" pattern="${timePattern/|"/>
            
        
    if>

    for brevity --->