Migrate portlets built with Struts Portlet Framework

Migrate portlets built with Struts Portlet Framework

+

Search Tips | Advanced Search

The Struts Portlet Framework is designed to allow users to package Struts portlet applications that can be deployed on multiple versions of WebSphere Portal. The steps for migration depend on the Struts Portlet Framework version that is being used by the application. Applications, which package more recent versions of the Struts Portlet Framework, may require no changes at all when migrating to the current version of WebSphere Portal. For example, a Struts portlet application that packages the Struts Portlet Framework v5.1.0.1 may be deployed on the current version of WebSphere Portal without any changes to the application. Applications packaging older versions of the Struts Portlet Framework may require manual migration steps to update the WAR file. For example, an application which packages the Struts Portlet Framework v4.x requires migration if the application will be deployed in the current version of WebSphere Portal. 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/or fixes. The following is a list of the Struts Portlet Framework versions that have been released either in a WebSphere Portal release or in the catalog:

WebSphere Portal V6.0

Struts Portlet Framework version: SPF 6.0

Struts release: Struts 1.1

WebSphere Portal V5.1.x

Struts Portlet Framework version: SPF 5.1.x

Struts release: Struts 1.1

WebSphere Portal V5.0.x

Struts Portlet Framework version: SPF 5.0.x

Struts release: Struts 1.1

Catalog v5.1.0.1

Struts Portlet Framework version: SPF 5.1.0.1

Struts release: Struts 1.1

Catalog v5.0.3

Struts Portlet Framework version: SPF 5.0.3

Struts release: Struts 1.1

If you are trying to determine whether the Struts portlet needs to be migrated to a newer version of the Struts Portlet Framework, it is important to know the current version of the Struts Portlet Framework. The Struts Portlet Framework includes a version file which allows you to determine the version.
In WebSphere Portal V6.0 and 5.1.x, the Struts Portlet Framework samples can be found in the installableApps directory of the WebSphere Portal installation. The Struts Portlet Framework sample application names begin with 'SPFLegacy' and 'SPFStandard'. The version information can be found 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) located in the WEB-INF/lib directory of the WAR. The JAR file contains a version.properties file and/or a version.txt file. If neither of these files can be found, then the manifest file may contain the necessary information.
For WebSphere Portal versions prior to 5.1, the Struts Portlet Framework samples and documentation are located in the dev/struts directory of the WebSphere Portal 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 of the WAR files in the dev/struts directory also contain 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.
If you are working with the Struts Portlet Framework from the Workplace Solutions Catalog, the version file can be found 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 WARs.

Portlet migration

Struts portlet applications that used previous versions of the Struts Portlet Framework can be migrated to the 6.0 version of the framework. The necessary steps to migrate a portlet application include updating the Struts Portlet Framework JARs, TLDs, and org.apache.commons.logging.LogFactory file, and some additional manual steps may be necessary, depending on which version of the Struts Portlet Framework that the application used.
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 the 6.0 version and can be used as templates. The SPFLegacyBlank.war contains the necessary files needed to migrate an IBM legacy container Struts portlet. The SPFStandardBlank.war is used in the migration of a Struts portlet to the Standard container of the current version. Standard container Struts portlets can be deployed in WebSphere Portal starting in v5.1.x. Portlets written for the legacy container can be migrated to use the Struts Portlet Framework for the Standard container.
Perform the following steps migrate the portlets:

Use the following steps to migrate portlets from previous versions of the Struts Portlet Framework to SPF 6.0:

Copy...
META-INF/services/org.apache.commons.logging.LogFactory

...from the template application and add it to the Struts application.
Overwrite this file if it already exists.

Copy the following JAR files from the template application to the WEB-INF/lib directory of the Struts application 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

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

commons-dpcp.jar
commons-logging.jar
commons-pool.jar
commons-resources.jar
commons-services.jar
jdbc2_0-stdext.jar

Remove the following Struts TLD files. Check the tag location in the Web deployment descriptor to verify the location of the TLD files.
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

Modify the application's JSPs to use the following tag library URI convention:
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

Example, 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"/>

Remove the Struts tag library descriptors from the Web deployment descriptor.
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>

Remove the following lines from the portlet.xml file:
In the 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 prior to 5.1 used transcoding to apply style sheets to XML documents, but releases 5.1.x and 6.0 offer an alternative that does not require transcoding (please see the SPFLegacyTransformation and SPFStandardTransformation samples for more details).
<config-param> <param-name>FilterChain</param-name> <param-value>StrutsTranscoding</param-value> </config-param>

Remove the ForwardAction class, located in...
WEB-INF/classes/org/apache/struts/actions

...if it exists.
Struts 1.1 has 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 may use ModuleConfig to determine the current module prefix. The Struts application code should be checked to see if the ApplicationConfig object has been used and should be migrated to use the ModuleConfig object instead. Also note that 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);
The SubApplicationSearchPath config parameter has been renamed ModuleSearchPath. For the Struts Portlet Framework to be consistent with Struts 1.1, a new init-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 init-parameter will continue to be supported, but will eventually be deprecated. If both the SubApplicationSearchPath and ModuleSearchPath parameters are specified as init-parameters, then the ModuleSearchPath value will be used.
The SubApplicationContext has been renamed ModuleContext. The Struts Portlet Framework will deprecate the SubApplicationContext class and introduce the ModuleContext class to be consistent with the Struts 1.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.

Use the following steps to migrate IBM legacy container Struts portlets to the Standard container:
If the portlet you want to migrate is not based upon SPF 6.0, please 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.

Copy...
META-INF/services/org.apache.commons.logging.LogFactory

...from the template application and update the file in the application.

Copy the following JAR files from the template application to the WEB-INF/lib directory of the Struts application 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
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

Delete the PortalStruts.jar file. It is only required on the IBM legacy container.

Use the following steps to modify the Web deployment descriptor:
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.

Use the following steps to modify the portlet deployment descriptor:
The definition for the portlet deployment descriptor for the Standard container is different than the legacy container. There are some changes required for the migrated example to deploy in 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 migrated from the Web deployment descriptor.

The Standard container does not have the abstract and concrete separation in the portlet deployment descriptor. The portlet element will define the supported modes, and portlet preferences.

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 needs to 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, then the Struts plugin needs to be migrated as well:
<plug-in className="com.ibm.portal.struts.plugins.WpTilesPlugin">

Migrate dependencies on the portal container. The application will have to replace the org.apache.jetspeed interfaces with the equivalent javax.portlet interfaces.

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();

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 may have been customized by extending the WpsStrutsPortlet class. If that is the case, then those changes will have to be migrated for the Standard 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 may 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 then these changes need to be migrated to the Standard interfaces.

Parent topic:
Migrating the customized resources