<<

. 46
( 87 .)



>>



270 Chapter 14


The CredentialVaultService has two associated components. The
credential service assists the portlet to handle basic authentication, LTPA
Token authentication, and simple form-based userid/password login chal-
lenges from back-end systems being accessed on a user™s behalf. The cre-
dential vault service is used to retrieve credentials from a secure, persisted
store, a Credential Vault. This service can also pass Tivoli Access Manager
or Netegrity SiteMinder single sign-on tokens to the back-end application
in the appropriate HTTP headers.
Portlet services are not available with the initial implementation of the
JSR 168 API.

Portlet Menus
The portlet menu service allows the portlet to add to the portal navigation
menu, providing users easier navigation through the portal. This service is
not available with the initial implementation of the JSR 168 API.

Portlet URI Addressability
References to a speci¬c portlet, portal page, or portal resource must be
encoded in the portal Web application URI. The IBM Portlet API creates
a PortletURI object for this encoding, while the JSR 168 API creates a
PortletURL object. In both cases you can set the portlet state or add pa-
rameters using these objects.
To encode the URI to reference portlet deployed resources, both APIs use
the encodeURL() method on the PortletResponse object.

IBM Portlet API Addressability
The IBM Portlet API uses the createURI() or createReturnURI()
method on the PortletResponse object to create a PortletURI object
referencing the portlet. The createURI() method creates a PortletURI
object pointing to the calling portlet with the current mode. The create
ReturnURI() method creates a PortletURI object pointing to the call-
ing portlet with the previous mode. The PortletURI toSring() method
will return a URI string that can be used in the markup for a link (such as
an action tag or href tag).
In order to associate a portlet action event with that URI, the Portlet
URI can be modi¬ed to add an action event trigger. This is done by using the
addAction(String actionName) method on the PortletURI object.
For example, you may want to have two buttons on a form input page
on your portlet. One button is to “save” the form data and one to “cancel”
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49




Portlet Programming Model and API 271


to return back from the input page without saving. The following code
segment shows the creation of the two URI strings.

// Create the URI with an action to save the form data
// Add the URI string to the request for use by the JSP
PortletURI saveURI = portletResponse.createURI();
saveURI.addAction("save");
portletRequest.setAttribute("saveURI", saveURI.toString());

// Create the URI to return to the previous (view) mode
// without saving. Add URI string for use by the JSP
PortletURI cancelURI = portletResponse.createReturnURI();
portletRequest.setAttribute("cancelURI", cancelURI.toString());


If the portlet class has implemented the ActionListener interface
then that class™s actionPerformed(ActionEvent event) method is
invoked when the HTTP request associated with that URI is processed
by the portal. The ActionEvent object that is passed when the action
Performed method is invoked will contain the name of the action event,
as is shown in the following code sample.

public void actionPerformed(ActionEvent event)
throws PortletException {

PortletRequest request = event.getRequest();
String actionName = event.getActionString();

if ("save".equals(actioName)) {
// Retrieve the form data from the request
// object and save it.
}
}


This is the same name that was used in the addAction(actionName)
method on the PortletURI. Using action names, you can distinguish the
action event noti¬cations that get processed by the portlet class and respond
appropriately. The following actionPerformed() method shows how
this is performed.
This same URI creation function is available through the portlet API JSP
tag library. The following tags are available and behave as expected given
the previous discussion. A required parameter “name” speci¬es the action
name for the URIAction tag.

<portletAPI:createReturnURI />
<portletAPI:createURI />
<portletAPI:URIAction />
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49




272 Chapter 14


JSR 168 API Addressability
As we said, references to a speci¬c portlet, portal page, or portal resource
must be encoded in the portal Web application URI. The JSR 168 API creates
a PortletURL to assist with this encoding. The RenderResponse object
has two methods to create URLs, the createActionURL() method and
the createRenderURL() method. The createActionURL() method
will create an action URL while the createRenderURL() method creates
a render URL.
There are two main differences to the portlet developer in the generation
and handling of portlet URLs. The ¬rst is that with the JSR 168 API you do
not have a single URL for the portlet to which you optionally add a named
action event, which then triggers an event noti¬cation and listener. Instead,
this API de¬nes two different URLs, one for the action phase processing
and one for the render phase.
The following code fragment shows the creation of two PortletURLs to
handle our example to provide the links for a button to save the form data
and a button to cancel without saving.
// Create the save URL for the page and add the
// URL string to the request for use by the JSP
PortletURL saveURL = renderResponse.createActionURL();
saveURL.setParameter("action", "save");
renderRequest.setAttribute("saveURL", saveURL.toString());

// Create the cancel URL for the page and add the
// URL string to the request for use by the JSP
PortletURL cancelURL = renderResponse.createActionURL();
renderRequest.setAttribute("cancelURL", cancelURL.toString());

The other difference between this approach and the IBM Portlet API is
how the action is identi¬ed. Portlets can add parameters to the Portlet
URL. Typically you would add a parameter (name“value pair) to an action
URL to indicate the action to be performed. This name is analogous to
the action name you added to the PortletURI in the IBM Portlet API.
It is a name that you can later interrogate in the action phase™s process
Action() method.
The JSP tag library with the JSR 168 API de¬nes custom tags that provide
the creation of PortletURLs in the JSP. The tags are <portlet:action
URL/> and <portlet:renderURL/>.
public void processAction(ActionRequest request,
ActionResponse response) throws PortletException, IOException {

String actionName = request.getParameter("action");
if ("save".equals(actionName)) {
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49




Portlet Programming Model and API 273


// Retrieve the form data from the request
// object and save it.
}
}



Portlet Window
Both APIs provide maximize, minimize, and normal window states. The
JSR 168 API also allows portlets to de¬ne custom window states. Cus-
tom window states are de¬ned by the portal. Portlets, in their deployment
descriptors, declare the window states that they support using the custom-
window-state element. These can be de¬ned in the portlet deployment
descriptor. The portlet can query these state de¬nitions using the get
SupportedWindowStates() method on the PortletContext object.
The portlets can change their window state when processing an action re-
quest.
A portlet window is de¬ned by the JSR 168 API as the occurrence of a
portlet and a PortletPreferences object on a portal page. There can
be more than one portlet window for a given portlet on a page. Each port-
let window associated with its own portlet mode, render parameters, and
PortletPreferences.


Developing JSR 168 Portlets for WebSphere Portal
The Portal Toolkit V5.0.2 includes JSR 168 API support. The toolkit provides
the ability to generate a portlet application project that uses the JSR 168
Portlet API and also includes the JSR 168 portlet tag library declaration ¬le
(std-portlet.tld).
The toolkit provides a JSR 168 project wizard for creates new portlet
application projects which extend the GenericPortlet class de¬ned in
the JSR 168 “Portlet Speci¬cation.”


Enabling the Portlet Container for JSR 168
The JSR 168 support is provided in WebSphere Portal 5.0 with ¬x pack 2
(version 5.0.2) and subsequent releases. In version 5.0.2 you must apply
interim ¬x PQ77263 to the WebSphere Application Server.
The portlet container for JSR 168 portlets is not enabled by default
with WebSphere Portal 5.0.2. You can enable this support by setting the
portal.enable.jsr168 property to true in the ConfigService
.properties ¬le. That properties ¬le is in the <wp-root>/shared/app/
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-14 WY009-BenNatan-v1.cls May 11, 2004 14:49




274 Chapter 14


config/services/ directory. The portal server will need to be restarted
for this change to take effect.


Which API Should You Use for Your Portlet?
While both portlet APIs are supported in the current version of WebSphere
Portal and will be supported for announced future product enhancements,
the focus of IBM™s development effort and IBM™s commitment to open stan-
dards should be on the JSR 168 API being the API of choice.
In the near term, the JSR 168 API implementation is not as functionally
rich as the IBM Portlet API as we have seen in this chapter. However, that
gap is expected to close quickly as the API and its implementation matures.
There is no immediate need to migrate existing portlets to the JSR 168
API. For development of new portlets you should consider using the JSR
168 API when the functional support meets the needs of the portlet, and
also if the portlet is going to be published as a Web service since JSR 168
portlets can be published as a Web Service for Remote Portlets (WSRP).


Summary
In this chapter you learned about the portlet APIs supported in WebSphere
Portal. We discussed the differences between both the IBM Portlet API and
the JSR 168 API in the contest of key portlet topic areas.
In the following chapters we will develop an example portlet using both
ofthese APIs to understand how these APIs are applied and to highlight
the differences by using a common example.
P1: FCH/SPH P2: FCH/SPH QC: FCH/SPH T1: FCH
WY009-15 WY009-BenNatan-v1.cls May 11, 2004 14:50




CHAPTER

15
WebSphere Portlet
Development Environment

In this chapter you will learn about portlet development using WebSphere
Studio and the IBM Portal Toolkit. Both of these components are part of the
WebSphere Portal package. WebSphere Portal version 5.0 ships WebSphere
Studio Site Developer (WSSD or WebSphere Studio) and the Portal Toolkit.
We will introduce the WebSphere Studio development environment and
the Portal Toolkit extension that assists in portlet development.
We will introduce a sample portlet application and then work through its
design and development in the next chapter. We will focus on showing key
aspects of the Portlet APIs and in the process show the Studio development
environment. We will use WebSphere Studio version 5.1.0 and the Portal
Toolkit version 5.0.2 throughout these examples.
This sample portlet will be implemented using both the IBM Portlet API
and the JSR 168. We will then compare the results seeing the differences in
the two implementations.



An Example Poll Portlet
In this example we will look at creating a portlet that handles an online

<<

. 46
( 87 .)



>>