WebSphere Portal, Express Beta Version 6.1
Operating systems: i5/OS, Linux,Windows

 

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.

The steps for migration depend on the Struts Portlet Framework version that is being used by the application. Applications that package more recent versions of the Struts Portlet Framework might require no changes when migrating to the current version of WebSphere Portal Express. Applications that package older versions of the Struts Portlet Framework might require manual migration steps to update the WAR file. For example, an application that packages the Struts Portlet Framework version 4.x requires migration if the application is deployed in the current version of WebSphere Portal Express. If manual migration steps are not required, the portlet developer can choose to migrate to the current version of the Struts Portlet Framework to take advantage of the new Struts Portlet Framework features and fixes. The following is a list of the Struts Portlet Framework versions that have been released either in a WebSphere Portal Express release or in the catalog:

The Struts Portlet Framework includes a version file that allows you to determine its version. The Framework version determines whether your Struts portlets need migrating.

The Struts Portlet Framework samples are in the installableApps directory of the WebSphere Portal Express installation. Sample application names begin with SPFLegacy and SPFStandard. The version information is inside the WAR files. To locate the version information for a given Struts application WAR file, inspect the contents of the PortalStruts.jar (IBM legacy container) or wp.struts.standard.framework.jar (standard container) in the WEB-INF/lib directory of the WAR file. The JAR file contains a version.properties file and a version.txt file or both. If neither of these files can be found, the manifest file might contain the necessary information.

For WebSphere Portal Express versions prior to 6.0, the Struts Portlet Framework samples and documentation are located in the dev/struts directory of the WebSphere Portal Express installation. The version.txt file in the dev/struts directory provides the version of the Struts Portlet Framework and the version of Apache Struts that is integrated in the package. Each WAR file in the dev/struts directory also contains the version file in the PortalStruts.jar. The sample applications also contain the version.txt file within the PortalStruts.jar inside the WEB-INF/lib directory of each WAR file.

If you are working with the Struts Portlet Framework from the Workplace Solutions Catalog, the version file is in the base directory of the catalog ZIP file and also in the PortalStruts.jar or wp.struts.standard.framework.jar located in the WEB-INF/lib directory of the sample WAR files.

In the current installation, locate SPFLegacyBlank.war and SPFStandardBlank.war in the installableApps directory. These applications contain the files that are needed to migrate a Struts portlet to Version 6.1 and can be used as templates. Use the SPFLegacyBlank.war to migrate an IBM legacy container Struts portlet. The SPFStandardBlank.war is used to migrate a Struts portlet to the standard container of the current version. Standard container Struts portlets can be deployed in WebSphere Portal Express starting in version 6.0. Portlets written for the legacy container can be migrated to use the Struts Portlet Framework for the standard container.

Migrate the portlets from earlier versions of the Struts Portlet Framework to Version 6.1:

  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.

  3. The following files are no longer part of the Struts packaging. Remove the files from the WEB-INF/lib directory, if they exist.

  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.

  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" >.

    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.
Parent topic: Migrating your customized resources
Library | Support | Terms of use |