Sun Java System Portal Server 7.1 Developer's Guide

Chapter 16 Converting Providers to Portlets

This chapter contains the following sections:

Introduction to Converting Providers to Portlets

There are numerous differences in the way portlets and providers generate content for the desktop. In order to perform a successful conversion, the user must first understand the portlet request handling sequence. The ability to access user preferences and LDAP attributes from the portlet is vital to generating the correct content.

Converting JSPs and tag libraries is the next step. JSPProvider-based JSPs and taglibraries need extensive reworking to function within the portlet framework. There is no need for a tag to wrap all the content; so all references to <dt:obtainChannel channel="$JSPProvider"> can be removed. All taglibraries specific to the desktop (desktop.tld, desktopProviderContext.tld) should be removed from the JSP and replaced with portlet taglibraries. Unfortunately, very few of the desktop taglibraries have portlet counterparts. The generic portlet taglibrary (portlet.tld in http://java.sun.com/portlet) has a number of useful tags. There are no handles to the portlet object available to the JSP, unlike providers. Any objects that need to be shared between external JSP and/or servlets and the portlet should be stored in the session at the application scope.

Note that there is no functionality present in the GenericPortlet abstract class to convert a template-based provider, other than the ability to use HTML files for each portlet mode.

Packaging, deploying and testing the new portlet are the last steps in this process. Portlets are deployed in a custom web-app. This means all JAR files, JSPs, templates, servlets, and properties files that the portlet uses must either be included or defined in the portlet deployment descriptor file (portlet.xml) or the web application deployment descriptor file (web.xml). A WAR file is created that contains all the files and information needed to deploy the web-app. The psadmin deploy-portlet command can be used to deploy the WAR file to the web container.

Mapping ProviderAdapter to GenericPortlet

The following table can be used as a guideline for comparing the Provider API to the Portlet API, when developing or trying to convert providers to portlets.

Table 16–1 Mapping ProviderAdapter to GenericPortlet


ProviderAdapter	GenericPortlet
`public void init(String n, HttpServletRequest req)`	`public void init (PortletConfig config)`
`public URL processEdit (HttpServletRequest request,HttpServletResponse response)`	`public void processAction (ActionRequest request,ActionResponse response)`
	`public void render (RenderRequest request, RenderResponse resposne)`
`public StringBuffer getContent (HttpServletRequest request, HttpServletResponse response)`	`protected void doView (RenderRequest request,RenderResponse response)`
`public StringBuffer getEdit (HttpServletRequest request, HttpServletResponse response)`	`protected void doEdit (RenderRequest request,RenderResponse response)`
`public URL getHelp(HttpServletRequest req, String key)`	`protected void doHelp (RenderRequest request, RenderResponse response)`
`public String getName()`	`public String getPortletName ()`
`public String getTitle()`	`protected String getTitle(RenderRequest request)`
`public ResourceBundle getResourceBundle(String base)` `public ResourceBundle getResourceBundle()`	`public java.util.ResourceBundle getResourceBundle (java.util.Locale locale)`
	`public PortletConfig getPortletConfig ()`
	`public PortletContext getPortletContext ()`
	`public String getInitParameter(java.lang.String name)`
	`public java.util.Enumeration getInitParameterNames()`
	`public void destroy ()`
`public int getEditType()`
`public int getWidth()`
`public boolean isEditable()`
`public boolean isPresentable()`
`public ProviderContext getProviderContext()`

The Javadocs for the Provider API can be accessed using the following URL:

http://portal-host:port/portal-ID/javadocs/index.html

For further reading on the Portlet API, see http://portals.apache.org/pluto/multiproject/portlet-api/apidocs/index.html.

Sample Code Fragments for Provider to Portlet Conversion

This section includes some sample code fragments for Provider to Portlet conversion.

Provider to Portlet Mapping

The

Maps To (or can use)

ProviderContext.getStringAttribute
("firstname");

Map ui = (Map)renderRequest.getAttribute
("javax.portlet.userinfo");
String firstname = (String)ui.get("firstname");

ProviderContext.getSessionProperty()
/setSessionProperty()

PortletSession.getAttribute(),
PortletSession.setAttribute()

ProviderContext.getDesktopURL()

PortletURL.RenderResponse.createRenderURL(),
RenderResponse.createActionURL()

Dispatching to a JSP

PortletRequestDispatcher dispatcher = pContext.getRequestDispatcher("test.jsp");
dispatcher.include(request, response);

Help Documentation

Help documentation for portlets follows a different scheme than in the providers. The help file name is stored as a preference and content is generated from that file the same way as any other content type.

getHelp(): In Provider, this method returns a helpURL which can be pointing to a static help file.
doHelp(): For portlets, this method has to be implemented for writing out the help content dynamically.

Title Mapping

getTitle()

For ProviderAdapter, this method returns the title from the Display Profile title property.

For portlets, the title is returned by the portlet implementation.

`editType` Property

For a provider, the editType display profile property can be specified to determine whether the provider implementation will draw the complete edit page or a subset of it.

For portlets, the editType is always EDIT_COMPLETE and the complete page including the form, the Finish, and the Cancel buttons have to be generated by the portlet. Only the banner and footer are drawn by the PortletEdit.jsp in PortalServer-DataDir/portals/portal-ID/desktop/default directory.

PortletPreferences Mapping

The ProfileProviderAdapter.getStringProperty(key) maps to PortletPreferences.getValue(key, default). The ProfileProviderAdapter.getListProperty(key) maps to PortletPreferences.getValues(key, default[]).