IBM Rational Application 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 Application Developer V6.0

    Chapter 3. Updating Faces runtime resources for portlet projects from Rational Application Developer V6.0

    Chapter 4. Migrating J2EE projects

  • Migrating secure Web services
  • J2EE 1.3 to 1.4 specification level migration
  • Enterprise JavaBean projects (EJB 2.0 to EJB 2.1)
  • 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
  • Migrating Enterprise JavaBeans projects (EJB 1.1 to EJB 2.1)
  • Web projects (Servlet level 2.2 to Servlet level 2.4)
  • Changes in the J2EE Migration Wizard in Rational Application Developer V6.0
  • Chapter 5. Migrating to the portal tools in Rational Application Developer V6.0

  • Migrating WebSphere Portal V4.2 portlets to V5.x
  • Updating Faces runtime resources in a portlet project
  • Chapter 6. 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 Application Developer V5.1.x to Rational(R) Application Developer V6.0.

    Additional information can be found on the following topics:

    Information about using Rational Application 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 Application 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 Application 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 Application 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 Application 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 Application Developer V6.0. All EGL projects are safely migrated without this perspective in Rational Application 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 Application Developer.
      3. Migrating projects imported using Project Interchange: Projects exported from WebSphere Studio V5.1.2 or V5.1.1 and imported into Rational Application 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 Application Developer V6.0. If you created JDBC connections using the DB2 Net JDBC Driver, you will not be able to reconnect in Rational Application 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 Application 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 Application Developer V5.1.x, you need to get the corresponding plug-ins for V6.0 and reinstall them.
    9. If you installed any back-level WebSphere V5.x unit test environments when you installed Rational Application Developer, and if you use the embedded messaging service, upgrade it by installing the version provided with Rational Application Developer. Refer to the installation guide for details on installing the embedded messaging service.
    10. If you use features that require Agent Controller, upgrade it by installing the version provided with Rational Application Developer. For details, refer to the installation guide.
    11. 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 Application Developer, it is automatically migrated. Once you have migrated a workspace, you can no longer open it in WebSphere Studio Application 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 Application 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 Application Developer V6.0 workspace. The .compatibility file is used by Rational Application 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 Application Developer V5.1.x, refer to Disabling compatibility with WebSphere Studio V5.1.x.

    Eclipse considerations

    This version of Rational Application 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 Application 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 Application 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 Application 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 Application 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 Application 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 Application Developer V6.0 and WebSphere Studio Application 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 Application Developer V6.0, J2EE project compatibility will be lost and will need to be reestablished.

    UML diagram compatibility

    UML diagrams that existed in WebSphere Studio Application Developer V5.1.x are forward compatible and can be opened in read-only mode in Rational Application Developer V6.0. In V6.0, the J2EE Migration Wizard automatically migrates UML diagrams created in V5.1.x J2EE projects during J2EE project structure migration. Once migrated, the UML diagrams can be edited in Rational Application Developer V6.0.

    Note:
    UML diagrams in a workspace migrated to or created in Rational Application Developer V6.0 cannot be opened in WebSphere Studio Application Developer V5.1.x.

    Disabling compatibility with WebSphere Studio V5.1.x

    Compatibility with WebSphere Studio Application Developer V5.1.x can be totally removed from an enterprise application project created in Rational Application 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 Application 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 Application Developer V5.1.x.


    Updating Faces runtime resources in a Web project

    The JavaServer Faces runtime resources that originally shipped in WebSphere Studio Application Developer V5.1.x have been updated for Rational Application 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 Application 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 Application Developer V5.1.x to Rational Application 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 Application 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 Application 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 Application Developer V5.1.x have been updated for Rational Application 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 Application 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 Application Developer V5.1.x to Rational Application 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 Application 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 Application 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 Application 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 Application 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 Application 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 Application Developer is opened in Rational Application 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 Application Developer V6.0. If you migrate a workspace from WebSphere Studio Application 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 Application 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 Application 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 Application Developer V6.0

    The JavaServer Faces and Faces Client runtime resources that originally shipped in Rational Application Developer V6.0 have been updated for Rational Application 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 Application 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 Application Developer V6.0 to Rational Application 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 Application 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. Updating Faces runtime resources for portlet projects from Rational Application Developer V6.0

    The JavaServer Faces and Faces Client runtime resources that originally shipped in Rational Application Developer V6.0 have been updated for Rational Application Developer V6.0.1. If you want to continue development on portlet 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 Application Developer V6.0.1, the Faces and Faces Client runtime resource updates happen automatically when a portlet project is imported or a workspace is opened that contains out-of-date Faces or Faces Client runtime resources. After importing a portlet project or opening a workspace from Rational Application Developer V6.0 to Rational Application 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 portlet project:

    1. Import a portlet project (or a workspace) containing Faces or Faces Client content from Rational Application 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 portlet project and select Build -> Project; the process of rebuilding a project opens the Project Migration window.
    2. If you have other portlet 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 portlet projects will be updated.
    3. Click one of the following:
    4. To update the portlet-specific Faces runtime resources, jsf-portlet.jar and jsf-wp.jar, you need to follow the manual update steps below.

    Manually updating runtime resources

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

    1. Create a new portlet project named JSFP601. 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 JSFP601 project and select Properties from the menu.
    3. Click Web Project Features and select Add Faces Client Framework for Portlet Project, then click OK.
    4. For each existing Faces portlet 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:
        • jsf-api.jar
        • jsf-ibm.jar
        • jsf-impl.jar
        • jsf-portlet.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 JSFP601 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.
        • If your portlet project uses the IBM(R) portlet API or person link component, copy the jsf-wp.jar file into your original project.
        • If you copy the file odc-jsf.jar, copy the file odc-jsf-portlet.jar as well.
    5. Delete the JSFP601 portlet project.

    Chapter 4. Migrating J2EE projects

    The J2EE Migration Wizard has been updated in Rational Application 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 Application 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.

    Enterprise JavaBean projects (EJB 2.0 to EJB 2.1)

    The J2EE Migration Wizard supports the migration of enterprise bean deployment descriptors from the J2EE 1.3 specification level EJB resource to J2EE 1.4. Stateless session beans and message-driven beans are migrated to J2EE 1.4.

    Migrating session beans

    The J2EE Migration Wizard migrates stateless session beans that are defined as service endpoint interfaces (SEI) in the webservices.xml descriptor of an EJB project in J2EE 1.3 to the J2EE 1.4 specification level by setting the service endpoint interfaces on the stateless session bean.

    The J2EE 1.4 specification requires a SEI be defined on a stateless session bean if the session bean is to be used as a Web services endpoint. During the migration of an EJB JAR file, all session beans in the EJB project get the service endpoint set to the name used in the webservices.xml descriptor of the EJB project. The following is an example of how the metadata of an EJB project looks before and after migration to the J2EE 1.4 specification level.

    EJB project in J2EE 1.3: webservices.xml descriptor with a stateless session bean used as a Web service endpoint interface before migration

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE webservices PUBLIC "-//IBM Corporation, Inc.//DTD J2EE Web services 1.0//EN" 
    "http://www.ibm.com/webservices/dtd/j2ee_web_services_1_0.dtd">
       <webservices id="WebServices_1084831328093">
          <webservice-description id="WebServiceDescription_1084831328093">
             <webservice-description-name>EchoEJBService</webservice-description-name>
             <wsdl-file>META-INF/wsdl/EchoEJB.wsdl</wsdl-file>
             <jaxrpc-mapping-file>META-INF/EchoEJB_mapping.xml</jaxrpc-mapping-file>
             <port-component id="PortComponent_1084831328103">
                <port-component-name>EchoEJB</port-component-name>
                <wsdl-port id="WSDLPort_1084831328103">
                   <namespaceURI>http://test</namespaceURI>
                   <localpart>EchoEJB</localpart>
                </wsdl-port>
                <service-endpoint-interface>test.EchoEJB</service-endpoint-interface>
                <service-impl-bean id="ServiceImplBean_1084831328103">
                   <ejb-link>EchoEJB</ejb-link>
                </service-impl-bean>
             </port-component>
          </webservice-description>
       </webservices>
    

    The <service-endpoint-interface> and <service-impl-bean> tags in the preceding example define stateless session bean "EchoEJB" as a service endpoint in the webservices descriptor at the J2EE 1.3 specification level prior to migration.

    EJB project in J2EE 1.4: EJB deployment descriptor for the same stateless session bean "EchoEJB" with service endpoint interface created by the migration process

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE ejb-jar>
    <ejb-jar id="ejb-jar_ID" version="2.1" xmlns="http://java.sun.com/xml/ns/j2ee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
    	<display-name>
    	EchoEJBProject</display-name>
    	<enterprise-beans>
    		<session id="EchoEJB">
    			<ejb-name>EchoEJB</ejb-name>
    			<home>test.EchoEJBHome</home>
    			<remote>test.EchoEJB</remote>
    			<service-endpoint>test.EchoEJB</service-endpoint>
    			<ejb-class>test.EchoEJBBean</ejb-class>
    			<session-type>Stateless</session-type>
    			<transaction-type>Container</transaction-type>
    		</session>
    	</enterprise-beans>
    </ejb-jar>
    

    The<service-endpoint> tag in the preceding example defines "EchoEJB" as a service endpoint in the J2EE 1.4 specification level after migration.

    Migrating message-driven beans

    The J2EE Migration Wizard supports the migration of EJB 2.0 to EJB 2.1 message-driven beans.

    Message-driven beans were introduced in EJB 2.0 to support the processing of asynchronous messages from a Java Message Service (JMS). The EJB 2.1 specification expands the definition of the message-driven bean so that it can support any messaging system, not just JMS.

    Note:
    Message-driven beans that have been migrated from the EJB 2.0 specification level to EJB 2.1 and are deployed to WebSphere Application Server version 6 must be deployed against a Java Connector Architecture (JCA) 1.5 resource adapter instead of a listener port (as in WebSphere Application Server version 5). You must use the Deployment Descriptor Editor to change the WebSphere Bindings settings for the EJB 2.1 message-driven beans to use a JCA adapter. See Configuring an EJB 2.1 message-driven bean to use a JCA adapter.

    The EJB 2.0 message-driven bean artifacts migrated are:

    Some of the EJB 2.0 message-driven bean elements are replaced with activation-config properties. The property names and values used in the activation-config property to describe the messaging service will vary depending on the type of message service used. However, EJB 2.1 defines a set of fixed properties for JMS-based message-driven beans.

    The following example compares the elements of a sample bean in EJB 2.0 with how the elements appear in EJB 2.1.

    An example of message-driven bean elements in EJB 2.0:

    <message-driven id="Mdb20">
    	  <ejb-name>Mdb</ejb-name>
    	  <ejb-class>ejbs.MdbBean</ejb-class>
    	  <transaction-type>Bean</transaction-type>
    	  <message-selector>mdbMessage</message-selector>
    	  <acknowledge-mode>Auto-acknowledge</acknowledge-mode>
    	  <message-driven-destination>
    		<destination-type>javax.jms.Topic</destination-type>
    		<subscription-durability>Durable</subscription-durability>
    	   </message-driven-destination>
    </message-driven>
    

    An example of message-driven bean elements in EJB 2.1:

        <message-driven id="Mdb21">
      <ejb-name>Foo/ejb-name>
      <ejb-class>ejbs.FooBean</ejb-class>
       <messaging-type>javax.jms.MessageListener</messaging-type>
       <transaction-type>Bean/transaction-type>
       <message-destination-type>javax.jms.Topic</message-destination-type>
        <activation-config>
    	 <activation-config-property>
    	   <activation-config-property-name>destinationType</activation-config-property-name>
    	   <activation-config-property-value>javax.jms.Topic</activation-config-property-value>
    	 </activation-config-property>
    	 <activation-config-property>
    	   <activation-config-property-name>subscriptionDurability</activation-config-property-name>
    	     <activation-config-property-value>Durable</activation-config-property-value>
    	  </activation-config-property>
    	  <activation-config-property>
    	     <activation-config-property-name>acknowledgeMode</activation-config-property-name>
    	     <activation-config-property-value>AutoAcknowledge</activation-config-property-value>
    	  </activation-config-property>
    	  <activation-config-property>
    		<activation-config-property-name>messageSelector</activation-config-property-name>
    		<activation-config-property-value>fooSelector</activation-config-property-value>
    	  </activation-config-property>
    </activation-config>
    </message-driven>
    

    Configuring an EJB 2.1 message-driven bean to use a JCA adapter

    Message-driven beans that have been migrated from Enterprise Java Bean (EJB) 2.0 to the EJB 2.1 specification level and are deployed to WebSphere Application Server version 6 must be deployed against a Java Connector Architecture (JCA) 1.5 resource adapter instead of a listener port.

    The following steps describe how to change the deployment descriptor of EJB 2.1 message-driven beans to use a JCA adapter:

    1. Open the EJB project in the Project Explorer.
    2. Double-click the EJB project's Deployment Descriptor file in the Project Explorer. The EJB deployment descriptor editor opens.
    3. Click the Bean tab to open the Bean page.
    4. For each EJB 2.1 message-driven bean in the EJB project, do the following:
      1. Select the EJB 2.1 message-driven bean in the list of beans on the left-hand side of the Bean page.
      2. Under the heading WebSphere Bindings, select the JCA Adapter button.
      3. Specify bindings deployment properties:
        1. ActivationSpec JNDI name.

          Type the JNDI name of the J2C activation specification that is to be used to deploy this message-driven bean. This name must match the name of a J2C activation specification that you define to WebSphere Application Server.

        2. ActivationSpec Authorization Alias.

          The name of a J2C authentication alias used for authentication of connections to the JCA resource adapter. A J2C authentication alias specifies the user ID and password that is used to authenticate the creation of a new connection to the JCA resource adapter.

        3. Destination JNDI name.

          Type the JNDI name that the message-driven bean uses to look up the JMS destination in the JNDI name space.

    5. Save the changes and close the Deployment Descriptor editor.

    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 4, Migrating J2EE projects.

    Migrating Enterprise JavaBeans projects (EJB 1.1 to EJB 2.1)

    Migrating an EJB project from the EJB 1.1 to EJB 2.1 specification level is described in this section.

    Migrating an EJB project from EJB 1.1 to EJB 2.1 involves the migration of container-managed persistence (CMP) entity beans.

    There have been no changes in entity beans between J2EE 1.3 and J2EE 1.4 specification level. Migrating CMP entity beans from the EJB 1.1 to EJB 2.1 specification level is accomplished the same way as migrating a CMP entity bean from EJB 1.1 to EJB 2.0. Migrating container-managed entity beans from EJB 1.1 to EJB 2.x specification level requires the following steps:

    1. Convert the EJB project from EJB 1.1 to EJB 2.x.
    2. Migrate the EJB code from EJB 1.1 to EJB 2.x.
    3. Migrate any user-defined EJB 1.1 references to local references in EJB 2.x.

    Converting projects from EJB 1.1 to EJB 2.x

    An EJB 1.1 project can be converted to an EJB 2.x project using the J2EE Migration Wizard.

    Or, if you want to preserve the original EJB 1.1 project, you can create a new 2.x project and then import the existing project JAR file into it (File -> Import -> EJB JAR).

    Although the project is an EJB 2.x project, the existing (or imported) EJB 1.1 container-managed persistence (CMP) entity beans remain EJB 1.1 beans. That is, the CMP entity beans are not converted to EJB 2.x.

    The J2EE Migration Wizard migrates the enterprise beans within an EJB 2.x project from 1.1 into 2.x. (If you choose to migrate your 1.1 CMP entity beans to 2.x, all beans in the 2.x project must be migrated. However, you can selectively choose to add local client views to these migrated 2.x beans.)

    Note:
    If you have any mapped associations, EJB 2.x associations will be created for the associations themselves, but the role maps for those associations will become invalid. If you run validation, you will see an error occur. To get around this, open the mapping editor first and save the map. The role maps will be removed. You may then run validation again and re-map the roles.

    Migrating code from EJB 1.1 to EJB 2.x

    For projects converted from EJB 1.1 to EJB 2.x, steps must be taken to migrate existing EJB 1.1 code to EJB 2.x.

    Note:
    EJB 2.x beans are only supported in an EJB 2.x project (although a 2.x project also supports 1.1 beans).

    1. For any CMP 1.1 bean, replace each CMP field with abstract getXXX and setXXX methods. (Then the bean class needs to be abstract.)
    2. For any CMP, create an abstract getXXX and setXXX method for the primary key.
    3. For any CMP 1.1 finder method, create an EJBQL (EJB Query Language) method for each finder method.
      Note:
      EJB Query Language has the following limitations in Rational Application Developer V6.0:
      • EJB Query Language queries involving EJBs with keys made up of relationships to other EJBs will appear as invalid and cause errors at deployment time.
      • The IBM EJB Query Language support extends the EJB 2.x specification in various ways, including relaxing some restrictions, adding support for more DB2 functions, and so on. If portability across various vendor databases or EJB deployment tool is a concern, then care should be taken to write all EJB Query Language queries strictly according to instructions described in Chapter 11 of the EJB 2.x specification.
    4. For any CMP 1.1 finder, return java.util.Collection instead of java.util.Enumeration.
    5. For any CMP 1.1 bean, change all occurrences of this.field = value to setField(value) in ejbCreate() and elsewhere throughout the code.
    6. Update your exception handling (rollback behavior) for non-application exceptions:
    7. Update your Exception handling (rollback behavior) for application exceptions:
    8. Update any CMP setting of application-specific default values to be inside ejbCreate (not using global variables, since EJB 1.1 containers set all fields to generic default values before calling ejbCreate which will overwrite any previous application specific defaults).

    Migrating EJB references for EJB 1.1 relationships

    When creating EJB 1.1 relationships were created, EJB references were created to the Remote Client view. During the EJB 1.1 project migration using the J2EE Migration Wizard, these EJB remote references for the EJB 1.1 relationships are removed and replaced with EJB local references. Local references for user-defined EJB references must be recreated manually.

    Note:
    In EJB 2.x, EJB relationships can be created only if the beans have Local Client view defined on them and the EJB local references are created for the EJB 2.x relationships.

    For user-defined EJB references, migration is not done using the J2EE Migration Wizard. However, follow these steps to set up the local references:

    1. Delete the existing EJB remote references in References page of the deployment descriptor editor.
    2. Add an EJB local reference in References page of the deployment descriptor editor.

    Method elements are merged during project structure migration

    During the project structure migration using the J2EE Migration Wizard, the method elements (that include security identity, container transaction, method permissions, access intent and isolation levels) of the same type for all the beans are merged to make them logically grouped.

    A sample of the method elements before and after the project structure migration.

    The following is a sample of the method permission in the source page of the deployment descriptor editor before project structure migration.

    		<method-permission>
    			<role-name>rol1</role-name>
    			<role-name>rol2</role-name>
    			<method>
    				<ejb-name>TestBean1</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>getEJBMetaData</method-name>
    				<method-params>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean1</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>getHomeHandle</method-name>
    				<method-params>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-namae>remove</method-name>
    				<method-params>
    					<method-param>java.lang.Object</method-param>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>remove</method-name>
    				<method-params>
    					<method-param>javax.ejb.Handle</method-param>
    				</method-params>
    			</method>
    		</method-permission>
    		<method-permission>
    			<role-name>rol1</role-name>
    			<role-name>rol2</role-name>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Remote</method-intf>
    				<method-name>isIdentical</method-name>
    				<method-params>
    					<method-param>javax.ejb.EJBObject</method-param>
    				</method-params>
    			</method>
    		</method-permission>
    

    The following is a sample of the method permission in the source page of the deployment descriptor editor after project structure migration.

    		<method-permission>
    			<role-name>rol1</role-name>
    			<role-name>rol2</role-name>
    			<method>
    				<ejb-name>TestBean1</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>getEJBMetaData</method-name>
    				<method-params>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean1</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>getHomeHandle</method-name>
    				<method-params>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>remove</method-name>
    				<method-params>
    					<method-param>>java.lang.Object</method-param>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Home</method-intf>
    				<method-name>remove</method-name>
    				<method-params>
    					<method-param>javax.ejb.Handle</method-param>
    				</method-params>
    			</method>
    			<method>
    				<ejb-name>TestBean2</ejb-name>
    				<method-intf>Remote</method-intf>
    				<method-name>isIdentical</method-name>
    				<method-params>
    					<method-param>javax.ejb.EJBObject</method-param>
    				</method-params>
    			</method>
    		</method-permission>
    
    Note:
    When the CMP 1.x to CMP 2.x bean migration is also selected along with the project structure migration in the J2EE Migration Wizard, the access intent and isolation levels are removed but everything else is merged during migration. The reason that access intents and isolation level are removed is that they are no longer valid due the changes in the extensions model. With the new model we have both access intents and isolation level defined in access intents and we have bean-level access intents and method-level access intents. It is always advised to use the bean-level access intents rather than the method-level access intents.

    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 Application Developer V6.0

    Changes have been made to the J2EE Migration Wizard in Rational Application 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 Application 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 Application 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 5. Migrating to the portal tools in Rational Application Developer V6.0

    Portal Toolkit V5.0.2.2 projects will be migrated automatically to Rational Application Developer V6.0 Portal Tools by migrating the Portal Toolkit workspace, or loading the project from a SCM (source code management) system, or importing the project using the Project Interchange feature. If you are migrating from earlier versions of Portal Toolkit, you will need to export your portlet projects to WAR files and import the WAR files into the Portal Tools in Rational Application Developer V6.0.

    Before migrating portal applications, you must install the portal tools feature of Rational Application Developer V6.0. Refer to the installation guide.

    Note:
    Backward compatibility of portlet projects is not supported.

    Automatic migration is only supported for projects created in Portal Toolkit V5.0.2.2 with WebSphere Studio V5.1.2. Refer to Chapter 1, Migrating from WebSphere Studio V5.1, 5.1.1, or 5.1.2 for details on migration.

    If your portlet project is associated to an enterprise application project, you will need to set the appropriate target server on the EAR project. You can set the target server on the Server Properties page (Properties -> Server).

    During migration of Portal Toolkit V5.0.2.2 projects, some additional changes take place:

    If you are migrating from earlier versions of Portal Toolkit, you need to manually migrate your portlet projects to Portal Tools in Rational Application Developer V6.0, as follows:

    1. Export the existing project to a WAR file: In the earlier version of Portal Toolkit, export each project to a WAR file with source files.
      1. Right-click the project and select Export.
      2. Select WAR file and Export source files and click Finish.
    2. Import the portlet WAR file:
      1. In the Portal Tools for Rational Application Developer V6.0, create a new empty portlet project.
        1. Select File -> New -> Project -> Portal -> Portlet Project or Portlet Project (JSR 168).
        2. Deselect Create a portlet.
        3. Click Show Advanced.
        4. If you are importing a WebSphere Portal 4.2 portlet, select 2.2 as the servlet version.
        5. Select WebSphere Portal v5.0 as the target server, and click Finish.
      2. Import the WAR file to this new empty portlet project.
        1. Select Import.
        2. Select WAR file and specify the WAR file that you exported above (Exporting project to WAR file in earlier version).
        3. Select the new empty portlet project.
        4. Select Overwrite existing resources without warning.
        5. Do not select Delete project on overwrite.
    3. Delete the TLD file:

      It is recommended that you delete the portlet TLD file from the project if it exists. Otherwise, you will get a warning message when you rebuild the project. Leaving it may cause a problem when the portlet project is deployed to WebSphere Portal and the TLD file of the portlet is different from the file in the server.

    4. If you are migrating a WebSphere Portal 4.2 portlet, you need to migrate this migrated portlet project to WebSphere Portal 5.x.

    For information on migrating WebSphere Portal V4.2 portlets to V5.x, refer to Migrating WebSphere Portal V4.2 portlets to V5.x.

    For information on migrating Faces resources in a portlet project, refer to Updating Faces runtime resources in a portlet project.


    Migrating WebSphere Portal V4.2 portlets to V5.x

    Rational Application Developer V6.0 does not support developing WebSphere Portal V4.2 portlets. You need to migrate WebSphere Portal V4.2 portlet projects to V5.x.

    Most portlets written for WebSphere Portal V4.2 will run unchanged in WebSphere Portal V5.x. Some of the Portlet 4.2.x APIs are now marked as deprecated, but still available on WebSphere Portal V5.x.

    Note:
    Migrated portlet application projects are not backward compatible.

    To migrate portlet applications for WebSphere Portal V4.2 to V5.x, do the following steps:

    1. Migrate the Portal V4.2 portlet projects to Portal V5.x portlet projects:
      1. Right-click the portlet application project that you want to migrate.
      2. Select Properties -> Portlet API to open the Portlet API page.
      3. Select WebSphere Portal Version 5.x from the Portlet API level drop-down list.
      4. Click OK, and the following changes are automatically made:
        • The tag library descriptor (TLD) file for the portlet API is removed if it exists.
        • The Web level is changed from 2.2 to 2.3.
        • The portlet specific class path entries are removed, as the WebSphere Portal JRE container and WebSphere Portal runtime target container will dynamically add them.
    2. If your portlet project is associated to an enterprise application project, it is recommended that you migrate the J2EE level of the EAR project to J2EE 1.3. Portlet applications designed for WebSphere Portal V5.x should be compliant with the J2EE level 1.3 specifications.
      Note:
      Before migrating your enterprise application project to J2EE 1.3, read Chapter 4, Migrating J2EE projects. For information on using the J2EE Migration Wizard, refer to the online help.
      1. If the migrated portlet project is only associated to the enterprise application project, do as follows:
        1. Close all editors in the workbench.
        2. Right-click the enterprise application project with which the migrated portlet project is associated.
        3. Select Migrate -> J2EE Migration Wizard and click Next.
        4. Select J2EE version 1.3 and WebSphere Portal as the target server.
        5. Click Finish.
      2. If other portlet projects are associated with the enterprise application project, you must remove the migrated portlet project and add it to another enterprise application project.
        1. Remove the module of the migrated portlet project from the enterprise application project.
          1. Expand the enterprise application project and select the deployment descriptor.
          2. Select Open With -> Deployment Descriptor Editor.
          3. Select the Module tab. On the Module page of the editor, select the WAR file of the migrated portlet project.
          4. Click Remove.
          5. Select File -> Save to save the changes.
        2. Create a new enterprise application project and add the portlet project to it.
          1. Select File -> New -> Project.
          2. Select Show All Wizards check box.
          3. Expand the J2EE and select Enterprise Application Project.
          4. Fill in the project Name field, select J2EE version 1.3 and WebSphere Portal as the target server and click Next.
          5. On the EAR Module Projects page, select the migrated portlet project and click Finish.

    The portlet project is now migrated to WebSphere Portal V5.x.


    Updating Faces runtime resources in a portlet project

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

    In Rational Application Developer V6.0.1, the Faces runtime resource updates happen automatically when a portlet project is imported or a workspace is opened that contains out-of-date resources. After importing a portlet project created with Portal Toolkit 5.0.2.2 for WebSphere Studio Application Developer V5.1.x to Rational Application 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 portlet project:

    1. Import a portlet project containing Faces content from WebSphere Studio Application 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 portlet project and select Build -> Project; the process of rebuilding a project opens the Project Migration window.
    2. If you have other portlet projects with Faces content in your workspace, check Apply this choice to any other projects that need to be upgraded and all your portlet projects will be updated.
    3. Click one of the following:
    4. To update the portlet-specific Faces runtime resources, jsf-portlet.jar and jsf-wp.jar, you need to follow the manual update steps below.
    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 portlet project:

    1. Import your existing portlet project with Faces content into a Rational Application Developer V6.0.1 workspace.
    2. Create a new portlet project named JSFP601 with the Faces portlet option selected in the second page. 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 JSFP601 project and select Properties from the menu.
    4. Click Web Project Features and select Add Faces Client Framework for Portlet Project, then click OK.
    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:
        • jsf-api.jar
        • jsf-ibm.jar
        • jsf-impl.jar
        • jsf-portlet.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>
        		<variable-resolver>com.ibm.faces.application.WPPortletVariableResolver</variable-resolver>
        		<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
        	</application>
        
        Note:
        If your portlet project is using the JSR 168 API, specify com.ibm.faces.application.PortletVariableResolver instead of com.ibm.faces.application.WPPortletVariableResolver.
      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 JSFP601 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.
        • If your portlet project uses the IBM portlet API or person link component, copy the jsf-wp.jar file into your original project.
        • If you copy the file odc-jsf.jar, copy the file odc-jsf-portlet.jar as well.
      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>
        
    6. Delete the JSFP601 portlet project.

    Chapter 6. Changes in WebSphere test environments

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

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

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

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


    WebSphere Application Server V4.x AEs WebSphere Application Server V5.x Base WebSphere Application Server Express 5.x WebSphere Application Server V5.x Portal WebSphere Application Server V6.0
    WebSphere Studio Application Developer V5.1 V4.0.6 V5.0.2 V5.0.2 N/A N/A
    WebSphere Studio Application Developer V5.1.1 V4.0.7 + PQ78374 V5.0.2 + PQ78374 +PQ78419, V5.1 V5.0.2 & V5.1 N/A N/A
    WebSphere Studio Application Developer V5.1.2 V4.0.7 + PQ78374 V5.0.2 + PQ78374 +PQ78419, V5.1.0.3 V5.0.2 & V5.1.0.3 V5.0.2.3 Base + WebSphere Portal V5.0.2.1 N/A
    Rational Application Developer V6.0 N/A V5.0.x, V5.1.1 V5.0.2 & V5.1.1 V5.0.2.6 Base + WebSphere Portal V5.0.2.2, V5.1.1 Base + WebSphere Portal 5.1 V6.0

    Copyright and notices