com.ibm.websphere.cache

Interface DistributedMap

All Superinterfaces:

java.util.Map

All Known Implementing Classes:

DistributedObjectCache

public interface DistributedMap
extends java.util.Map

This class provides applications with an extended java.util.Map interface to access the WebSphere Dynamic Cache, allowing inspection and manipulation of the cache. The cache does not have any authorization checking done before allowing access to its contents, so care should be taken on the type of data that is placed in the cache. The default WebSphere Dynamic Cache instance is created when the cache is enabled in the administrative console and is bound into the global JNDI namespace with the name "services/cache/distributedmap". Additional cache instances can be created using a properties file cacheinstances.properties with the following format: cache.instance.0=/services/cache/instance_one cache.instance.0.cacheSize=1000 cache.instance.0.enableDiskOffload=true cache.instance.0.diskOffloadLocation=${WAS_INSTALL_ROOT}/temp cache.instance.1=/services/cache/instance_two cache.instance.1.cacheSize=1500 cache.instance.1.enableDiskOffload=true cache.instance.1.diskOffloadLocation=C:/disk The distributedmap.properties file must be located in either you application server or application's classpath. The first entry in the properties file (cache.instance.0) specifies the JNDI name for the cache instance in the global namespace. You could then lookup the cache instance using the following code: InitialContext ic = new InitialContext(); DistributedMap dm =(DistributedMap)ic.lookup("services/cache/instance_one"); Alternatively, you can define a resource-ref for in cache in your module's deployement descriptor and then lookup the cache using the java:comp namespace. <resource-ref> <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> An example of looking up the resource-ref: InitialContext ic = new InitialContext(); DistributedMap dm =(DistributedMap)ic.lookup("java:comp/env/dmap/LayoutCache");

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Method Summary

Methods

Modifier and Type	Method and Description
void	addAlias(java.lang.Object key, java.lang.Object[] aliasArray) Adds an alias for the given key in the cache's mapping table.
boolean	addChangeListener(ChangeListener listener) addChangeListener - adds a change listener for this DistributedMap.
boolean	addInvalidationListener(InvalidationListener listener) addInvalidationListener - adds an invalidation listener for this DistributeMap.
boolean	containsKey(java.lang.Object key, boolean includeDiskCache) Returns true if this map contains mapping for the specified key.
boolean	enableListener(boolean enable) enableListener - enable or disable the invalidation and change listener support.
java.lang.Object	get(java.lang.Object key) Returns the value to which this map maps the specified key.
int	getSharingPolicy() getSharingPolicy - gets the sharing policy for DistributedMap.
void	invalidate(java.lang.Object key) invalidate - invalidates the given key.
void	invalidate(java.lang.Object key, boolean wait) invalidate - invalidates the given key.
boolean	isDRSBootstrapEnabled() isDRSBootstrapEnabled - check whether DRS bootstrap for DistributedMap is enabled or not.
boolean	isEmpty(boolean includeDiskCache) Returns true if this map contains no key-value mappings.
java.util.Set	keySet(boolean includeDiskCache) Returns a set view of the keys contained in this map.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map (optional operation).
java.lang.Object	put(java.lang.Object key, java.lang.Object value, int priority, int timeToLive, int inactivityTime, int sharingPolicy, java.lang.Object[] dependencyIds) Associates the specified value with the specified key in this map (optional operation).
java.lang.Object	put(java.lang.Object key, java.lang.Object value, int priority, int timeToLive, int sharingPolicy, java.lang.Object[] dependencyIds) Associates the specified value with the specified key in this map (optional operation).
void	removeAlias(java.lang.Object alias) Removes an alias from the cache's mapping table.
boolean	removeChangeListener(ChangeListener listener) removeChangeListener - removes a change listener for this DistributedMap.
boolean	removeInvalidationListener(InvalidationListener listener) removeInvalidationListener - removes an invalidation listener for this DistributedMap.
void	setDRSBootstrap(boolean drsBootstrap) setDRSBootstrap - Enables or disbales DRS bootstrap support
void	setPriority(int priority) Sets the global priority for this map..
void	setSharingPolicy(int sharingPolicy) setSharingPolicy - sets the sharing policy for DistributedMap.
void	setTimeToLive(int timeToLive) Set the global time-to-live this this map.
int	size(boolean includeDiskCache) Returns the total number of key-value mappings.

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, putAll, remove, size, values

Method Detail

setSharingPolicy

void setSharingPolicy(int sharingPolicy)

setSharingPolicy - sets the sharing policy for DistributedMap.

Parameters:

sharingPolicy - policy to set. Default is EntryInfo.NOT_SHARED

See Also:

getSharingPolicy()

getSharingPolicy

int getSharingPolicy()

getSharingPolicy - gets the sharing policy for DistributedMap.

Returns:

returns the current sharing policy of DistributedMap.

See Also:

setSharingPolicy(int)

setDRSBootstrap

void setDRSBootstrap(boolean drsBootstrap)

setDRSBootstrap - Enables or disbales DRS bootstrap support

Parameters:

drsBootstrap - - true (default) to enable DRS bootstrap support, or false to ignore DRS bootstrap messages for this cache instance

See Also:

isDRSBootstrapEnabled()

isDRSBootstrapEnabled

boolean isDRSBootstrapEnabled()

isDRSBootstrapEnabled - check whether DRS bootstrap for DistributedMap is enabled or not.

Returns:

returns the current DRS bootstrap of DistributedMap. True means enabled

See Also:

setDRSBootstrap(boolean)

setTimeToLive

void setTimeToLive(int timeToLive)

Set the global time-to-live this this map.

Parameters:

timeToLive - the time in seconds that cache entries should remain in the cache. The default value is -1 and means the entry does not time out.

setPriority

void setPriority(int priority)

Sets the global priority for this map..

Parameters:

priority - the global priority value for the cache entries. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow. Valid priorities are 1 through 16 with 1 being the default value. 1 is the lowest priority and 16 is the highest.

get

java.lang.Object get(java.lang.Object key)

Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

Specified by:

get in interface java.util.Map

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

Throws:

java.lang.ClassCastException - if the key is not of an inappropriate type for this map. (Currently supports only String)

java.lang.NullPointerException - key is null and this map does not not permit null keys.

See Also:

Map.containsKey(Object)

put

java.lang.Object put(java.lang.Object key,
                   java.lang.Object value)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced. This method will use optional metadata looked up from the cache configuration file. If no meta data is found, the entrie is cached with an infinite timeout and the cache's default priority. Metadata found in the cache configuration is looked up via class name and includes priority, timeout, and dependency ids.

Specified by:

put in interface java.util.Map

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map.

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.

put

java.lang.Object put(java.lang.Object key,
                   java.lang.Object value,
                   int priority,
                   int timeToLive,
                   int sharingPolicy,
                   java.lang.Object[] dependencyIds)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced.

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow. Valid priorities are 1 through 16 with 1 being the default value. 1 is the lowest priority and 16 is the highest.

timeToLive - the time in seconds that the cache entry should remain in the cache. The default value is -1 and means the entry does not time out.

sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, EntryInfo.SHARED_PUSH_PULL and EntryInfo.SHARED_DEFAULT. EntryInfo.SHARED_DEFAULT indicates the default sharing policy of the cache instance should be used.

dependencyIds - an optional set of dependency ids to associate with the cache entry

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map.

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.

put

java.lang.Object put(java.lang.Object key,
                   java.lang.Object value,
                   int priority,
                   int timeToLive,
                   int inactivityTime,
                   int sharingPolicy,
                   java.lang.Object[] dependencyIds)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced.

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

priority - the priority value for the cache entry. entries with higher priority will remain in the cache longer than those with a lower priority in the case of cache overflow. Valid priorities are 1 through 16 with 1 being the default value. 1 is the lowest priority and 16 is the highest.

timeToLive - the time in seconds that the cache entry should remain in the cache. The default value is -1 and means the entry does not time out.

inactivityTime - the time in seconds that the cache entry should remain in the cache if not accessed. This is reset once an entry is accessed.

sharingPolicy - how the cache entry should be shared in a cluster. values are EntryInfo.NOT_SHARED, EntryInfo.SHARED_PUSH, EntryInfo.SHARED_PUSH_PULL and EntryInfo.SHARED_DEFAULT. EntryInfo.SHARED_DEFAULT indicates the default sharing policy of the cache instance should be used.

dependencyIds - an optional set of dependency ids to associate with the cache entry

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map.

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.

invalidate

void invalidate(java.lang.Object key)

invalidate - invalidates the given key. If the key is for a specific cache entry, then only that object is invalidated. If the key is for a dependency id, then all objects that share that dependency id will be invalidated.

Parameters:

key - the key which will be invalidated

See Also:

Map.remove(Object key)

invalidate

void invalidate(java.lang.Object key,
              boolean wait)

invalidate - invalidates the given key. If the key is for a specific cache entry, then only that object is invalidated. If the key is for a dependency id, then all objects that share that dependency id will be invalidated.

Parameters:

key - the key which will be invalidated

wait - if true, then the method will not complete until the invalidation has occured. if false, then the invalidation will occur in batch mode

See Also:

Map.remove(Object key)

enableListener

boolean enableListener(boolean enable)

enableListener - enable or disable the invalidation and change listener support. You must call enableListener(true) before calling addInvalidationListner() or addChangeListener().

Parameters:

enable - - true to enable support for invalidation and change listeners or false to disable support for invalidation and change listeners

Returns:

boolean "true" means listener support was successfully enabled or disabled. "false" means this DistributedMap is configurated to use the listener's J2EE context for event notification and the callback registration failed. In this case, the caller's thread context will be used for event notification.

addInvalidationListener

boolean addInvalidationListener(InvalidationListener listener)

addInvalidationListener - adds an invalidation listener for this DistributeMap.

Parameters:

listener - the invalidation listener object

Returns:

boolean "true" means the invalidation listener was successfully added. "false" means either the passed listener object is null or listener support is not enable.

See Also:

removeInvalidationListener(com.ibm.websphere.cache.InvalidationListener)

removeInvalidationListener

boolean removeInvalidationListener(InvalidationListener listener)

removeInvalidationListener - removes an invalidation listener for this DistributedMap.

Parameters:

listener - the invalidation listener object

Returns:

boolean "true" means the invalidation listener was successfully removed. "false" means either passed listener object is null or listener support is not enable.

See Also:

addInvalidationListener(com.ibm.websphere.cache.InvalidationListener)

addChangeListener

boolean addChangeListener(ChangeListener listener)

addChangeListener - adds a change listener for this DistributedMap.

Parameters:

listener - the change listener object

Returns:

boolean "true" means the change listener was successfully added. "false" means either the passed listener object is null or listener support is not enable.

See Also:

removeChangeListener(com.ibm.websphere.cache.ChangeListener)

removeChangeListener

boolean removeChangeListener(ChangeListener listener)

removeChangeListener - removes a change listener for this DistributedMap.

Parameters:

listener - the change listener object

Returns:

boolean "true" means the change listener was successfully removed. "false" means either passed listener object is null or listener support is not enable.

See Also:

addChangeListener(com.ibm.websphere.cache.ChangeListener)

addAlias

void addAlias(java.lang.Object key,
            java.lang.Object[] aliasArray)

Adds an alias for the given key in the cache's mapping table. If the alias is already associated with another key, it will be changed to associate with the new key.

Parameters:

key - the key assoicated with alias

aliasArray - the alias to use for lookups

Throws:

java.lang.IllegalArgumentException - if the key is not in the cache's mapping table.

removeAlias

void removeAlias(java.lang.Object alias)

Removes an alias from the cache's mapping table.

Parameters:

alias - the alias to move out of the cache's mapping table

size

int size(boolean includeDiskCache)

Returns the total number of key-value mappings. Returns size of memory map plus disk map if includeDiskCache is true. Returns size of memory map size if includeDiskCache is false.

Parameters:

includeDiskCache - true to get the size of the memory and disk maps; false to get the size of memory map.

Returns:

the number of key-value mappings in this map.

isEmpty

boolean isEmpty(boolean includeDiskCache)

Returns true if this map contains no key-value mappings. Checks both memory and disk maps if includeDiskCache is true. Check only memory cache if includeDiskCache is false.

Parameters:

includeDiskCache - true to check the memory and disk maps; false to check the memory map.

Returns:

true if this map contains no key-value mappings.

containsKey

boolean containsKey(java.lang.Object key,
                  boolean includeDiskCache)

Returns true if this map contains mapping for the specified key. Checks both memory and disk map if includeDiskCache is true. Check only memory map if includeDiskCache is false.

Parameters:

key - whose presence in this map is to be tested.

includeDiskCache - true to check the specified key contained in the memory or disk maps; false to check the specified key contained in the memory map.

Returns:

true if this map contains a mapping for the specified key.

keySet

java.util.Set keySet(boolean includeDiskCache)

Returns a set view of the keys contained in this map. Returns all the keys in both memory map and disk map if includeDiskCache is true. Return only keys in memory map if includeDiskCache is false. Warning: If this method is used with includeDiskCache set to true, all the keys on disk are read into memory and that might consume a lot of memory depending on the size of disk map.

Parameters:

includeDiskCache - true to get keys contained in the memory and disk maps; false to get keys contained in the memory map.

Returns:

a set view of the keys contained in this map.