Migrating JavaServer Faces resources with Faces Client Components

If you created projects in WebSphere® Studio V5.1.x containing Faces Client Components in JavaServer Faces JavaServer Pages (JSPs), you must migrate the runtime resources of the Faces Client Components to the latest levels.

After opening in V6.0 a project containing JavaServer Faces JSPs with Faces Client Components created in WebSphere Studio V5.1.x, you must do the following in order to migrate the runtime resources of Faces Client Components:
  1. Create a new JSP file, and for the model select Basic with client-side data caching. This JSP is only needed temporarily in order to cause Rational® Application Developer to migrate all the system Java™ archive (JAR) files to the latest levels.
  2. You will be prompted that you can migrate the project runtime resources to the latest levels. Select Yes to complete the migration process. Important: If you select No, or cancel the dialog box, your project's Faces Client Components will not be migrated to the latest levels and you will not get prompted again, causing several serious issues between the new tooling and the old runtime JAR files.
  3. After creating the new JSP file, you can delete it from the project.
  4. Select any data object in the Client Data area, right click and select Configure. On the Advanced tab select Regenerate All, which will regenerate all your mediators.
    Note: Do not use the Regenerate from server-side data button. You must use Regenerate All.
  5. There are WebSphere Data Objects (WDO) schema elements in version 5.12 that are no longer used in version 6.0. The mediator classes for these elements will not be regenerated and will continue to have compile errors. These mediators will have the naming convention *_DataGraphSchema_wdo4js_*.java. Delete these mediator classes from your project to prevent these compile errors.
If you are working in the Linux™ platform, or if you are using a non-English locale: Prior to following the steps described above to migrate your projects created in WebSphere Studio V5.1.x containing Faces Client Components in JavaServer Faces JSPs, you may get the following error message when the projects are loaded into V6.0:
Project can not be built due to <class_name>.java could not be read.
The files could not be read because the Client Data mediator classes in the V5.1.x project may contain special characters which were not encoded, whereas the mediator classes in Rational Application Developer V6.0 encode these characters. These error messages will stop once you regenerate your Client Data by following the steps described above. However, before you follow the steps to migrate your project containing Faces Client Components, you must first delete the Client Data mediator files from the project you loaded in V6.0 so that your workspace can be built. To delete the Client Data mediator files:
  1. Delete from your project all Client Data mediator class packages that have the naming convention com.ibm.dynwdo4jsmediators.<client-data- name>.
  2. 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.
  3. After you have deleted the mediator packages, your project will now build. You can now complete the migration steps described above.

In some instances, you may get a mediator generation failed message. To correct this problem, edit the OdysseyBrowserFramework.properties file and delete the entries for the EMAP_FILES and ECORE_FILES properties and try again.

Note: 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. This is done as follows:
    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 containing Faces Client Data in your project, 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. Right-click on the Client Data in your JSP and select Configure.
    6. Select the Advanced tab. Click the Regenerate All button. This will regenerate all the artifacts needed for all Client Data on the current JSP.
    7. Repeat these steps for each JSP containing Client Data in your project.

    After regenerating the Client Data mediator classes for the JSPs in your project, 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.0. These mediators will have the naming convention *_DataGraphSchema_wdo4js_*.java and *_RootDataObject_wdo4js_*.java. Delete these mediator classes from your project to prevent these compile errors.

    After the migration completed successfully, restore the original contents of the OdysseyBrowserFramework.properties file.

  • Tree View Faces Client Components bound to WDOs fail to run on server after changing the project's target server to WebSphere Application Server V6.0.
    The workaround for this 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. To do so, you need to do the following steps:
  1. Generate the new Diff handlers and processors. To do so, on each Client Data Object in your project you must do the following:
    1. Select the Client Data Object, right-click and select Configure.
    2. On the Advanced tab, select 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. The following is an example of how the code might look:
    String Diff = getClientData1().getDiffStr();
    if (DiffProcessor.Synch(getRoot(), Diff) == true)
     return "";
    return "failure";
  3. Remove from your project the files corresponding to the old custom handlers and processors you created.
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 legacy 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 Client Components:
    • TabbedPanel: onInitialPageShow
    • Tree: onNodeExpand, onNodeCollapse, onExpand, onCollapse
    • DataGrid: onPage, onSort, onFilter
Related tasks
Migrating JavaServer Faces resources in a Web project
Migrating Faces resources in a portlet project
Terms of use | Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.