By using the DistributedMap or DistributedObjectCache interfaces, Java Platform, Enterprise Edition
(Java EE) applications and system
components can cache and share Java objects
by storing a reference to the object in the cache.
About this task
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 administrative 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 Java virtual machine
(JVM) enable applications to separately configure cache instances
as needed. Each instance of the DistributedMap interface has its own
properties.
Important: If
you are using custom object keys, you must 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
Managing 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, you
must make these particular objects serializable. If the objects you
place in cache are non-serializable, you must 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:
- Configuring the default object cache (method one below)
- Creating and configuring the custom object cache (method three
below)
- Creating and configuring the custom object cache by using the
cacheinstances.properties file (method four below)
- Using the resource reference (method five below)
- Method 1 - Configure default cache instances.
The
default servlet cache instance (JNDI name: services/cache/basecache)
is created when the server starts , if servlet caching is enabled.
The default object cache instance (JNDI name: services/cache/distributedmap)
is always created when the server starts.
- In the administrative console, select Servers >
Server Types > WebSphere application servers > server_name >
Container services > Dynamic cache service .
- Configure other cache settings. Refer to the Dynamic
cache service settings article for more information.
- Click Apply or OK.
- Restart WebSphere® Application
Server.
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 - 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, your applications have greater flexibility
and better tuning of the cache resources. The Java™ Naming and Directory
Interface (JNDI) name that is 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.
gotcha
- In the administrative console, click Resources >
Cache instances > Servlet cache instances.
- Enter the scope, as follows:
- Specify CELL SCOPE to view and configure cache instances that
are available to all servers within the cell.
- Specify NODE SCOPE to view and configure cache instances that
are available to all servers with the particular node.
- Specify SERVER SCOPE to view and configure cache instances that
are available only on the specific server.
- Enter the required display name for the resource in
the name field.
- 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.
- Configure other cache settings. Refer the Dynamic cache
service settings article for more information.
- Click Apply or OK.
- Optional: If you want to set up additional
custom properties for this instance, click Resources >
Cache instances > Servlet cache instances > servlet_cache_instance_name>
Custom properties > New .
- 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.
- Enter a valid value for the property in the Value field.
- 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™ Platform, Enterprise Edition (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 application programming interface,
see the API documentation.
Attention: Method three
is an extension to method one or method two, listed above. First use
either method one or method two.
Create and configure the
object cache instance, as follows:
- In the administrative console, click Resources >
Cache instances > Object cache intances.
- Enter the scope:
- Specify CELL SCOPE to view and configure cache instances that
are available to all servers within the cell.
- Specfy NODE SCOPE to view and configure cache instances that area
available to all servers with the particular node.
- Specify SERVER SCOPE to view and configure cache instances that
are available only on the specific server.
- Enter the required display name for the resource in
the name field.
- 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.
- Configure other cache settings. See the
Dynamic cache service setting article for more information.
- Click Apply or OK.
- Optional: If you want to set up additional
custom properties for this instance, click Resources >
Cache instances > Object cache instances > servlet_cache_instance_name >
Custom properties > New.
- 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 in
the Name field.
- Enter a valid value for the property in the Value field.
- Save the property and restart WebSphere Application Server.
If you defined two object 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");
// 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.
You can create cache instances using the cacheinstances.properties
file and package the file in your Enterprise Archive (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:
The 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. 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 your application server or application class path.
For example, you can use your 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.
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");
// 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 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.
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.
You 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:
- In the administrative console, click Servers > Server
Types > WebSphere application servers > server_name >
Java and process management > Process definition > Java virtual
machine > Custom properties > New.
- 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.
- Enter a valid value for the property in the Value field.
- Save the property and restart WebSphere Application
Server.