JBoss.orgCommunity Documentation

Chapter 2. Getting started with RichFaces

2.1. Technical Requirements
2.1.1. Project libraries and dependencies
2.2. Development environments
2.3. Setting up RichFaces
2.4. Creating a project with JBoss Developer Studio
2.5. Creating a project with Maven
2.5.1. Setting up Maven
2.5.2. Using the RichFaces project archetype
2.6. Using RichFaces in existing JSF 2 projects

Follow the instructions in this chapter to configure the RichFaces framework and get started with application development.

If you have existing projects that use a previous version of RichFaces, refer to the RichFaces Migration Guide .

The minimum technical requirements needed to get started with RichFaces are outlined below.

The RichFaces library is distributed across three jars providing all the components and services of the RichFaces framework.

RichFaces Library

  • richfaces.jar
  • richfaces-a4j.jar
  • richfaces-core.jar

The framework depends on both mandatory and optional third-party dependencies. Some of the framework services are only enabled when the optional libraries are present.

Note that these dependencies may further depend on their own runtime dependencies.

Mandatory third-party dependencies

  • Java Server Faces 2.x implementation

    • javax.faces.jar (version 2.1.28 or higher)
    • or myfaces-impl.jar (version 2.1.10 or higher)
  • Google Guava

    • guava.jar (version 16.0.1)
  • CSS Parser

    • cssparser.jar (version 0.9.14)
  • Simple API for CSS

    • sac.jar (version 1.3)

Optional third-party dependencies

  • Bean validation (JSR-303) integration for client-side validation (JSR-303 API and Implementation)

    • validation-api.jar (version 1.0.0.GA)
    • hibernate-validator.jar (version 4.2.0.Final or higher)
  • Push transport library - Atmosphere (without dependencies)

    • atmosphere-runtime.jar (version 1.0.18)

      (selected compatibility modules atmosphere-compat-*.jar may be necessary)

  • Push JMS integration (JMS API and Implementation)

    • jms.jar (version 1.1)
    • hornetq-jms.jar (version 2.2.7.Final or higher)
  • Push CDI integration (CDI API and Implementation)

    • cdi-api.jar (version 1.0-SP4)
    • javax.inject.jar (version 1)
    • jsr-250-api.jar (version 1.0)
    • weld-servlet.jar (version 1.1.18.Final)
  • Extended caching (EhCache)

    • ehcache.jar (version 1.6.0)

Dependencies for servlet containers

Some of the dependencies are part of the Java EE 6 specification and thus it is not necessary to include them in projects running on Java EE applications servers. It is still necessary to include them when using servlet containers.

This does not apply to dependencies on the Servlet API: the JSP API and the EL API. These APIs are integral parts of both application servers and servlet containers.

RichFaces applications can be developed using a range of tools, including integrated development environments (IDEs). This chapter covers only two such environments in detail:

Other development environments such as Idea™ or NetBeans™ could also be used for RichFaces development, but such usage is not detailed in this book.

Follow the instructions in this section to set up a project with the RichFaces framework and begin building applications.

  1. Download the RichFaces archive

    Download RichFaces from the JBoss RichFaces Downloads area at http://www.jboss.org/richfaces/download.html. The binary files (available as a .zip archive) contain the following:

    • compiled, ready-to-use Java Archives (JAR files) of the RichFaces library
    • library source JAR files
    • documentation, including Java documentation and JavaScript documentation
    • archetypes
    • example source code
  2. Unzip the archive

    Create a new directory named RichFaces, then unzip the archive that contains the binaries into this new directory.

Follow the procedure in this section to create a new RichFaces application with JBoss Developer Studio™. Ensure you are using the latest version of JBoss Developer Studio™ to take advantage of the latest feautures and stability improvements.

You are now ready to begin developing your RichFaces application. RichFaces components can be dragged and dropped from the JBoss Developer Studio™ RichFaces palette into your application’s XHTML pages.

Apache Maven™ is a build automation and project management tool for Java projects. Follow the instructions in this section to create a Maven™ project for RichFaces™.

Maven™ can be downloaded and installed from Apache’s website at http://maven.apache.org/download.html. Due to the use of dependency importing, Maven™ version 3.0.4 or above is required.

Once Maven™ has been installed, no further configuration is required to begin building Maven projects.

A Maven archetype is a template for creating projects. Maven™ uses an archetype to generate a directory structure and files for a particular project, as well as creating pom.xml files that contain build instructions.

The RichFaces distribution includes a Maven archetype named richfaces-archetype-simpleapp for generating the basic structure and requirements of a RichFaces application project. Maven can obtain the archetype from maven central at http://search.maven.org. The archetype is also included with the RichFaces distribution in the archetypes directory. Follow the procedure in this section to generate a new Maven-based RichFaces project using the archetype.

  1. Generate the project from the archetype

    The project can be generated with the richfaces-archetype-simpleapp archetype. Create a new directory for your project, then run the following Maven command in the directory:

    mvn archetype:generate -DarchetypeGroupId=org.richfaces.archetypes -DarchetypeArtifactId=richfaces-archetype-simpleapp -DarchetypeVersion=4.5.0.Beta2 -DgroupId=org.docs.richfaces -DartifactId=new_project

    The following parameters can be used to customize your project:

    Defines the package for the Managed Beans

    Defines the name of the project

    The command generates a new RichFaces project with the following structure:

    ├── pom.xml
    ├── readme.txt
    └── src
        └── main
            ├── java
            │   └── org
            │       └── docs
            │           └── richfaces
            │               └── RichBean.java
            └── webapp
                ├── index.xhtml
                ├── templates
                │   └── template.xhtml
                └── WEB-INF
                    ├── faces-config.xml
                    └── web.xml
  2. Add test dependencies (optional)

    Your root directory of your project contains a project descriptor file: pom.xml. If you wish to include modules for test-driven JSF development, add any dependencies for the tests to the pom.xml file.

    For testing the server-side part of your application, check out JBoss Arquillian project™.

    If you want to test JSF from client’s perspective with ability to access state of JSF internals, use Arquillian Warp™.

    For automation of client-side tests in real-browser, you may want to employ Arquillian Graphene™ and Arquillian Drone™ extensions.

  3. Build the project

    Build the project from the command line by entering the mvn install command.

    The BUILD SUCCESSFUL message indicates the project has been assembled and is ready to import into an IDE (integrated development environment), such as JBoss Developer Studio™.

  4. Import the project into an IDE

    To import the project into Eclipse™ and JBoss Developer Studio™, open the importing wizard by choosing FileImport from the menu.

    1. Select the project

      Select MavenExisting Maven Projects as the import source and choose the directory with the pom.xml file for your project.

Exporting from Maven

The ability to prepare the project for Eclipse and export it using Maven is deprecated in RichFaces 4.5.0.Beta2. The process does not support JBoss integration-specific features, such as JSF Facets.

Your project is now ready to use. Once components and functionality have been added, you can run the application on a server and access it through a web browser at the address http://localhost:8080/jsf-app/ (where jsf-app is the name of your project).

RichFaces can be added to existing JSF 2 projects by adding the new RichFaces libraries. Refer to Step 2 and Step 3 in Section 2.4, “Creating a project with JBoss Developer Studio” for details.

Application-level settings

In RichFaces 4, it is not necessary to add any extra settings to the web.xml or config.xml settings files to use the framework.