Manual migration steps

 

+
Search Tips   |   Advanced Search

 

  1. Move an existing Portlet Project to Rational Application Developer V6.0
  2. Migrate WebSphere Studio V5.0 to Rational Application Developer V6.0
  3. Change the class path and taglib descriptor for WebSphere Portal V5.1
  4. Migrate themes and skins
  5. Migrate custom portlet code
  6. Migrate Click-to-Action portlets
  7. Migrate portlets built with the Struts Portlet Framework
  8. Migrate collaborative portlets
  9. Transcoding Technology migration
  10. Verifying updated portlets

 

Move an existing Portlet Project to Rational Application Developer V6.0

Follow these steps to migrate WebSphere Studio, Portal Toolkit 5.x, and their associated projects to Rational Application Developer V6.0:

  1. Export each portlet application project to WAR files with source files.

  2. Uninstall the previous version of Portal Toolkit and WebSphere Studio (WebSphere Studio Site Developer or WebSphere Studio Application Developer) 5.1.

  3. Install Rational Application Developer V6.0 and necessary fixes.

  4. Create a new portlet application project, specifying the Create empty portlet and J2EE Level 1.2/WebSphere Portal 5.0 option.

  5. Import the WAR files that were exported in Step 1 to the new portlet application project.

  6. Turn off the Overwrite existing resources without warning option.

  7. Answer No to Overwrite portlet.tld.

  8. Answer Yes to Overwrite portlet.xml and web.xml.
use a new workspace after installing the new version of Rational Application Developer.

 

Migrate WebSphere Studio V5.0 to Rational Application Developer V6.0

In order to migrate projects, update any version 5.0 Web project that contains J2EE Web project resources to Rational Application Developer V6.0. The steps you take to update the Web projects depend on which version of WebSphere Application Server you are using. Follow the steps under the appropriate case:

Case 1: Move a WebSphere Studio project to Rational Application Developer V6.0, while continuing to use WebSphere Application Server 5.x:

  1. Display the context menu for the project and select Migrate > J2EE Migration Wizard.

  2. Select all of the projects that you would like to migrate, and deselect the box that says Migrate project from version level J2EE 1.2 to J2EE 1.3.

    This is an important step because J2EE 1.3 Web projects are supported on WebSphere Application Server V5.0 but not on version 4.0.

  3. Then click Finish.

Case 2: Move a WebSphere Studio V5.1 project to Rational Application Developer V6.0, while using WebSphere Application Server 5.0 and WebSphere Portal V5.0.x:

  1. Display the context menu for the project and select Migrate > J2EE Migration Wizard.

  2. Select all of the projects that you would like to migrate. Do not deselect the box that says Migrate project from version level J2EE 1.2 to J2EE 1.3.

  3. Then click Finish.

Resource classes that are generated with wizards other than those contained in the version 5.0 plug-in will not allow the resources to be used for content management by IBM DB2 Content Manager. Resources from version 4.2 or later might be regenerated as part of the project migration in WebSphere Studio. You can regenerate the resources by right-clicking on the HRF file and selecting the option for resource regeneration. HRF files can be found in $WAS_HOME/personalization/publishedResources. Resources that are generated prior to version 4.2 will have to be re-created by going through the wizard and remodeling the resource. Resources that are generated prior to version 5 can still be used at run time on version 5.0.

 

Change the class path and taglib descriptor for WebSphere Portal V5.1

Portlet Projects that are migrated from WebSphere Portal V4.x need to be updated with the class path and taglib descriptor for WebSphere Portal V5.1.

  1. Select your portlet project in Studio J2EE Navigator view.

  2. Select File > Properties.

  3. Select Java build path.

  4. You find the following definition for WebSphere Portal V4.x:

    <classpathentry kind="var" path="WPS_PLUGINDIR/portlet-api.jar"/>

    <classpathentry kind="var" path="WPS_PLUGINDIR/wpsportlets.jar"/>

    <classpathentry kind="var" path="WPS_PLUGINDIR/wps.jar"/>

    Change these definitions so that they will work in WebSphere Portal V5.1:

    <classpathentry kind="var" path="SERVERJDK_51_PLUGINDIR/jre/lib/rt.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/cm.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/cmInt.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/dynacache.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/ivjejb35.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/j2ee.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/naming.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/ras.jar""/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/runtime.jar""/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/servletevent.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/utils.jar"/>

    <classpathentry kind="var" path="WAS_51_PLUGINDIR/lib/xerces.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/databeans.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/wpcpauthor.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/wpcpquery_src.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/wpcpresources.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/wpcpruntime.jar"/>

    <classpathentry kind="var" path="WCM_PLUGINDIR/lib/wpcpruntimecommon.jar"/>

    <classpathentry kind="var" path="WPS_V51_PLUGINDIR/portlet-api.jar"/>

    <classpathentry kind="var" path="WPS_V51_PLUGINDIR/wpsportlets.jar"/>

    <classpathentry kind="var" path="WPS_V51_PLUGINDIR/wps.jar"/>

    Note the following information:

    • Make sure to check your class path entries in the new Studio products tooling after migration. Ensure that the class path entries are pointing to the new WebSphere Portal V5.1 paths.

    • When you create a Portlet Project for WebSphere Portal V5.1, you can choose WPS_V5_PLUGINDIR as a class variable.

  5. Click File > Import > File System.

  6. Press Next.

  7. Select the following directory as a source directory: Rational Application Developer _root/wstools/eclipse/plugins/com.ibm.wps_v5_<WebSphere_Portal_version>

    where:

    • Rational Application Developer _root is the root directory of Rational Application Developer.

    • <WebSphere_Portal_version> is the specific 5.x version of WebSphere Portal.

  8. Select the following directory as a target directory: <portlet_project>/Web Content/WEB-INF/tld

    where: <portlet_project> is the name of your project.

  9. Override the existing portlet.tld file with the new one.

 

Migrate themes and skins

WebSphere Portal V4.1 supported a two-level hierarchy (places, or pageGroups, and pages). In V4.1, theme JSPs (Navigation.jsp, Banner.jsp) provided navigation for places and pages. JSP developers could customize the theme and skin JSPs by using the <wps:page/> and <wps:pageGroup/> tags.

WebSphere Portal V4.2 introduced multilevel navigation, in which users and administrators could create pages that are nested within other pages. Themes developed for V4.1 do not provide navigation to nested nodes that were introduced in V4.2. The <wps:navigation/> tag was added to allow JSP developers to make use of the new hierarchy. The original <wps:page/> and <wps:pageGroup/> tags remained in V4.2 for compatibility reasons. By default in V4.2, if nested nodes exist for a user, a navigation column provides complete access to all nodes not accessible from the theme. This navigation column is created by LayeredContainer-V.jsp in the /skins directory. A Java scriptlet that invoked the Composition Model API was used to implement the nested navigation tree in LayeredContainer-V.jsp.

More changes were introduced in the portal organization for V5.0. The representation of places or pagegroups was removed entirely. Also, a new enhanced Object Model API replaced the Composition Model API for use in the navigation tree. The Object Model API is not available for public use. However, you can manipulate the appearance of the navigation tree by making changes to the images, colors, and other style settings that are used by the layered container. Also, developers who used the Composition Model API in V4.2 should read Migrate from the V4.2 Composition Model API to the V5.0 Object Model, available at http://www.ibm.com/support/docview.wss?uid=swg27004260.

WebSphere Portal V5.1 included several major changes. Portal JSPs should use the portal.tld tag library instead of the engine.tld tag library. The engine.tld tag library is still available, but only for backward compatibility prior to migration.

See Designing your portal to get a better understanding of how the portal page is constructed for this release of WebSphere Portal.

 

Updates to engine tags

The following tags, deprecated in WebSphere Portal V4.2, were removed in WebSphere Portal Versions 5.0 and 5.1:

  • <wps:pageGroupLoop/>

    Replaced by <wps:navigationLoop/>.

  • <wps:pageGroup/>

    This tag was mostly used with attribute="title" to obtain the title of a pagegroup to display in the navigation. Replaced by the <wps:title/> tag.

  • <wps:pageLoopInit/>

    Replaced by the maxPages attribute on <wps:navigationShift/>.

  • <wps:page/>

    This tag was mostly used with attribute="title" to obtain the title of a page to display in the navigation. Replaced by the <wps:title/> tag.

  • <wps:frameURL/>

    In WebSphere Portal, support for frames is removed completely.

  • <wps:pageLoop/>

    Replaced by <wps:navigationLoop/>.

  • <wps:pageLoopShift/>

    Replaced by <wps:navigationShift/>.

  • <wps:pageRender/>

    Removed in V5.0, but restored in V5.1 to replace <wps:compositionRender/>.

The <wps:URLSelect> tag, introduced in WebSphere Portal V4.2, was deprecated and replaced by the <URLGeneration/> tag in V5.1.

The following tags were added in WebSphere Portal Versions 5.0 and 5.1:

The following tags were changed in WebSphere Portal V5.0:

  • <wps:urlParent/>

    With the removal of <wps:pageGroupLoop/> and <wps:pageLoop/>, you cannot use <wps:urlParent/> to obtain the URL for a page or node in the portal. Instead, links to nodes are created within the <wps:navigationLoop/> by using either the wpsNavNode scripting variable or the <wps:navigationURL/> tag.

  • <wps:text/> and <wps:textParam/> tags

    4.1 rendering classes for these tags were removed (TextTag_old.class and TextParamTag_old.class). These classes used the body contents of the tag only if the specified key was not found in the specified resource bundle. Starting in V5.0, these tags use TextTag.class and TextParamTag.class, respectively. This change caused the behavior of these tags to change. For V5.0, if your JSPs provide content in the body of the <wps:text/> tag, it will now always be written to the page. The new classes were introduced in V4.2, but not used by default.

    Starting in V5.1, the <wps:text/> tag is still supported, but deprecated in favor of using the <i18n:message/> and <i18n:message/> tags of the JSP Standard Tag Library (JSTL).

  • <wps:navigation/>

    computeSelectionPath and useModelFromRequestAttributeNamed attributes removed

  • <wps:urlFind/>

    id attribute added

  • <wps:if/>

    Changes to attributes:

    • pageSelected (removed, replaced by nodeInSelectionPath)
    • pageGroupSelected (removed, replaced by nodeInSelectionPath)
    • pageAvailable (removed, replaced by navigationAvailable)
    • pageGroupAvailable (removed, replaced by navigationAvailable)
    • frameMode (removed, support for frames is removed completely)
    • showTools (added)
    • nodeInSelectionPath (added)
    • navigationAvailable (added)
    • portletSolo (added)
    • error (previously deprecated attribute has been removed)

  • <wps:unless/>

    Exact same changes as <wps:if/> tag.

Starting with WebSphere Portal V5.1, skins are rendered using the <wps:pageRender/> tag from the portal.tld tag library. This is in contrast to the <wps:compositionRender/> tag defined in the V5.0 engine.tld tag library. Skins called from the <wps:pageRender/> tag do not include the portal navigation tree. In WebSphere Portal V5.1, all navigation is handled by the theme JSPs.

The following table lists the tags of the engine.tld tag library and the replacements from the portal.tld tag library.

Tags from engine tag library Replacements in the portal tag library
<compositionRender/> <pageRender/>, but no corresponding attributes are available
<wps:captureContent/> none
<wps:componentRender/> <wps:layoutNodeRender/>
<wps:date/> use JSTL equivalent
<wps:time/> use JSTL equivalent
<wps:text/> use JSTL equivalent
<wps:popupMenu/> moved to portal-wml.tld tag library
<wps:popupMenuItem/> moved to portal-wml.tld tag library
<wps:popupMenuParam/> moved to portal-wml.tld tag library
<wps:popupMenuTemplate/> moved to portal-wml.tld tag library
<wps:urlGeneration/> Same tag, but pacCheck attribute deprecated and replaced by accessControlCheck
<wps:width/> no direct replacement, although <wps:layoutNodeProperty propertyName="width"/> could be used

The following new tags are introduced in the portal.tld tag library for WebSphere Portal V5.1.

 

Compatibility between tag libraries

During migration, it is possible to mix the use of tags from the engine tag library and the portal tag library in your themes, screens, and skins.

  • The <wps:compositionRender/> tag in a screen invoked from a portal.tld theme behaves like a <wps:pageRender/> tag.
  • The <wps:pageRender/> tag in a screen invoked from an engine.tld theme behaves like the <wps:compositionRender/> tag.

In the case that you have custom themes and skins that include some of the common JSPs provided by WebSphere Portal, use both tag libraries in the following circumstances.

  • Head.jsp uses the <wps:stateBase/> tag from the portal tag library. If your custom theme does not include a customized Head.jsp, update Head.jsp as follows.

    1. Import the tag library: 
       <%@ taglib uri="/WEB-INF/tld/portal.tld" prefix="wps-fix" %>

    2. Change the prefix of the <wps:stateBase/> tag to match the new taglib. 
       <wps-fix:stateBase/>

  • PlaceBarInclude.jsp uses the <wps:closePage/> tag from the portal tag library. If your custom theme does not include a customized PlaceBarInclude.jsp, update PlaceBarInclude.jsp as follows.

    1. Import the tag library: 
       <%@ taglib uri="/WEB-INF/tld/portal.tld" prefix="wps-fix" %>

    2. Change the prefix of the <wps:closePage/> tag to match the new taglib. 
       <wps-fix:closePage>
  ...
 </wps-fix:closePage>

  • AdminLinkBarInclude.jsp uses the <wps:adminNavHelper/> tag from the portal internal tag library (portal-internal.tld). This tag must be present in all JSPs used by administrative themes and portlets. For any customized versions of AdminLinkBarInclude.jsp, make sure you have the following tag library and tag at the beginning of the file. 
     <%@ taglib uri="/WEB-INF/tld/portal-internal.tld" prefix="wps-internal" %>                              
 <wps-internal:adminNavHelper/>

Even though JSPs from different tag libraries can be mixed, this is only to support backward compatibility during migration. New themes, screens, and skins should be developed using the <wps:pageRender/> tag and the portal.tld.

 

Suggested migration steps

Before performing any migration steps for themes and skins, read Designing your portal to get a good understanding of how the portal page is built in WebSphere Portal V5.0.x. It is especially important that you understand how the startLevel and stopLevel attributes on the <wps:navigation/> tags work. This is explained in Working with portal navigation.

If your existing portal site has custom themes and skins based on WebSphere Portal V4.x, follow these steps to migrate them to WebSphere Portal V5.1.

  1. Install and configure WebSphere Portal V5.1, if you have not already done so. Refer to Install for instructions. Verify that WebSphere Portal V5.1 is installed and operating successfully.

  2. Copy customized themes and skins from directory <wp4_root>/app/wps.ear/wps.war on WebSphere Portal V4.x to the <was5_root>/installedApps/<node_name>/wps.ear/wps.war directory on the WebSphere Portal V5.1 system, where <node_name> is the name of the WebSphere Portal V5.1 node.

  3. Themes and skins that were copied in the previous step need to be upgraded before they can be used on WebSphere Portal V5.1. Update the JSPs that are used by themes and skins. Review the Updates to engine tags section here to determine what has changed and how to accommodate the changes in your JSPs. See also Tags used by the portal JSPs for complete descriptions of all new and changed tags.

  4. Update style sheets (themes only) by adding the new classes that have been introduced. Classes that are introduced with each release are identified in the style sheets:

    • Classes that were added in V4.2 have the comment, New in v4.2.

    • Classes that were added in V5.0.x have the comment, New in v5.

    • Classes that were added in V5.1 have the comment, New in v5.1.

    Complete the following steps to update the style sheets with the new classes:

    1. Copy these new classes from one of the WebSphere Portal V5.1 theme style sheets to the style sheet of each of your themes.

    2. Modify the classes to match the look of your themes.

  5. Add the upgraded themes and skins to WebSphere Portal V5.1 using the Manage themes and skins portlet in Portal Administration.

  6. Add your customized skins to the themes.

  7. Use the Page Customizer to create a root page to use for testing themes and skins. Do not assign the customized themes to any of the installed pages (Home, Portal Administration, and so on) at this point.

  8. Assign a customized theme to the new page.

  9. Add some portlets to the page and assign one or more customized skins to the portlets.

  10. Navigate to the new page to test the new themes and skins.

  11. Repeat Steps 8 through 10 as needed for each of your customized themes and skins that were added in Step 5.

 

Migrate custom portlet code

The following list describes the changes to the Portlet API since WebSphere Portal V4.1. Use this as a reference when updating portlet source code for WebSphere Portal V5.0.x. Deprecated APIs will continue to work in WebSphere Portal V5.1; however, it is recommended that alternatives be used as soon as possible.

The portlet.tld file is a common resource that should not be bundled with the portlet WAR file. If present, this file must be removed from any portlet WAR file prior to installation on WebSphere Portal V5.0.x.

  • In V5.0.x, the <portletAPI:text/> tag has been deprecated in favor of the <fmt:bundle/> and <fmt:message/> tags from the Java Standard Tag Library. See Deprecated portlet JSP tags for details.

  • In V5.0, the WindowEvent and WindowListener interfaces were deprecated. Support for these interfaces is withdrawn completely in V5.1.

  • In V4.2, the PortletURI.addAction(PortletAction action) method was deprecated in favor of PortletURI.addAction(java.lang.String simpleAction). This change was made to support use of actions on WML phones and also to reduce session size. This change also affects the PortletAction and DefaultPortletAction objects, which have been deprecated.

  • In V4.2, the ActionEvent.getAction() method was deprecated in favor of the ActionEvent.getActionString() method. This change was made to support the use of browser back and refresh buttons.

  • In V4.2, the PortletSession.getUser() method was deprecated in favor of PortletRequest.getUser(). In Versions 5.0.x and 5.1, PortletSession.getUser() returns a null value.

  • In V4.2.1, multiple portlets within a portlet application are not allowed to point to the same servlet definition in the web.xml file. Each portlet must have a 1-1 relationship with a servlet definition, although each servlet definition might actually point to the same servlet code.

  • Originally, WebSphere Portal provided the portal user's ID and password to portlets through the user's Java Authentication and Authorization Service subject to support single signon. This functionality was deprecated in WebSphere Portal V4 in favor of using the credential vault service for single signon. Using the JAAS Subject to obtain the user's credentials was not always reliable, and support for this method has been removed in WebSphere Portal V5. For WebSphere Portal V5.0.x, portlets that are written to use the JAAS Subject to access the user's credentials must be updated to use the credential vault service instead.

  • In V4.1.2, the PortletResponse.encodeURL() method that is used by JSPs to access content in the WAR file returned fully qualified URLs, for example: http://<hostname.setgetweb.com>/wps/portal/.../button.gif

    In V4.1.3a, this method was changed to return the relative URL of the content, for example: 

    /wps/portal/.../button.gif

    This change was made to support SSL by allowing the configured protocol (for example, HTTPS) to be used in the URL.

  • Portlet classes and interfaces from the following packages have been deprecated in Versions 5.0.x and 5.1.

  • In previous versions of WebSphere Portal, the method com.ibm.wps.portletservices.CredentialVaultService.getDefaultUserVaultSegmentId() returned com.ibm.wps.util.ObjectId. In V5.1, this method was changed to return com.ibm.portal.ObjectId. Therefore, you have to change the import statement from com.ibm.wps.util.ObjectId to com.ibm.portal.ObjectId. This API change was necessary due to portlet API compatibility.

 

Migrate Click-to-Action portlets

The Click-to-Action functionality that is provided in WebSphere Portal V4.2 has been expanded to give developers more control over how their portlets share information, or properties. All portlets on a page that send or receive properties using the property broker are called cooperative portlets. Click-to-Action is a term that describes how portlets can provide a pop-up menu to allow users to designate how they want properties to be transferred on the page. Click-to-Action is a subset of the framework behind cooperative portlets, which is handled by the property broker run time.

The behavior of output parameters has changed from WebSphere Portal V4.x to WebSphere Portal V5.0.x. Output parameters will not be automatically propagated unless they have been explicitly wired to input parameters of other portlets. Apart from the output parameter behavior change, all previous functionality will work as before without source code changes. To use new functionality that is introduced in WebSphere Portal V5.0.x, source code changes might be required. See the section on Cooperative portlets for details about how to adjust your portlets for these changes.

Follow these steps to migrate Click-to-Action portlets:

  1. Locate the pbportlet.jar file. The default location for this file is <wp_root>/pb/lib.

  2. Copy the file to the WEB-INF/lib directory in the WAR file of each Click-to-Action portlet application that is developed for WebSphere Portal V4.x. This will overwrite the previous version of pbportlet.jar from WebSphere Portal V4. If you had moved the WebSphere Portal V 4.0 version of pbportlet.jar to another location in the WAR file or renamed it, remove it in order to avoid classloading conflicts.

  3. Redeploy or update the WAR file in the portal server.

  4. To verify successful migration of Click-to-Action portlet applications, complete the following steps:

    • After completing the migration steps, place the migrated portlets on a page. Click-to-Action should work as expected, with clickable icons appearing next to properties that can be transferred to other portlets. A pop-up menu allowing an action to be chosen should appear when an icon is clicked, and the target portlet should react in the expected manner. The default look and feel of the icon and the menu are slightly different in WebSphere Portal V5.0.x than in WebSphere Portal V4.0.

    • The behavior of output parameters has changed in WebSphere Portal V5.0.x. If your application was using output parameters to automatically transfer data to other portlets, this behavior will be different until a wire is created. See the section on Cooperative portlets for details.

 

Migrate portlets built with the Struts Portlet Framework

The Struts Portlet Framework is designed to allow users to package Struts applications that can be deployed on multiple versions of WebSphere Portal. The steps for migration depend on the Struts Portlet Framework version. More information is available for migrating Struts applications, including servlet-based Struts and non-JSR 168 portlets, in Migrate existing Struts applications.

 

Determine the version of the Struts Portlet Framework

The version.txt file in the dev/struts directory allows you to determine the version of the Struts Portlet Framework and the version of Jakarta Struts that is integrated in the package.

If you are if you are migrating Struts Portlet Framework from a previous version of WebSphere Portal, you will need a was.policy file to complete the migration. See Using Java 2 security with WebSphere Portal for more information.

Here is a list of the Struts Portlet Framework versions:

  1. WebSphere Portal V4.2

    1. Struts Portlet Framework : V4.2

    2. Struts release : Struts 1.1 Beta 2

  2. WebSphere Portal 4.2.1

    1. Struts Portlet Framework : V4.2.1

    2. Struts release : Struts 1.1 RC 1

  3. WebSphere Portal V5.0.x

    1. Struts Portlet Framework : V5.0.x

    2. Struts release : Struts 1.1

  4. Portlet Catalog

    1. Struts Portlet Framework : V4.1.5

    2. Struts release : Struts 1.1 RC 1

  5. Portlet Catalog

    1. Struts Portlet Framework : V5.0.3

    2. Struts release : Struts 1.1

 

Migrate from Struts Portlet Framework with Struts 1.1 Beta 2

The Struts Portlet Framework now includes Struts 1.1.0. There are several changes in Struts 1.1.0 that can affect Struts applications that were written using previous versions of the Struts Portlet Framework.

  1. The Portlet Deployment Descriptor should be checked to see if the Struts Filter chain is specified. If the following lines are specified in the portlet.xml file they should be removed. The filter chain is no longer required, unless the portlet needs to run on a portal earlier than V5.1 and the portlet needs to serve static content.

    <config-param>

    <param-name>FilterChain</param-name>

    <param-value>StrutsTranscoding</param-value>

    </config-param>

  2. Unzip the SPFLegacyBlank.war file located in the <wp_root> /installableApps directory. This is an actual Struts application so the directory structure is similar to many Struts applications. Copy the following JAR files in the WEB-INF/lib directory from the SPFLegacyBlank.war to the WEB-INF/lib directory of the Struts application:

    • commons-beanutils.jar

    • commons-collections.jar

    • commons-digester.jar

    • commons-fileupload.jar

    • commons-lang.jar

    • commons-validator.jar

    • jakarta-oro.jar

    • PortalStruts.jar (Struts Portlet Framework)

    • PortalStrutsCommon.jar (Struts Portlet Framework)

    • PortalStrutsTags.jar (Struts Portlet Framework - new)

    • struts.jar

    • StrutsUpdateForPortal.jar (Struts Portlet Framework)

    • wp.struts-commons-logging.jar

  3. Remove the following files from the WEB-INF/lib directory:

    • commons-services.jar

    • jdbc2_0-stdext.jar

    • commons-dpcp.jar

    • commons-pool.jar

    • commons-resources.jar

    • commons-logging.jar

  4. Update the TLD files. The location of the TLD varies from application to application. Use the tag location element in the Web deployment descriptor to determine the location of the TLD files in your application. Update the TLDs with the versions from the WEB-INF/tld directory of the SPFLegacyBlank.war.

  5. Remove the previous TLD files that were in the WEB-INF directory. Note that the location of the TLDs has changed; they are now in the WEB-INF/tld directory. The TLD files that ship with the Struts Portlet Framework and should be used in the Struts application are listed here.

    • 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

  6. Remove the ForwardAction class when migrating to the current release. The ForwardAction class can be found in the WEB-INF/classes/org/apache/struts/actions directory. Struts also ships an IncludeAction class. The Struts implementation of IncludeAction writes directly to the response object; this behavior is not supported for an action in WebSphere Portal, so it is also suggested that you use ForwardAction instead of IncludeAction.

    1. Copy the org.apache.commons.logging.LogFactory file to the META-INF/services directory of the application. This release of the Struts Portlet Framework specifies the commons logger through the services directory. The commons logger can also be specified in the commons-logging.properties file, but the services directory is the suggested way.

  7. Create the new WAR file and deploy the Struts application in WebSphere Portal.

  8. Struts 1.1 has changed the name of subapplications to modules after the Beta 2 release. This change led to the renaming of the ApplicationConfig class to ModuleConfig. Some tags and actions might use ModuleConfig to determine the current module prefix. The Struts application code should be checked to see if the ApplicationConfig object was used, and if so it should be migrated to 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);

    You can obtain additional information about the ModuleConfig class from the Jakarta Web site.

    The name change of SubApplication to Module also caused the name change of an init-parameter supported by the Struts Portlet Framework. The Struts Portlet Framework supports customization through the specification of init-parameters in the Web deployment descriptor. Previous versions of the Struts Portlet Framework supported an init-parameter named SubApplicationSearchPath. For the Struts Portlet Framework to be consistent with Struts 1.1.0, the SubApplicationSeachPath init-parameter has been renamed ModuleSearchParameter. The SubApplicationSearchPath init-parameter continues to be supported, but is expected to be deprecated in a future release. If both the SubApplicationSearchPath and ModuleSearchPath parameters are specified as init-parameters in the Web deployment descriptor, then the ModuleSearchPath value will be used.

    For example, if the Struts application had the following init-parameter in the Web deployment descriptor:

    <init-param>

    <param-name>SubApplicationSearchPath</param-name>

    <param-value>markupName,mode</param-value>

    </init-param>

    it would be replaced with the following data:

    <init-param>

    <param-name>ModuleSearchPath</param-name>

    <param-value>markupName,mode</param-value>

    </init-param>

 

Migrate from Struts Portlet Framework with Struts 1.1 RC 1

The Struts Portlet Framework that was released with WebSphere Portal 4.2.1 and downloads from the Portal Catalog for WebSphere Portal V4.1 includes Struts 1.1 RC 1.

  1. The Portlet Deployment Descriptor should be checked for these applications to verify that the Struts Filter chain is specified. The following lines should be in the portlet.xml file:

    <config-param>

    <param-name>FilterChain</param-name>

    <param-value>StrutsTranscoding</param-value>

    </config-param>

    The filter chain is used to implement solutions for some of the differences between the versions of WebSphere Portal.

  2. The Struts application must be migrated to the newer version of the Struts Portlet Framework. Unzip the SPFStandardBlank.war file that is located in the <wp_root> /installableApps directory. This is an actual Struts application so the directory structure is similar to many Struts applications. Copy the following JAR files in the WEB-INF/lib directory from the SPFStandardBlank.war to the WEB-INF/lib directory of the Struts application:

    • commons-beanutils.jar

    • commons-collections.jar

    • commons-digester.jar

    • commons-fileupload.jar

    • commons-lang.jar

    • commons-validator.jar

    • jakarta-oro.jar

    • PortalStruts.jar (Struts Portlet Framework)

    • PortalStrutsCommon.jar (Struts Portlet Framework)

    • PortalStrutsTags.jar (Struts Portlet Framework - new)

    • struts.jar

    • StrutsUpdateForPortal.jar (Struts Portlet Framework)

    • wp.struts-commons-logging.jar

  3. Remove the following files from the WEB-INF/lib directory:

    • commons-services.jar

    • jdbc2_0-stdext.jar

    • commons-dpcp.jar

    • commons-pool.jar

    • commons-resources.jar

    • commons-logging.jar

  4. Update the TLD files. The location of the TLD varies from application to application. Use the tag location element in the Web deployment descriptor to determine the location of the TLD files in your application. Update the TLDs with the versions from the WEB-INF/tld directory of the SPFStandardBlank.war.

  5. Remove the previous TLD files that were in the WEB-INF directory. Note that the location of the TLDs has changed; they are now in the WEB-INF/tld directory. The TLD files that ship with the Struts Portlet Framework and should be used in the Struts application are listed here.

    • 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

  6. Remove the ForwardAction class when migrating to the current release. The ForwardAction class can be found in the WEB-INF/classes/org/apache/struts/actions directory. Struts also ships an IncludeAction class. The Struts implementation of IncludeAction writes directly to the response object; this behavior is not supported for an action in WebSphere Portal, so it is also suggested that you use ForwardAction instead of the IncludeAction.

  7. Copy the org.apache.commons.logging.LogFactory file to the META-INF/services directory of the application. This release of the Struts Portlet Framework specifies the commons logger through the services directory. The commons logger can also be specified in the commons-logging.properties file, but the services directory is the suggested way.

  8. Create the new WAR file and deploy the Struts application in WebSphere Portal.

For additional information, see Migrate existing Struts applications.

 

Migrate collaborative portlets

If you plan to use an older version of the Lotus Instant Messaging and Web Conferencing Contact List portlet (from WebSphere Portal V4.2.1 or older) in a WebSphere Portal V5.1 environment, make sure that the hostAddress.xml file is made available to this portlet.

  • Before upgrading, locate the file in the /peopleawareness directory and keep a copy.

  • After installing, copy the file to the same directory in the 5.1 installation.

  • Edit the file and verify the Lotus Instant Messaging and Web Conferencing server name that is specified matches the one that is specified in the CSEnvironment.properties file in the WebSphere Portal V5.1 installation.

 

Transcoding Technology migration

The Transcoding Technology supports preference profiles (device and user), plug-ins, annotators, and style sheet resources that allow it to make Web-based information available to users of handheld and other pervasive devices. Refer to What is Transcoding Technology for more information.

If you have not used or made any customizations to these resources using the Transcoding Technology, you can skip this section.

The Transcoding Technology supplies scripts that can be used to create XML-based definition of transcoding resources. These scripts will be used to accomplish the migration. The Transcoding device profiles provide additional functional enhancements to help select the most appropriate WebSphere Portal client based on the request parameters. If you have created additional device profiles or updated existing ones, use the following steps to migrate these changes to WebSphere Portal V5.1.

  1. Change your working directory to where Transcoding Technology was installed in your WebSphere Portal V4.x environment. Depending on your operating system, the path will be:

       Windows: C:\Program Files\IBMTrans

       UNIX: /opt/IBMTrans

       AIX: /usr/IBMTrans

  2. Invoke the following command to export device profile configuration information from Transcoding:

       Windows: ExportResources.bat -ResourceType device -FileName devices.xml

       UNIX: ./ExportResources.sh -ResourceType device -FileName devices.xml

  3. Copy the file that was exported in Step 2 to the directory where Transcoding is installed for WebSphere Portal V5.1. In WebSphere Portal V5.1, Transcoding Technology is always installed under <wp51_root>/IBMTrans, where <wp51_root> is the root installation directory of WebSphere Portal V5.1.

  4. Change your working directory to <wp51_root>/IBMTrans.

  5. Invoke the following command to import device profile configuration information, to the Transcoding in WebSphere Portal V5.1:

       Windows: C:\ImportResources.bat -ResourceType device -FileName devices.xml

       UNIX: ./ImportResources.sh -ResourceType device -FileName devices.xml

    If you have also modified other transcoding resources in WebSphere Portal V4.0, repeat these steps for each of these resources, replacing device in steps 2 and 5 with the appropriate value for the other resources. Valid values for the -ResourceType arguments are device, plugin, stylesheet, annotator, and user. Refer to Using XML configuration for special considerations when migrating plug-in, style sheet, annotator resources, and any other additional information.

 

Verifying updated portlets

It is important to verify that the portlets you have migrated work correctly on WebSphere Portal. Use Rational Application Developer on your V5.1 system to verify that the updated portlets are functioning properly. You could also verify that the portlets are functioning correctly on a WebSphere Portal V5.1 development environment before deploying them to your production environment. Specific verification steps are listed in the Verifying the migration tasks section, which refer to as you are running the migration tasks.

 

Next steps

You have completed this step. Continue to the next step by choosing the following topic:

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

Rational is a trademark of the IBM Corporation in the United States, other countries, or both.