Use the DistributedMap and DistributedObjectCache interfaces for the dynamic cache

 

By using the DistributedMap or DistributedObjectCache interfaces, Java 2 platform, Enterprise Edition (J2EE) applications and system components can cache and share Java objects by storing a reference to the object in the cache. Enable the dynamic cache service. See Enabling the dynamic cache service for more information.

 

Overview

The DistributedMap and DistributedObjectCache interfaces are simple interfaces for the dynamic cache. Using these interfaces, J2EE applications and system components can cache and share Java objects by storing a reference to the object in the cache. The default dynamic cache instance is created if the dynamic cache service is enabled in the console. This default instance is bound to the global Java Naming and Directory Interface (JNDI) namespace using the name services/cache/distributedmap.

Multiple instances of the DistributedMap and DistributedObjectCache interfaces on the same JVM enable applications to separately configure cache instances as needed. Each instance of the DistributedMap interface has its own properties that can be set using Object cache instance settings.

For more information about the DistributedMap and DistributedObjectCache interfaces, see the API documentation for the com.ibm.websphere.cache package. See Reference: Generated API documentation for more information.

If you are using custom object keys, place your classes in a shared library. You can define the shared library at cell, node, or server level. Then, in each server create a class loader and associate it with the shared library that you defined. See Manage shared libraries and Class loader settings for more information.

Place JAR files in a shared library when you deploy the application in a cluster with replication enabled. Simply turning on replication does not require a shared library; however, if you are using application-specific Java objects, such as cache key or cache value, those Java classes are required to be in the shared library. If those values are not in a shared library, you will get ClassNotFound exceptions when the data replication service (DRS) attempts to deserialize those objects on the receiving side.

In a clustered environment, the content you place in cache might be shared with other servers in the cluster. The content might also be offloaded to disk. If you intend to have the cached objects shared or offloaded to disk, make these particular objects serializable. If the objects you place in cache are non-serializable, specify that the sharing policy for these objects is not shared. The DistributedMap interface DistributedMap interface contains information about how to specify the sharing policy for a cached object. Specifying a sharing policy other than not shared for non-serializable objects can result in poor system performance. There are three methods for configuring and using cache instances.

 

Procedure

 

• Method 1 - Administrative console You can create additional cache instances using the console.

  1. In the console, select Resources > Object cache instances and create a new object cache instance.

  If you defined two object cache instances in the console with JNDI names of services/cache/instance_one and services/cache/instance_two, you can use the following code to look up the cache instances:

   InitialContext ic = new InitialContext();
  DistributedMap dm1 = (DistributedMap)ic.lookup("services/cache/instance_one");
  
  DistributedMap dm2 = (DistributedMap)ic.lookup("services/cache/instance_two");
  
  // or
  
  InitialContext ic = new InitialContext();
  DistributedObjectCache dm1 = (DistributedObjectCache)ic.lookup("services/cache/instance_one");
  
  DistributedObjectCache dm2 = (DistributedObjectCache)ic.lookup("services/cache/instance_two");
  
  

   

• Method 2 - Properties file You can create cache instances using the cacheinstances.properties file and package the file in your EAR file. Following is an example of how you can create additional cache instances using the cacheinstances.properties file:

  cache.instance.0=/services/cache/instance_one
   cache.instance.0.cacheSize=1000
   cache.instance.0.enableDiskOffload=true
   cache.instance.0.diskOffloadLocation=${app_server_root}/diskOffload
   cache.instance.0.flushToDiskOnStop=true
   cache.instance.0.useListenerContext=true
   cache.instance.0.enableCacheReplication=false
   cache.instance.0.disableDependencyId=false
   cache.instance.0.htodCleanupFrequency=60
   cache.instance.1=/services/cache/instance_two
   cache.instance.1.cacheSize=1500
   cache.instance.1.enableDiskOffload=false
   cache.instance.1.flushToDiskOnStop=false
   cache.instance.1.useListenerContext=false
   cache.instance.1.enableCacheReplication=true
   cache.instance.1.replicationDomain=DynaCacheCluster
   cache.instance.1.disableDependencyId=true
  

  The preceding example creates two cache instances named instance_one and instance_two. instance_one has a cache entry size of 1,000 and instance_two has a cache entry size of 1,500. Disk offload is enabled in instance_one and disabled in instance_two. Use listener context is enabled in instance_one and disabled in instance_two. Flush to disk on stop is enabled in instance_one and disabled in instance_two. Cache replication is enabled in instance_two and disabled in instance_one. The name of the data replication domain for instance_two is DynaCacheCluster. Dependency ID support is disabled in instance_two. You must place the cacheinstances.properties file in either your appserver or application class path. For example, you can use your application WAR file, WEB-INF\classes directory, or was_root\classes directory. The first entry in the properties file (cache.instance.0) specifies the JNDI name for the cache instance in the global namespace. You can use the following code to look up the cache instance:

       InitialContext ic = new InitialContext();
       DistributedMap dm1 = (DistributedMap)ic.lookup("services/cache/instance_one");
       DistributedMap dm2 = (DistributedMap)ic.lookup("services/cache/instance_two");
  

  For more information about the DistributedMap and DistributedObjectCache interfaces, see the API documentation for the com.ibm.websphere.cache package.

   

• Method 3 - Resource references

  Method three is an extension to method one or method two, listed above. First use either method one or method two. Define a resource-ref in your module deployment descriptor (web.xml and ibm-web-bnd.xmi files) and look up the cache using the java:comp namespace.

  Resource-ref example:
  File: web.xml
  <resource-ref id="ResourceRef_1">
    <res-ref-name>dmap/LayoutCache</res-ref-name>
    <res-type>com.ibm.websphere.cache.DistributedMap</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
  <resource-ref id="ResourceRef_2">
    <res-ref-name>dmap/UserCache</res-ref-name>
    <res-type>com.ibm.websphere.cache.DistributedMap</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
  
  
  File: ibm-web-bnd.xmi
  <?xml version="1.0" encoding="UTF-8"?>
  <webappbnd:WebAppBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
  xmlns:webappbnd="webappbnd.xmi" 
  xmlns:webapplication="webapplication.xmi" xmlns:commonbnd="commonbnd.xmi" 
  xmlns:common="common.xmi" 
  xmi:id="WebApp_ID_Bnd" virtualHostName="default_host">
    <webapp href="WEB-INF/web.xml#WebApp_ID"/>
    <resRefBindings xmi:id="ResourceRefBinding_1" jndiName="services/cache/instance_one">
      <bindingResourceRef href="WEB-INF/web.xml#ResourceRef_1"/>
    </resRefBindings>
    <resRefBindings xmi:id="ResourceRefBinding_2" jndiName="services/cache/instance_two">
      <bindingResourceRef href="WEB-INF/web.xml#ResourceRef_2"/>
    </resRefBindings>
  </webappbnd:WebAppBinding>
  

  The following example shows how to look up the resource-ref:

  InitialContext ic = new InitialContext();
    DistributedMap dm1a =(DistributedMap)ic.lookup("java:comp/env/dmap/LayoutCache");
    DistributedMap dm2a =(DistributedMap)ic.lookup("java:comp/env/dmap/UserCache");
  // or
    DistributedObjectCache dm1a =(DistributedObjectCache)ic.lookup("java:comp/env/dmap/LayoutCache");
    DistributedObjectCache dm2a =(DistributedObjectCache)ic.lookup("java:comp/env/dmap/UserCache");
  

  The previous resource-ref example maps java:comp/env/dmap/LayoutCache to /services/cache/instance_one and java:comp/env/dmap/UserCache to /services/cache/instance_two. In the examples, DistributedMap dm1 and dm1a are the same object. DistributedMap dm2 and dm2a are the same object.

  DistributedMap and DistributedObjectCache do not have authorization or access control associated with the cache entries.

---

Object cache instance settings

Object cache instance collection

Invalidation listeners

 

Related concepts

Cache instances

 

Related tasks

Enabling the dynamic cache service
Configure dynamic cache disk offload
Use object cache instances
Task overview: Using the dynamic cache service to improve performance

 

Related Reference

Java virtual machine cache settings