Use DistributedMap and DistributedObjectCache for the dynamic cache

 

+

Search Tips   |   Advanced Search

 

Use the interfaces...

• DistributedMap
• DistributedObjectCache

...to cache Java objects.

The default dynamic cache instance is bound to the global JNDI namespace using the name...

services/cache/distributedmap

Use multiple instances of DistributedMap and DistributedObjectCache on the same JVM to enable applications to separately configure cache instances as needed. Each instance of the DistributedMap interface has its own properties.

For more info, see the API documentation for the package...

com.ibm.websphere.cache

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

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 we 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 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.

Non-serializable objects

If we 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.

Methods for configuring cache instances

There are four methods for configuring cache instances:

• Set the default object cache (Method 1)
• Configure the custom object cache (Method 3)
• Configure the custom object cache by using cacheinstances.properties (Method 4)
• Use the resource reference (Method 5)

 

Method 1 - Set default cache instances

The default servlet cache instance...

services/cache/basecache

...is created when the server starts , if servlet caching is enabled.

The default object cache instance...

services/cache/distributedmap

...is created when the server starts.

1. In the admin console, select...

   Servers | Application servers | server_name | Container services | Dynamic cache services

2. Set other cache settings.

3. Click Apply or OK.

4. Restart WAS.

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 - Set 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 cachespec.xml.

1. In the admin console, click...

   Resources | Cache instances | Servlet cache instances

2. Enter the scope, as follows:

   CELL SCOPE	Cache instances that are available to all servers within the cell.
   NODE SCOPE	Cache instances that are available to all servers with the particular node.
   SERVER SCOPE	Cache instances that are available only on the specific server.

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 cachespec.xml. This tag finds the particular cache instance in which to store cache entries.
5. Set 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.

   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 WAS.

 

Method 3 - Set 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.

See about the DistributedObjectCache API, see the API documentation.

Method three is an extension to method one or method two, listed above. First use either method one or method two.

Configure the object cache instance, as follows:

1. In the admin console, click...

   Resources | Cache instances | Object cache instances

2. Enter the scope:

   • Specify CELL SCOPE to set cache instances that are available to all servers within the cell.

   • Specfy NODE SCOPE to set cache instances that area available to all servers with the particular node.

   • Specify SERVER SCOPE to set cache instances that are available only on the specific server.

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. Set 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.

   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 WAS.

If we defined two object cache instances in the admin console with JNDI names of services/cache/instance_one and 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 - Set cache instances using cacheinstances.properties

We can create cache instances using cacheinstances.properties and package the file in the EAR file.

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.

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

• customPropertyValue is the possible custom property value.

Examples

The following is an example of how we can create additional cache instances using cacheinstances.properties...

cache.instance.0=/services/cache/instance_one 
cache.instance.0.cacheSize=1000 
cache.instance.0.enableDiskOffload=true 
cache.instance.0.diskOffloadLocation=${APP_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 cacheinstances.properties in either the appserver 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

This method is an extension to method three and method four, listed above. First use either method three or method four.

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-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.

 

Method 6: Java virtual machine cache settings

We can set 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). Set the cache instance globally, as follows:

1. In the admin console, click...

   Servers | 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. Refer to the Dynamic cache custom properties article for more information. After you find the custom property name, add the com.ibm.ws.cache.CacheConfig prefix to the front of custom property name. For example, if the custom property name is createCacheAtServerStartup, enter com.ibm.ws.cache.CacheConfig.createCacheAtServerStartup in the Name field.

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

4. Save the property and restart WAS.

 

Related concepts

Cache instances
Object cache instance settings
Object cache instance collection
cacheinstances.properties
Invalidation listeners

 

Related tasks

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

 

Related

Java virtual machine cache settings