Saturday, October 8, 2011

MyEclipse JSF Tutorial

Outline




 

1. Preface

This document was written using MyEclipse. However, if you notice discrepancies between this document and the version of MyEclipse you are using to perform the install that make it difficult or impossible to follow this guide, please see the User Feedback section on how to

 

2. Introduction

In this tutorial we will be walking through a small JSF demo application using MyEclipse. Previous knowledge of JSF and/or MyEclipse is not necessary, but would be helpful.

Since Struts is such a prevalent web application framework, similarities between JSF and Struts will be noted, wherever appropriate, to help the reader with previous Struts experience. However, if you have no prior experience with Struts, you may feel free to skip those sections.

3. Requirements

Below is a list of software used by this guide:
  • MyEclipse (download available here)
  • For this demo the User Name is "myeclipse" and the Password is "myeclipse" as well.

4.  New Project Setup & Structure 

To organize our development artifacts, we will need to create a new Web Module Project in MyEclipse that has JSF Capabilities added to it.  You can create a web project by selecting Web Project from the new toolbar menu:

Figure 4.1: Create a new web project

Figure 4.2: Web Project Wizard Dialog
The wizard will allow you to customize your project settings by entering your preferences into the dialog fields, as demonstrated in Figure 4.2.
NoteIt is popular when developing JSF applications to also use the JSTL libraries, so selecting add "JSTL Libraries" during project creation is recommended.  However, it is also possible to add the JSTL libraries later, via the "Add JSTL Libraries" item from the MyEclipse context menu.
Once the Web Project is created, we need to add JSF Capabilities to it. This is done by right clicking on the root of our project in the Package Explorer View, and selecting MyEclipse > Add JSF Capabilities, as shown in Figure 4.3.

Figure 4.3: Adding JSF Capabilities to a Web Project
The default values for the JSF dialog are fine for the purposes of this tutorial.  Advanced users may perform additional configuration by changing the default settings in the dialog, as shown in Figure 4.4.

Figure 4.4: Configuring JSF Capabilities
After the wizard completes, the project structure will look like what is shown in Figure 4.5.

Figure 4.5: Project Layout After Configuration
Now that the project has been created, we can start editing and creating our application.

5. Creating the Message Bundle

Let's start off our new application with the creation of the MessageBundle file. This is a simple property file that stores all our messages along with their associated keys.  Then the bundle can be used in any of our JSP pages to allow our application to be easily internationalized.  As an analogy, Struts provided similar support in this area by using the ApplicationResources.properties file,  the various <bean /> tags, and the message bundle attributes that the bean tags accepted.

In JSF, we can load a message bundle into a page with the line:
<f:loadBundle basename="com.jsfdemo.MessageBundle" var= "bundle"/>

Note: This line of code creates a page-scoped message bundle that we can reference later in the page via the 'bundle' variable name, use to lookup messages keys, and return the associated message value.

Before creating the message bundle file, create a  com.jsfdemo package in the source folder by right-clicking it and selecting New > Package.   To create the message bundle file, we'll use the New File Wizard that is accessed from the context menu of the project by right-clicking on the project's 'source' folder and selecting New > File.
The new file is opened in the MyEclipse Properties Editor.
After successfully creating the new message bundle file, we need to fill the file with key/value pairs for each label or text string that we want to display in the JSP page. Add the contents from Figure 5.2 by clicking on the Add button, provide values for Name and Value in the Add Property dialog and click Finish.
MessageBundle.properties
user_name_label=User Name:
user_password_label=Password:
login_button_label=Login

Figure 5.1: Contents of MessageBundle.properties
After adding the properties, the MessageBundle.properties file will look like the one shown in Figure:5.2


Figure 5.2: MessageBundle.properties
file
When specifying the file location, select Browse..., choose the directory /JSFLoginDemo/src/com/jsfdemo, name the file MessageBundle.properties, and select Finish.
Now that we have the MessageBundle complete, in the next section we will create the ManagedBean now that will handle our user logging in.

6. Creating the Managed Beans

In this section we'll see how to create the ManagedBean that will perform the login operation when prompted by the login JSP page as well as store the user name and password entered by the user. For the purpose of this demo, the login operation simply checks if the username and password are both "myeclipse"  and then redirects the user to the userLoginSuccess.jsp page.  Otherwise it sends them back to the login page.
First open up the faces-config.xml file with the MyEclipse JSF Editor:

Figure 6.1: Opening faces-config.xml file for editing
Open Tree page and select Managed Beans node on the tree. Press Add... to open new managed bean wizard. Figure 6.2:

Figure 6.2: Launch the managed bean wizard
You will then be presented with the new Managed Bean wizard;  Fill out the values as shown in Figures 6.3 below:

Figure 6.3: Setup the new managed bean
Press "Add..." next to managed properties list to add a new property:

Figure 6.4: Managed bean editor
Fill managed property wizard as described below to create a password property:

Figure 6.5: Managed bean property wizard
Repeat for userName property.
You will now notice that the new UserBean was added to the Outline View as shown in Figure 6.6:

Figure 6.6: UserBean now shown in the Outline View
Open UserBean.java source file will also be opened in the java editor:

Figure 6.7: UserBean Java source opened up in an editor
Notice that the getters and setters for our two properties (username and password) were already generated for us, so the only thing we need to add to this class is the implementation of the loginUser method that will be called to process the user login.
The code snippet for the loginUser method is in Figure 6.8 below.  Please copy and paste it into your file, adding any new imports as necessary:
UserBean.java
    public String loginUser() {
        if("myeclipse".equals(getUserName()) && "myeclipse".equals(getPassword()))
            return "success";
       
        FacesContext facesContext = FacesContext.getCurrentInstance();
        FacesMessage facesMessage = new FacesMessage(
            "You have entered an invalid user name and/or password");
        facesContext.addMessage("loginForm", facesMessage);
       
        return "failure";
    }
Figure 6.8: loginUser code for the new UserBean.java file

Looking at the bean code, we can notice some unique properties about it. For example, the UserBean class doesn't extend or implement any classes or interfaces tied to JSF. It is simply a javabean that includes the additional logic to perform a useful operation.  In Struts terms, it contains all the functionality of a Struts Form and a Struts Action, conveniently located in one class.

Another thing to note is that unlike Struts, these methods do not return special classes, like an ActionForward, because navigation is specified externally in a declarative fashion in the faces-config.xml deployment descriptor.  And, in Section 8 we will show how this descriptor is created and configured.

7. Creating the JSP Pages

In this section we are going to focus on creating the JSP pages for our example JSF application, which will mimic a simple website login screen.  As a result, we will only need 2 JSP pages, one to prompt the user to login and the other to indicate that login was successful.  We will call these pages loginUser.jsp and loginUserSuccess.jsp, respectively. For simplicity, if there is an authorization error during the login attempt, we will redirect the user back to the loginUser.jsp page.  To avoid confusion, we are not using any validation in this demo, but you can easily add validators to the two inputText/Secret JSF components.  We will use these fields to validate the user's entry for length and additionally display an error message if the login was incorrect.
MyEclipse also provides tools that make it simple to create the web pages for our JSF application by editing the faces-config.xml file in the MyEclipse JSF Editor. So make sure that file is still open and we can get started creating our userLogin.jsp page.
To create our userLogin.jsp page we are going to first click the JSP button, then click on our canvas.  When the new JSP wizard comes up, type in the File Name and select the JSF template as shown in Figure 7.1:

Figure 7.1: Creating userLogin.jsp using the faces-config.xml editor

We can also create our userLoginSuccess.jsp now in the same manner:

Figure 7.2: Creating userLoginSuccess.jsp using the faces-config.xml editor

Let's start working on our application now by opening up the userLogin.jsp page:

Figure 7.3: Begin editing the userLogin.jsp page
Now, what we need to do now on this page is:
  • Add an h:inputText component for the user name
  • Add an h:inputSecret component for the password
  • Add an h:outputLabel for the user name inputText
  • Add an h:outputLabel for the password
First thing we need to do is remove the default template text as well as type in our bundle basename so our page can use our MessageBundle.  We will end up with JSP that looks like Figure 7.4:

Figure 7.4: Remove template text and add our MessageBundle to the JSP page

Figure 7.4a: Create the new form
In Figure 7.4a we create the new HTML form element that will contain our login controls. Now we need to actually create the input text boxes!
Now let's create our h:inputText component for the user name, this is shown in Figures 7.6 and 7.7:

Figure 7.6: Adding new inputText component


Figure 7.7: Adding new inputText component continued
Now let's add our h:inputSecret component (no labels yet):

Figure 7.8 Adding new inputSecret component

Figure 7.9 Adding new inputSecret component continued
Now let's add the outputLabel's for both of our input components, starting with our userLabel:


Figure 7.10: Adding outputLabel component to our userName component
We will also need to add a label for our h:inputSecret component in the same manner. After we are done, as mentioned above, let's manually change our h:outputLabel components to wrap h:outputText components that are bound to our MessageBundle so we can see them in the designer, it will look something like this:

Figure 7.11: Adding outputText components to our labels
Be sure to make the modification to both the userName label and password label.
Now it is time to add our login button, we will do that almost identically to how we have added the other components so far, as shown in Figures 7.12 and 7.13:

Figure 7.12: Adding a new commandButton component

Figure 7.13: Adding a new commandButton component continued
Now we have a page that looks something like this:

Figure 7.14: Our almost-complete userLogin.jsp page
You might notice that everything looks pretty ugly on 1 line, so let's add some space to put things on separate lines:

Figure 7.15: Nicely laid out userLogin.jsp page

Now that our userLogin.jsp page is done, let's quickly do our userLoginSuccess.jsp page which is much simpler. Open that file up and edit it, simply adding a line to print out the name of the user that logged in as shown in Figure 7.16:

Figure 7.16: Making userLoginSuccess.jsp page print out the user's name
Now that we have created our two pages, the only thing left for us to do is hook them together with proper Navigation Cases, that is done by visual editing our faces-config.xml file, so open that file. After the file is open for editing, perform the following steps to create the navigation case: 
  1. Click the Navigation Case tool
  2. Click your userLogin.jsp file
  3. Then click on your userLoginSuccess.jsp file
  4. You will be prompted with a wizard to create the navigation case.
Follow Figures 7.17 and 7.18 for creating the success navigation case. In order to create the failure navigation case, we simply do the same steps as before but click twice on the userLogin.jsp file, in order to create a circular navigation case.


Figure 7.17: Creating the success navigation case

Figure 7.18: Creating the success navigation case continued
After we have created both navigation cases, our file will look something like this:

Figure 7.19: Reviewing navigation cases for our app
Now that we have created all our JSP pages and added our Navigation Cases correctly, the only thing left is to run our application!

8. Running the Application

In this section we will quickly show what our new application looks like when its running.

Select your project in the Package Explorer. Expand Run... dropdown. In the Run As menu select MyEclipse Server Application.

Figure 8.1: Run your project as server application
The output from the server log will be redirected to the Eclipse Console View.  From the log shown in Figure 8.2, it is evident that the sever started successfully.

Figure 8.2: Tomcat Startup Log
Once Tomcat is running,  we can test it by opening the MyEclipse Browser View.  This can be done by clicking the Browser button as shown in Figure 8.3.

Figure 8.3: Opening the Web Browser View
 In the browser's address bar, enter http://localhost:8080/JSFLoginDemo/userLogin.faces to activate the example application, as shown in Figure 8.7.
NOTE : The reason the URL ends in .faces and not .jsp is because above, we mapped our FacesServlet to the *.faces extension, that means in order for JSF to be given a chance to process the request and build out the component tree, we must use the .faces extension to access the actual pages. If you don't, you will get an exception along the lines of "FacesContext cannot be found".

Figure 8.4: Accessing the Example Application
Now type in myeclipse for the user name and password and click Login to see your app in action!

Figure 8.5: Logging in...

Figure 8.6: Successful Login
We see our navigation rules kick in as we are validated and directed to the userLoginSuccess.jsp page where our name is displayed. While this application is certainly simple, it does convey the basics of developing a JSF application using MyEclipse.

0 comments:

Post a Comment