Click here to download code

Do you remember learning how to swim? I remember heading straight for the bottom of the pool, desperate for air and thinking that I would never be able to get my head back above the water. However, with some persistence and motivation, as well as my parents' swim-or-sink training methodology, I started to make some progress. A couple of years later, I swam across a narrow stretch of Akhtuba, a southern Russian river that ranges in width from 520 to 3,500 yards.

I find the experience of learning how to develop Web applications to be quite similar. Your first exposure to Web application development might be overwhelming, and the task of writing a Web application seems unachievable — after a few tries, though, you finally create your first "hello world" application. New concepts start to make sense, and you are eventually able to apply the basic set of Web development skills to write different types of Web applications — static, dynamic, service-oriented, and portals. Writing a Web application is no longer a challenge; it's simply a workout.

From the end-user perspective, the most sophisticated type of Web application is the portal. Features unique to portals that run in WebSphere Portal include the ability to display multiple applications (portlets) on one Web page, customization of portal look and feel, interportlet communication, single sign-on capability, integration with collaboration components, role-based security, and others. I have good news for both new and experienced Web developers. If you are an experienced Web programmer, you already know more about portlet development than you think. If you are new to Web development, you'll find that portlet development has a shorter learning curve than J2EE Web application development.

More sophisticated functionality usually results in higher development cost, but is this the case with portlet development? Decide for yourself by implementing a simple portlet that reads and writes data to an iSeries database. This article guides you through building an FAQ portlet that lets you search for questions and save search preferences. I use WebSphere Development Studio Client for iSeries (WDSc) V6 to build the portlet.

Getting Started

First, we need to lay out the architecture of the FAQ portlet application. One key best practice is to use the Model-View-Controller (MVC) design pattern to build applications. The main idea of the MVC pattern is to separate business (model) and presentation (view) logic to create applications that contain reusable components and are easier to maintain. Figure 1 shows a sample portlet application architecture based on the MVC pattern. JSPs capture user input and invoke the portlet. The portlet processes requests that come in from the JSP and calls business logic implemented in the JavaBean.

In developing any type of application, having the right tools is critical to success. IBM WebSphere Studio and Rational tools provide excellent tools for portlet development: Portal Toolkit (a wizard for building portlets) and Portal Test Environment. Portal Toolkit gives you the option to create either JSR168 or IBM Portlet API portlets. JSR168 is the industry standard, and IBM recommends it for new portlet development. (The FAQ portlet application in this article is implemented using JSR168 APIs.) You can find out more about the differences between the two APIs at ibm.com/developerworks/websphere/library/techarticles/0312_hepper/hepper.html.

Release 1 of JSR168 is a relatively small API — it contains fewer than 30 Java classes. JSR168 classes provide functions for request processing, session management, default portlet implementation, portlet configuration, and user preferences handling. It's always a good idea to have Javadoc for quick reference; download it at the Java Community Process Web site at jcp.org/en/jsr/detail?id=168.

I usually begin portlet development by generating a portlet application with the Portlet Toolkit wizard in WDSC. The wizard creates a fully functional portlet (no changes required to test it in WebSphere Portal) that you can modify to implement business logic specific to your application. To invoke the wizard, select File|New|Portlet Project in WDSC. You will be presented with the following choices when stepping through the portlet project creation wizard:

• Portlet Type: The basic portlet is the best choice because it will generate some sample code; the empty portlet option is often used for migrating portlets to JSR168; the JSF portlet option sets up an environment for developing portlets that use Java Server Faces (JSF) components.
• Portlet Settings: All information on this screen will be saved in the generated portlet descriptor file, which can be modified; you may want to change the display name to make it more readable.
• Action and Preferences: On this page, you specify code generation options (portlet action handling is selected by default); if you want to implement user preferences handling, select Add preferences handling to generate sample code.
• Miscellaneous: On this page, you can set code generation options for different types of markups (e.g., chtml, wml) and portlet modes. Portlet modes are views that usually implement different functions, such as displaying information ("View" mode), setting end-user preferences ("Edit" mode), setting portlet configuration properties ("Configure" mode), displaying help information ("Help") mode, and others.

When creating the FAQ portlet project, I selected the following options in the portlet project creation wizard:

• New Portlet Project (JSR168): Name ­ FAQ
• Portlet Type: Basic Portlet (JSR168)
• Features: default values
• Portlet settings: default values
• Action and Preferences: default values
• Miscellaneous: checked Additional modes Edit, Help, and Configure

The wizard generates a set of Java classes, JSPs, and descriptor files; Figure 2 shows generated code artifacts. Understanding generated code is a prerequisite for completing portlet implementation, so let's look at what each artifact represents:

• FAQPortlet.java: a portlet class that processes requests that come in from portal (JSP fragments that are displayed on a portal page)
• FAQPortletSessionBean.java: a helper class that transfers values between JSPs and the portlet
• FAQPortletConfigure.jsp, FAQPortletEdit.jsp, FAQPortletHelp.jsp, and FAQPortletView.jsp: JSPs that represent different portlet modes
• Portlet and Web deployment descriptors: deployment descriptor files that are used by a portal server; in most cases you don't need to (and shouldn't) modify the generated deployment descriptor files, but it's still a good idea to review the files to understand what information is stored in them

Figure 3 shows the FAQ portlet's architecture. Business logic is implemented in FAQServer.java JavaBean (Figure 4). This class uses JDBC APIs to create a connection to the iSeries, retrieve all FAQ records, search for questions, and add new questions. Search results are returned in a collection of QnA.java objects. FAQServer.java does not use JSR168 API.

Implementing the Portlet

Before we proceed with portlet and JSP implementation, let's review how a portal server handles portlet requests. All requests from a portal page will invoke two methods in a portlet: the process Action() method and the rendering method that corresponds to the portlet mode (e.g., doView(), doEdit()). This request-processing model is called two-phase processing.

Two-phase processing is required in a portal because of the nature of portal applications — when a portal page is displayed, multiple portlets must be aggregated into a single HTML source code that can be displayed in a browser. If we have four portlets on a portal page, and a user invokes an action on one of the portlets, WebSphere Portal will call processAction() on the portlet that the user invoked, and then call doView() on all four portlets on the same portal page. Portal programming best practice is to encapsulate business logic calls in the processAction() method of the portlet. This technique lets you avoid invoking business logic every time a page is refreshed by an action from another portlet. I'll discuss processAction() implementation in a moment.

In the next step of FAQ portlet implementation, I modified the generated JSPs to capture input for methods of the FAQServer.java class and display results. I kept the generated references to the portlet tag library and FAQPortlet.java. I also added HTML to display the input fields and results, added Java code to display results returned by methods of the FAQServer.java, and modified FAQPortletSessionBean.java to pass information to and from the portlet. Figure 5 shows the completed JSPs.

The last step in the portlet implementation is to tie the JSP requests to business logic implemented in FAQServer.java. The JSPs generated by the portal wizard will invoke the FAQPorlet.java processAction() method because of this line of code

<FORM ACTION="<portlet:actionURL/>
  " METHOD="POST">

The <portlet:actionURL> tag is from the portlet tag library that invokes the portlet. Notice that portlet URL is not hardcoded in the JSP — it is a generated value that should only be used internally by the portal server. All JSPs in the FAQ portlet application point to the same portlet.

Figure 6 shows the FAQPortlet.java processAction() method. First, the code checks what action invoked the processAction() method. FAQPortlet has four JSPs. Each JSP has one or more submit buttons; after we determine which action to process, we invoke a method on the FAQServer.java, which contains business logic.

Let's review what happens when a user clicks the search button of the FAQ portlet:

• The portlet request comes in to the processAction() method of the FAQPortlet.
• The processAction() determines which business function has to be called.
• FAQServer.java searches for questions and answers that contain the search string.
• FAQPortlet stores results returned by the search in the helper. FAQPortlet SessionBean.java class; this completes the action processing part of handling a portlet request.
• The portal server starts the rendering phase of request processing; the doView() method FAQPortlet.java is called; when FAQPortletView.jsp is processed, it reads search results from the FAQPortletSessionBean.java class.

We used the majority of JSR168 Java classes in the default portlet implementation, request processing, and session management. User preference-handling APIs are used in the FAQPortletEdit.jsp processing. PortletPreferences.java is a JSR168 class used to store and retrieve user preferences. Saving user preferences is implemented in the processPreferences() method that I added to the generated implementation of FAQPortlet.java. You will also find user preferences in the Show All (questions) button processing — the code looks up user preferences and returns all questions that match user preferences. One of the nice features of the portlet API is that we don't have to look up the user ID to retrieve or store user preferences; the portal server does this automatically.

To finish the FAQ portlet application, I implemented the functionality to add new question and answer combinations in the Configure mode of the portlet and provided information on how to use the portlet in the Help mode. The only method that I changed in the generated FAQPortlet.java code is processAction().

Ready to Write Portlet Apps

To summarize, I completed the following steps to implement the FAQ portlet:

1. Created a JSR168 portlet project with WDSC portlet wizard
2. Implemented business logic to retrieve data from DB2 on iSeries
3. Modified JSPs to capture user input and display results
4. Added code to the portlet to process JSP requests

If you have average Web programming skills, you should be able to develop this application in two to three hours. The reason you can build this type of application so quickly is the built-in functionality of WebSphere Portal, simplified portlet API, and portlet development tools. To install the FAQ portlet, see "FAQ Portlet Setup Instructions," below.

I hope that by now you are eager to start building your first portlet. You don't have to be an ubergeek to write portal applications — just like you don't need to be Michael Phelps (six-time Olympic gold medalist) to enjoy swimming.

Elena Lowery is a technical consultant in the IBM eServer Solutions Enablement organization in Rochester, Minnesota. Elena works with ISVs helping them design and implement iSeries applications that use J2EE technologies. You can e-mail Elena at elowery@us.ibm.com.

---

PRODUCT INFORMATION

IBM WebSphere Portal Part of IBM's suite of integration and application infrastructure hardware, WebSphere Portal enables personalized interaction among applications, content, processes, and people. It integrates business processes and portal users via orchestrated workflow. Platform i5/OS, AIX,, HP-UX, Linux, Windows Price Contact your local IBM marketing representative Vendor IBM Corporation

---

FAQ Portlet Setup Instructions

Desktop software requirements Install one of the following products: WebSphere Development Studio Client for iSeries V6 Rational Web Developer V6 Rational Application Developer V6 Rational Software Architect V6 You need Portal Tools installed in one of the products mentioned in the previous requirement; Portal Test Environment doesn't have to be installed to review portlet code, but it's needed to test the portlet. Server requirements iSeries server V5R3 or V5R2 Installation Instructions Unzip FAQPorltet.zip to C:\. Restore FAQDB.savf located in C:\FAQPortlet on the iSeries system: FTP the FAQDB.savf to the iSeries system. Prior to FTP, create a new FAQDB save file on the iSeries system. Run command: RSTLIB SAVLIB(FAQDB) DEV(*SAVF) SAVF(QGPL/FAQDB) Import FAQPortlet.war located in C:\FAQPortlet into WDSC or Rational Tools: Select File|Import, and import FAQPortlet.war. Make sure to select WebSphere Portal 5.0 as the target server. Configure the FAQDB data source: Create the Portal Test Environment server. Double-click the newly created server and switch to the Security tab. Create a JAAS Authentication Entry; use a user ID that exists on your iSeries system. Switch to the Data source tab. Create a new JDBC driver: Toolbox Driver. Create a data source with the following properties: JNDI name: jdbc/faqds Authentication aliases: a user ID that you created in JAAS Authentication entry Server Name: your iSeries server name Libraries: faqdb To test the portlet, right-click the Portlet project and select Run on Server. — E.L.