RichFaces Build Re-Structure

As part of the RichFaces 5 effort, we have undergone a huge refactoring of the RichFaces project structure .

Why?

Over time we have identified requirements which the project build cannot meet because the build at the time was not ready to support them.

We have collected most of these needs as user stories. Let me just re-iterate ones which are related to a final framework user:

User Perspective

As a RichFaces user I want to

include only a single jar in my applications pom file so that I can easily make use of the RichFaces components and framework without requiring complicated changes to the build

include only a single namespace for use of RichFaces components so that I can more quickly and easily author new pages, with all components being discoverable with IDE autocompletion

use RichFaces samples/examples as a starting point for my project so that I can easily include the provided sample code in my application.

As you can read further in Where we are section, we have succeeded to cover first two points completely!

Contributor Perspective

As an open source project we rely on the simplicity of our build and code structure to encourage new contributions. If it is hard for the core developer team to navigate the project structure, how must it be hard for others?

I won’t dive into specific user stories here, but let’s just say that the build is way, way simpler then it was.

We believe that this re-structure will lower the development barrier of the great new features we have planned for RichFaces 5. With the new build structure we can code as quickly as possible while maintaining even better stability.

And it should also encourage you, our community, to dive into the framework code!

Where we are?

The upcoming 5.0.0.Alpha1 is intended to be functionally equivalent with last release of RichFaces 4 available today (4.3.2).

Aside from the namespace change and package refactorings, we strove to make sure that everything works the same, with extensive QA efforts in this regard for this release.

Dependencies

Most visible changes were introduced into system dependencies:

Maven users should include just one dependency (org.richfaces:richfaces),
Ant users should include just one JAR (richfaces.jar).

This is a huge simplification over what you need to go through in the RichFaces 4 setup.

Namespaces

Additionally, two RichFaces tag libraries (a4j/rich) were merged to one, so there is only one namespace (http://richfaces.org/rich) with a new default prefix (r):

<!DOCTYPE html>
<html lang="en"
    xmlns="http://www.w3.org/1999/xhtml"
    ...
    xmlns:r="http://richfaces.org/rich">

</html>

This is simple to change in your own projects with some simple "sed" commands (or whatever regexp tool you prefer) over your entire code base:

sed -ri 's#xmlns:a4j="http://richfaces.org/a4j"##g'
sed -ri 's#xmlns:rich="http://richfaces.org/rich"#xmlns:r="http://richfaces.org/rich#g'
sed -ri 's#<(/?)(a4j|rich):#<\1r:#g'

Remember to commit all any previous changes before performing those changes: I can’t provide any guaranties! :-)

Refactored Java Packages

The last concern is that we made sure the whole project is structured properly on the level of Java packages.

Your code will be affected mainly when you use component bindings (binding=#{…}) or programatic component instantiation (Application#createComponent(…)).

Additionally, there are also changes to packages in which the RichFaces servlets reside, so check your web.xml configuration:

org.richfaces.servlet.PushServlet
org.richfaces.servlet.ResourceServlet

Note that moving Java classes across packages was done in a 1:1 fashion, so once you switch from RichFaces 4 to RichFaces 5, you just need to review & fix compilation failures and you are all set (statically typed languages FTW!).

Restructured Resources

As we merged all the components to single module, we found out the resource structure to be quite unwiedly. We did resource cleanup, so any resource keys you might use will be changed. You can go to the META-INF/resources to see where to find the re-located resources.

Sample/Example Simplification?

Still Work in Progress

We didn’t yet touch samples and a Showcase application much - it’s for specific reason - we want you to see Alpha1 as a first milestone for a migration to RichFaces 5 and this major release should not really be migration nightmare.

In fact, I imagine the migration path through the use of RichFaces 5 Alpha1 as a base where just small changes are needed, followed by upgrade to Beta/CR/Final releases which will already have all the new shiny goodness inside.

By the time we release RichFaces 5.0.0.Final, the examples will be more easy to run with and they will be used to show and document advanced use-cases of our components, as you can already see in our prototype of the Bootstrap Showcase which was incredible effort of our awesome community (yeah, I’m pointing to you, Paul Dijou).

Give it a try!

That’s it. For medium sized projects, this could be almost effortless migration (not that I’m encouraging your production system to use alpha release :-) ).

However if you start a RichFaces project today on a green field, you can use Alpha1 as a base for your development. As we will proceed further with upcoming milestones, you will be able to upgrade in order to evaluate our shiny new components!