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

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

Chapter 3. Migrating J2EE projects

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:

• Migrating J2EE projects.
• Changes in WebSphere test environments.

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:

   • For each V5.1.x project migrated to V6.0, the migration program automatically adds a .compatibility file to the project folder in V6.0. This file is used for the purpose of backward compatibility with WebSphere Studio V5.1.x. Do not edit or delete this file. Refer to the section on compatibility with WebSphere Studio V5.1.x for more information.

   Important:

   • If there are debug launch configurations associated with the workspace you are migrating, you should note that some launch configuration will not migrate automatically. For information on how to restore launch configurations to a migrated workspace, refer to Debugger changes in V6.0.
   • If you used the XSLT debugger or EGL debugger on projects in your migrated workspace, you will need to change the Java runtime environment (JRE) that is installed with Rational Web Developer V6.0. Refer to Debugger changes in V6.0 for details on how to make this change.
   • If you have programs developed using the Enterprise Generation Language that were migrated to V6.0, you should note that there are new reserved words for EGL in version 6.0. If you use these words as variable or part names you will need to change them. Refer to EGL reserved words in V6.0
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:

• Alter the compatibility metadata that is added to the .project file and the .compatiblity file created by the migration tool.
• Delete the .compatibility file from those projects.

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:

• Compatibility with Previous Releases
• Upgrading Workspace from a Previous Release
• Interoperability with Previous Releases

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.

   • <classpathentry kind="con" 
     path="org.eclipse.jdt.launching.JRE_CONTAINER/
     org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/WebSphere v5.1 JRE"/>
     

   • <classpathentry kind="con" 
     path="com.ibm.wtp.server.java.core.container/
     com.ibm.etools.websphere.runtime.core.runtimeTarget.v51/was.base.v51"/>
     

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:
   • Yes to complete the update automatically.
   • Later to defer the update. To update runtime resources automatically after selecting Later, you have to close and reopen the Web project or restart the workbench before rebuilding your Web project. If you have disabled automatic builds, right-click your Web project and select Build Project.
   • Never to keep your runtime resources back-level. If you choose Never and intentionally stay with the back-level runtime resources, you will not be prompted again to update them. In the future, you will need to update the runtime resources manually if you require them.

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:
   • Yes to complete the update automatically.
   • Later to defer the update. To update runtime resources automatically after selecting Later, you have to close and reopen the Web project or restart the workbench before rebuilding your Web project. If you have disabled automatic builds, right-click your Web project and select Build Project.
   • Never to keep your runtime resources back-level. If you choose Never and intentionally stay with the back-level runtime resources, you will not be prompted again to update them. In the future, you will need to update the runtime resources manually if you require them.
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:

• Client data mediator classes that have already been generated will no longer compile. They need to be regenerated one JSP at a time::
  1. Open the OdysseyBrowserFramework.properties file found in the root Java source folder. Save the contents for future use.
  2. In the OdysseyBrowserFramework.properties file, for each JSP in your Web project containing Faces client data, find the <client-data-name>.ecore and <client-data-name>.emap entries for properties EMAP_FILES and ECORE_FILES.
  3. Keep only the matching entries for the client data on your JSP, and delete all other entries.

     For example, if your current page has a Client Data called ACCOUNT, and your properties file had entry like:

     EMAP_FILES=com\\ibm\\dynwdo4jsmediators/account.emap com\\ibm\\dynwdo4jsmediators/orders.emap
     

     you should delete com\\ibm\\dynwdo4jsmediators/orders.emap from the entry. The entry would now appear as:

     EMAP_FILES=com\\ibm\\dynwdo4jsmediators/account.emap
     

  4. Save the properties file.
  5. Select a client data object in a JSP then right-click and select Configure.
  6. On the Advanced tab, click Regenerate All. This will regenerate all the artifacts needed for all client data on the current JSP.
  7. Repeat these steps 2-6 for each JSP containing client data in your Web project.
  8. After regenerating the client data mediator classes, there will still be some mediator classes left that will not compile. These are mediators for schema elements no longer used in Service Data Objects (SDOs) in V6.x and have the naming convention *_DataGraphSchema_wdo4js_*.java and *_RootDataObject_wdo4js_*.java. Delete these mediator classes from your Web project to prevent these compile errors.
  9. After the update completes successfully, restore the original contents of the OdysseyBrowserFramework.properties file.
• Tree view Faces Client components bound to WDOs fail to run on the server after changing the project's target server to WebSphere Application Server V6.0. The workaround is to modify the source view of your JSP to change all className tags to use SDO DataObject class instead of WDO DataObject class. For example, for a WDO named account:
  1. For the root object, change the className tag from className="com.ibm.etools.wdo.DataObject(DynWDO`account`RootDataObject)" to className="commonj.sdo.DataObject(DynWDO`account`DataGraphRoot)".
  2. For all child nodes, change the className tag from className="com.ibm.etools.wdo.DataObject(DynWDO`account`ACCOUNT)" to className="commonj.sdo.DataObject(DynWDO`account`ACCOUNT)", where ACCOUNT is the name of the data node.

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.

• The DiffHandler interface has changed as follows:
  • The handle method now throws Exception in addition to DiffException.
  • The new find method is used by the framework to find objects.
  • The new getId method is used for debugging and allows the framework to print the value of an object.

  The find and getId methods are used internally by the generated DiffHandlers. For your custom DiffHandlers, you can implement empty methods just to comply with the interface. Those methods will not be called by the framework.

  The DiffHandler interface is now:

  public interface DiffHandler
   {
     public void   handle(DiffInfo Diff) throws DiffException, Exception;
     public Object find  (DiffInfo Diff) throws DiffException, Exception;
     public String getId (DiffInfo Diff, boolean Original);
   }
  

• The DiffInfo class has changed as follows:
  • The method ArrayList getAncestors() has been replaced by the method DiffInfo getParent(), which provides an easier way to access the information for each object in the ancestor tree in a recursive manner.
  • The methods getCurrent() and getOriginal() now return a DataObject object instead of an EObject object. It is not mandatory that you change your code to use the DataObject object. However, the DataObject interface is much easier and more intuitive to use than EObject. You can easily cast a DataObject object to an EObject object for existing code.
  • A new method String getPropertyName() was added to identify the property name for which this object applies. This is important if, for example, a given class has two properties of the same type. Previously in the DiffInfo class, the code would have been unable to differentiate between the two properties.

  The DiffInfo class is now:

  public class DiffInfo
   {
     public char       getCrud()
     public DataObject getCurrent()
     public String     getEClassName()
     public DataObject getOriginal()
     public String     getPropertyName()
     public DiffInfo   getParent()
   }
  

  Note:

  The DiffInfo class is no longer supported for public use as Diff processors and handlers are now automatically generated. Keeping your old handlers is only a temporary solution and it is strongly advised that automated handlers be used.

Changes to Faces Client components in V6.0

• Support for WebSphere Application Server V6.0.
• Support for Service Data Objects (SDO) on WebSphere Application Server V6.0.
• EGL data is now supported as client data.
• Diff processors and handlers are automatically generated.
• There are new events for the following components:
  • TabbedPanel: onInitialPageShow
  • Tree: onNodeExpand, onNodeCollapse, onExpand, onCollapse
  • DataGrid: onPage, onSort, onFilter

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 on Server: Launch configurations that were previously created via the Debug on Server action will not migrate to V6.0. To launch an application for debugging on a server in V6.0, reselect the application and choose Debug on Server. This will create a new launch configuration for the application.
• Server Attach: WebSphere Application Server debug launch configurations that were previously created for a server attach will not migrate to V6.0. The WebSphere Application Server debug launch configuration no longer exists. To perform a server attach for debugging in V6.0, use the Debug on Server action and create a WebSphere V5 server attach for 5.x or a WebSphere V6.0 server attach for 6.0.
• SQLJ debugger: The SQLJ debug launch configuration no longer exists and SQLJ launch configurations that were previously created will not migrate to V6.0. To launch SQLJ programs for debugging in V6.0, use the Java Application launch configuration.
• Stored Procedure debugger: Stored procedure debugger launch configurations that were previously created will migrate to Rational Web Developer V6.0 and be available for use in the Debug launch configurations dialog box. After migrating, if you use the Debug action in the Data Definition view pop-up menu, a new launch configuration will be created for you.

  Note:

  If you migrate a workspace containing a stored procedure and then rebuild the stored procedure for debugging, migrated launch configurations associated with the stored procedure will not work.

• EGL debugger: After migrating a workspace, the following steps must be performed for existing EGL debugger launch configurations:
  1. Modify the installed Java runtime environment (JRE) to point to the correct location. After migrating a workspace, its installed JRE will point to the JRE from the previous version of WebSphere Studio Site Developer. To change this, point to the new JRE location as follows:
     1. Select Window -> Preferences from the workbench menu.
     2. In the resulting Preferences dialog, expand the Java node and then select Installed JREs.
     3. On the right-hand side, set the installed JRE to point to the JRE that has been installed with the current version of this product. The location of the JRE is the subdirectory \eclipse\jre of the installation directory of Rational Web Developer V6.0.
  2. In the launch configuration, select the Source tab prior to launching (failing to do this will result in a "source not found" error). If you had added source locations to the launch configuration in the V5.1.x workspace, you will need to manually add these locations back to the migrated launch configuration.
• Compiled Language debugger: After migrating a workspace, the following steps need to be performed for existing compiled language debugger launch configurations:
  1. If you had set environment variables in the System Environment tab of the Compiled Application launch configuration, you will need to manually add them back to the migrated launch configuration.
  2. If you had added source locations to the Compiled Application or Attach to a running process launch configurations, you will need to manually add them back to the migrated launch configuration.

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:

• Change the JRE for the entire workspace by pointing it to the new JRE location by doing the following steps:
  1. Select Window -> Preferences from the workbench menu.
  2. In the Preferences window, expand the Java node and then select Installed JREs.
  3. On the right hand side, set the installed JRE to point to the one that has been installed with the current version of this product. The location of the JRE is the subdirectory \eclipse\jre of the installation directory of Rational Web Developer V6.0.
• If you intend to launch the debug session via the Debug launch configurations dialog box, you can change the JRE for the launch configuration by pointing it to the new JRE location. To do this, open the launch configuration in the Debug launch configurations dialog box. Select the JRE tab and specify the new JRE location in the Alternate JRE field.

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:

• You can modify the target server using the project's properties dialog. Right-click on the project in the Project Explorer view, and select Properties -> Server -> Target runtime.
• During J2EE migration using the J2EE Migration Wizard you can re-target the application to use another server.

  Note:

  You can only migrate to a higher J2EE specification level.

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

• Any code written to the public application programming interfaces (APIs) for the WDO access beans will be supported in V6.0 (although the implementation classes have changed to target the SDO runtime).
• New code generated for WebSphere Application Server V6.0 will not use the WDO access beans, but will instead generate code for the pure SDO APIs.
• Any code generated to a project while targeted at V6.0 will not run on a V5.1 server even if migrated back by re-targeting the server.
• Code written for V5.1 can be migrated forward and backwards by targeting a V5.1 server.

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:

• The Java archive (JAR) files wdo_web.jar and wdo_jdbc_access.jar are removed from the project.
• The following JAR files are removed from the project's class path:
  • emf-runtime.jar
  • emf-event.jar
  • wdo-interface.jar
  • wdo.jar
  • jdbcmediator.jar
  • wdo.xmlmediator.jar
• The files sdo_web.jar and sdo_access_beans.jar are added to the project (SDO runtime JAR files are automatically added to any V6.0 project's classpath).
• Any JavaServer Pages Standard Tag Library (JSTL) 1.0 JAR files are removed from the project. (JSTL 1.1/JSP 2.0 JAR files are automatically added to any V6.0 project's class path).
• The following import statements are changed in any Java sourcre files:
  • com.ibm.websphere.wdo.access.connections.ConnectionManager changes to com.ibm.websphere.sdo.access.connections.ConnectionManager.
  • com.ibm.websphere.wdo.mediator.rdb.ConnectionWrapper changes to com.ibm.websphere.sdo.mediator.jdbc.ConnectionWrapper.

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:

• The JAR files sdo_web.jar and sdo_access_beans.jar are removed from the project.
• The JAR files wdo_web.jar and wdo_jdbc_access.jar are added to the project.
• The following JAR files are added to the project's classpath:
  • emf-runtime.jar
  • emf-event.jar
  • wdo-interface.jar
  • wdo.jar
  • jdbcmediator.jar
  • wdo.xmlmediator.jar
• JSTL 1.0 JAR files are added to the project. (JSTL 1.1/JSP 2.0 JARs are removed from the project's class path).
• The following import statements are changed in any Java source files:
  • com.ibm.websphere.sdo.access.connections.ConnectionManager becomes com.ibm.websphere.wdo.access.connections.ConnectionManager.
  • com.ibm.websphere.sdo.mediator.jdbc.ConnectionWrapper becomes com.ibm.websphere.wdo.mediator.rdb.ConnectionWrapper.

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.

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:

• as
• isa
• like
• matches
• money
• openUI
• ref
• self
• string
• this

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:
   • Yes to complete the update automatically.
   • Later to defer the update. To update runtime resources automatically after selecting Later, you have to close and reopen the Web project or restart the workbench before rebuilding your Web project. If you have disabled automatic builds, right-click your Web project and select Build Project.
   • Never to keep your runtime resources back-level. If you choose Never and intentionally stay with the back-level runtime resources, you will not be prompted again to update them. In the future, you will need to update the runtime resources manually if you require them.

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:

• Backup your entire workspace.
• If you are working with a shared repository, check out or lock all corresponding projects.

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:

• Migration of secure Web services (J2EE 1.3 to 1.4) requires manual migration of the secure binding and extension files. Refer to Migrating secure Web services for details.

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.

• The following elements are moved from the ResourceAdaptor object to the OutboundResourceAdaptor object:
  • reauthenticationSupport
  • transactionSupport
• The following elements are moved from the ResourceAdaptor object to the ConnectionDefinition object:
  • managedConnectionFactoryClass
  • connectionFactoryInterface
  • connectionFactoryImplClass
  • connectionInterface
  • connectionImplClass
• The outboundResourceAdaptor object contains a list of ConnectionDefinition definitions. Hence the ConnectionDefinition is added to the ConnectionDefinition list held by OutboundResourceAdaptor.
• The OutboundResourceAdaptor object is contained by the ResourceAdaptor object.
• The AuthenticationMechanism object has undergone some changes in JCA 1.5 where the customAuthMechType element is replaced by the authenticationMechanism and the authenticationType element is replaced by authenticationMechanism
• The description attribute in the ResourceAdaptor object is replaced with a Description object where the description attribute string is set to value element in the Description object for the following objects:
  • SecurityPermission
  • AuthenticationMechanism
  • ConfigurationProperties

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:

• servlets with JAXR-RPC
• servlets with direct SOAP
• stateless session beans

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:

• Web services descriptor
• Web services client descriptor
• JAX-RPC mapping descriptor

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.

• Web services descriptor (webservices.xml)

  The webservices.xml deployment descriptor is present in Web projects that contain J2EE Web services. Both the <wsdl-port> element and the <soap-header> element contain qualified names and their contents will be migrated to the J2EE 1.4 format.

  For example, if <wsdl-port> is represented as follows before migration,

  <wsdl-port>
    <namespaceURI>http://addressbook.webservice</namespaceURI>
    <localpart>AddressBook</localpart>
  </wsdl-port>
  

  after migration <wsdl-port> will be represented as:

  <wsdl-port xmlns:pfx="http://addressbook.webservice">pfx:AddressBook</wsdl-port>
  

  The prefix "pfx" is used as the namespace prefix for all qualified names that are migrated.

• Web services client descriptor (webservicesclient.xml)

  The webservicesclient.xml deployment descriptor is present in J2EE 1.3 Web projects, and application client projects that contain J2EE Web service clients. During migration from J2EE 1.3 to 1.4, the contents of webservicesclient.xml are migrated and moved to the deployment descriptor for the project. The process that occurs is as follows:

  • For Web projects, all <service-ref> elements in webserivcesclient.xml are moved under the <web-app> element in web.xml.
  • For application client projects, all <service-ref> elements in webservicesclient.xml are moved under the <application-client> element in application-client.xml.
  • Webservicesclient.xml is deleted.

  Both the <service-qname> element and the <soap-header> element contain qualified names and their contents will be migrated to the J2EE 1.4 format. For example, if <service-qname> is represented as follows before migration,

  <service-qname>
    <namespaceURI>http://addressbook.webservice</namespaceURI>
    <localpart>AddressBookService</localpart>
  </service-qname>
  

  after migration <service-qname> will be represented as:

  <service-qname xmlns:pfx="http://addressbook.webservice">pfx:AddressBookService</service-qname>
  

  The prefix "pfx" is used as the namespace prefix for all qualified names that are migrated.

• JAX-RPC mapping descriptor

  Both the webservices.xml and webservicesclient.xml deployment descriptors can reference one or more JAX-RPC mapping deployment descriptors.

  In the webservices.xml file, these references are contained in the <jaxrpc-mapping-file> element under each <webservice-description> element. In the webservicesclient.xml file, these references are contained in the <jaxrpc-mapping-file> element under each <service-ref> element.

  During migration from J2EE 1.3 to 1.4, all the JAX-RPC mapping deployment descriptors referenced in webservices.xml and webservicesclient.xml are migrated. Migration includes migrating all qualified names to the J2EE 1.4 format (see the sections above on webservices.xmland webservicesclient.xml for examples of qualified names following migration).

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:

• WebSphere Application Server V4.x servers are no longer supported test environments. However, J2EE 1.2 specification level applications can still be exported and deployed manually for testing on remote V4.x servers.
• WebSphere Application Server V6.0 server has been added as an installable test environment. It supports running J2EE 1.4 specification level applications.

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