+

Search Tips   |   Advanced Search

Configure dynamic cache (DynaCache) to use the WebSphere eXtreme Scale dynamic cache provider

The dynamic cache engine is the default cache provider for the dynamic cache APIs and framework. However, dynamic cache allows WebSphere eXtreme Scale to act as its core caching engine. We can configure dynamic cache to use WebSphere eXtreme Scale as the cache provider instead of the default dynamic cache engine. Configuring dynamic cache to use WebSphere eXtreme Scale lets you leverage transactional support, improved scalability, high availability, and other WebSphere eXtreme Scale features without changing the existing dynamic cache caching code.

If we decide that is beneficial for the applications, use the information provided in the "Configuring the dynamic cache provider for WebSphere eXtreme Scale" section of the WebSphere eXtreme Scale Version 7.0 Product Overview to determine the appropriate WebSphere eXtreme Scale topology for the caching deployment.

If we use WebSphere eXtreme Scale, instead of the default dynamic cache engine, dynamic cache has the following limitations:

Complete the following actions to enable the WebSphere eXtreme Scale dynamic cache provider.

  1. Install the WebSphere eXtreme Scale client, or the WebSphere eXtreme Scale client and server packages in the application server for the remote server and the other topologies respectively.

    (zos) Avoid trouble: Only the WebSphere eXtreme Scale client installation, and the remote topology are supported.gotcha

  2. Designate the WebSphere eXtreme Scale dynamic cache provider as the cache provider.

    Each cache instance can be individually configured to use WebSphere eXtreme Scale. The dynamic cache engine is the default cache provider for a cache instance. Cache instances configured with WebSphere eXtreme Scale can coexist with cache instances configured with DRS.

    Complete one of the following actions to designate the WebSphere eXtreme Scale dynamic cache provider as the cache provider:

    1. Use the console to designate the WebSphere eXtreme Scale dynamic cache provider as the cache provider.

      1. In the console, click Servers > Server Types > WebSphere application servers > server_name.

      2. Under Container Services, click Dynamic cache service server_name, and then, in the Cache provider field, select WebSphere eXtreme Scale dynamic cache provider .

      3. Click OK.

    2. Add the cacheProviderName property to the cacheinstances.properties file bundled in an enterprise application, and set the property to com.ibm.ws.objectgrid.dynacache.CacheProviderImpl.

      For example, for cache.instance.26, you would add the following line to the cacheinstances.properties file:

        cache.instance.26.cacheProviderName = com.ibm.ws.objectgrid.dynacache.CacheProviderImpl

    3. Add the following Factory APIs to the code for an enterprise application: 
      Properties p = new Properties();
                ==>p.put(CacheConfig.CACHE_PROVIDER_NAME, CacheConfig.CACHE_PROVIDER_OBJECT_GRID);
                DistributedMap map1 = DistributedMapFactory.getMap("myMap", p);
                DistributedMap map2 = DistributedObjectCacheFactory.getMap("myMap2", p);

  3. Configure the replication setting for the cache instance.

    With the WebSphere eXtreme Scale dynamic cache provider we can have local cache instances, and replicated cache instances.

    If we are only going to use local cache instances, go to the last step, and save the configuration changes. In a local cache the WebSphere eXtreme Scale container is co-located with the JVM; that is, the WebSphere eXtreme Scale container and WebSphere Application Server share the same JVM heap.

    If we are going to use replicated caches, complete one of the following actions, depending on how we have created the cache instance:

    1. On the JVM > Custom properties page in the console, click New again. Enter com.ibm.ws.cache.CacheConfig.enableCacheReplication in the Name field, and true in the Value field, and then click OK.

    2. Add the enableCacheReplication property to the cacheinstances.properties file bundled in an enterprise application, and set the property to true.

      For example, for cache.instance.26, you would add the following line to the cacheinstances.properties file:

        cache.instance.26.enableCacheReplication = true

    3. Add the following Factory APIs to the code for an enterprise application: 
      Properties p = new Properties();
                p.put(CacheConfig.CACHE_PROVIDER_NAME, CacheConfig.CACHE_PROVIDER_OBJECT_GRID);
                ==>p.put(CacheConfig.ENABLE_CACHE_REPLICATION, "true");
                DistributedMap map1 = DistributedMapFactory.getMap("myMap", p);
                DistributedMap map2 = DistributedObjectCacheFactory.getMap("myMap2", p);

  4. Configure the WebSphere eXtreme Scale replication topology.

    The only required configuration parameter for the WebSphere eXtreme Scale dynamic cache provider is the cache topology parameter.

    1. On the JVM > Custom properties page in the console, click New again. Enter com.ibm.websphere.xs.dynacache.topology in the Name field, and one of the following values in the Value field:

      • embedded

      • embedded_partitioned

      • remote

      Avoid trouble: If we specify embedded_partitioned, you must also add the com.ibm.websphere.xs.dynacache.num_initial_containers custom property to the JVM settings, and set this property to an integer that is equal to or slightly less than the total number of server instances that are accessing this distributed cache instance.gotcha

    2. Add the com.ibm.websphere.xs.dynacache.topology property to the cacheinstances.properties file bundled in an enterprise application, and set the property to embedded, embedded_partitioned, or remote.

      For example, for cache.instance.26, you would add the following line to the cacheinstances.properties file:

        cache.instance.26.com.ibm.websphere.xs.dynacache.topology = embedded

      Avoid trouble: If we specify embedded_partitioned, you must also add the com.ibm.websphere.xs.dynacache.num_initial_containers property to the cacheinstances.propertiesfile, and set this property to an integer that is equal to or slightly less than the total number of server instances that are accessing this distributed cache instance.gotcha

      For example, if a dynamic cache service is shared between grid members, then the variable should be set to the number of grid members.

    3. Add the following Factory APIs to the code for an enterprise application: 
      Properties p = new Properties();
p.put(CacheConfig.CACHE_PROVIDER_NAME, CacheConfig.CACHE_PROVIDER_OBJECT_GRID);
p.put(CacheConfig.ENABLE_CACHE_REPLICATION, "true");
==>p.put("com.ibm.websphere.xs.dynacache.topology", "embedded");
==>p.put("com.ibm.websphere.xs.dynacache.num_initial_containers", "3");
DistributedMap map1 = DistributedMapFactory.getMap("myMap", p);
DistributedMap map2 = DistributedObjectCacheFactory.getMap("myMap2", p);

    See the topic Configure the dynamic cache provider for WebSphere eXtreme Scale in the WebSphere eXtreme Scale Version 7 Information Center for more information about the embedded, embedded_partitioned, and remote settings.

  5. Configure the eXtreme Scale catalog service grid.

    When you run a catalog service grid, set the catalog.services.cluster custom property for the catalog service endpoints.

    See the topic Start the catalog service process in a WAS environment in the WebSphere eXtreme Scale Version 7 Information Center for a description of how to start the catalog service process in a WAS environment.

    1. In the console, click System administration > Cell > Custom properties > New.

    2. Enter catalog.services.cluster in the Name field, and the appropriate server_name:host:client_port:peer_port:listener_port value in the Value field.

      • server_name is the fully qualified name of the WebSphere process, such as the cell name, node name, or server name, of the server that hosts the catalog service. Example: cellA\node1\nodeagent
      • host is the name of the hosting server.
      • client_port is the port used for peer catalog grid communication.
      • peer_port is the port used for peer catalog grid communication.
      • listener_port is the listener port. This port must match the BOOTSTRAP_ADDRESS value defined in the server configuration.

      Following is an example of a valid value: 

      cellA\node1\nodeagent:host.local.domain:6600:6601:2809,cellA\node2\ nodeagent:host.foreign.domain:6600:6601:2809

    3. Click OK.

  6. Click Save to save all of the configuration changes.

  7. Restart all the application servers configuredd to use WebSphere eXtreme Scale.

  8. Configure custom key objects.

    When using custom objects as keys, the objects must implement the Serializable or Externalizable interface. If we are using custom objects with the embedded or embedded partitioned topologies, place the objects on the shared library path, in the same way that you do if you are using the default dynamic cache provider. For more information, see the topic Using the DistributedMap and DistributedObjectCache interfaces for the dynamic cache.

    For the remote topology, place the custom key objects on the CLASSPATH for the stand-alone WebSphere eXtreme Scale containers. See the steps to start a container process in the WebSphere eXtreme Scale Version 7.0 Administration Guide for more information. This publication is available on the WebSphere eXtreme Scale library page

  9. Configure eXtreme Scale container servers.

    The cached data is stored in WebSphere eXtreme Scale containers. These containers can run inside or outside of a WAS process. The eXtreme Scale provider automatically creates containers inside a WAS process when we are using embedded or embedded partitioned topologies for a cache instance. No further configuration is needed for these topologies.

    When you use the remote topology, you must start up stand-alone eXtreme Scale containers before you start the WAS instances that access the cache instance. The WebSphere eXtreme Scale Version 7.0 Administration Guide documents the steps that we need to complete to start stand-alone containers.

    Avoid trouble: Make sure that all the containers for a specific dynamic cache point to the same catalog service endpoints. gotcha

    The dynacache-remoteobjectgrid. xml and dynacache-remote-definition.xml configuration files for the stand-alone eXtreme Scale Dynamic Cache provider containers are located in the install_root/customLibraries/ ObjectGrid/dynacache/etc directory if WebSphere eXtreme Scale is installed on top of the WAS, or in the install_root/ObjectGrid/dynacache/etc directory if you are using a stand-alone version of WebSphere eXtreme Scale. Make copies of these files to edit and use when launching stand-alone containers for the eXtreme Scale dynamic cache provider. The value specified for the numIntitialContainers parameter in the dynacache-remote-deployment.xml file should be based on the number of container processes being run.

    The following example illustrates a UNIX-based command line entry that launches a stand-alone container for the WebSphere eXtreme Scale dynamic cache provider:

      startOgServer.sh container1 -objectGridFile ../dynacache/etc/dynacache-remoteobjectgrid.xml -deploymentPolicyFile ../dynacache/etc/dynacache-remotedeployment.xml -catalogServiceEndpoints MyServer1.company.com:2809

    The set of container processes needs to have enough free memory to service all the dynamic cache instances configured to use the remote topology. Any WebSphere Application Server process that shares the same or equivalent values for catalog.services.cluster must use the same set of stand-alone containers. The number of containers and number of machines they reside on needs to be sized appropriately. See the topic Capacity planning and high availability in the WebSphere eXtreme Scale Version 7.0 Product Overview for additional details. This publication is available on the WebSphere eXtreme Scale library page.gotcha

  10. Verify that the WebSphere eXtreme Scale dynamic cache provider is correctly configured.

    If the WebSphere eXtreme Scale dynamic cache provider is correctly configured, the system log contains a number of messages similar to the following messages: 

    DYNA1001I: WebSphere Dynamic cache instance named "{0}" initialized successfully using cache provider "{1}".
DYNA1071I: The cache provider \"{0}\" is being used.

    If the configuration and initialization of the cache instance with WebSphere eXtreme Scale fails the dynamic cache runtime reverts to the default dynamic cache cache provider, and you should see messages similar to the following message in the system log.

      DYNA1066E: Unable to initialize the cache provider \"{0}\". The Dynamic cache will be used to create the cache instance \"{1}\" instead of the configured cache provider.


Subtopics


Related concepts

Introduction: Dynamic cache
  • Use the DistributedMap and DistributedObjectCache interfaces for the dynamic cache
    WebSphere eXtreme Scale library page