Integrating HCL Commerce version 9 with WebSphere eXtreme Scale

Integrate with WebSphere eXtreme Scale to improve high-volume performance.

Overview

Before you decide to integrate HCL Commerce with WebSphere eXtreme Scale, review the benefits of the integration, the prerequisites, and the necessary configuration steps. For IBM HCL Commerce version 9.0.0.7 and later, you can integrate with IBM WebSphere eXtreme Scale to improve performance in your high-volume implementation. The WebSphere eXtreme Scale licensed program is an elastic, scalable, in-memory data grid that you can use as an advanced cache for WebSphere Commerce. WebSphere eXtreme Scale processes a massive transaction volume with high efficiency and linear scalability. Integrating with WebSphere eXtreme Scale can provide significant performance benefits for high volume HCL Commerce customers.

WebSphere eXtreme Scale was used in HCL Commerce version 7.x and 8.x as an external cache provider.

Prerequisites

To integrate WebSphere eXtreme Scale with HCL Commerce, the following versions are required:
  • The required WebSphere eXtreme Scale server version is 8.6.1.2 or later. From this version, WebSphere eXtreme Scale clients that run in both traditional WebSphere Application Server and WebSphere Application Server Liberty can simultaneously access the same WebSphere eXtreme Scale server.
  • The required HCL Commerce version is 9.0.0.7 or later. From this version, the WebSphere eXtreme Scale client is packaged in Application Server Docker (for the HCL Commerce Transaction server, Store server, and Search server).
Additionally, you need to select a cache instance for WebSphere eXtreme Scale. The WebSphere Commerce internal cache is developed using the WebSphere Application Server DynaCache API, and this cache is organized by cache instances. WebSphere eXtreme Scale provides transparent support for the DynaCache API, so it can be used as the cache provider for any HCL Commerce cache instance.
Important: Do not put all of your cache instances into WebSphere eXtreme Scale. If you put unsuitable cache instances into WebSphere eXtreme Scale, it may cause loss of functionality or severe performance issues. Cache instances are suitable to be put into WebSphere eXtreme Scale under the following circumstances:
  • The cache-miss cost is much higher than cache-hit cost, which means that improving the cache-hit ratio can significantly improve performance.
  • The cache object is large sized, or the total number of cache entries is very large (for example, millions of cache entries). In this circumstance, storing the cache instance in the Application Server local Java Virtual Machine requires a very large heap size.
  • When cache-invalidation events do not frequently occur, which means that there is not a large number of invalidation calls issued to WebSphere eXtreme Scale.
The criteria used to determine if a cache instance is suitable for use in WebSphere eXtreme Scale is determined by your actual workload pattern. Therefore, you need to do performance testing to determine if a cache instance is suitable for WebSphere eXtreme Scale. Some cache instances (for example, services/cache/SearchCatHierarchyDistributedMapCache on the Search server) use a data source that is not centrally stored (that is, not a database). This type of cache instance should not be put into WebSphere eXtreme Scale to avoid a cache invalidation issue.
Before you begin
Although the WebSphere eXtreme Scale client is packaged in application Docker containers, the WebSphere eXtreme Scale connection is not enabled by default. To enable the WebSphere eXtreme Scale integration, you must perform the configuration steps in this tutorial.
Additionally, there are Run Engine commands in HCL Commerce that can simplify the configuration procedure if you build a customized Docker container.
Important: These commands can be run during testing or building a customized Docker image, but these commands should not be run in a production container.

Procedure

1. Configuring the Transaction server

The procedure for configuring the Transaction server is different than the one used to configure the Search server and Store server, because the server environment is traditional WebSphere Application Server rather than Liberty.

  1. Execute the Run Engine command create-xs-domain to create a WebSphere eXtreme Scale domain. The WebSphere eXtreme Scale catalog server host name and port are needed to execute the create-xs-domain Run Engine command. For example:
    run create-xs-domain test.cn.ibm.com 2809

    In this example, test.cn.ibm.com is the host name of the WebSphere eXtreme Scale catalog server, and 2809 is the listening port.

    This step creates the catalogservice.xml configuration file in the traditional WebSphere Application Server configuration repository.

    Note: Run step 1 only one time.
  2. Connect the specific cache instance to WebSphere eXtreme Scale. You need the Java Naming and Directory Interface cache instance name and the new cache size to execute the connect-basecache-wxs Run Engine command.
    • For the BaseCache, call connect-basecache-wxs. For example:
      run connect-basecache-wxs 5000
      In this example, 5000 is the new cache size for baseCache. The baseCache configuration file is server.xml, and the configuration file for other cache instances is resources-pme502.xml.
      Note: The command for baseCache is different for other cache instances, because the configuration file that is updated is different.
    • For other Cache instances, call connect-objectcache-wxs. For example: 
      run connect-objectcache-wxs services/cache/WCLayoutDistributedMapCache 1000
      In this example, services/cache/WCLayoutDistributedMapCache is the target cache instance Java Naming Directory Interface name and 1000 is the new cache size.

      You must specify the new cache size when you connect a specific cache instance to WebSphere eXtreme Scale because the total cache entry number calculation is different when using the default (local) cache provider than when using the WebSphere eXtreme Scale cache provider. When the default cache provider is used, the total cache entry number is determined only by the CacheSize parameter of the cache instance.

      When the WebSphere eXtreme Scale cache provider is used, the total cache entry number equals CacheSize*Partition-number/Replica-number. In this scenario, Patition-number and Replica-number are determined by the WebSphere eXtreme Scale server side configuration.

      Therefore, when you put a cache instance into WebSphere eXtreme Scale, the CacheSize parameter must be adjusted according to the WebSphere eXtreme Scale server side configuration.
      Important: Ignoring the cache size specification may cause unexpected behavior, such as an out-out-memory error on the WebSphere eXtreme Scale server.

      Additionally, in this procedure, step 2 puts only one cache instance into WebSphere eXtreme Scale. If you need to put multiple cache instances into WebSphere eXtreme Scale, run step 2 one time for each needed cache instance.

    This is a sample Docker file to customize the Transaction server Docker image by leveraging the Run Engine commands to enable WebSphere eXtreme Scale integration:
    FROM repname/library/ts-app:tsapp

RUN run create-xs-domain test.cn.ibm.com 2809 && \

run connect-basecache-wxs 2000 && \

run connect-objectcache-wxs services/cache/DM_UserCache 10000 && \

run connect-objectcache-wxs services/cache/WCPriceDistributedMapCache 5000 && \

...

2. Configuring the Search server and Store server

The procedure for configuring the Search server and Store server is different than the one that is used to configure the Transaction server, because the server environment is Liberty rather than traditional WebSphere Application Server.

  1. Enable the Elastic Cache feature. The WebSphere eXtreme Scale catalog server host name and port are needed to execute the enable-xs-feature Run Engine command. For example: 
    run enable-xs-feature test.cn.ibm.com 2809
    In this example, test.cn.ibm.com is the host name of the WebSphere eXtreme Scale catalog server, and 2809 is the listening port.

    This step creates a configuration file (elasticCache.xml) in the Liberty configDropins folder. The file content includes enabling the elasticCacheClient-1.0 feature and defining a default elasticCacheClient (with the specified WebSphere eXtreme Scale host name and port).

  2. Connect the specific cache instance to WebSphere eXtreme Scale. The Java Naming Directory Interface Cache instance name and new cache size are needed to execute the connect-searchcache-wxs and connect-crscache-wxs Run Engine commands.
    • For the Search server, call connect-searchcache-wxs. For example:
      run connect-searchcache-wxs services/cache/SearchFacetDistributedMapCache 2000
      In this example, services/cache/SearchFacetDistributedMapCache is the target cache instance Java Naming Directory Interface name and 2000 is the new cache size.
      Note: The command for the Search server is different than the command for Store server because the configuration pattern in the configuration file is different.
    • For the Store server, call connect-crscache-wxs. For example: 
      run connect-crscache-wxs services/cache/WCLayoutDistributedMapCache 2000
      In this example, services/cache/WCLayoutDistributedMapCache is the target cache instance Java Naming Directory Interface name and 2000 is the new cache size.
      Note: Unlike with the Transaction server, there is no differentiation between baseCache and other cache instances. Therefore, you use the same Run Engine command for both the Search server and Store server, and the baseCache Java Naming Directory Interface name is baseCache.
    This is a sample Docker file to customize the Search server Docker image by leveraging the Run Engine commands to enable WebSphere eXtreme Scale integration:
    FROM repname/library/search-app:searchapp

RUN run enable-xs-feature test.cn.ibm.com 2809 && \

run connect-searchcache-wxs services/cache/SearchFacetDistributedMapCache 2000 && \

...
    This is a sample Docker file to customize the Store server Docker image by leveraging the Run Engine commands to enable WebSphere eXtreme Scale integration:
    FROM repname/library/crs-app:crsapp

RUN run enable-xs-feature test.cn.ibm.com 2809 && \

run connect-crscache-wxs baseCache 2000 && \

run connect-crscache-wxs services/cache/WCLayoutDistributedMapCache 1000 && \

...

3. Advanced configuration

When you do the basic configuration steps (step 1 and step 2), all cache instances are put in the default WebSphere eXtreme Scale grid named DYNACACHE_REMOTE. Different cache instances are put in different maps, and the name pattern is IBM_DC_PARTITIONED_ plus the cache instance name.

Based on performance or other considerations, you can put cache instances into a specific WebSphere eXtreme Scale grid and map. In this scenario, two more parameters are required when you execute the Run Engine commands for step 2.

For example:
run connect-searchcache-wxs services/cache/SearchFacetDistributedMapCache 2000 searchGrid MapA
In this example, searchGrid is the target GridName and MapA is the target MapName.

Limitations

These assumptions were made during the development of the Run Engine commands, which can limit your usage of the commands. To circumvent these limitations, you must configure HCL Commerce differently (for example, by updating the configuration file directly).

Cache invalidation between Transaction server and Store server
When one cache instance of the Store server is put in to WebSphere eXtreme Scale, the corresponding cache instance (with the same Java Naming Directory Interface name) of the Transaction server must also be put into WebSphere eXtreme Scale (using the same catalog server, the same grid, and the same map). Otherwise, the cache content generated by the Store server cannot be correctly invalidated by an invalidation message from the Transaction server.
Single WebSphere eXtreme Scale catalog server limitation
The current Run Engine command implementation only creates one default WebSphere eXtreme Scale catalog server (host name and port) in the configuration file. Therefore, all the cache instances must access the same WebSphere eXtreme Scale catalog server. You may want different cache instances to access different WebSphere eXtreme Scale catalog servers for high-availability consideration. In this scenario, you can implement it using a virtual IP or dynamic DNS. However, if you want to specify a different WebSphere eXtreme Scale server host name for different cache instances, you can only do so in the Liberty environment for Store Server and Search Server. Additionally, you need to modify the configuration file directly to create multiple elasticCacheClient entries.
Limitation on using gridName and mapName in the Liberty environment
For advanced configuration in Liberty environment, the gridName and mapName parameters must be unique. This means you cannot put two different cache instances of Search server or Store server into the same non-default grid.
Note: There is not a similar limitation on the Transaction server in traditional WebSphere Application Server environment.

Known issues

First Failure Data Capture exception in Transaction server
For advanced configuration, when the gridName parameter is specified in Transaction server in a traditional WebSphere Application Server environment, a First Failure Data Capture exception regarding the gridName parameter occurs in the log. An example of the exception message is:
FFDC Exception:java.lang.NoSuchFieldException SourceId:com.ibm.ws.util.FieldInitializer ProbeId:133 Reporter:java.lang.Class@fdc0cd34

java.lang.NoSuchFieldException: grid_name

...
This exception can be ignored because the functionality still works and the exception only happens during server start up.
Cache Monitor issue in Transaction server
The Extended Cache Monitor is used to analyze the cache behavior in a traditional WebSphere Application Server environment. However, when a cache instance uses WebSphere eXtreme Scale as cache provider, you cannot view the Cache Contents (a blank page is displayed) even though there is no issue in the Liberty Cache Monitor.
To bypass this issue, extract the contents.jsp file from webCacheMonitor-1.0.tar.gz (which is packaged in the Search server Docker and Store server Docker). This file is located in com.ibm.ws.dynacache.cachemonitor_1.0.13.jar. Replace this file with one with a similar name in the traditional WebSphere Application Server CacheMonitor.war.
Warning about conflict configuration in Search server and Store server
The WebSphere eXtreme Scale-related configuration is put in elasticCache.xml file under the Liberty configDropins folder. Additionally, the same configuration value (for example, cacheSize) resides in the default configuration file (server.xml). An example of the conflict configuration warning message in the Liberty log is:
com.ibm.ws.config.xml.internal.ConfigValidator A CWWKG0102I: Found conflicting settings for baseCache instance of distributedMap configuration.

Property memorySizeInEntries has conflicting values:

Value 1000 is set in file:/opt/WebSphere/Liberty/usr/servers/default/server.xml.

Value 2000 is set in file:/opt/WebSphere/Liberty/usr/servers/default/configDropins/overrides/elasticCache.xml.

Property memorySizeInEntries will be set to 2000.
This warning is expected and can be ignored.

Result

You integrated HCL Commerce with WebSphere eXtreme Scale to improve the performance of your high-volume implementation.