Use the DistributedMap and DistributedObjectCache interfaces for the dynamic cache

By using the DistributedMap or DistributedObjectCache interfaces, Java EE applications and system components can cache and share Java objects by storing a reference to the object in the cache.

The DistributedMap and DistributedObjectCache interfaces are simple interfaces for the dynamic cache. Using these interfaces, Java EE 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 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.

For more information see the API documentation for the com.ibm.websphere.cache package.

If we are using custom object keys, place the classes in a shared library. We 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 definedd. See:

• Manage shared libraries
• Class loader settings

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 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 we intend to have the cached objects shared or offloaded to disk, you must 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 four methods for configuring and using cache instances:

• Method one: Configure the default object cache
• Method three: Create the custom object cache
• Method four: Create the custom object cache using the cacheinstances.properties file
• Method five: Use the resource reference

• Method 1 - Configure default cache instances.

  If servlet caching is enabled. The default object cache instance, services/cache/distributedmap, is always created when the server starts. The default servlet cache instance is created when the server starts. ...

  services/cache/basecache

  1. In the console, enable the dynamic cache service by selecting...
     Servers | Server Types | WebSphere application servers | server_name | Container services | Dynamic cache service

  2. Configure other cache settings.

  3. Click Apply or OK.

  4. Restart WebSphere Application Server.

  We 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 - Configure servlet cache instances.

  A servlet cache instance is a location, in addition to the default servlet cache, where dynamic cache can store, distribute, and share data. By using servlet cache instances, the applications have greater flexibility and better tuning of the cache resources. The JNDI name specified for the cache instance is mapped to the name attribute in the <cache instance> tag in the cachespec.xml configuration file.

  Avoid trouble: Servlet caches cannot be looked up. An attempt to do a look up fails, and returns null.

  1. In the console, click...
     Resources | Cache instances | Servlet cache instances

  2. Enter the scope, as follows:
     • CELL SCOPE
     • NODE SCOPE
     • SERVER SCOPE

  3. Enter the required display name for the resource in the name field.

  4. Enter the JNDI name for the resource.

     Specify this name in the attribute field in the <cache-instance> tag in the cachespec.xml configuration file. This tag finds the particular cache instance in which to store cache entries.

  5. Configure other cache settings

  6. Click Apply or OK.

  7. Optional: To set up additional custom properties for this instance, click...
     Resources | Cache instances | Servlet cache instances | servlet_cache_instance_name | Custom properties | New

  8. Optional: Enter the name of the custom property in the Name field. Refer to the Dynamic cache custom properties article for more information.

     Important: Use the custom property with scope indicated Per cache instance only. For example, enter createCacheAtServerStartup in the Name field.

  9. Enter a valid value for the property in the Value field.

  10. Save the property and restart WebSphere Application Server.

  
  

• Method 3 - Configure object cache instances.

  An object cache instance is a location, in addition to the default object cache, where dynamic cache can store, distribute, and share data for Java EE applications. Use cache instances to give applications better flexibility and tuning of the cache resources. Use the DistributedObjectCache programming interface to access the cache instances. For more information about the DistributedObjectCache API, see the API documentation.

  This method is an extension to method one or method two. First use either method one or method two.

  Create and configure the object cache instance, as follows:

  1. In the console, click...
     Resources | Cache instances | Object cache intances

  2. Enter the scope:
     • CELL SCOPE
     • NODE SCOPE
     • SERVER SCOPE

  3. Enter the required display name for the resource in the name field.

  4. Enter the JNDI name for the resource.

     Use this name when looking up a reference to this cache instance. The results return a DistributedMap object.

  5. Configure other cache settings.

  6. Click Apply or OK.

  7. Optional: To set up additional custom properties for this instance, click...
     Resources | Cache instances | Object cache instances | servlet_cache_instance_name | Custom properties | New

  8. Optional: Enter the name of the custom property in the Name field.

     Important: Use the custom property with scope indicated Per cache instance only. For example, enter...

     createCacheAtServerStartup

  9. Enter a valid value for the property in the Value field.

  10. Save the property and restart WebSphere Application Server.

  If we defined two object cache instances in the console with JNDI names of...

  • services/cache/instance_one
  • services/cache/instance_two

  ...we 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 4 - Configure cache instances using the cacheinstances.properties file.

  We can create cache instances using the cacheinstances.properties file and package the file in the EAR file. Use the table information in the cacheinstances.properties file article as a reference of the names, values, and explanations.

  The first line defines the cache instance name. The subsequent lines define custom properties. The formats are as follows:

  cache.instance.x=InstanceName
  cache.instance.x.customPropertyName=customPropertyValue

  ...where...

  • x is the instance name number, which starts with 0.

  • customPropertyName is the custom property name. Refer to the Dynamic cache custom properties article for more information.

    Important: Use the custom property with scope indicated per cache instance only.

  • customPropertyValue is the possible custom property value.

  The following is an example of how we 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. Cache 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.

Place the cacheinstances.properties file in either the application server or application class path. For example, we can use the application WAR file, WEB-INF\classes directory or server_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.

We 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");

// or 

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




• Method 5: Resource reference.

  Important: This method is an extension to method three and method four, listed at the beginning of the Procedure section. First use either method three or method four.

  Define a resource-ref in the module deployment descriptor (web.xml and ibm-web-bnd.xmi files) and look up the cache using the java:comp namespace. The following resource-ref example uses 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-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
  

  The following resource-ref example uses 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>
  

  Supported configurations: For IBM extension and binding files, the .xmi or .xml file name extension is different depending on whether you are using a pre-Java EE 5 application or module or a Java EE 5 or later application or module. An IBM extension or binding file is named ibm-*-ext.xmi or ibm-*-bnd.xmi where * is the type of extension or binding file such as app, application, ejb-jar, or web. The following conditions apply:

  • For an application or module that uses a Java EE version prior to version 5, the file extension must be .xmi.

  • For an application or module that uses Java EE 5 or later, the file extension must be .xml. If .xmi files are included with the application or module, the product ignores the .xmi files.

  However, a Java EE 5 or later module can exist within an application that includes pre-Java EE 5 files and uses the .xmi file name extension.

  The ibm-webservices-ext.xmi, ibm-webservices-bnd.xmi, ibm-webservicesclient-bnd.xmi, ibm-webservicesclient-ext.xmi, and ibm-portlet-ext.xmi files continue to use the .xmi file extensions. sptcfg

  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.

  
  

• Method 6: Java virtual machine cache settings.

  We can set the custom properties globally to affect all cache instances. This overwrites the settings in method 1, method 2 and method 3, but not method 4 (cacheinstances.properties). Configure the cache instance globally, as follows:

  1. In the console, click...
     Servers | Server Types | WebSphere application servers | server_name | Java and process management | Process definition | Java virtual machine | Custom properties | New

  2. Enter the name of the custom property in the Name field.

     After you find the custom property name, add the prefix...

     com.ibm.ws.cache.CacheConfig

     ...to the front of custom property name. For example, if the custom property name is createCacheAtServerStartup, in the Name field, enter...

     com.ibm.ws.cache.CacheConfig.createCacheAtServerStartup

  3. Enter a valid value for the property in the Value field.

  4. Save the property and restart WebSphere Application Server.

Subtopics

• Use object cache instances
• Cache instances
• Object cache instance settings
• Object cache instance collection
• Invalidation listeners

Related concepts

Cache instances

Use the dynamic cache service

Configure dynamic cache disk offload

Use object cache instances

Java virtual machine cache settings