Converting HCL Digital Experience portlets (AIX, Linux, Windows) to the Java Standard API
You can convert your DX portlets that use the Struts Portlet Framework and the deprecated Portlet API to the Standard portlet API.
Converting basic Portlet API or Struts portlets to the Standard Portlet API
This section describes some of the more common changes (but not all) that are required to convert a basic portlet built using the deprecated Portlet API, or using the Struts Portlet Framework to a Java standard portlet. Many conversion tasks depend on the amount of complexity in the portlet code. You must become familiar with the Java Portlet Specification to determine any remaining changes that are not covered in this section.-
-
- Change the tag library to use the standard tag library. Change this:
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
to this:<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>
- Change references to API objects. In the standard portlet API, the
<portlet:defineObjects />
JSP tag makes the RenderRequest, RenderResponse, and PortletConfig objects available to JSP files. After making this change, all references in the JSP to the PortletRequest and PortletResponse should be changed to the corresponding RenderRequest and RenderResponse.Change this:<portletAPI:init /> ... <% PortletData prefs = portletRequest.getData(); %>
to this:<portlet:defineObjects /> ... <% PortletPreferences prefs = renderRequest.getPreferences(); %>
- Change JSP tags that are used for namespace encoding. For example,
if the portlet uses
<portletAPI:encodeNamespace/>
to uniquely qualify the name of a text input field, this tag must be changed as follows.Change this:<input name="<portletAPI:encodeNamespace value='name'/>" type="text" >
to this:<input name="<portlet:namespace/>name" type="text" >
- Change how portlet URLs are generated. If the portlet JSP creates a
URL to itself, it should specify which method gets control using the
<portlet:actionURL/>
or<portlet:renderURL/>
tags. Any parameters passed on the URL are specified using the<portlet:param/>
tag.Change this:<a href="<portletAPI:createURI> <portlet:URIParameter name='action' value='search'/> </portlet:createURI>" >
to this:<a href="<portlet:actionURL> <portlet:param name='action' value='search'/> </portlet:actionURL>" >
- Change resource bundles. The
<portletAPI:text/>
tag of the HCL Portlet API has been deprecated and should be replaced in all portlets by the JSTL equivalent. See Using JSTL in portlet JSPs for more information.Change this:<portletAPI:text key="my.label" bundle="nls.myproperties"/>
to this:<fmt:setBundle basename="nls.myproperties"/> ... <fmt:message key="my.label"/>
- Change how resources are invoked from the JSP. For example, if the
JSP displays an image, it should use the encodeURL() method of the
appropriate response object and, in addition, add the context path
of the portlet from the request. Change this:
<img src='<%= portletResponse.encodeURL("images/photo01.jpg") %>' alt="photo">
to this:<img src='<%= renderResponse.encodeURL(renderRequest.getContextPath() + "/images/photo01.jpg") %>' alt="photo">
- Change the tag library to use the standard tag library.
-
The following steps describe some of the differences between the portlet deployment descriptors of the HCL Portlet API and the Java Portlet Specification. However, the order of the elements in the standard portlet descriptor is important and strictly enforced during deployment. You should use a tool, such as Rational® Application Developer, that performs validation as you develop the portlet deployment descriptor.
- Remove the DOCTYPE declaration. The portlet descriptor for the
standard portlets uses an XML schema that is added in the next
step. Remove this:
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd ">
- Remove the
<portlet-app-def/>
element. The first-level element in the standard portlet descriptor is <portlet-app/>.Remove this code:<portlet-app-def> .... </portlet-app-def>
- Update the
<portlet-app/>
element.- Add the schema definition and namespace declarations.
- Remove the major-version and minor-version attributes.
- Set the version attribute to the required version of the
Java Portlet Specification. Currently, version
1.0
is the only supported specification version. - Change the uid attribute to id.
Change this code:<portlet-app uid="com.mycompany.samples.MyPortletApp.001c" major-version="1" minor-version="0">
to this code:<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" id="com.mycompany.samples.MyPortletApp.001c" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
- Remove all
<concrete-portlet-app/>
elements and their contents. Save any required information, such as configuration parameters and language definitions, for use in the portlet definition. - Update the
<portlet/>
element. Remove the href, minor-version, and major-version attributes.Change this code:<portlet id="com.mycompany.samples.MyPortlet.110x" href="WEB-INF/web.xml#com.mycompany.samples.MyPortlet.href110x" major-version="1" minor-version="0">
to this code:<portlet id="com.mycompany.samples.MyPortlet.110x">
- Move the definition of the portlet class from the
web.xml file to the
portlet.xml file. Remove this code from the web.xml file:
<servlet id="com.mycompany.samples.MyPortlet.001c"> <servlet-name>MyPortlet</servlet-name> <servlet-class>com.mycompany.samples.MyPortlet</servlet-class> </servlet> <servlet-mapping id="ServletMapping_com.mycompany.samples.MyPortlet.001c"> <servlet-name>MyPortlet</servlet-name> <url-pattern>/MyPortlet/*</url-pattern> </servlet-mapping>
Add this code to the portlet.xml file:<portlet-class>com.mycompany.samples.MyPortlet</portlet-class>
- Change how caching is defined. Use the
<expires/>
value from the HCL portlet descriptor as the value for the<expiration-cache/>
element in the standard descriptor. There is no equivalent in the standard descriptor to the<shared/>
element.Change this code:<cache> <expires>-1</expires> <shared>no</shared> </cache>
to this code:<expiration-cache>-1</expiration-cache>
- Change the content of the
<supports/>
element.- Change supported markups to MIME types.
- Use the
<portlet-mode/>
element.
The standard portlet descriptor allows you to declare only MIME types. In some cases, two markup types use the same MIME type. For example, both HTML and cHTML use 'text/html' as the MIME type. For standard portlets, HCL Portal accepts the value of a
wps.markup
initialization parameter as the markup type.Change this code:<supports> <markup name="html"> <view /> <edit /> </markup> </supports>
to this code:<init-param> <name>wps.markup</name> <value>html,chtml</value> </init-param> ... <supports> <mime-type>text/html</mime-type> <portlet-mode>VIEW</portlet-mode> <portlet-mode>EDIT</portlet-mode> </supports>
Be sure to place the initialization parameters before the
<expiration-cache>
element. - Remove window state elements. Normal, maximized, and minimized
window states are supported by default and not declared in the
standard portlet deployment descriptor.Remove this:
<allows> <maximized/> <minimized/> </allows>
- Change configuration parameters to preferences. In
the standard portlet descriptor, preferences can be changed by
users in any of the standard modes, or they can be declared as
read-only and modified only by an administrator. Change this:
<config-param> <param-name>Location</param-name> <param-value>Antartica</param-value> </config-param>
to this:<portlet-preferences> <preference> <name>Location</name> <value>Antartica</value> <read-only>true</read-only> </preference> </portlet-preferences>
- Change localized settings.
- Remove the
<default-locale/>
element. In the standard portlet descriptor, the first locale listed in the descriptor is the default. If no locale is specified, then English is used as the default. - Create resource bundles for each supported language
containing the title, short title, and keywords for the
portlet. Use the following parameter names:
javax.portlet.title = My Portlet Title javax.portlet.short-title = Title javax.portlet.keywords = portlets, JSR 168, portal
- Declare the resource bundle in the portlet descriptor as
in the following example.
<resource-bundle>nls.MyPortlet</resource-bundle>
In this example, the default resource bundle
MyPortlet.properties
is in the/WEB-INF/nls
sub-directory of the WAR file and all of the locale-specific resource bundles append the locale to the file name (for example,MyPortlet_ja.properties
for Japanese). - Declare each supported locale as in the following
example:
<supported-locale>en</supported-locale> <supported-locale>de</supported-locale>
- Set the localized values for the portlet description and
display name as in the following example.
<description xml:lang="EN"> English description </description> <display-name xml:lang="EN"> English display name </display>-name> <description xml:lang="DE"> German description </description> <display-name xml:lang="DE"> German display name </display>-name>
Note: The display name should be set for compatibility reasons. However, it is not currently used by HCL Portal.
- Remove the
- Remove the DOCTYPE declaration. The portlet descriptor for the
standard portlets uses an XML schema that is added in the next
step.
Converting HCL Digital Experience portlets that use the Struts Portlet Framework
The existing versions of the Struts Portlet Framework supported the Portlet API, or the legacy container. This release uses a newer version of the Struts Portlet Framework that supports the standard portlet container. This release will continue to ship a version to support the legacy container and a new version for the Standard container. The Struts Portlet Framework is still shipped as example war files that can be used to build the Struts application. The war files for each container can be distinguished by the name. The SPFLegacy examples support the legacy container, and the SPFStandard examples support the standard container. The SPFLegacyBlank.war file is the starting point for Struts applications for the Legacy container, and the SPFStandardBlank is the starting point for the Struts applications for the Standard container.
-
The SPFLegacyBlank.war file contains the files to include with the Struts application. The directories of interest are the
WEB-INF/lib
and theWEB-INF/tld
directory. Here is the list of libraries to be used in the application from theWEB-INF/lib
directory:- PortalStruts.jar
- PortalStrutsCommon.jar
- PortalStrutsTags.jar
- StrutsUpdateForPortal.jar
- wp.struts-commons-logging.jar
- commons-beanutils.jar
- commons-collections.jar
- commons-fileupload.jar
- commons-lang.jar
- commons-validator.jar
- struts-legacy.jar
- struts.jar
The files from theTLD
directory are- struts-bean.tld
- struts-chtml.tld
- struts-html.tld
- struts-logic.tld
- struts-nested.tld
- struts-portal-html.tld
- struts-portal-wml.tld
- struts-template.tld
- struts-tiles.tld
- struts-wml.tld
-
The following files are the Jakarta Struts 1.1 binary files, and the same in both the Standard and Legacy versions of the Struts Portlet Framework:
- commons-beanutils.jar
- commons-collections.jar
- commons-fileupload.jar
- commons-lang.jar
- commons-validator.jar
- struts-legacy.jar
- struts.jar
The following files from the TLD directory are same on for both containers. This can change in future releases, so it is strongly encouraged to use the files from the blank for the required container.- struts-bean.tld
- struts-chtml.tld
- struts-html.tld
- struts-logic.tld
- struts-nested.tld
- struts-portal-html.tld
- struts-portal-wml.tld
- struts-template.tld
- struts-tiles.tld
- struts-wml.tld
-
Converting the legacy version of the Struts Portlet Framework to the Standard versions starts with updating the jars, and TLDs cataloged with the SPFStandardBlank.war file.
Here is a list of the files that should be updated in theWEB-INF/lib
directory of the application:- wp.struts.standard.framework.jar
- PortalStrutsCommon.jar
- PortalStrutsTags.jar
- StrutsUpdateForPortal.jar
- wp.struts-commons-logging.jar
- commons-beanutils.jar
- commons-collections.jar
- commons-fileupload.jar
- commons-lang.jar
- commons-validator.jar
- struts-legacy.jar
- struts.jar
- commons-digester.jar
- commons-logging.jar
- jakarta-oro.jar
Here is a list of the TLD files that should be updated with the TLDs from the SPFStandardBlank.war file:- struts-bean.tld
- struts-chtml.tld
- struts-html.tld
- struts-logic.tld
- struts-nested.tld
- struts-portal-html.tld
- struts-portal-wml.tld
- struts-template.tld
- struts-tiles.tld
- struts-wml.tld
The PortalStruts.jar file is only required on the HCL container and must be deleted.
-
The Standard container requires a web deployment descriptor because the application is packaged as a war file. However, most of the initialization parameters are now configured through the portlet deployment descriptor.
- Remove the servlet class from the web deployment descriptor. The servlet-class is no longer that way to specify the portlet class for the application in the Standard container. The portlet is now specified as the portlet class in the portlet deployment descriptor.
- Move the init parameters from the web deployment descriptor to the portlet deployment descriptor. Since the portlet class is now defined in the portlet deployment descriptor, the init parameters are also specified in the portlet deployment descriptor. Note, the init-parameter are specified as name and value in the portlet deployment descriptor, not param-name and param-value as they are named in the web deployment descriptor.
- The taglib elements still remain in the web deployment descriptor, no changes required.
- The welcome file elements still remain in the web deployment descriptor, no changes required.
-
The definition for the Portlet Deployment Descriptor for the Standard container is different from the legacy container. There are some changes that are required for the converted example to deploy in the Standard container. The Help Center contains details for the semantics of the portlet deployment descriptor for the Standard container.
- The Standard container introduces the portlet-class element for
specifying the class of the portlet. The portlet class for the
Struts Portlet Framework is
com.ibm.portal.struts.portlet.StrutsPortlet
. - The init parameters for the portlet are defined in the portlet deployment descriptor. The init parameters should be converted from the web deployment descriptor.
- The Standard container does not have the abstract and concrete separation in the portlet deployment descriptor. The portlet element defines the supported modes, and portlet preferences.
- The Struts Portlet Framework no longer uses a portlet filter. The FilterChain init parameter should not be converted.
- The Standard container introduces the portlet-class element for
specifying the class of the portlet. The portlet class for the
Struts Portlet Framework is
-
The Struts Portlet Framework defines the Request Processor that must be configured in the Struts configuration file. The controller attribute processClass must be converted to the following value to be deployed on the Standard container:
<controller processorClass="com.ibm.portal.struts.portlet.WpRequestProcessor">
If the Struts application is using the Struts Request processor that supports Tiles, then the Struts plug-in must be converted as well:<plug-in className="com.ibm.portal.struts.plugins.WpTilesPlugin">
-
The Struts action class is passed a HttpServletRequest object, so the application may not have a dependency on the Portal container. However, many applications use the PortletApiUtils to obtain the portlet request and interface directly with the portlet API. If so, then the application must replace the org.apache.jetspeed interfaces with the equivalent javax.portlet interfaces. The new interfaces are documented in the Help Center.
Note: The following example illustrates the change in which the PortletApiUtils object is obtained:- Old:
PortletApiUtils portletUtils = PortletApiUtils.getInstance();
- New:
PortletApiUtils portletUtils = PortletApiUtils.getUtilsInstance();
- Old:
-
The
com.ibm.wps.portlets.struts.WpsStrutsPortlet
class for the legacy container extended the PortletAdapter class. The Struts application using the Struts Portlet Framework may have been customized by extending the WpsStrutsPortlet class. If so, those changes should be applied for the Standard container. Thecom.ibm.portal.struts.portlet.StrutsPortlet
class for the Standard container extends the standard container's GenericPortlet. -
The
com.ibm.wps.portlets.struts.WpsRequestProcessor
class for the legacy container may have been extended to customize the processing. The Request Processor class for the standard container iscom.ibm.portal.struts.portlet.WpRequestProcessor
. If the legacy interfaces were used for the customizations, these changes should be converted to the Standard interfaces.