Migrating the HCL Commerce Version 9.1 code to Commerce+

To migrate your HCL Commerce Version 9.1 code to Commerce+, run the migration commands. This procedure applies to customers migrating Version 9.1 code for use with the Transaction server in Commerce+. It does not apply to customers migrating to PBC mode. As part of this migration, you must remove all IBM-related code, such as com.ibm.commerce, and include only the code that is proprietary to your organization.

Procedure

  1. Download the migration utility from IBM WebSphere.
  2. Extract or install the Open Liberty Migration Toolkit, following the migration tool instructions.
  3. Run the Open Liberty Migration Toolkit, pointing it to the location of your workspace.
  4. Review the tool’s output, a scan report that includes sections matching the table provided.
  5. Use the following table, together with the report actions, to facilitate the code migration.
    Messages Required Action
    ThreadManagement classes com.ibm.commerce.threadmanagement.* this is changed to com.hcl.commerce.threadmanagement.*
    The WebSphere Service Data Objects (SDO) APIs are unavailable Replacing Eclipse modeling framework service data objects with Eclipselink and the Java Persistence API
    Java API for XML-based RPC (JAX-RPC) is unavailable
    1. Validate service calls:
      • Test a few service calls related to the component you're working on.
      • You can use request bodies from the Web Service Reference Page.
    2. Import the following projects into your workspace:
      • <Component>-Server.jar
      • <Component>ServicesHTTPInterface.war
    3. Modify <Component>ServicesHTTPInterface.war:
      • Update the servlet version level to 3.1 in the following file: 
        src/projects/<Component>ServicesHTTPInterface/.settings/org.eclipse.wst.common.project.facet.core.xml
      • Update the servlet name in web.xml to point to the service implementation class: com.ibm.commerce.<Component>.facade.server.<Component>ServicesImpl
    4. Modify <Component>-Server.jar:
      • Set EJB module level to 3.1: src/projects/<Component>-Server/.settings/org.eclipse.wst.common.project.facet.core.xml
      • Delete the following files and references:

        • JAX-RPC specific mapping file: <Component>Services_mapping.xml

        • version="1.2" from ejb-jar.xml files (this caused issues with Open Liberty)

        • pc binding from ibm-webservices-bnd.xmi (keep only router mapping)

        • ibm-webservices-ext.xmi

        • webservices.xml (optional due to annotated port/service classes)

      • Add or Modify the following:
        • Create jws-handler-chains.xml to list handlers and map to the service.
        • Locate service code under: com.ibm.commerce.<Component>.facade.server
        • Use the provided code skeleton to implement the service methods in <Component>ServicesImpl.java
        • Annotate the class with @HandlerChain, and replace SOAPElement with Object
        • Override ComponentServicesPortType.java with the provided version.
        • Copy ObjectFactory.java into the same package.
        • Update the MANIFEST.MF file with:
          Include-Scanning-Packages:
          com.ibm.commerce.<component>.facade.server
        • Ensure copyright comments are updated.
    5. Update WC.ear:
      • Remove <Component>-Server.jar from the Ignore-Scanning-Archives list in the manifest.
    CommonJ Timer and Work Manager APIs are unavailable on Liberty According to Examples to migrate to EE Concurrency, alternative interfaces can be used to migrate CommonJ work managers to Java EE concurrency utilities (such as ExecutorService and ManagedExecutorService).
    The WAS Performance Monitoring Infrastructure (PMI) APIs and SPIs are unavailable If there is custom code or functionality that depends on PMI, you must remove it and adopt a Grafana-compatible solution instead.
    The WebSphere Servlet API was superseded by a newer implementation Classes in the Servlet API have changed, and this functionality is no longer provided. Reimplementation is required.
    The WebSphere logging and RAS APIs and SPIs are unavailable The following classes have been deprecated because they include WebSphere Application Server (WAS)-specific functionality that does not exist in Liberty.

    Any code that references these deprecated classes must be updated to use the new replacements.

    • Deprecated Classes:
      • com.ibm.commerce.ras.WASLog
      • com.ibm.commerce.ras.WASTrace
      • com.ibm.commerce.edp.utils.EDPLog
      • com.ibm.commerce.edp.utils.EDPTrace
    • Replacement Classes
      Use the following classes instead of the deprecated ones:
      • com.hcl.commerce.ras.WASLog
      • com.hcl.commerce.ras.WASTrace
      • com.hcl.commerce.edp.utils.EDPLog
      • com.hcl.commerce.edp.utils.EDPTrace
    WebSphere Asynch. Beans API was superseded by a newer implementation Use the same design approach that was adopted to replace the CommonJ Work Manager implementation.
    The WebSphere Common Exception APIs are unavailable Replace all instances of com.ibm.websphere.ce.cm.DuplicateKeyException with java.sql.SQLIntegrityConstraintViolationException
    Getting the server name on Liberty Replace com.ibm.websphere.runtime.ServerName with com.hcl.commerce.common.utils.FoundationUtil.getTransactionServerName()
    The WSSecurityHelper revokeSSOCookies method is deprecated Replace WSSecurityHelper.revokeSSOCookies() with HttpServletRequest.logout()
    Missing dependency com.ibm.ws.cache.servlet
    • Use com.hcl.commerce.pagelayout.cache.PageLayoutTagHelper instead of com.ibm.commerce.pagelayout.cache.PageLayoutTagHelper
    • Use com.ibm.websphere.servlet.cache.ServletCacheRequest to retrieve com.ibm.websphere.servlet.cache.FragmentInfo as an alternative to com.ibm.ws.cache.servlet.FragmentInfo (previously found in com.ibm.websphere.appserver.api.webCache-1.1.65.jar)
    Missing dependency com.ibm.bsf.BSFManager API Use org.apache.bsf.BSFManager instead of com.ibm.bsf.BSFManager. The replacement class can be found by adding the following Maven dependency: 
    <dependency>
  <groupId>bsf</groupId>
  <artifactId>bsf</artifactId>
  <version>2.4.0</version>
</dependency>
    Missing dependency com.ibm.misc.BASE64Encoder Use sun.misc.BASE64Encoder instead of com.ibm.misc.BASE64Encoder
    Missing dependency com.ibm.ivj.ejb.runtime
    • Use java.util.Hashtable instead of com.ibm.ivj.ejb.runtime.AccessBeanHashtable.
    • Use com.hcl.commerce.persistence.AccessBeanNullValue instead of com.ibm.ivj.ejb.runtime.AccessBeanNullValue.
    • Use com.ibm.commerce.persistence.AbstractJpaEntityAccessBean instead of com.ibm.ivj.ejb.runtime.AbstractEntityAccessBean.
    Missing dependency com.ibm.vap APIs Use com.hcl.commerce.base.helpers.AbstractConverter instead of com.ibm.vap.converters.VapAbstractConverter
    Missing dependency com.ibm.jsse and com.ibm.jsse2 APIs Use sun.security.provider.Sun instead of com.ibm.jsse2.IBMJSSEProvider2
    Remove the ComponentMetadata dependency Use com.hcl.commerce.foundation.server.services.dataaccess.db.ComponentBaseMetadata instead of com.ibm.commerce.foundation.server.services.dataaccess.db.jdbc.ComponentMetadata
    Some WebSphere Security APIs and SPIs are unavailable When importing com.ibm.websphere.security.*, it can be found by using the Maven Open Liberty library: com.ibm.websphere.appserver.api.basics-1.2.16.jar
    Review use of the dynamic cache service Use com.ibm.wsspi.cache.web.CacheMonitor instead of com.ibm.wsspi.cache.CacheMonitor

    This class is available in the following Open Liberty Maven library:

    com.ibm.websphere.appserver.spi.webCache-1.0.65.jar
    The WebSphere Enterprise JavaBeans APIs and SPIs are unavailable

    These are mostly related to EJB code that has been deprecated. We are now using JPA instead of EJB CMPs.
    Use the default InitialContext JNDI properties Use ctx = new javax.naming.InitialContext(); instead of ctx = new javax.naming.InitialContext(jndiProperties);
    Transaction propagation is not supported for Enterprise JavaBeans (EJB) remote interfaces Removed references to <remote> for the affected EJBs.
    The WebSphere Management APIs and SPIs are unavailable
    • Use com.hcl.commerce.base.helpers.BaseJDBCHelper instead of com.ibm.commerce.base.helpers.BaseJDBCHelper
    • Use com.hcl.commerce.base.objects.ECAbstractEntityBean instead of com.ibm.commerce.base.objects.ECAbstractEntityBean
    • Use com.hcl.commerce.base.objects.ECEntityBean instead of com.ibm.commerce.base.objects.ECEntityBean
    IBM JSON4J ClassNotFound The IBM json4j.jar file is deprecated. In Commerce+ the corresponding library is wink-json4j-1.4.jar. In previous Commerce versions, packages and classes such as org.apache.commons.json.* were located inside json4j.jar. Corresponding classes are now named org.apache.wink.json4j.*. Find and replace any references to the deprecated packages and classes. For example, 
    org.apache.commons.json.JSONArray
org.apache.commons.json.JSONObject
    in JSON4J.jar becomes 
    org.apache.wink.json4j.JSONArray 
org.apache.wink.json4j.JSONObject
    in the replacement Wink .jar file.

    When building new customizations, refer to the new .jar file.