Migrating portlets built with Struts Portlet Framework

The Struts Portlet Framework allows users to package Struts portlet applications to be deployed on multiple versions of WebSphere Portal Express. Struts portlet applications that use earlier versions of the Struts Portlet Framework can be migrated to V6.1. Migrating a Struts portlet application includes updating the Struts Portlet Framework JAR files, TLDs, and org.apache.commons.logging.LogFactory file. Some additional manual steps might be necessary, depending on which version of the Struts Portlet Framework that your application used.

1. Copy the META-INF/services/org.apache.commons.logging.LogFactory file from the template application and add it to your Struts application. Overwrite this file if it already exists.
2. Copy the files listed below from the template application to the WEB-INF/lib directory of the Struts application that you are migrating. Overwrite the JAR files if they already exist.
   • commons-beanutils.jar
   • commons-collections.jar
   • commons-digester.jar
   • commons-fileupload.jar
   • commons-lang.jar
   • commons-validator.jar
   • jakarta-oro.jar
   • PortalStruts.jar (IBM legacy container) or wp.struts.standard.framework.jar (standard container)
   • PortalStrutsCommon.jar
   • PortalStrutsTags.jar
   • struts.jar
   • struts-legacy.jar
   • StrutsUpdateForPortal.jar
   • wp.struts-commons-logging.jar
   • wp.struts.tlds.common.jar
3. The following files are no longer part of the Struts packaging. Remove the files from the WEB-INF/lib directory, if they exist.
   • commons-dpcp.jar
   • commons-logging.jar
   • commons-pool.jar
   • commons-resources.jar
   • commons-services.jar
   • jdbc2_0-stdext.jar
4. Remove the following Struts TLD files. Check the tag location in the Web deployment descriptor to verify the location of the TLD files.
   Note: Do not remove the app.tld 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
5. Modify the application JSP files to use the following tag library URI convention:
   Note: Do not modify <%@ taglib uri="/WEB-INF/app.tld" prefix="app" >.
   • http://struts.apache.org/tags-bean
   • http://struts.apache.org/tags-chtml
   • http://struts.apache.org/tags-html
   • http://struts.apache.org/tags-logic
   • http://struts.apache.org/tags-nested
   • http://portal/struts/tags-html-1.0
   • http://portal/struts/tags-wml-1.0
   • http://struts.apache.org/tags-template
   • http://struts.apache.org/tags-tiles
   • http://struts.apache.org/tags-wml-1.0
   For example, in the JSP original source:

   <%@ taglib uri="/WEB-INF/tld/struts-logic.tld" prefix="logic" %>
   <logic:forward name="welcome"/>

   Would be converted to:

   <%@ taglib uri="http://struts.apache.org/tags-logic" prefix="logic" %>
   <logic:forward name="welcome"/>

6. Remove the Struts tag library descriptors from the Web deployment descriptor.
   Note: Do not remove the following tag library:

   <taglib>
     <taglib-uri>/WEB-INF/app.tld</taglib-uri>
     <taglib-location>/WEB-INF/app.tld</taglib-location>
   </taglib>

7. Remove the following lines from the portlet.xml file:
   Note: In your existing Struts portlet, check the portlet deployment descriptor to see if the Struts filter chain is specified. In general, the Struts filter chain is not required unless the application uses static or XML IViewCommands or the URL rewriting feature of static content. Struts Portlet Framework releases earlier than V5.1 used transcoding to apply stylesheets to XML documents, but versions 5.1.0.1 and later offer an alternative that does not require transcoding. See the SPFLegacyTransformation and SPFStandardTransformation samples for more details.

   <config-param>
   	 <param-name>FilterChain</param-name>
   	 <param-value>StrutsTranscoding</param-value>
   </config-param>

8. Remove the ForwardAction class, located in the WEB-INF/classes/org/apache/struts/actions directory, if it exists.
   Notes:

   1. Struts V1.1 changed the name of SubApplications to Modules after the Beta 2 release. This change lead to the renaming of the ApplicationConfig class to ModuleConfig. Some tags and actions might use ModuleConfig to determine the current module prefix. Use the Struts application code to see if the ApplicationConfig object has been used and should be migrated to use the ModuleConfig object instead. The method of obtaining the ModuleConfig object from the request object has changed. Here is an example of the new implementation: ModuleConfig config = (ModuleConfig) pageContext.getRequest().getAttribute (org.apache.struts.Globals.MODULE_KEY);
   2. The SubApplicationSearchPath configuration parameter has been renamed to ModuleSearchPath. For the Struts Portlet Framework to be consistent with Struts V1.1, a new initialization parameter, ModuleSearchPath, has been added. This parameter allows for customization in which client attributes are used for determining a module. The typical example would be ModuleSearchPath of "mode," which would use the portlet's mode to determine the module. The SubApplicationSearchPath initialization parameter will continue to be supported, but will eventually be deprecated. If both the SubApplicationSearchPath and ModuleSearchPath parameters are specified as initialization parameters, the ModuleSearchPath value is used.
   3. The SubApplicationContext class has been renamed to ModuleContext. The Struts Portlet Framework will deprecate the SubApplicationContext class and introduce the ModuleContext class to be consistent with the Struts V1.1 name change of SubApplication to Module. The ModuleContext object is obtained from the ExecutionContext object that is passed into those classes that implement the IViewCommand interface. The ModuleContext is used to store ViewCommandsFactories. The view command factories are implemented per module.
9. Use the following steps to migrate IBM legacy container Struts portlets to the standard container:
   Note: If the portlet you want to migrate is not based upon Struts Portlet Framework V6.1, migrate it to this level prior to migrating it to the standard container. The migration from the legacy version of the Struts Portlet Framework to the standard container starts with updating files shipped with the SPFStandardBlank.war file.
   1. Copy the META-INF/services/org.apache.commons.logging.LogFactory file from the template application and update the file in the application.
   2. Copy the following JAR files from the template application to the WEB-INF/lib directory of the Struts application you are migrating:
      Note: Overwrite the JAR files if they already exist.
      • commons-beanutils.jar
      • commons-collections.jar
      • commons-digester.jar
      • commons-fileupload.jar
      • commons-lang.jar
      • commons-validator.jar
      • jakarta-oro.jar
      • PortalStrutsCommon.jar
      • PortalStrutsTags.jar
      • struts.jar
      • struts-legacy.jar
      • StrutsUpdateForPortal.jar
      • wp.struts-commons-logging.jar
      • wp.struts.standard.framework.jar
      • wp.struts.tlds.common.jar
   3. Delete the PortalStruts.jar file. It is only required on the IBM legacy container.
   4. 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. Use the following steps to modify the Web deployment descriptor:
      1. Remove the servlet class from the Web deployment descriptor. The servlet class is no longer the 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.
      2. Move the initialization parameters from the Web deployment descriptor to the portlet deployment descriptor. Because the portlet class is now defined in the portlet deployment descriptor, the initialization parameters are also specified in the portlet deployment descriptor. Note, the initialization parameters 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.
      3. The <taglib> elements still remain in the Web deployment descriptor, and no changes are required.
      4. The welcome file elements still remain in the Web deployment descriptor, and no changes are required.
   5. The definition for the portlet deployment descriptor for the standard container is different than the legacy container. Some changes are required for the migrated example to deploy in the standard container. Use the following steps to modify the portlet deployment descriptor:
      1. Ths 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.
      2. The initialization parameters for the portlet are defined in the portlet deployment descriptor. The initialization parameters should be migrated from the Web deployment descriptor.
      3. 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.
   6. Modify the Struts configuration file. The Struts Portlet Framework defines the request processor that must be configured in the Struts configuration file. The controller attribute processClass must be migrated 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, the Struts plugin needs to be migrated:

      <plug-in className="com.ibm.portal.struts.plugins.WpTilesPlugin">

   7. Migrate dependencies on the portal container. The application must replace the org.apache.jetspeed interfaces with the equivalent javax.portlet interfaces.
   8. Many applications use the PortletApiUtils to obtain the portlet request and interface directly with the portlet API. Verify that the PortletApiUtils object is obtained as follows: com.ibm.portal.struts.common.PortletApiUtils portletUtils = com.ibm.portal.struts.common.PortletApiUtils.getUtilsInstance();
   9. Migrate any application customizations to the standard container.

      StrutsPortlet

      The com.ibm.wps.portlets.struts.WpsStrutsPortlet class for the legacy container extended the PortletAdapter class. The Struts application using the Struts Portlet Framework might have been customized by extending the WpsStrutsPortlet class. If so, those changes must be migrated for the Sstandard container. The com.ibm.portal.struts.portlet.StrutsPortlet class for the standard container extends the standard container's GenericPortlet.

      Request processor

      The com.ibm.wps.portlets.struts.WpsRequestProcessor class for the legacy container might have been extended to customize the processing. The Request Processor class for the standard container is com.ibm.portal.struts.portlet.WpRequestProcessor. If the legacy interfaces were used for the customizations, these changes must be migrated to the standard interfaces.