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
- WebSphereCommerceServerExtensionsData
- WebSphereCommerceServerExtensionsLogic
- Export the Stores dynamic web project
(WebSphereCommerceServerExtensionsData) as a ZIP archive from your IBM Websphere Commerce Version 8 development environment workspace.
- Open your IBM Websphere Commerce Version 8 development environment workspace, then open the J2EE perspective.
- From the Enterprise Explorer view, right-click the
WebSphereCommerceServerExtensionsData
project, then click . The Export window is displayed. - Expand the General folder, then click .
- Under the WebSphereCommerceServerExtensionsData directory, clear the
WebSphereCommerceServerExtensionsData check box, and select the following
sub-directories:
- ejbModule
- classdiagram.dnx
- Ensure that the Create only selected directories option is selected.
- Click Browse and define a path where the archive file is to be exported.
- Click Finish. A WebSphereCommerceServerExtensionsData.zip archive file is created.
- Copy the exported WebSphereCommerceServerExtensionsData.zip archive file to your HCL Commerce Version 9 development environment so that it can be imported.
- Export the
WebSphereCommerceServerExtensionsLogic
Java project as a Java Archive (JAR) file from your IBM Websphere Commerce Version 8 development environment workspace.- Open your IBM Websphere Commerce Version 8 development environment workspace, then open the J2EE perspective.
- Select the project that contains your customized code. Right-click, then select .
- Click Next.
- In the list of resources under Select the resources to export, ensure that your project is selected.
- Ensure that Export generated class files and resources and Export java source files and resources are selected.
- Click Browse and choose a path to save the exported Java archive file.
- Ensure Compress the contents of the file is selected.
- Click Finish. The
WebSphereCommerceServerExtensionsLogic
Java project is exported as a JAR file.
- Import the Stores dynamic web project
(WebSphereCommerceServerExtensionsData) into your HCL Commerce Version 9
development environment.
- Open your HCL Commerce Version 9 development environment workspace, and then open the Java EE perspective.
- From the Enterprise Explorer view, right-click the
WebSphereCommerceServerExtensionsData
project, then click . The Import window is displayed. - Expand the General folder, then click .
- Click Browse and select the WebSphereCommerceServerExtensionsData.zip archive file that you exported from your IBM Websphere Commerce Version 8 development environment in step 1.
- Click the Overwrite existing resources without warning check box.
- Click Finish. The
WebSphereCommerceServerExtensionsData
project is replaced with the content from your IBM Websphere Commerce Version 8 development environment.
- Import the
WebSphereCommerceServerExtensionsLogic
Java project as a Java Archive (JAR) file into your HCL Commerce Version 9 development environment.- Open your HCL Commerce Version 9 development environment workspace, and then open the Java EE perspective.
- Select .
- Right click the target project and click Import. The Import window is displayed.
- Expand the General folder, then click .
- 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
- .setting
- If you are asked to overwrite any files, click Yes for each file.
- 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
- 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.
- By using RAD, generate JPA entities from your database schema for your
WebSphereCommerceServerExtensionsData project.
- Open Rational Application Developer.
- Right-click WebSphereCommerceServerExtensionsData, then click Rename.
- Back up the project by renaming it to something else, for example,
WebSphereCommerceServerExtensionsData-EJB
. - Right-click the WC project, then click to change what is included in the Enterprise Archive (EAR).
- Click the WebSphereCommerceServerExtensionsData project that you renamed, for example, WebSphereCommerceServerExtensionsData-EJB. Then, click .
- Click .
- For the project name, enter WebSphereCommerceServerExtensionsData.
- 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.
- Switch to your Data source Explorer.
- Right-click Database Connections, then click New.
- Select a database manager:
- For DB2 for Linux, UNIX, and Windows:
- Select JDBC driver IBM Data Server Driver for JDBC and SQLJ (JDBC 4.0) Default.
- Complete the fields for Database, Host, Port number, User name, Password, and Default schema.
- Click Finish.
- For Oracle:
- Select JDBC driver Oracle 12 - Oracle Thin Driver Default.
- Click the ellipsis button (...) next to the JDBC driver, add or edit your JDBC driver, then click Ok.
- Fill out SID, Host, Port number, User name, Password, Default schema.
- Click Finish.
- For DB2 for Linux, UNIX, and Windows:
- Right-click the JPA project in the Project Explorer, then click .
- On the Select tables page of the Generate Entities from Tables wizard, select the database connection that you created.
- Complete the wizard, then click Finish.
- Build your project by clicking .
- Convert your EJB data beans to JPA data beans in your
WebSphereCommerceServerExtensionsLogic project.
- Open a data bean class.
- Remove the references to the methods removed in the WebSphereCommerceServerExtensionsData project.
- Remove code references to the following exceptions by removing them from
throws
clauses in method declarations, and removingcatch
clauses that catch them.java.rmi.RemoteException
javax.naming.NamingException
- Replace code references to the following exceptions by the appropriate
javax.persistence.PersistenceException
subclass by replacing them inthrows
clauses in method declarations, and replacingcatch
clauses that catch them.javax.ejb.CreateException
javax.ejb.FinderException
- Find all references to the
setEJBRef(...)
method and update the method name tosetEntity
. - Find all references to
.getEJBRef().remove()
and update them to:.remove()
. - Find all references to the
getEJBRef()
method and update the method name togetEntity
. - Repeat these substeps for all of your data bean classes.
- Convert your command classes to use JPA code in your
WebSphereCommerceServerExtensionsLogic project.
- Open a command class.
- Remove the references to the methods removed in the WebSphereCommerceServerExtensionsData project.
- Remove code references to the following exceptions by removing them from
throws
clauses in method declarations, and removingcatch
clauses that catch them.java.rmi.RemoteException
javax.ejb.CreateException
javax.ejb.FinderException
javax.naming.NamingException
- Update the logic to coincide with JPA.
- Repeat these substeps for every command class.
- By using RAD, generate JPA entities from your database schema for your
WebSphereCommerceServerExtensionsData project.
-
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
andgetOwner
methods. For more information, see Protectable interface. - For a Groupable interface, you must implement the
getGroupingAttributeValue
method. For more information, see Groupable interface.
- For a Protectable interface, you must implement the
- For EJB 1.1:
- Use the
following tables as a reference for your required changes.