[Version 5.0.2 and later]Using the DistributedMap interface for the dynamic cache

Why and when to perform this task

The DistributedMap interface is a simple interface for the dynamic cache. Using the DistributedMap interface, J2EE applications and system components can cache and share Java objects by storing a reference to the object in the cache. The default WebSphere dynamic cache instance is created if dynamic cache service is enabled in the administrative console. This default instance is bound into the global JNDI namespace using the name services/cache/distributedmap. For information on how to enable the dynamic cache service globally, see Enabling the dynamic cache service.

Multiple instances of the DistributedMap interface on the same Java virtual machine (JVM) enable applications to separately configure cache instances as needed. Each instance of DistributedMap has its own properties:

There are three methods for configuring and using cache instances.

Method 1 - Administrative Console

You can create additional cache instances using the Administrative Console. Click Resources > Cache Instances. After you create a new cache instance, you can optionally add additional properties, such as flushToDiskOnStop and useListenerContext, using the custom properties. SeeCache instance settings for more information.

If you defined two cache instances in the Administrative 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");

Note: For more information about the DistributedMap interface, see the Javadoc for the com.ibm.websphere.cache package.

Method 2 - Properties file

Note: The distributedmap.properties file will be deprecated in a future release. Using the Administrative Console is the recommended way to configure cache instances.

Following is an example of how you can create additional cache instances using the distributedmap.properties file:

	cache.instance.0=/services/cache/instance_one
	cache.instance.0.cacheSize=1000
	cache.instance.0.enableDiskOffload=true
	cache.instance.0.diskOffloadLocation=${WAS_INSTALL_ROOT}/diskOffload
	cache.instance.0.flushToDiskOnStop=true
	cache.instance.0.useListenerContext=true
	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

The preceding example creates two DistributedMap 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.

You must place the distributedmap.properties file in either your application server 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");

Note: For more information about the DistributedMap interface, see the Javadoc for the com.ibm.websphere.cache package.

Method 3 - Resource references

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

[5.0 only][Version 5.0.1]The following describes resource reference files. Alternately, you can use the Application Assembly Tool to create the resource reference.

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");
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 map. DistributedMap dm2 and dm2a are the same map.

Note: The DistributedMap interface does not currently have authorization or access control associated with any of the cache entries.

What to do next

To learn how to share cached objects in a clustered environment, see Sharing cached objects in a clustered environment.

Related tasks
Configuring the dynamic cache service to improve performance
Enabling the dynamic cache service
Configuring the dynamic cache disk offload
Configuring WebSphere variables
Using cache instances[Version 5.0.2 and later]



Searchable topic ID:   tdyn_distmap
Last updated: Jun 21, 2007 8:07:48 PM CDT    WebSphere Business Integration Server Foundation, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.wasee.doc/info/ee/ae/tdyn_distmap.html

Library | Support | Terms of Use | Feedback