Developing JSF Portlets with Rational Application Developer 6.0 and WebSphere Portal Server 5.1: Part 1, Developing JSR168 JSF Portlets

This article is Part 1 in a two-part article series regarding portal development using IBM® Rational® Application Developer 6.0 (IRAD). As part of understanding this functionality, you will also learn about the basic JavaServerFaces (JSF) and IBM® WebSphere® Portal Server features included with IRAD. Finally, this article will discuss how you can rapidly create sophisticated Web pages using JSF, and then display those pages in Java Specification Request (JSR) 168 portlets.

Mikhail Genkin (genkin@ca.ibm.com), Scenario Designer, IBM

Mikhail GenkinMikhail Genkin is a Scenario Designer working with the IBM SWG System House group at the IBM Toronto Software Development lab. His work involves conducting expert reviews of IBM and competitor tools for Java and Web service-based enterprise access. He advises several IBM development teams building WebSphere tools for J2EE, Web services, RDBMS, and EIS access about the usability, performance, and interoperability aspects of their products. He has contributed to several releases of VisualAge® for Java, Enterprise Edition; WebSphere Application Developer; and WebSphere Application Developer Integration Edition. Mikhail holds a bachelor's degree in Geophysics from Carleton University, Ottawa, Canada, and an M.Sc. in Earth Sciences from University of Ottawa. He is a Sun Certified Java Programmer, and an IBM Certified Developer Associate - IBM VisualAge for Java.



15 March 2005

Introduction

JavaServerFaces (JSF) is a relatively new specification defined under the Java Community Process(SM). The JSF 1.0 specification describes a framework for rapid development of client-server user interfaces. In addition, portals and portlets have become a popular choice for implementing sophisticated and customizable Web interfaces. Addressing this process, JSR 168 is an industry specification that describes a standard way to implement portlets.

This article will describe how you can construct a portal-based application for customer relationship management. It will demonstrate how to use features provided with IRAD to:

  • Construct JSR 168 portlets
  • Develop portlet views with JSF
  • Enable cooperative portlet behavior
  • Pass user-defined JavaBeans between portlets
  • Switch portlet view in response to a message from another portlet

This article series is organized into two parts. This article gives an overview of IRAD tools and describes the scenario that you will use for the series. Then it focuses on basic portlet and JSF development. In Part 2, you will look at implementing sophisticated user interface flows by enabling cooperative portlet behavior. Both articles are written using a tutorial-like format, and you are encouraged to follow along with the instructions, or browse the provided sample code. You can download the sample code from the Download section later in this article.


Tools for JSF and portlet development

IRAD provides tool support to facilitate portal and JSF development.

IRAD's portal and portlet development tools include:

  • The New Portal Project wizard: Once you create a new portal project, you can use additional tools -- such as the New Theme wizard and the Portal Designer -- to create new skins and themes, and to edit the layout of your portal, respectively. Rational Application Developer 6.0 supports portal development for WebSphere Portal Server 5.0 only.
  • The New Portlet wizard: This wizard helps you develop and unit-test portlets written to the IBM standard portlet API.
  • The New Portlet (JSR 168) wizard: This wizard helps you develop and unit-test portlets written to the JSR 168 standard API. Once you create a new portlet project, you can use additional tools -- such as the portlet deployment descriptor editor -- to develop and unit-test your portlets.
  • Support for portal unit test and remote server environments: This functionality allows you greater flexibility for testing and debugging. IRAD supports WebSphere Portal Server 5.0 and 5.1 unit test environments, as well as remote server attach for testing and debugging.

Tooling support for JSF development includes:

  • The Faces Portlet option of the New Portlet (JSR 168) wizard
  • The New Faces JSP wizard for JavaServer Pages (JSP)
  • Page designer with associated supporting views (Palette, Page Data, and Properties)

By combining portal and JSF technologies, you can rapidly construct sophisticated user interfaces for the Web. In this article, you will focus on developing JSR 168 portlets with JSF views. Later you will take a look at how you can use tools provided with IRAD to construct a simple customer relationship management (CRM) browser application, which we'll call CRMBrowser.


A simple CRM application

The example used in both parts of this article series is based on a scenario where a call center agent needs to look up information for a particular customer. This example application consists of two portlets (see Figure 1) - the Summary portlet and the Detail portlet. The agent begins by browsing customer information in the Summary portlet, and then clicks on links in that portlet to display additional information in the Detail portlet.

Both portlets are JSR 168 compliant. Portlet views are implemented using JSF. The summary portlet communicates with the detail portlet via the property booker.

Figure 1. The CRMBrowser application interface
The CRMBrowser application interface

In order to develop this application, you will need to complete two stages:

  1. Develop the two portlets that show summary and detail information next to each other, and then create the JSP views for these portlets to display the actual data.
  2. Get the two portlets to pass information to one another, so that actions performed in the Summary Portlet will result in changes to views being shown in the Detail Portlet.

This part of the article series will focus on completing the first stage. You will learn how to enable and leverage IRAD's portal and JSF tools to construct portlets and portlet views.

Part 2 of this article series will focus on the more advanced aspects of cooperative portlet behavior. You will learn how to pass complex data types between portlets, and how to switch views in the target portlet in response to changes in the source.


Developing the CRMBrowser

In order to develop your CRMBrowser application, you need to complete the following high-level steps:

  1. Enable the correct capabilities in your IRAD workbench.
  2. Develop the portlets.
  3. Develop portlet views.
  4. Enable portlet cooperation to pass data between them (you will do this in Part 2).

Let's take a detailed look at each of these steps.

Preparing the workbench

In order to use IRAD's portal tools, you need to make sure that the Portal Tools advanced feature is selected during product installation. Once they are installed, you need to enable the portal capabilities of the workbench. To do this:

  • Click Window > Preferences > Workbench-Capabilities (see Figure 2)
  • Expand the Web Developer (advanced) node
  • Select the Portal Development check box

Developing cooperative JSR 168-compliant portlets involves designing and editing XML schema (XSD) and WSDL files. Rational Application Developer provides excellent graphical tools that make working with WSDL and XSD files easier.

Figure 2. Enabling workbench capabilities via the Preferences dialog
Enabling workbench capabilities via the Preferences dialog

To enable the WSDL and XSD tools:

  • Click Window > Preferences > Workbench-Capabilities
  • Expand the Web Services Developer and XML Developer nodes
  • Select the Web Services Development and XML Development nodes

Next time you open a WSDL or XSD file it will be displayed in the corresponding editor, which allows you to view the contents graphically.

Now that the right workbench capabilities have been enabled, you need to connect to the WebSphere Portal Server 5.1 Unit Test Environment. If you have not installed the Unit Test Environment on your machine already, you will need to get the WebSphere Portal Server 5.1 for multiplatforms installation CD (or download it) and run the install -- see the Resources section later in this article. Make sure you select Test Environment during the installation. (If you have any problems during the installation, please refer to the WebSphere documentation -- see the Resources section later in this article.)

Now that the portal server unit test environment has been installed, we need to make sure that the workbench is aware of it:

  1. Click Window > Preferences from the workbench menu.
  2. In the Preferences dialog, expand the Server node and select the Installed Runtimes branch (see Figure 3).
  3. Click the Add button to bring up the New Server Runtime wizard.
Figure 3. Adding another runtime via the Preferences dialog box
Adding another runtime via the Preferences dialog box
  1. Select WebSphere Portal v5.1 from the list box (as shown in Figure 4).
Figure 4. Adding a new runtime with the New Server Runtime wizard
Adding a new runtime with the New Server Runtime wizard
  1. Click Next.
  2. Enter the location of the portal server and the base application server (see Figure 5). Note: these locations will likely vary from machine to machine.
  3. Click Finish.
Figure 5. Entering the portal and base application server locations
Entering the portal and base application server locations

Now that you've enabled your workbench to use WebSphere Portal 5.1 Unit Test Environment, you are ready to begin developing the application.

Developing the portlets

Our CRMBrowser application consists of two cooperating portlets -- the Summary portlet, and the Detail portlet. This section will discuss the steps required to construct these portlets using IRAD tools.

Creating a project for your portlets

  1. With the IRAD workbench started, switch to the Web perspective by clicking Window > Open Perspective > Web.
  2. Click Dynamic Web Projects in the Project Explorer view and right-click to bring up the context menu.
  3. Click New > Portlet Project (JSR 168). This launches the New Portlet Project (JSR 168) wizard shown in Figure 6.
  4. Enter CRMBrowser as the Name.
  5. Clear the Create a portlet checkbox. You will create your portlets separately in order to have better control over portlet naming conventions.
  6. Click the Show Advanced button.
  7. Select WebSphere Portal v5.1 Unit Test Environment in the Target Server list.
  8. Accept defaults for the other fields.
  9. Click Finish.
Figure 6. The New Portlet Project (JSR 168) wizard
The New Portlet Project (JSR 168) wizard

You have now created a project named CRMBrowser in the workbench. The corresponding EAR project CRMBrowserEAR has also been created.

Creating your portlets

  1. Select the CRMBrowser project in the Project Navigator view.
  2. Right-click to bring up the context menu, and click New > Portlet. This launches the New Portlet wizard shown in Figure 7.
  3. On the first page of the wizard, select the Faces portlet (JSR 168) radio button.
  4. Click Next.
Figure 7. Selecting the portlet type in the New Portlet wizard
Selecting the portlet type in the New Portlet wizard
  1. On the Portlet Settings page, change the portlet settings for Portlet Name, Description, and Code Generation Options to match those shown in Figure 8.
Figure 8. Portlet settings for the Summary portlet
Portlet settings for the Summary portlet

Repeat the same steps to create the Detail portlet, with the following differences:

  • Use DetailPortlet as the portlet name on page 2 of the New Portlet wizard.
  • Change the name of the view to /CustomerDetailView.jsp on page 3 of the wizard.

Now take a look at the structure of your project. The portlet project, as shown in the Project Explorer view, contains an icon representing the portlet deployment descriptor. If you expand this tree node, you will see two additional icons representing the portlets (see Figure 9).

Figure 9. Structure of the JSR 168 Portlet project
Structure of the JSR 168 Portlet project

The Web Content folder contains two JSP files -- one view for each of your portlets. Double-click on one of the views to open it in the Page Designer. The generated view JSPs are essentially blank canvases. You will now use JSF to turn them into a sophisticated browser.

Developing The Portlet Views

Our two portlets will be able to show a total of three views:

  • The Summary portlet will always show the CustomerSummaryView.jsp. This JSP page will display a summary of customer information as follows.
    • The unique customer identification number
    • The customer's first name
    • The customer's last name
    • A table listing issues that this customer has been discussing with call center personnel

    Call center staff will be able to click on action links highlighting customer id number, or issue id number. In response, the Detail portlet will display an appropriate view showing expanded information about the selection.

  • The Detail portlet can show two views.
    • The CustomerDetailView.jsp shows detailed information about the customer (such as phone numbers and address), in addition to the information shown in the Summary portlet.
    • The IssueDetailView.jsp shows expanded information about a particular issue (such as extended description, status, and product id).

    The Detail Portlet will display one of these views based on what the user selects in the Summary portlet view.

You are now ready to develop the portlet views. Since the JSF framework is designed following the Model-View-Controller pattern, we should first consider the data which each view will display (the Model). At this stage you could either develop your own simple beans to act as the model for your views, or import code available with this article.

The JavaResources > JavaSource folder contains the package com.ibm.sample.crmbrowser.beans. Inside this package you will find all of the beans used by CRMBrowser views.

First, you?ll build the CustomerSummaryView.jsp. The com.ibm.sample.crmbrowser.beans.Customer bean will be the model for this view. This bean defines a number of properties:

  • firstName, lastName, and customerId will provide string values that will populate customer summary controls shown on the page.
  • detailInfo (type CustomerDetailInfo) contains additional contact information that this view will not show, but will pass as a property to the Detail portlet.
  • issues (type java.util.ArrayList) contains a list of Issue objects, each of which describes a separate interaction that the customer had with the call center in the past. This will be displayed as a table with each issue id acting as an action link.

Building the Summary JSP

Following are the steps to build the CustomerSummaryView JSP:

  1. Double-click CustomerSummaryView.jsp in the Project Explorer view to open it in Page Designer. You will find the Page Date view on the bottom left of the main workbench window.
  2. Right-click and click New > Java Bean (see Figure 10). This will launch the Add JavaBean wizard shown in Figure 11.
Figure 10. Adding a new JavaBean to the Page Data view
Adding a new JavaBean to the Page Data view
  1. Enter customerSummary as the Name of the bean, and com.ibm.sample.crmbrowser.bean.Customer (or the fully qualified name of the type you chose to create) as the Class
  2. Click Finish. You?ve now added an instance of this JavaBean to the page data.
Figure 11. The Add JavaBean wizard
The Add JavaBean wizard
  1. Expand the customerSummary bean in the Page Data view and change the contained type for the issues property (see Figure 12). Do this by right-clicking the contained type icon, clicking Change Contained Type, and entering com.ibm.sample.crmbrowser.beans.Issue as the type in the dialog box.
Figure 12. Changing the contained type for the issues property
Changing the contained type for the issues property

Generating the user interface controls

In these next steps, you'll generate the required user interface controls using this bean definition.

  1. Drag the customerSummary bean from the Page Data view to the canvas of the Page Designer. This action launches the Insert JavaBean wizard (see Figure 13).
Figure 13. The Insert JavaBean wizard
The Insert JavaBean wizard

This wizard lists the properties of the customerSummary bean (and other beans which that bean contains), and page controls which will be used to display the information to the end-user.

  1. Clear the checkbox next to customerDetailInfo (see Figure 13). We will not display this bean in the page UI.
  2. Click the right-most button in the issues row of the Fields to display table to launch the Insert JavaBean -- Configure Data Controls wizard for that bean (see Figure 14).
  3. Clear all the fields except issueId and shortDesc. We will display only these values for a given issue on the CustomerSummaryView.jsp.
  4. Click Finish twice to complete both wizards.
Figure 14. Configuring which fields will display in the Summary portlet issues list
Configuring which fields will display in the Summary portlet issues list

The IRAD JSF tooling will now generate the form shown in Figure 15.

Figure 15. The form IRAD's JSF tooling generates
The form IRAD's JSF tooling generates

You can use the rich editing functionality provided by the Page Designer, the Properties view, and the Palette view to refine the layout and appearance of the page. This article will not go into details about how to do this, but there is more information in the Resources section.

To complete your page, we need to add some action controls to drive our interaction with the Detail Portlet. To do this:

  1. Expand the Palette view Faces Components.
  2. Click Command Hyperlink.
  3. Drop the hyperlink onto the customerId output field.
  4. Repeat this process to drop the hyperlink onto the issueId output field.

Figure 16 shows the resulting form UI.

Figure 16. Finalized UI for CustomerSummaryView.jsp
Finalized UI for CustomerSummaryView.jsp

Developing the Customer Detail and Issue Detail views

To develop the other two views you need to repeat the same steps as for CustomerSummaryView.jsp. To develop CustomerDetailView.jsp:

  1. Open it in Page Designer.
  2. Add the com.ibm.sample.crmbrowser.beans.CustomerDetailInfo bean to the Page Data view just as you did for the Summary view.
  3. Drag this bean to the canvas of the Page Designer to generate the UI.
  4. Allow the tool to generate controls for all the fields of this bean.

To develop IssueDetailView.jsp, complete these steps:

  1. Select the WebContent folder of the CRMBrowser project in the Project Explorer.
  2. Right-click and click New > Faces JSP File from the context menu.
  3. Enter IssueDetailView.jsp as the file name in the wizard that follows.
  4. Click Finish. The Page Designer should open, displaying the newly created page.
  5. Add the com.ibm.sample.crmbrowser.beans.Issue bean to the Page Data view as described previously.
  6. Drag this bean to the canvas of the Page Designer.
  7. Allow the tools to generate controls for all of the bean fields.

Specifying the initial view for the Detail portlet

You have now created all three of your views. You've mapped controls that display data to the end-user to properties of JavaBean instances, and they will display data once executed. The only steps that remain are to edit the portlet deployment descriptor, and to set the initial view for the Detail Portlet. To do this:

  1. Select the portlet deployment descriptor icon in the Project explorer
  2. Double-click to open it in the Portlet Deployment Descriptor editor.
  3. Click on the DetailPortlet link in the editor's Overview tab.
  4. Scroll down the right column of the Portlets page to show the Initialization list.
  5. Edit the com.ibm.faces.portlet.page.view parameter and set it to show CustomerDetailView.jsp (see Figure 17).
  6. Save and exit the editor.
Figure 17. Specifying the initial view in the portlet deployment descriptor editor
Specifying the initial view in the portlet deployment descriptor editor

Conclusion

You can construct sophisticated Web interfaces by combining JSF and portal technologies. IRAD provides tooling support to help you build, unit-test, and deploy your application very quickly.

Part 2 will discuss how you can enable cooperative portlet behavior so that you can fully implement Summary to Detail browsing interactions.


Download

DescriptionNameSize
Code supporting articlecrmbrowser.zip2.6 MB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=56558
ArticleTitle=Developing JSF Portlets with Rational Application Developer 6.0 and WebSphere Portal Server 5.1: Part 1, Developing JSR168 JSF Portlets
publish-date=03152005