IBM Rational Web Developer for Windows and Linux, Version 6.0 Migration Guide


Contents

Chapter 1. Migrating from WebSphere Studio V5.1, 5.1.1, or 5.1.2

  • Compatibility with WebSphere Studio V5.1.x
  • Disabling compatibility with WebSphere Studio V5.1.x
  • Updating Faces runtime resources in a Web project
  • Updating Faces Client runtime resources in a Web project
  • Migrating Struts Web projects
  • Debugger changes in V6.0
  • WDO to SDO migration
  • EGL reserved words in V6.0
  • Chapter 2. Updating Faces runtime resources for Web projects from Rational Web Developer V6.0

    Chapter 3. Migrating J2EE projects

  • Migrating secure Web services
  • J2EE 1.3 to 1.4 specification level migration
  • Web projects (Servlet level 2.3 to Servlet level 2.4)
  • Connector projects (JCA 1.0 to JCA 1.5)
  • Web services (J2EE 1.3 to J2EE 1.4)
  • J2EE 1.2 to 1.4 specification level migration
  • Web projects (Servlet level 2.2 to Servlet level 2.4)
  • Changes in the J2EE Migration Wizard in Rational Web Developer V6.0
  • Chapter 4. Changes in WebSphere test environments



    Chapter 1. Migrating from WebSphere Studio V5.1, 5.1.1, or 5.1.2

    This documentation provides instructions for migrating from WebSphere(R) Studio Site Developer V5.1.x to Rational(R) Web Developer V6.0.

    Additional information can be found on the following topics:

    Information about using Rational Web Developer can be found in the online help.

    Refer to www.ibm.com/developerworks/rational for updated documentation.

    For information on migrating from prior versions of WebSphere Studio to v5.x or migrating from VisualAge(R) for Java(TM) to WebSphere Studio, go to www.ibm.com/software/awdtools/studioappdev/support/ and search for "migration guide".

    To migrate from WebSphere Studio V5.1.x:

    1. Before installing, read about compatibility with Eclipse V2.x and WebSphere Studio V5.1.x. Note that backward compatibility is not supported for portlet application projects migrated from Portal Toolkit V5.0.2.2 with WebSphere Studio V5.1.2.
    2. Back up your WebSphere Studio V5.1.x workspace.
    3. Install Rational Web Developer. Refer to the Installation Guide (install.html file) which is available at the root of the first product CD.
    4. Recommended: By default, the first time you start Rational Web Developer, you are prompted to confirm that you want to use a workspace called rationalsdp6.0\workspace. That is, the Workspace Launcher dialog box points to a directory that is not your WebSphere Studio workspace. To explore the new environment before migrating your old workspace, accept the default or specify some other new directory name when you start Rational Web Developer. You might do this, for example, so you can create one or two test projects, read about what's new (Help -> Welcome), do some of the new tutorials (Help -> Tutorials Gallery), or experiment with some of the new samples (Help -> Samples Gallery).
    5. Migrate your projects to V6.0. Projects created in WebSphere Studio V5.1.x can be automatically migrated to V6.0 as follows:
      1. Migrating a workspace: When you are ready to migrate your V5.1.x workspace for good, start Rational Web Developer with your old workspace. A progress indicator confirms that your projects are being automatically migrated.

        Notes: During workspace migration a Problems dialog box opens with the message Could not restore workbench layout. Reason: Problems occurred restoring workbench. The error messages have no impact on the successful migration of the workspace. Note the name of perspective that could not be restored by clicking the Details button in the error dialog box, then click OK to close the dialog box.

        To restore the perspective:

        1. Close the perspective by selecting Window -> Close Perspective
        2. Reopen the perspective by selecting Window -> Open Perspective.
        Note:
        For Enterprise Generation Language (EGL) projects that used EGL Web perspective in WebSphere Studio V5.1.2: this perspective has been removed in Rational Web Developer V6.0. All EGL projects are safely migrated without this perspective in Rational Web Developer V6.0. Do the following if you used the EGL Web perspective:
        1. Close the EGL Web perspective.
        2. Enable EGL capabilities in the Preferences (Window -> Preferences). Refer to the online help for details on enabling EGL capabilities.
        3. Select Window -> Open Perspective and choose the Web perspective.
      2. Migrating projects loaded from a SCM (source code management) system: Projects from WebSphere Studio 5.1.x that exist in a SCM system are automatically migrated to V6.0 when they are loaded into Rational Web Developer.
      3. Migrating projects imported using Project Interchange: Projects exported from WebSphere Studio V5.1.2 or V5.1.1 and imported into Rational Web Developer V6.0 using the Project Interchange feature are automatically migrated to V6.0. The Project Interchange feature was available in WebSphere Studio V5.1.2 and was an optional plug-in for V5.1.1.

      Notes:

      Important:

    6. The DB2(R) Net JDBC Driver is not supported in Rational Web Developer V6.0. If you created JDBC connections using the DB2 Net JDBC Driver, you will not be able to reconnect in Rational Web Developer V6.0. You will need to change the connection to use one of the supported JDBC drivers. Refer to the online help for more information on the JDBC drivers supported in V6.0.
    7. If you have Web or XML file content migrated from WebSphere Studio Site Developer V5.1.x that used the Shift_JIS character set and included vendor selected characters, you must specify the Windows-31J character set instead.
    8. If you installed any vendor plug-ins with WebSphere Studio Site Developer V5.1.x, you need to get the corresponding plug-ins for V6.0 and reinstall them.
    9. If you use features that require Agent Controller, upgrade it by installing the version provided with Rational Web Developer. For details, refer to the installation guide.
    10. To migrate from VisualAge Generator, consult the VisualAge Generator to Enterprise Generation Language (EGL) Migration Guide that is available in PDF format in the "Installing and migrating" section of the online help under the help topic "Accessing the VisualAge Generator to EGL Migration Guide." The most recent copy can be obtained from http://www.ibm.com/developerworks/rational/library/egldoc.html.

    Compatibility with WebSphere Studio V5.1.x

    When you first open any WebSphere Studio V5.1.x workspace in Rational Web Developer, it is automatically migrated. Once you have migrated a workspace, you can no longer open it in WebSphere Studio Site Developer. However, the projects in the V6.0 workspace can still be shared with WebSphere Studio V5.1.x, either by using a source code management (SCM) system (such as Rational ClearCase(R)), by importing and exporting the project using Project Interchange, or through importing archives and exporting projects. Important: portlet applications from Portal Toolkit V5.0.2.2 that are migrated to Portal Tools in Rational Web Developer V6.0 will not be backward compatible.

    Note:
    The following does not apply to portlet application projects.

    Existing V5.1.x projects that are loaded into V6.0 from a SCM system or another developer using Project Interchange will be compatible for sharing with V5.1.x provided you do not take any the following actions:

    A .compatibility file is automatically created in the project directory when a V5.1.x project is opened in the Rational Web Developer V6.0 workspace. The .compatibility file is used by Rational Web Developer to track the timestamps of project resources when these resources are migrated. You should not edit or delete it.

    For information on disabling compatibility with WebSphere Studio Site Developer V5.1.x, refer to Disabling compatibility with WebSphere Studio V5.1.x.

    Eclipse considerations

    This version of Rational Web Developer is based on Eclipse V3.0. If you develop your own plug-ins, you should read about changes to the platform before migrating.

    For details, refer to the readme file in the sub-directory eclipse\readme of the installation location of Rational Web Developer V6.0. The sections of the readme file that are of interest for migration are:

    J2EE project compatibility

    Compatibility of projects created in WebSphere Studio V5.1.x with Rational Web Developer V6.0 is enabled by means of metadata that is automatically added to .project files when you migrate your V5.1.x workspace. Similarly, if you create a new J2EE 1.2 or 1.3 module or application in Rational Web Developer V6.0, build metadata is automatically added to the .project file for compatibility with V5.1.x. Do not edit or delete this information directly.

    Note:
    This compatibility metadata will cause messages about "missing builders" to be displayed or logged when a new J2EE 1.2 and J2EE 1.3 module or application created in V6.0 is used in WebSphere Studio Site Developer V5.1.x where the V6.0 builders are not available. These messages are normal; you can ignore them.

    As long as this compatibility metadata is present, you will messages about "missing builders" when Rational Web Developer V6.0 projects are loaded back in WebSphere Studio V5.1.x. The following is an example of a "missing builder" message:

    !ENTRY org.eclipse.core.resources 2 1 Sep 06, 2004 19:55:20.592
    !MESSAGE Skipping builder com.ibm.wtp.j2ee.LibCopyBuilder for project Test60EARWeb. 
    Either the builder is missing from the install, or it belongs to a project nature that is missing or disabled.
    

    These messages are normal; you can ignore them. When you are sure you no longer need to work with a given project in WebSphere Studio V5.1.x, you can stop the messages by disabling backward compatibility for that project.

    Important: New J2EE 1.2 or 1.3 specification projects created in V6.0 are compatible with WebSphere Studio V5.1.x, but once the project is loaded into WebSphere Studio there are some manual steps that are required before you can work with the project. These steps are required because runtime targets on new J2EE 1.2 or 1.3 specification projects created in 6.0 are not directly backward compatible to target servers in V5.1.x. The manual steps after loading a new V6.0 project in V5.1.x are as follows:

    1. Open the .classpath file for each J2EE project that has a .classpath file.
    2. Delete the following classpath entries from the .classpath file and save and close the file.
    3. Make sure server targeting support is enabled in the J2EE preferences page. Select Window -> Preferences -> J2EE and confirm that Enable server targeting support is selected under "Server Targeting Support."
    4. Right click on the project and select Properties -> J2EE.
    5. Select the corresponding target server for the runtime target on the project (for example, WebSphere Application Server V5.1 using the JDK 1.4 runtime environment) and click OK.
    6. The target server you selected will be compatible for both Rational Web Developer V6.0 and WebSphere Studio Site Developer V5.1.x. After the changes are committed into the SCM system, the J2EE projects are interoperable between V5.1.x and V6.0 using a SCM system.
      Note:
      If the target server is set again in Rational Web Developer V6.0, J2EE project compatibility will be lost and will need to be reestablished.

    Disabling compatibility with WebSphere Studio V5.1.x

    Compatibility with WebSphere Studio Site Developer V5.1.x can be totally removed from an enterprise application project created in Rational Web Developer V6.0 or an enterprise application project migrated from an earlier version of WebSphere Studio. You should disable compatibility with WebSphere Studio V5.1.x only if you are certain that the enterprise application project should no longer be either interoperable or compatible with V5.1.x.

    To remove compatibility with WebSphere Studio Site Developer V5.1.x:

    1. Right-click on an enterprise application project and select the Remove Compatibility menu option from the pop up.
    2. A dialog box asks for confirmation to remove the backward compatibility of the enterprise application project and all the modules and utility projects nested under the project.
    3. Click Yes to continue with the Remove Compatibility operation.

    Once the Remove Compatibility operation is run, the enterprise application project and all the module and utility projects nested under the enterprise application project are no longer backward compatible with WebSphere Studio Site Developer V5.1.x.


    Updating Faces runtime resources in a Web project

    The JavaServer Faces runtime resources that originally shipped in WebSphere Studio Site Developer V5.1.x have been updated for Rational Web Developer V6.0.1. If you want to continue development on Web projects that were created with this previous product version, it is recommended that you update the Faces runtime resources to the latest levels.

    In Rational Web Developer V6.0.1, the Faces runtime resource updates happen automatically when a Web project is imported or a workspace is opened that contains out-of-date resources. After importing a Web project or opening a workspace from WebSphere Studio Site Developer V5.1.x to Rational Web Developer V6.0.1, you will be prompted to update the Faces runtime resources to the latest levels.

    Automatically updating runtime resources

    To update the Faces runtime resources automatically for a Web project:

    1. Import a Web project (or a workspace) containing Faces content from WebSphere Studio Site Developer V5.1.x. The Project Migration window opens.
      Note:
      If the Project Migration window does not open, your automatic build preference setting is probably disabled. In Project Explorer, right-click your Web project and select Build -> Project; the process of rebuilding a project opens the Project Migration window.
    2. If you have other Web projects with Faces content in your workspace, check Apply this choice to any other projects that need to be upgraded and all your Web projects will be updated.
    3. Click one of the following:
    Note:
    If you created Faces JSPs that contained Faces Client components, you must separately update the Faces Client components runtime resources to the latest levels. Refer to Updating Faces Client runtime resources in a Web project.

    Manually updating runtime resources

    To update the Faces runtime resources manually for a Web project:

    1. Import your existing Web project with Faces content into a Rational Web Developer V6.0.1 workspace.
    2. Create a new Web project (or, if you are working with EGL, create a new EGL Web project) named JSF601. You will use this project only as a source for the latest runtime resources; it can be deleted after the update is complete.
    3. In the Project Explorer, right-click on the JSF601 project and select Properties from the menu.
    4. Click Web Project Features and select Add Faces Base Components and Add Faces Client Framework, then click OK.
    5. If you are working with EGL, create a JSF page file as follows:
      1. Right-click the WebContent folder of your new EGL Web project.
      2. Select New -> Other -> Faces JSP File.
      The eglintdebug.jar and eglintdebugsupport.jar files are added to your project.
    6. For each existing Faces project that you want to update, do the following:
      1. In Project Explorer, expand an existing project to show the files in the WebContent/WEB-INF/lib/ folder. Locate and delete any of the following JAR files in this directory:
        • eglintdebug.jar (EGL only)
        • eglintdebugsupport.jar (EGL only)
        • fda.jar (EGL only)
        • fdaj.jar (EGL only)
        • jsf-api.jar
        • jsf-ibm.jar
        • jsf-impl.jar
        • odc-jsf.jar
      2. Locate and open the file WebContent/WEB-INF/faces-config.xml. Add the following elements into this configuration file if they are not already present:
        	<lifecycle>
        		<phase-listener>com.ibm.faces.webapp.ValueResourcePhaseListener</phase-listener>
        	</lifecycle>
        	
        	<application>
        		<variable-resolver>com.ibm.faces.databind.SelectItemsVarResolver</variable-resolver>
        		<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
        	</application>
        
      3. For any JAR files that you deleted, copy the JAR file of the same name from the WebContent/WEB-INF/lib directory of the JSF601 project and paste it into your original project in the same location. Some configurations will not require all of these JAR files to be present in the project; do not copy a particular JAR file if it was not in the original project.
      4. Open the web.xml deployment descriptor in the original project and add the following to the configuration:
        	<context-param>
        		<param-name>com.ibm.ws.jsf.JSP_UPDATE_CHECK</param-name>
        		<param-value>true</param-value>
        	</context-param>
        	<context-param>
        		<param-name>com.ibm.ws.jsf.LOAD_FACES_CONFIG_AT_STARTUP</param-name>
        		<param-value>true</param-value>
        	</context-param>
        
      5. If your original project used WebSphere Data Objects (WDO) for any data access, do the following additional steps:
        1. In your original project, click File -> New -> Faces JSP File to create a new temporary Faces JSP file.
        2. Drag a relational record list component from the Data drawer on the palette to the page.
        3. Pick any connection and data source and click Finish. The data selected is not important. This process will generate any necessary configuration to continue using WDO in this project.
        4. Delete the temporary JSP file.
      6. If you are working with EGL, right click on the name of each EGL Web project and click Generate; then, if you are not building the projects automatically, click Project -> Build All.
    7. Delete the JSF601 Web project.

    Updating Faces Client runtime resources in a Web project

    The JavaServer Faces Client runtime resources that originally shipped in WebSphere Studio Site Developer V5.1.x have been updated for Rational Web Developer V6.0.1. If you want to continue development on Web projects that were created with this previous product version, it is recommended that you update the Faces Client runtime resources to the latest levels.

    In Rational Web Developer V6.0.1, the Faces Client runtime resource updates happen automatically when a Web project is imported or a workspace is opened that contains out-of-date resources. After importing a Web project or opening a workspace from WebSphere Studio Site Developer V5.1.x to Rational Web Developer V6.0.1, you will be prompted to update the Faces Client runtime resources to the latest levels.

    Automatically updating runtime resources

    To update the Faces Client runtime resources automatically for a Web project:

    1. Import a Web project (or a workspace) containing Faces Client content from WebSphere Studio Site Developer V5.1.x. The Project Migration window opens.
      Note:
      If the Project Migration window does not open, your automatic build preference setting is probably disabled. In Project Explorer, right-click your Web project and select Build -> Project; the process of rebuilding a project opens the Project Migration window.
    2. If you have other Web projects with Faces Client content in your workspace, check Apply this choice to any other projects that need to be upgraded and all your Web projects will be updated.
    3. Click one of the following:
    4. From the Java Resources -> JavaSource folder in your Web project, delete all client data mediator class packages with the naming convention com.ibm.dynwdo4jsmediators.<client-data-name>. Do not delete the package named com.ibm.dynwdo4jsmediators. This package contains metadata (ecore and emap files) for the client data in your project that will be used to regenerate the mediators.
    5. From the Java Resources -> JavaSource folder in your Web project, open the OdysseyBrowserFramework.properties file and delete the entries for EMAP_FILES and ECORE_FILES.
    6. For each data object in the Client Data view:
      1. Right-click and select Configure.
      2. On the Advanced tab, click Regenerate from server-side data to regenerate all mediators for the data object.

    Manually updating runtime resources

    To update the Faces Client runtime resources manually for a Web project:

    1. Complete the Manually updating runtime resources steps in Updating Faces runtime resources in a Web project.
    2. Complete steps 4-6 of the Automatically updating runtime resources section above.

    Problems may occur when changing the target server of a project containing Faces Client components from WebSphere Application Server V5.1 to V6.0.

    There are two problems that may occur when changing the target server of a project containing Faces Client components from WebSphere Application Server V5.1 to V6.0:

    Upgrading to automated Diff handlers and processors

    Diff processors and handlers are now automatically generated. If you wrote Diff handlers and processors for your Faces Client components in WebSphere Studio V5.1.x, it is recommended that you discard that code and use the automatically generated processors and handlers:

    1. Generate the new Diff handlers and processors on each client data object in your Web project.
      1. Select the client data object, right-click and select Configure.
      2. On the Advanced tab, click Regenerate All.
    2. Remove the code you wrote to invoke your Diff processor and handlers since the generated processors and handlers are invoked automatically. A typical example of where this code was used would be for the Command event for the Command Button component, as such:
      String Diff = getClientData1().getDiffStr();
      if (DiffProcessor.Synch(getRoot(), Diff) == true)
       return "";
      return "failure";
      
    3. Remove the files corresponding to the old custom handlers and processors you created from your Web project.

    Keeping custom Diff handlers and processors written for V5.1.x

    Although this is not recommended, if you decide you need to keep your custom Diff handlers and processors from V5.1.x, they will need to be modified in order to work in V6.0, as the DiffHandler interface and DiffInfo class have changed.

    Changes to Faces Client components in V6.0


    Migrating Struts Web projects

    For Struts Web projects created in WebSphere Studio V5.1.x, you must make a small modification to the Web project's deployment descriptor in order to run the EAR project on WebSphere Application Server V6.0. You may also wish to manually convert existing Struts 1.0.2 or Struts 1.1 Beta (2 or 3) Web projects to Struts 1.1.

    Modifying the deployment descriptor of existing Struts Web Projects

    When a Struts project is created in WebSphere Studio v5.x, the config parameter (<param-name>config</param-name>) in the web project's deployment descriptor is set to WEB-INF/struts-config.xml. WebSphere Application Server V6.0 requires that a leading "/" be present in this parameter. If you run a Struts Web project that was created in WebSphere Studio V5.1.x on WebSphere Application Server V6.0, you may receive a java.net.MalformedURLException exception upon starting the EAR project.

    Note:
    Rational Web Developer V6.0 will add the "/" when a new Struts project is created; however, it must be added manually when migrating from WebSphere Studio V5.1x.

    Follow these steps to correct in V6.0 the deployment descriptor of a Struts Web project that was created in WebSphere Studio v5.1.x:

    1. Open the Struts Web project in the Project Explorer.
    2. Double-click the Web project's Web Deployment Descriptor file in the Project Explorer. The Web deployment descriptor editor opens.
    3. Click the Source tab to open the Source page.
    4. Change the line

      <param-value>WEB-INF/struts-config.xml</param-value> (this is located within the <servlet></servlet> tags)

      to

      <param-value>/WEB-INF/struts-config.xml</param-value> .

    5. Save the Web Deployment Descriptor

    The java.net.MalformedURLException exception should not occur when the EAR project is restarted.

    Converting Struts 1.1 Beta Web projects to Struts 1.1

    In WebSphere Studio V5.1.x, the Struts runtime library stepped up from Struts 1.1 Beta (2 or 3) in V5.0.x to Struts 1.1 (final). If you have existing Struts 1.1 Beta (2 or 3) Web projects and you want to convert them to Struts 1.1 (final), you may convert them manually. (Note: it is not required that you convert Struts 1.1 Beta (2 or 3) projects to Struts 1.1. )

    To convert Struts 1.1 Beta (2 or 3) projects to Struts 1.1, do the following:

    1. Load your Struts 1.1 Beta projects into a Rational Web Developer V6.0 workspace.
    2. Create a new Struts 1.1 Web project named, for example, Struts11. You create this temporary project in order to provide convenient access to the Struts 1.1 runtime files you will need while you are converting your real projects. You can delete this project when you are done.
    3. For each Struts 1.1 Beta project that you want to convert to Struts 1.1, do the following:
      1. Delete the following JAR files from your project's Web Content/WEB-INF/lib directory:
        • commons-*.jar.
        • struts.jar.
      2. Copy the following JAR files from Struts11/WebContent/WEB-INF/lib directory to your project's Web Content/WEB-INF/lib directory:
        • commons-*.jar.
        • struts.jar.
      3. Delete the following Tag Library Descriptor (TLD) files from your project's Web Content/WEB-INF directory: struts-*.tld.
      4. Copy the following TLD files from Struts11/WebContent/WEB-INF directory to your project's Web Content/WEB-INF directory: struts-*.tld.

    Converting Struts 1.0.2 Web projects to Struts 1.1

    In WebSphere Studio V5.1.x (and V5.0.x), when adding Struts support to a Web project you had the option to choose Struts 1.0.2. If you have existing Struts 1.0.2 Web projects and you want to convert them to Struts 1.1, you may convert them manually. (Note: it is not required that you convert Struts 1.1 Beta (2 or 3) projects to Struts 1.1. )

    To convert Struts 1.0.2 projects to Struts 1.1, do the following:

    1. Load your Struts 1.0.2 projects into a Rational Web Developer V6.0 workspace.
    2. Create a new Struts 1.1 Web project named, for example, Struts11. You create this temporary project in order to provide convenient access to the Struts 1.1 runtime files you will need while you are converting your real projects. You can delete this project when you are done.
    3. For each Struts 1.0.2 project that you want to convert to Struts 1.1, do the following:
      1. Delete the struts.jar file from your project's Web Content/WEB-INF/lib directory.
      2. Copy the following JAR files from the Struts11/WebContent/WEB-INF/lib directory to your project's Web Content/WEB-INF/lib directory:
        • commons-*.jar.
        • struts.jar.
        • jarkarta-oro.jar.
      3. Delete the following Tag Library Descriptor (TLD) files from your project's Web Content/WEB-INF directory: struts-*.tld.
      4. Copy the following TLD files from Struts11/WebContent/WEB-INF directory to your project's Web Content/WEB-INF directory: struts-*.tld.

    Debugger changes in V6.0

    There are a number of changes to the debugging tools in Rational Web Developer V6.0. You will need to be aware of these changes in order to use these tools with your projects following migration. You may need to change or restore settings.

    Migrating workspaces and launch configurations

    When a V5.1.x workspace from WebSphere Studio Site Developer is opened in Rational Web Developer V6.0, the following debugger launch configurations associated with the workspace will not automatically migrate:

    Debug views

    The Storage and Storage Mapping views no longer exist. They have been replaced by the Memory and Memory Rendering views.

    The XSLT debugger

    The XSLT debugger has changed in V6.0 and many of its views and actions have changed significantly. For further information, see the XSLT debugger documentation in the information center.

    One of the most significant changes in the XSLT debugger is its dependency on the JRE that is installed with Rational Web Developer V6.0. If you migrate a workspace from WebSphere Studio Site Developer V5.1.x, you will need to modify the installed JRE to point to the correct location before you can launch an XSLT debug session for it. To do this, you can perform one of the following actions:


    WDO to SDO migration

    If you created code in a Web project targeted at WebSphere Application Server V5.1 that used WebSphere Data Objects (WDO) relational records or relational record lists, when you target these applications to WebSphere Application Server V6.0 you will now use Service Data Objects (SDO) relational records and relational record lists. The migration from WDO to SDO happens automatically when you change the target server of your application from WebSphere Application Server V5.1 to WebSphere Application Server V6.0.

    The target server can be changed in two ways:

    Help topics on changing your target server and using the J2EE Migration Wizard can be found in the online help for Rational Web Developer.

    Compatibility considerations

    Type collision errors may occur following migration from WDO to SDO

    After a project utilizing WDO is migrated to an SDO-based project, if you add SDO data to an existing JSP page that has existing WDO data, type collision errors may occur. This arises due to the mixing of existing WDO access beans and stand-alone SDO APIs. For example, you may see a compilation error on the Java source file of the JSP similar to the following:

    The import com.ibm.websphere.sdo.mediator.exception.MediatorException collides with another imported type
    

    These type collision errors can be corrected as follows:

    1. Remove the colliding import statement from the Java source file. Using the example above, you would remove the following import statement from the source file:
      import com.ibm.websphere.wdo.mediator.exception.MediatorException;
      
    2. Modify the Java source file that references that type to use the fully qualified class name. Based on the example above, the type MediatorException must be changed to com.ibm.websphere.wdo.mediator.exception.MediatorException. For instance, source code written as
      catch ( MediatorException e1 ) {
      

      must be changed to

      catch ( com.ibm.websphere.wdo.mediator.exception.MediatorException e1 ) {
      

    Changes to a Web project after changing the target server from V5.1 to V6.0 (WDO to SDO)

    The following changes are made automatically when the target server is changed from V5.1 to V6.0:

    Changes to a Web project after changing the server target from V6.0 to V5.1 (SDO to WDO)

    The following changes are made automatically when the target server is changed from V6.0 to V5.1:

    Changes to a Web project after changing the J2EE level of your application from 1.3 to 1.4

    In addition to the changes that occur to migrate from WDO to SDO by changing the server target to WebSphere Application Server V6.0, changing the J2EE specification level of your application from 1.3 to 1.4 updates any tag library (taglib) references in your JavaServer Pages (JSPs) from using WDO, JSTL 1.0 tag libraries to SDO, JSTL 1.1/jsp 2.0 tag libraries. The following table shows the changes in the JSP taglib references when you move from J2EE 1.3 to J2EE 1.4.


    Table 1. JSP taglib references in J2EE 1.3 and J2EE 1.4.

    J2EE 1.3 taglib (WDO) J2EE 1.4 taglib (SDO)
    http://www.ibm.com/websphere/wdo/core http://www.ibm.com/websphere/sdo/core
    http://java.sun.com/jstl/core http://java.sun.com/jsp/jstl/core
    http://java.sun.com/jstl/fmt http://java.sun.com/jsp/jstl/fmt
    http://java.sun.com/jstl/xml http://java.sun.com/jsp/jstl/xml
    http://java.sun.com/jstl/sql http://java.sun.com/jsp/jstl/sql

    EGL reserved words in V6.0

    There are new reserved words in Enterprise Generation Language (EGL) in Rational Web Developer.

    The new reserved words are listed here:

    EGL programs from WebSphere Studio V5.1.x that are imported and built in a V6.0 workspace that use these words as variable or part names will be tagged with the following message:IWN.SYN.2002.e 39/2 Syntax error on input "variableName". You can correct the problem by renaming the variable.


    Chapter 2. Updating Faces runtime resources for Web projects from Rational Web Developer V6.0

    The JavaServer Faces and Faces Client runtime resources that originally shipped in Rational Web Developer V6.0 have been updated for Rational Web Developer V6.0.1. If you want to continue development on Web projects that were created with this previous product version, it is recommended that you update the Faces and Faces Client runtime resources to the latest levels.

    In Rational Web Developer V6.0.1, the Faces and Faces Client runtime resource updates happen automatically when a Web project is imported or a workspace is opened that contains out-of-date Faces or Faces Client runtime resources. After importing a Web project or opening a workspace from Rational Web Developer V6.0 to Rational Web Developer V6.0.1, you will be prompted to update these runtime resources to the latest levels.

    Automatically updating runtime resources

    To update the Faces and Faces Client runtime resources automatically for a Web project:

    1. Import a Web project (or a workspace) containing Faces or Faces Client content from Rational Web Developer V6.0. The Project Migration window opens.
      Note:
      If the Project Migration window does not open, your automatic build preference setting is probably disabled. In Project Explorer, right-click your Web project and select Build -> Project; the process of rebuilding a project opens the Project Migration window.
    2. If you have other Web projects with Faces or Faces Client content in your workspace, check Apply this choice to any other projects that need to be upgraded and all your Web projects will be updated.
    3. Click one of the following:

    Manually updating runtime resources

    To update the Faces and Faces Client runtime resources manually for a Web project:

    1. Create a new Web project (or, if you are working with EGL, create a new EGL Web project) named JSF601. You will use this project only as a source for the latest runtime resources; it can be deleted after the update is complete.
    2. In the Project Explorer, right-click on the JSF601 project and select Properties from the menu.
    3. Click Web Project Features and select Add Faces Base Components and Add Faces Client Framework, then click OK.
    4. If you are working with EGL, create a JSF page file as follows:
      1. Right-click the WebContent folder of your new EGL Web project.
      2. Select New -> Other -> Faces JSP File.
      The eglintdebug.jar and eglintdebugsupport.jar files are added to your project.
    5. For each existing Faces project that you want to update, do the following:
      1. In Project Explorer, expand an existing project to show the files in the WebContent/WEB-INF/lib/ folder. Locate and delete any of the following JAR files in this directory:
        • eglintdebug.jar (EGL only)
        • eglintdebugsupport.jar (EGL only)
        • fda6.jar (EGL only)
        • fdaj6.jar (EGL only)
        • jsf-api.jar
        • jsf-ibm.jar
        • jsf-impl.jar
        • odc-jsf.jar
      2. For any JAR files that you deleted, copy the JAR file of the same name from the WebContent/WEB-INF/lib directory of the JSF601 project and paste it into your original project in the same location. Some configurations will not require all of these JAR files to be present in the project; do not copy a particular JAR file if it was not in the original project.
      3. If you are working with EGL, right click on the name of each EGL Web project and click Generate; then, if you are not building the projects automatically, click Project -> Build All.
    6. Delete the JSF601 Web project.

    Chapter 3. Migrating J2EE projects

    The J2EE Migration Wizard has been updated in Rational Web Developer V6.0 to migrate J2EE projects to the J2EE 1.4 specification level. The J2EE Migration Wizard supports the migration from both the J2EE 1.2 and 1.3 specifications to the J2EE 1.4 specification level for all J2EE module types.

    Refer to J2EE 1.3 to 1.4 specification level migration and J2EE 1.2 to 1.4 specification level migration for details on the migration of J2EE 1.3 and 1.2 specification level artifacts to J2EE 1.4 specification level.

    Note:
    Before using the J2EE Migration Wizard, it is strongly recommended that you take the following steps:

    The J2EE Migration Wizard can be accessed as follows:

    1. In the J2EE Hierarchy view of the J2EE perspective, right-click the enterprise application project that you want to migrate.
    2. Select Migrate -> J2EE Migration Wizard from the pop-up menu.
    3. Follow the instructions on the J2EE Migration Wizard Welcome Page before proceeding with the migration process.

    Note:

    Refer to the online help for full details on using the J2EE Migration Wizard. Changes to the wizard are described in Changes in the J2EE Migration Wizard in Rational Web Developer V6.0.

    Refer to J2EE 1.3 to 1.4 specification level migration and J2EE 1.2 to 1.4 specification level migration for details on the changes to J2EE 1.3 and 1.2 specification level artifacts when they are migrated to J2EE 1.4.


    Migrating secure Web services

    Secure Web services are not migrated by the J2EE Migration Wizard when Web services are migrated from J2EE 1.3 to J2EE 1.4. The migration of secure Web services requires manual steps.

    After the J2EE migration, the secure binding and extension files must be migrated manually to J2EE 1.4 as follows:

    1. Double click on the webservices.xml file to open the Web Services editor.
    2. Select the Binding Configurations tab to edit the binding file.
    3. Add all the necessary binding configurations under the new sections Request Consumer Binding Configuration Details and Response Generator Binding Configuration Details.
    4. Select the Extension tab to edit the extension file.
    5. Add all the necessary extension configurations under the new sections Request Consumer Service Configuration Details and Response Generator Service Configuration Details.
    6. Save and exit the editor.

    J2EE 1.3 to 1.4 specification level migration

    J2EE projects can be migrated from the J2EE 1.3 to J2EE 1.4 specification level. This section describes, for each type of J2EE project, the artifacts migrated from J2EE 1.3 to J2EE 1.4 by the J2EE Migration Wizard.

    Web projects (Servlet level 2.3 to Servlet level 2.4)

    Artifacts of a Web deployment descriptor are migrated by the J2EE Migration Wizard when a J2EE 1.3 level Web project is migrated to J2EE 1.4.

    The following Web application artifacts are migrated:

    Authentication constraints

    J2EE 1.4 includes a Description object that has two attributes: language and value. This Description object did not exist in J2EE 1.3; the description was an attribute on the Authentication Constraint. So, when the artifacts of a Web deployment descriptor are migrated to J2EE 1.4, the value of the Description object is taken from the description attribute of the Authentication constraint.

    Security constraints

    Similarly, in J2EE 1.3 the description was an attribute on Security Constraint . In J2EE 1.4 there is a new Description object with the attributes language and value. So, the value of the Description object is taken from the description attribute of the Security Constraint.

    Web application

    The description string attribute of the ContextParam object in the J2EE 1.3 specification level has been moved to a Description object in ParamValue in J2EE 1.4.

    The TagLib object in J2EE 1.3 has been moved to the JSPConfig object in J2EE 1.4. The JSPConfig objects belonged to the Web root object in 1.3.

    Connector projects (JCA 1.0 to JCA 1.5)

    The J2EE Migration Wizard migrates the artifacts of a J2EE Connector architecture (JCA) 1.0 descriptor to JCA 1.5. The migrated artifacts are related to the elements of the ResourceAdaptor object as two new objects, OutboundResourceAdaptor and ConnectionDefinition, were added to the ResourceAdaptor object in J2EE 1.4 specification level for Connector projects.

    The mapping of the migrated elements is described below.

    Web services (J2EE 1.3 to J2EE 1.4)

    The J2EE 1.4 specification has added support for Web services through the new JAX-RPC 1.0 API.

    The JAX-RPC API supports service endpoints through:

    The J2EE 1.4 specification supports the Web services for J2EE specification (JSR 109). JSR 109 defines the deployment requirements for Web services and utilizes the JAX-RPC programming model.

    The following Web services artifacts are migrated using the J2EE Migration Wizard:

    Migrating Web service deployment descriptors

    Any Web service deployment descriptors contained in J2EE 1.3 projects that are migrated to the J2EE 1.4 specification level will be migrated from JSR-109 V1.0 (for J2EE 1.3) to J2EE 1.4.

    Web service deployment descriptors, as defined by JSR-109 V1.0, consist of the files webservices.xml, webservicesclient.xml, and all JAX-RPC mapping deployment descriptors that are referenced by the webservices.xml and webservicesclient.xml files. As with other J2EE deployment descriptors, migration will modify the structure of the information contained in the descriptors in order to make them comply with the J2EE 1.4 specification. One structural change which is particular to the Web service deployment descriptors is the change to the way in which qualified names are represented. In JSR-109 V1.0, qualified names are represented using a sequence of two elements, <namespaceURI> and <localpart>, which contain the namespace URI and the local part of the name respectively. Qualified names in J2EE 1.4 are based on the XMLSchema QName type, which uses XML namespaces.

    Further details on the migration of each of the Web service deployment descriptors is provided below.


    J2EE 1.2 to 1.4 specification level migration

    J2EE modules can be migrated from the J2EE 1.2 specification level to J2EE 1.4. This section describes the artifacts migrated for J2EE projects from J2EE 1.2 to J2EE 1.4 specification level by the J2EE Migration Wizard.

    For details on using the J2EE Migration Wizard, refer to Chapter 3, Migrating J2EE projects.

    Web projects (Servlet level 2.2 to Servlet level 2.4)

    Artifacts of a Web deployment descriptor are migrated by the J2EE Migration Wizard when a J2EE 1.2 Web project is migrated to the J2EE 1.4 specification level.

    The following Web application artifacts are migrated:

    Authentication constraints

    J2EE 1.4 includes a Description object that has two attributes: language and value. This Description object did not exist in J2EE 1.2; the description was an attribute on the Authentication Constraint. So, when the artifacts of a Web deployment descriptor are migrated to J2EE 1.4, the value of the Description object is taken from the description attribute of the Authentication constraint.

    Security constraints

    Similarly, in J2EE 1.2 the description was an attribute on Security Constraint . In J2EE 1.4 there is new Description object with the attributes language and value. So, the value of the Description object is taken from the description attribute of the Security Constraint.

    Web application

    The description string attribute of the ContextParam object in the J2EE 1.2 specification level has been moved to a Description object in ParamValue in J2EE 1.4.

    The TagLib object in J2EE 1.2 has been moved to the JSPConfig object in J2EE 1.4. The JSPConfig objects belonged to the Web root object in 1.2.


    Changes in the J2EE Migration Wizard in Rational Web Developer V6.0

    Changes have been made to the J2EE Migration Wizard in Rational Web Developer V6.0 that are common to the migration of all J2EE specification levels.

    Project structure migration is optional

    In WebSphere Studio V5.1.x through V5.1.2, project structure migration would take place simultaneously with J2EE specification level migration. Project structure migration was not optional when migrating J2EE specification levels.

    In the J2EE Migration Wizard in Rational Web Developer V6.0, Migrate project structure is a separate, optional selection from Migrate project J2EE specification level. J2EE specification level migration and project structure migration may be performed independently.

    Target server is required

    In Rational Web Developer V6.0, new and existing J2EE projects migrated to a higher J2EE specification level require a target server be set on the project. Server targeting is the default mechanism of how the classpath is set on a J2EE project in V6.0. For information in setting a target server and using the J2EE Migration Wizard, refer to the online help.


    Chapter 4. Changes in WebSphere test environments

    In Rational Web Developer V6.0, the WebSphere Application Server test environments included with the product have changed from those included with previous editions of WebSphere Studio Site Developer.

    The following is a summary of the changes to the WebSphere Application Server test environments in Rational Web Developer V6.0:

    The following table shows the WebSphere Application Server test environment levels included with the different versions of WebSphere Studio Site Developer and Rational Web Developer.

    Table 2. WebSphere Application Server test environments in WebSphere Studio Site Developer and Rational Web Developer


    WebSphere Application Server V4.x AEs WebSphere Application Server V5.x Base WebSphere Application Server Express V5.x WebSphere Application Server V6.0
    WebSphere Studio Site Developer V5.1 V4.0.6 V5.0.2 V5.0.2 N/A
    WebSphere Studio Site Developer V5.1.1 V4.0.7 + PQ78374 V5.0.2 + PQ78374 +PQ78419, V5.1 V5.0.2 & V5.1 N/A
    WebSphere Studio Site Developer V5.1.2 V4.0.7 + PQ78374 V5.0.2 + PQ78374 +PQ78419, V5.1.0.3 V5.0.2 & V5.1.0.3 N/A
    Rational Web Developer V6.0 N/A V5.0.x, V5.1.1 V5.0.2 & V5.1.1 V6.0

    Copyright and notices