. 56
( 87 .)


permissions and their page associations.

Deploying Using XML Con¬guration Interface
You can also deploy the portlet application using the XML con¬guration
interface. The XML con¬guration interface is a command line portal con-
¬guration utility that uses an XML input ¬le for con¬guration information
and action requests. A stand-alone utility reads the XML source ¬le and
executes against a portal server through an HTTP connection.
Along with deploying portlet applications you can use this utility to back
up and restore complete portal con¬gurations, copy parts of a con¬gura-
tion to another portal, install additional resources on a portal, and perform
recurring administrative tasks through a programmable interface.
See the current Portal Information Center for a de¬nition of the structure
of the XML ¬le, the XML schema, and examples of common function (in-
cluding deploying a portlet). If for any reason the administrative portlets
to deploy portlets or manage access control become unavailable, it is very
helpful to keep this utility in mind as it can provide critical function to re-
solve problems with portlets that you typically rely on to manage the portal

Developing the Poll Portlet with JSR 168 API
In this next section we will discuss the changes needed to your Poll portlet
implementation to use the JSR 168 API. A general discussion of the differ-
ences in the programming interface was described in Chapter 14. In the
remaining section of this chapter we will apply that understanding to the
portlet we just created using the IBM Portlet API.
Again we will start our portlet development using the Portal Toolkit in
WebSphere Studio. We will be using the Studio wizard to create a new
portlet application project to set up the correct class path de¬ned for the
JSR168 API, to create the base deployment descriptors, and to de¬ne our
project directory structure.
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

334 Chapter 17

Figure 17-8 Create New Project.

Create the Poll Project
Using Studio 5.1 with the Portal Toolkit 5.02 (or later combination) select
File ➪ New ➪ Project from the toolbar. From the New Project page that
opens (see Figure 17-8), expand Portlet Development in the left pane and
select JSR 168. In the right pane select Portlet Application Project (JSR 168)
and select Next.
In the next page enter the project name Poll JSR 168 and select Create
Basic Portlet (JSR 168). Then select Con¬gure Advanced Options and select
In the J2EE Settings page (see Figure 17-9) accept the default settings and
select Next.
In the Portlet Settings page select Change Code Generation Options to
specify the poll portlet class name and the package name that is the same
as the portlet you created using the IBM Portlet API. Then we can just copy
that code into this project and make changes to the portlet classes without
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 335

Figure 17-9 J2EE (left) and Portlet Settings (right) pages.

changing the deployment descriptor. The sample code provided speci¬es
the Package pre¬x as com.ibm.sample.portlet.poll.portlet and
the Class pre¬x as PollPortlet. Select Next.
In the Action and Preferences page (see Figure 17-10) deselect Add Form
Sample and select Next. In the Miscellaneous page select Add Edit Mode
and Add Con¬gure Mode to see an example of the portlet implementation
for processing of a standard mode (edit) and a custom mode (con¬gure).
Select Finish, completing the wizard and creating the project.

Generated Portlet Code
Next you will inspect the generated portlet code. The deployment descrip-
tors are a key part of the generated portlet project.
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

336 Chapter 17

Figure 17-10 Action and Preferences (left) and Miscellaneous (right) pages.

Deployment Descriptors
The portlet and Web deployment descriptors are generated when the wiz-
ard completes. In a previous chapter we discussed the differences in the
deployment descriptors between both APIs. Here we see the differences in
these ¬les.
Notice that with the JSR 168 API the portlet class is no longer de¬ned
in the Web descriptor <servlet-class> element. Instead it is de¬ned
in the portlet descriptor <portlet-class> element. The Web descriptor
now simply has the welcome ¬le list and a tag lib de¬nition.
Also in the portlet descriptor you see the de¬nition for con¬gure cus-
tom portlet mode. You should update this ¬le to include the portlet pref-
erences (the portlet settings from the previous API) in the <portlet-
preferences> element. The <resource-bundle> element should also
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 337

be updated to reference the correct path and ¬lename of the bundle from
the previous project that you will import.
<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-
version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<portlet-name>Poll JSR</portlet-name>
<display-name>Poll JSR portlet</display-name>
<display-name xml:lang="en">Poll JSR portlet</display-name>
<title>Poll JSR portlet</title>
<value> </value>
<value> </value>
<value> </value>
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

338 Chapter 17

Poll Portlet Class
Review the generated PollPortlet class. The ¬rst obvious difference be-
tween this class and the IBM Portlet API version is that the portlet API
objects are imported from the javax.portlet.* package. Those classes
are resolved in the portlet.jar ¬le that has been added to the build
class path by the portlet application creation wizard. The portlet creation
wizard also includes the portlet-api.jar, wpsportlets.jar, and
wps.jar in the build path. You should remove the portlet-api.jar
and wpsportlets.jar from the build path to help ensure you are not
including any IBM Portlet API references. The wps.jar ¬le includes the
org.apache.pluto.tags.* classes which are needed for the custom JSP
tags de¬ned in the std-portlet.tld tag library.
The next noticeable difference is in the PollPortlet class de¬nition:
public class PollPortlet extends GenericPortlet. The portlet class ex-
tends javax.portlet.GenericPortlet and does not implement
ActionListener. The JSR 168 API also implements two-phase process-
ing, an action phase and a render phase. But the API de¬nes two dif-
ferent URLs to reference the portlet, an ActionURL and a RenderURL
instead of an event noti¬cation and listener mechanism. If the portlet is
invoked using the ActionURL then the portlet™s processAction method
is called ¬rst. Also notice that this method is passed an ActionRequest
object and an ActionResponse object. For render phase processing the
doView, doEdit, doHelp, and doConfigure methods are passed a
RenderRequest object and a RenderResponse object. The request and
response objects are different between the processing phases.
In render phase processing notice that the do methods get invoked from
the doDispatch method instead of the service method as in the previous
API. The GenericPortlet implementation of the doDispatch method
simply determines the current portlet mode and invokes the appropriate
do method.

protected void doDispatch(RenderRequest request,
RenderResponse response)
throws PortletException, IOException {
WindowState state = request.getWindowState();
if(!state.equals(WindowState.MINIMIZED)) {
PortletMode mode = request.getPortletMode();
doView(request, response);
doEdit(request, response);
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 339

doHelp(request, response);
throw new PortletException("unknown portlet mode: " + mode);

However, the base implementation does not support a con¬gure mode.
The API allows portal vendors to support additional portlet modes as cus-
tom modes. The custom mode must be de¬ned in the portlet deployment
descriptor and then can be invoked by overriding the doDispatch method
as shown in our generated PollPortlet code.
protected void doDispatch(RenderRequest request, RenderResponse
response) throws PortletException, IOException {
if( !WindowState.MINIMIZED.equals(request.getWindowState()) ){
PortletMode mode = request.getPortletMode();
if( CUSTOM_CONFIG_MODE.equals(mode) ) {
doCustomConfigure(request, response);
super.doDispatch(request, response);

Modifying the Poll Project Source
We will work through the changes needed to convert our existing Poll Port-
let to use the JSR 168 API. To do that we will copy the existing portlet
code into this new project, preserving only the generated Web and port-


. 56
( 87 .)