Migrating IBM Websphere Commerce Version 8 EJB entity beans to Java Persistence API

Enterprise Java Entity Beans are no longer supported in HCL Commerce Version 9. By using a combination of tools and manual steps, you can migrate your EJB 1.1 entity beans to JPA, and update your code to use HCL Commerce Version 9 APIs.

The well-established Java Persistence API (JPA) has numerous advantages, including simplicity and speed. To take advantage of JPA technology, you can use the Code Migration Tool to help you migrate existing beans to JPA. The Code Migration Tool scans EJB beans and identifies entities and code that need to be updated to the JPA specification. Where possible, the tool can perform substitutions, such as class, exception, and method name changes and removals. Where it is unable to make any changes, the utility logs what is found.
Note: Stateless Session EJBs are still supported and do not need to be migrated to JPA.

Before you begin

Export the following two projects from your IBM Websphere Commerce Version 8 development environment to your HCL Commerce Version 9.0.0.1+ development environment.
  • WebSphereCommerceServerExtensionsData
  • WebSphereCommerceServerExtensionsLogic
  1. Export the Stores dynamic web project (WebSphereCommerceServerExtensionsData) as a ZIP archive from your IBM Websphere Commerce Version 8 development environment workspace.
    1. Open your IBM Websphere Commerce Version 8 development environment workspace, then open the J2EE perspective.
    2. From the Enterprise Explorer view, right-click the WebSphereCommerceServerExtensionsData project, then click Export > Export .... The Export window is displayed.
    3. Expand the General folder, then click Archive File > Next.
    4. Under the WebSphereCommerceServerExtensionsData directory, clear the WebSphereCommerceServerExtensionsData check box, and select the following sub-directories:
      • ejbModule
      • classdiagram.dnx
    5. Ensure that the Create only selected directories option is selected.
    6. Click Browse and define a path where the archive file is to be exported.
    7. Click Finish. A WebSphereCommerceServerExtensionsData.zip archive file is created.
    8. Copy the exported WebSphereCommerceServerExtensionsData.zip archive file to your HCL Commerce Version 9 development environment so that it can be imported.
  2. Export the WebSphereCommerceServerExtensionsLogic Java project as a Java Archive (JAR) file from your IBM Websphere Commerce Version 8 development environment workspace.
    1. Open your IBM Websphere Commerce Version 8 development environment workspace, then open the J2EE perspective.
    2. Select the project that contains your customized code. Right-click, then select Export > Java > Jar file.
    3. Click Next.
    4. In the list of resources under Select the resources to export, ensure that your project is selected.
    5. Ensure that Export generated class files and resources and Export java source files and resources are selected.
    6. Click Browse and choose a path to save the exported Java archive file.
    7. Ensure Compress the contents of the file is selected.
    8. Click Finish. The WebSphereCommerceServerExtensionsLogic Java project is exported as a JAR file.
  3. Import the Stores dynamic web project (WebSphereCommerceServerExtensionsData) into your HCL Commerce Version 9 development environment.
    1. Open your HCL Commerce Version 9 development environment workspace, and then open the Java EE perspective.
    2. From the Enterprise Explorer view, right-click the WebSphereCommerceServerExtensionsData project, then click Import > Import .... The Import window is displayed.
    3. Expand the General folder, then click Archive File > Next.
    4. Click Browse and select the WebSphereCommerceServerExtensionsData.zip archive file that you exported from your IBM Websphere Commerce Version 8 development environment in step 1.
    5. Click the Overwrite existing resources without warning check box.
    6. Click Finish. The WebSphereCommerceServerExtensionsData project is replaced with the content from your IBM Websphere Commerce Version 8 development environment.
  4. Import the WebSphereCommerceServerExtensionsLogic Java project as a Java Archive (JAR) file into your HCL Commerce Version 9 development environment.
    1. Open your HCL Commerce Version 9 development environment workspace, and then open the Java EE perspective.
    2. Select Java EE perspective > Other Projects > WebSphereCommerceServerExtensionsLogic > src.
    3. Right click the target project and click Import. The Import window is displayed.
    4. Expand the General folder, then click Archive File > Next.
    5. Click Browse and select the WebSphereCommerceServerExtensionsLogic.jar Java archive file that you exported from your IBM Websphere Commerce Version 8 development environment in step 2.
      Note:
      • The class path for each custom project must be updated to resolve the dependencies on libraries and between projects.
      • Do not import any of the metadata, or your migration will fail. Metadata includes the following files:
        • .setting
          • org.eclipse.wst.common.component
          • org.eclipse.wst.common.project.facet.core.xml.factorypath
        • .project
        • .classpath
        • META-INF/
          • MANIFEST.MF
    6. If you are asked to overwrite any files, click Yes for each file.
    7. Click Finish. The WebSphereCommerceServerExtensionsLogic Java project is replaced with the content from your IBM Websphere Commerce Version 8 development environment.

About this task

The migration of your EJB 1.1 entity beans to JPA involves modifying two projects within your HCL Commerce Version 9.0.0.1+ development environment:
WebSphereCommerceServerExtensionsData
To migrate this project, you can use a combination of tools. You start by leveraging Rational Application Developer (RAD) to generate JPA entities from your database schema. You can then identify and correct any remaining errors that occurred from the JPA generation that is performed by RAD.
WebSphereCommerceServerExtensionsLogic
To migrate this project, you can manually convert EJB data beans to JPA data beans, and convert command classes to use JPA code, then use the Code Migration Tool to identify and correct any remaining errors that occurred from the manual conversions.

Procedure

  1. Migrate your custom EJB 1.1 EJBs and AccessBeans to JPA by using either the WC-JPA-Modeler, or the manual method.
    • Obtain the WC-JPA-Modeler and follow the contained README file for instructions on its usage.
    • For the manual method, complete the following steps.
      1. By using RAD, generate JPA entities from your database schema for your WebSphereCommerceServerExtensionsData project.
        1. Open Rational Application Developer.
        2. Right-click WebSphereCommerceServerExtensionsData, then click Rename.
        3. Back up the project by renaming it to something else, for example, WebSphereCommerceServerExtensionsData-EJB.
        4. Right-click the WC project, then click Properties > Deployment Assembly to change what is included in the Enterprise Archive (EAR).
        5. Click the WebSphereCommerceServerExtensionsData project that you renamed, for example, WebSphereCommerceServerExtensionsData-EJB. Then, click Remove > OK.
        6. Click File > New > JPA Project.
        7. For the project name, enter WebSphereCommerceServerExtensionsData.
        8. In the EAR membership section, click Add project to an EAR, select WC for your EAR project name, then click Finish.
          Note: If you are asked to change the perspective to the JPA perspective, click Yes.
        9. Switch to your Data source Explorer.
        10. Right-click Database Connections, then click New.
        11. Select a database manager:
          • DB2For DB2 for Linux, UNIX, and Windows:
            1. Select JDBC driver IBM Data Server Driver for JDBC and SQLJ (JDBC 4.0) Default.
            2. Complete the fields for Database, Host, Port number, User name, Password, and Default schema.
            3. Click Finish.
          • OracleFor Oracle:
            1. Select JDBC driver Oracle 12 - Oracle Thin Driver Default.
            2. Click the ellipsis button (...) next to the JDBC driver, add or edit your JDBC driver, then click Ok.
            3. Fill out SID, Host, Port number, User name, Password, Default schema.
            4. Click Finish.
        12. Right-click the JPA project in the Project Explorer, then click JPA Tools > Generate Entities from Tables.
        13. On the Select tables page of the Generate Entities from Tables wizard, select the database connection that you created.
        14. Complete the wizard, then click Finish.
        15. Build your project by clicking Projects > Build All.
      2. Convert your EJB data beans to JPA data beans in your WebSphereCommerceServerExtensionsLogic project.
        1. Open a data bean class.
        2. Remove the references to the methods removed in the WebSphereCommerceServerExtensionsData project.
        3. Remove code references to the following exceptions by removing them from throws clauses in method declarations, and removing catch clauses that catch them.
          • java.rmi.RemoteException
          • javax.naming.NamingException
        4. Replace code references to the following exceptions by the appropriate javax.persistence.PersistenceException subclass by replacing them in throws clauses in method declarations, and replacing catch clauses that catch them.
          • javax.ejb.CreateException
          • javax.ejb.FinderException
        5. Find all references to the setEJBRef(...) method and update the method name to setEntity.
        6. Find all references to .getEJBRef().remove() and update them to: .remove().
        7. Find all references to the getEJBRef() method and update the method name to getEntity.
        8. Repeat these substeps for all of your data bean classes.
      3. Convert your command classes to use JPA code in your WebSphereCommerceServerExtensionsLogic project.
        1. Open a command class.
        2. Remove the references to the methods removed in the WebSphereCommerceServerExtensionsData project.
        3. Remove code references to the following exceptions by removing them from throws clauses in method declarations, and removing catch clauses that catch them.
          • java.rmi.RemoteException
          • javax.ejb.CreateException
          • javax.ejb.FinderException
          • javax.naming.NamingException
        4. Update the logic to coincide with JPA.
        5. Repeat these substeps for every command class.
  2. Update all references to the default EJB 1.1 EJBs and AccessBeans to JPA.
    • Use the following tables as a reference for your required changes.
      Change all uses of any class of the form To
      com.ibm.commerce.*BeanFinderObject com.ibm.commerce.*QueryHelper.
      com.ibm.commerce.*BeanFinderObjectBase com.ibm.commerce.*QueryHelperBase.
      com.ibm.commerce.base.objects.JDBCFinderObject com.ibm.commerce.base.objects.QueryHelper.
      com.ibm.commerce.*BeanBase com.ibm.commerce.*EntityBase.
      com.ibm.commerce.base.objects.ECEntityBean com.ibm.commerce.base.objects.EntityBase.
      com.ibm.commerce.*BeanAccessHelper com.ibm.commerce.*AccessHelper.
      Remove all uses of: Additional notes:
      com.ibm.commerce.*AccessBeanData None
      com.ibm.commerce.*Key Where it represented a primary key that is composed of only a single column in the corresponding table.
      com.ibm.commerce.*JDBCHelper Including any class that also had javax.ejb.EJBObject as a superclass
      com.ibm.commerce.*JDBCHelperAccessBean
      • For EJB 1.1:

        None

      • For EJB 3 and above:

        Session beans were moved from EJB 1.1 to EJB 3.

        The session bean EJBs were changed to remove the home and remote interfaces and are now simple beans annotated with the Stateless annotation: @Stateless(name="ServerJDBCHelper")

        The access bean classes for session beans were removed.

        SessionBeanHelper.lookupSessionBean is recommended.
      com.ibm.commerce.*JDBCHelperFactory None
      com.ibm.commerce.*JDBCHelperHome None
      com.ibm.commerce.*Home. Replace it by using the appropriate JPA entity directly, or use the corresponding AccessBean class.
      com.ibm.commerce.*AccessBeanData None
      • javax.naming.NamingException
      • java.rmi.RemoteException
      		 Where these exceptions were thrown by methods in IBM Websphere Commerce Version 8.
      • javax.ejb.CreateException
      • javax.ejb.FinderException
      		 Where these exceptions were thrown by methods in IBM Websphere Commerce Version 8. Replace these by the appropriate javax.persistence.PersistenceException subclass.
      javax.ejb.DuplicateKeyException Where these exceptions were thrown by methods in IBM Websphere Commerce Version 8. Replace these exceptions with javax.persistence.EntityExistsException.
      ejbCreate() From any class of the form com.ibm.commerce.*
      ejbPostCreate() From any class of the form com.ibm.commerce.*BeanBase.
      ejbPostCreate() From any class of the form com.ibm.commerce.*BeanAccessHelper.
      getSessionContext() From any class of the form com.ibm.commerce.*.
      ejbActivate() From any class of the form com.ibm.commerce.*.
      ejbCreate() From any class of the form com.ibm.commerce.*.
      ejbPassivate() From any class of the form com.ibm.commerce.*.
      ejbRemove() From any class of the form com.ibm.commerce.*.
      instantiateEJBByPrimaryKey() From any class of the form com.ibm.commerce.*AccessBean.
      defaultJNDIName() From any class of the form com.ibm.commerce.*AccessBean.
      commitCopyHelper() From any class of the form com.ibm.commerce.*AccessBean.
      refreshCopyHelper() From any class of the form com.ibm.commerce.*AccessBean.
      copyFields() From any class of the form com.ibm.commerce.*EntityCreationData.
      getMemorySizeExcludingObjectsToScrub() From any class of the form com.ibm.commerce.*Key.
      getObjectsToScrub() From any class of the form com.ibm.commerce.*Key.
      getObjectSize() From any class of the form com.ibm.commerce.*Key.
      setScrubbedObjects() From any class of the form com.ibm.commerce.*Key.
      getObjectModelFacade() From any class of the form com.ibm.commerce.*.
      getOMF() From any class of the form com.ibm.commerce.*.
      getObjectModuleFacade() From any class of the form com.ibm.commerce.*.
      getPPCJDBCHelper() From any class of the form com.ibm.commerce.*.
      getPaymentsFacade() From any class of the form com.ibm.commerce.*.
      getActivityLoggerFacade() From any class of the form com.ibm.commerce.*.
      get*InEJBType() From any class of the form com.ibm.commerce.*. Replace with get*InEntityType.
      instantiateEJB() From any class of the form com.ibm.commerce.*AccessBean. Replace with instantiateEntity.
      Reads and Writes of all public fields in classes of the form com.ibm.commerce.*BeanBase with the corresponding getter or setter method. Getters and setters for some foreign key fields are replaced by a getter/setter that gets/sets a parent or child JPA entity.
      Note:
      • If you added your own customizations to the JSP files that use EJB technology, you must migrate your customizations. Use the previous tables as a reference to help with the migration.
      • In some cases where EJB's have access control policies applied, your JPA entity bean will need to implement the Groupable or Protectable interface, to comply with same security and policy scheme.
        • For a Protectable interface, you must implement the fulfills and getOwner methods. For more information, see Protectable interface.
        • For a Groupable interface, you must implement the getGroupingAttributeValue method. For more information, see Groupable interface.