Release Notes 2.0 M5
Added by Matt Raible, last edited by tibi@dds.nl on Jun 25, 2007 03:58

Labels:

(None)

Add Labels

Enter labels to add to this page:

Tip: Looking for a label? Just start typing.

The major features in this release are Code Generation, Full Source and XFire support. Please see about the AppFuse Maven Plugin (AMP) for more information on how to generate code and import AppFuse source into your project. In addition, we've finally solved the DAO Framework switching problem. However, AMP relies on a hibernate.cfg.xml file to generate code, so if you switch to iBATIS or JPA, you may need to keep this file around until we come up with a better solution. Finally, we added an "appfuse-core" archetype that allows you to create a backend-only application with Managers, DAOs and Web Services.

Please see the Upgrade Guide below or the QuickStart Guide to get started with this release.

Upgrade Guide

If you're currently using AppFuse 2.0 M4, here's a few things you'll need to change to upgrade to 2.0 M5. If you're using a version prior to 2.0 M4, you may want to follow previous upgrade instructions first.

Diff is your friend
The easiest way to make the changes below might be to compare your pom.xml, web.xml and web-tests.xml with the ones from a new archetype. Beyond Compare is a fabulous diff tool for Windows users.

Backup your project on your local file system or (even better) in your source control system.
In pom.xml, change <appfuse.version>2.0-m4</appfuse.version> to <appfuse.version>2.0-m5</appfuse.version>.
War inplace
Take care when using mvn war:inplace (exploded war for mvn jetty:run) to remove old class file first from the WEB-INF folder: rm -r src/main/webapp/WEB-INF/classes
The default usernames and passwords have changed from mraible/tomcat and tomcat/tomcat to admin/admin and user/user. In addition, the default role names have changed from "admin" and "user" to "ROLE_ADMIN" and "ROLE_USER". You'll need to update your login.xml, applicationContext-struts.xml, menu-config.xml, sample-data.xml, web-tests.xml and security.xml (if you've customized it) to reflect this change. Using a diff tool to do this is probably the easiest solution.
Own roles
You need to change your roles to the same format. From myRole to ROLE_myRole (or better ROLE_MY_ROLE).
If you've created any Managers or DAOs, you'll may need to make some changes as described below.
Maven's war overlay feature is based on timestamps. If you've overridden AppFuse files in your project, you'll need to "touch" them in order to give them a newer timestamp. Here's a sample of what you might run:
```
touch src/main/webapp/*
touch src/main/webapp/scripts/*
touch src/main/webapp/WEB-INF/*
touch src/main/webapp/WEB-INF/pages/*
```
Another, more permanent, solution is to use <dependentWarExcludes> to prevent the files from being overlayed.
In pom.xml, change the groupId of the appfuse-maven-plugin from org.appfuse to org.codehaus.mojo.
If you'd like to use the appfuse-maven-plugin to generate code in a pre-2.0 M5 project, you'll need to add placeholders to various XML files
The default goal in basic projects has changed from "package" to "install".
JPA: The <warpathExcludes> should have **/persistence.xml instead of "persistence.xml".

If you want to switch your persistence framework from Hibernate to iBATIS or JPA, you'll need to configure your appfuse-${web.framework} dependency to exclude appfuse-hibernate. If you're using a modular archetype, put the following exclusion on your appfuse-service dependency.

<dependency>
    <groupId>org.appfuse</groupId>
    <artifactId>appfuse-${web.framework}</artifactId>
    <version>${appfuse.version}</version>
    <type>warpath</type>
    <!-- This exclusion and the dependency following this one allow DAO framework switching. -->
    <!-- You only need these if you want to use JPA or iBATIS. See APF-565 for more information. -->
    <!-- It does no harm to leave it in for Hibernate, but it's not needed. -->
    <exclusions>
        <exclusion>
            <groupId>org.appfuse</groupId>
            <artifactId>appfuse-hibernate</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.appfuse</groupId>
    <artifactId>appfuse-${dao.framework}</artifactId>
    <version>${appfuse.version}</version>
</dependency>

Add <version>2.0</version> to the cobertura-maven-plugin to fix its "100% code coverage" bug.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>cobertura-maven-plugin</artifactId>
    <version>2.0</version>
</plugin>

Configure the maven-pmd-plugin so it works with JDK 5.

<plugin>
    <artifactId>maven-pmd-plugin</artifactId>
    <configuration>
        <linkXref>true</linkXref>
        <targetJdk>1.5</targetJdk>
    </configuration>
</plugin>

Change <spring.version> to 2.0.5 if you have it specified in your pom.xml.
The maven-warpath-plugin has a new version of 1.0-m5. Update your pom.xml.
In webapp/common/menu.jsp, change the path of the Velocity template from "WEB-INF/classes/cssHorizontalMenu.vm" to "cssHorizontalMenu.vm". This is necessary if you plan on using "mvn jetty:run" after running "mvn appfuse:full-source".
Some menu location changes were made: the Main Menu is now hidden on the login screen and Upload File has moved to Admin Menu. You're not required to make these changes in your project, it was more of a cosmetic change.
The OpenSessionInViewFilter is now commented out in web.xml by default. It's not needed by AppFuse and makes it more difficult to test everything with iBATIS and JPA.
XFire is now integrated by default. If you'd like to use web services in your project, you'll need to make a few changes to your web.xml. Diffs are available for JSF, Spring, Struts and Tapestry. Thanks to Luke McLean for detailed instructions on integration.
The syntax for setting the heading has changed. If you haven't customized your decorators/default.jsp, you'll need to change your headings from <content tag="heading"><fmt:message key="mainMenu.heading"/></content> to <meta name="heading" content="<fmt:message key='mainMenu.heading'/>"/>. This was done to reduce errors from JSP editors in Eclipse and IDEA.

Change in usage of Managers and DAOs

In versions prior to M5, the EntityManager.merge() method was being used incorrectly. This has been fixed for M5, and the fix requires a slight modification of how Manager and DAO methods are used. Previously, the 'save' methods (semantically, these methods handle saving a new object or updating a previously saved one) returned void. Now, these methods return a value.

So, for example, when SignupAction.java used the userManager in versions prior to M5, it did so like this:

userManager.saveUser(user);

Starting with version M5, the code should look like this:

user = userManager.saveUser(user);

This change is required if you used jpa-hibernate as your persistence implementation. Incidentally, if you used hibernate or iBatis as your persistence implementation, this change is not required for your code to still work the same. That being said, it is recommended that you make the modifications for the latter two options as time allows for the sake of consistency.

If you have any questions about how to use these manager or daos, a good place to look for usage examples is the tests, as all tests in M5 have been updated to reflect this subtle change.

If you're really interested in understanding the motivation behind the change, feel free to look at APF-695.

About the AppFuse Maven Plugin

This release marks the first release of the AppFuse Maven Plugin (AMP). This plugin currently does two things: 1) code generation for CRUD and 2) allows you to convert your project to use AppFuse's source instead of using its binary dependencies. If you'd like to use this plugin in your pre 2.0-M5 project, see its usage instructions.

Generating CRUD with AMP

In the 2.0 M5 release, you can run the following command to generate CRUD screens/classes for a POJO:

mvn appfuse:gen -Dentity=Name

If you don't specify the entity name, you will be prompted for it. Currently, if a @Column has "nullable = false", a "required field" validation rule will be generated as part of the web framework's validation configuration. After generating the code, you can install it using:

mvn appfuse:install -Dentity=Name

Your entity must be defined in your hibernate.cfg.xml file for this to work.
You should also make sure that the database tables for your entities have been generated by running

mvn compile hibernate3:hbm2ddl

and connecting to the database to check that a table with the correct name exists.

In a modular project, these commands must be run in the "core" and "web" modules. The plugin is smart enough to figure out when it should/should not generate stuff based on the packaging type (jar vs. war). In a future release, we hope to combine "gen" and "install" into a single command.

There's also a goal that allows you to generate model objects from database tables.

appfuse:gen-model

This goal does not install the generated files into your source tree, so you'll need to manually copy it. If you want to generate CRUD for the object, you'll also want to add it to your hibernate.cfg.xml.

We hope to combine these commands in a future release.

Installing AppFuse's source into your project

The good news is creating an "old style" project is now pretty easy. If you create a new project using 2.0-m5-SNAPSHOT, you can now use:

mvn appfuse:full-source

This goal will convert your project to use all of AppFuse's source and remove all dependencies on AppFuse. Known issues with "full-source" include:

It only supports basic archetypes. It will likely only take a couple of hours to add modular project support, so this feature will be in the next release.
It doesn't do package renaming. We plan to add this as part of the next release.

What the full-source plugin does:

Exports all sources from Subversion into your project. It reads the dao.framework and web.framework properties to determine what you need.
Removes warpath plugin from pom.xml.
Calculates dependencies by reading pom.xml files form the various AppFuse modules. It replaces your dependencies with these new ones. The order of the dependencies added is alphabetical based on groupId.
Reads properties from the root AppFuse pom.xml and adds the ones that don't exist to your project. Since these are stored in a java.util.Properties, I was unable to sort them alphabetically.

If you have issues developing AppFuse in Eclipse or NetBeans because of the WarPath plugin, running "appfuse:full-source" should fix that problem. It removes the warpath plugin as part of its installation process.

Detailed Changelog