In this chapter, we are going to set up and understand our project in order to get ready to develop an application using the RichFaces framework.
We'll explain how to create a project (both automatically and manually) and the Integrated Development Environments ( IDEs) that you can use to boost your productivity during the development.
We are going to talk a little about other technologies such as JBoss Seam and Facelets. You don't have to know them to understand this book, but we suggest you to learn them as they really can boost your productivity.
Obviously, we can create the project from scratch using our preferred IDE, but it is a boring and long task, as you have to set a lot of configuration files and check all the library dependencies. The most convenient method of creating a new project is to use an IDE that supports it (for example, Eclipse with the JBoss tools plugin) or use a tool such as seam-gen.
In real life, you would use RichFaces together with other technologies such as JBoss Seam, Facelets, JPA, and so on. The task of creating a complete and ready-to-run project (for different IDEs) is done very well by this tool, which is included in the JBoss Seam distribution.
Of course, we can just configure everything manually (and we'll see how later in the chapter), but for 90% of "real" projects, this is a good starting point, which means you will save a lot of time.
We strongly recommend the use of seam-gen for your first project creation. By using it, you will be able to create "in seconds" a new project, which is ready to deploy and to be opened using the Eclipse, IntelliJ Idea, and NetBeans IDEs!
Seam-gen generates an ANT build script, common configuration files, and a basic structure with Facelets templating support.
Moreover, it can automatically generate the JPA entities from a database using the Hibernate hbm2java tool and a simple CRUD (Create, Read, Update, Delete) application (using a Ruby on Rails approach), although we don't want that at this time.
Seam-gen uses RichFaces as the default component library (both seam-gen and Richfaces are JBoss projects) and automatically configures it into the project. We are going to use it to have a fast start and concentrate on the RichFaces features.
The project we are going to develop has support for EJB, JPA, JSF (of course!), Facelets, JBoss Seam, and RichFaces. All of the libraries are put into the lib directory of the generated project, and you can update them by just overwriting them (see the Update RichFaces libraries in a seam-gen generated project section).
Seam-gen is a command-line tool and is very simple to use. First, let's download and install it in the following way:
- Go to http://seamframework.org/Download and download the latest version of JBoss Seam (now Version 2.2)
- Decompress the zip (or
tar.gz)package into your local drive
That's it; as you can see, it is not a real install, because seam-gen is included in the JBoss Seam distribution package.
Creating a project with seam-gen is quite simple. Just open the terminal window, navigate inside the JBoss Seam folder where you have decompressed the package, and launch the following command if you're using Microsoft Windows:
seam setup
If you are using a Unix-like system such as GNU/Linux or Mac OS X, enter the following command:
./seam setup
Seam-gen will ask some questions, which you will have to answer. Be sure to say no when it asks if you want to use ICEFaces instead of RichFaces (no is the default answer), and yes to the question "Are you working with tables that already exist in the database?", if you want to generate the entities from an existing database.
In the next chapter, we will develop an example starting from a seam-gen project, and we will see the meaning of every question.
When the setup is complete, you can call seam-gen again to create the project with the following command, if you are using Microsoft Windows:
seam create-project
If you are using a Unix-like system, such as GNU/Linux or Mac OS X, use the following command:
./seam create-project
This command creates an empty project with all the things we need in order to start coding.
To generate the JPA entities, you can enter the following command if you are using Microsoft Windows:
seam generate-model
If you are using a Unix-like system, use the following command:
/seam generate-model
You can use other commands in order to generate a CRUD application, new actions, forms, and so on. For a complete list of commands, type the following command if you are using Microsoft Windows:
seam help
If you are using a Unix-like system, use the following command:
./seam help
For more information about seam-gen, you can also consult the official documentation for JBoss Seam at http://docs.jboss.org/seam/2.2.0.GA/reference/en-US/html/gettingstarted.html
The seam-gen generated projects can be opened using your preferred IDE (or if you use Eclipse, you can import them into your workspace), and are ready to be edited in order to implement new features.
Whenever a new version of the RichFaces framework is released, updating your project is very simple, as shown in the following steps:
- Download the latest ZIP package of RichFaces (the
binversion) from http://www.jboss.org/richfaces/download/stable.html. - Unzip the package onto your hard drive.
- Enter into the
libdirectory of the RichFaces folder you've just unzipped. - Rename the library files, by removing the version number (For example,
richfaces-api-3.3.1.GAbecomesrichfaces-api.jar). - Copy all of the three files into the
libdirectory of your project, overwriting the old ones. - Call the
deployANT target in order to deploy the new libraries into the Application Server.
Once we finish generating seam-gen, we have a complete project to start working on. Here is a screenshot of the project structure as we can see it when it is opened in Eclipse:
You will notice that there are three source folders (src/main, src/hot, and src/test) and other folders described as follows:
|
Folder |
Description |
|---|---|
|
src/main |
Contains the model classes (the JPA entities we have seen). |
|
src/hot |
It is the source folder for session beans, Seam components, and everything that your project needs in order to control the model and the view. |
|
src/test |
It contains the test classes. |
|
/classes |
It contains the compiled classes (it is used by Eclipse, you don't have to worry about it). |
|
/lib |
It contains all the libraries of the project. If you want to add a new library, just add it here and then add the library name into deployed-jars-ear.list and deployed-jars-war.list (depending on whether you want to add the library into the EAR package or the WAR package). |
|
/nbproject |
It contains the project information for the Sun NetBeans IDE. |
|
/src |
This is the folder containing the source files (that you see on the top as source folders). |
|
/view |
It is the root for published web files and contains web-related stuff such as XHTML files, images, other folders, |
Besides these folders, we can see other files in the previous screenshot, such as the AdvContactManager.ipr file (that is, the project file for the IntelliJ Idea IDE) and the build.properties file (to configure the JBoss home directory and the domain where the application will be deployed). After these, you can see the build.xml file (an ANT script that manages the deploying phase and other actions), some launch configurations, the library deployment list that we have seen, the properties file for the Hibernate console, the seam-gen file, and the ANT file for the validation task.
Actually, there isn't complete out of the box, hot deployment support. You can enable the debug mode on Seam and Facelets by adding the following line to the components.xml file found in the resources/WEB-INF/ folder:
<core:init debug="true">
During the debug mode, you can change any Facelets XHTML and pages.xml file, and immediately see the changes.
Unfortunately, you can't do the same with Enterprise Java Bean (EJB) components, but there is a medium support for POJO Seam components. In fact, you can change the content of methods in a class and immediately see the modifications without the need to restart the application. However, the only limitation is that if you change the signature of the component (for example add, remove, or change method names), you have to restart the application in order to see the modification. This is not a big development limitation, but they are working to fix it anyway.
JBoss Seam is becoming very popular, because it can really do what it promises: it simplifies the use of EJB/JPA frameworks with JSF.
It stays on top of Java EE 5, extending it and solving integration problems, and simplifying the development of enterprise applications. One of the most important things in JSF development is that Seam provides an approach to integrate EJB and JSF in a clean and consistent solution, adding many new features and reducing configuration steps.
Besides the integration of EJB and JSF, Seam also has very interesting, new features and we suggest you to consider this technology while developing a JSF application.
As a plus, a lot of ideas coming from Seam will be integrated into the new Java EE specification (the core features of Seam will be in a new standard framework called Web Beans JSR-299). Therefore, using and understanding this technology is an investment for the future too.
Facelets is a very useful open source framework that enables the use of XHTML for JSF web pages, improving performance, readability, and productivity. While using Facelets, you don't have to enclose the free text into the f:verbatim tag. Also, it offers a complete (and advanced) templating system, debugging support, better error pages (with the exact position of the error), and very useful components. JSF 2.0 specification got many ideas from Facelets.
RichFaces works out of the box with Seam and Facelets. In the case of Seam 2, you just have to define the Facelets view handler context-param (as we have seen in the Facelets support), and then use the Seam filter without configuring anything else.
The real world application that we are going to develop in the coming chapters will use JBoss Seam and Facelets technologies (but you don't have to know them to understand the code, and they can also be used with other frameworks). You can get the web.xml file for JBoss Seam, Facelets, and JBoss RichFaces support from the source code of the application.