Distributed Map interface for Dynamic Caching

Distributed Map interface for Dynamic Caching

This feature provides a local cache service which can be accessed through the DistributedMap API. A default cache is bound in JNDI at "services/cache/distributedmap". Caches can be distributed through addition of a network cache provider such as WebSphere eXtreme Scale.

Enable this feature

To enable the Distributed Map interface for Dynamic Caching feature, add the following element declaration inside the featureManager element in the server.xml file:
<feature>distributedMap-1.0</feature>

Developing a feature that depends on this feature

If we are developing a feature that depends on the Distributed Map interface for Dynamic Caching feature, include the following item in the Subsystem-Content header in the feature manifest file for the new feature:
com.ibm.websphere.appserver.distributedMap-1.0; type="osgi.subsystem.feature"

Features that this feature enables

Java Naming and Directory Interface

Features that enable this feature

Web Admin Center

OAuth

OpenID Connect Client

JMX REST Connector

Web Response Cache

API packages provided by this feature

com.ibm.websphere.cache

com.ibm.websphere.cache.exception

com.ibm.websphere.exception

com.ibm.ws.cache.spi

com.ibm.wsspi.cache

Feature configuration elements

We can use the following elements in the server.xml file to configure the Distributed Map interface for Dynamic Caching feature:

classloading

distributedMap

cacheGroup

member

adapterBeanName

diskCache

library

file

fileset

folder

library

file

fileset

folder

classloading

Global classloading

Attribute name Data type Default value Description
useJarUrls boolean false Whether to use jar: or wsjar: URLs for referencing files in archives

distributedMap

Distributed map configuration for a local cache.

Attribute name Data type Default value Description
cacheProviderName string default Configure an alternate cache provider for the Web Cache.
highThreshold int
Minimum: -1
Maximum: 100
-1 Specifies when the memory cache eviction policy starts. The threshold is expressed in terms of the percentage of the memory cache size in megabytes (MB).
id string A unique configuration ID.
jndiName string ${id} JNDI name for a cache instance.
libraryRef A reference to top level library element (string). Specifies a reference to a shared library.
lowThreshold int
Minimum: -1
Maximum: 100
-1 Specifies when the memory cache eviction policy ends. The threshold is expressed in terms of the percentage of the memory cache size in megabytes (MB).
memorySizeInEntries int
Minimum: 0
2000 Positive integer that defines the maximum number of entries that the cache can hold. Values are usually in the thousands. The minimum value is 100, with no set maximum value. The default value is 2000.
memorySizeInMB int
Minimum: -1
-1 Specifies a value for the maximum memory cache size in megabytes (MB).

distributedMap > cacheGroup

Description: Specifies sets of external caches that are controlled by WebSphere(R) Application Server on servers such as IBM(R) WebSphere(R) Edge Server and IBM(R) HTTP Server.

Required: false

Data type:

Attribute name Data type Default value Description
name string Specifies a unique name for the external cache group. The external cache group name must match the ExternalCache property defined in the servlet or Java(TM) Server Pages (JSP) cachespec.xml file.

distributedMap > cacheGroup > member

Description: Members of an external cache group that are controlled by WebSphere Application Server.

Required: false

Data type:

Attribute name Data type Default value Description
host string Fully qualified host name
port int
Minimum: 0
Port.

distributedMap > cacheGroup > member > adapterBeanName

Description: Name of a class, which is located on the WebSphere Application Server class path, of the adapter between WebSphere Application Server and this external cache.

Required: false

Data type: string

distributedMap > diskCache

Description: Enable disk offload to specify that when the cache is full, cache entries are removed from the cache and saved to disk. The location is a fully-qualified directory location used by the disk offload function. The Flush to Disk on Stop option specifies that when the server stops, the contents of the memory cache are moved to disk.

Required: false

Data type:

Attribute name Data type Default value Description
evictionPolicy

RANDOM

SIZE

RANDOM Eviction algorithm and thresholds that the disk cache uses to evict entries. When the disk size reaches a high threshold limit, the disk cache garbage collector wakes up and evicts randomly-selected (Random) or the largest (Size) entries on the disk until the disk size reaches a low threshold limit.

RANDOM

Random

SIZE

Size

flushToDiskOnStopEnabled boolean false Set to true to have objects that are cached in memory saved to disk when the server stops. This value is ignored if Enable disk offload is set to false.
highThreshold int
Minimum: 0
Maximum: 100
80 Specifies when the eviction policy starts.
location Path to a directory Directory to use for disk offload.
lowThreshold int
Minimum: 0
Maximum: 100
70 Specifies when the eviction policy ends.
sizeInEntries int
Minimum: 0
100000 Specifies a value for the maximum disk cache size, in number of entries.
sizeInGB int
Minimum: 3
3 Specifies a value for the maximum disk cache size, in gigabytes (GB).

distributedMap > library

Description: Specifies a reference to a shared library.

Required: false

Data type:

Attribute name Data type Default value Description
apiTypeVisibility string spec,ibm-api,api The types of API package this library's class loader will be able to see, as a comma-separated list of any combination of the following: spec, ibm-api, api, third-party.
description string Description of shared library for administrators
filesetRef List of references to top level fileset elements (comma-separated string). Id of referenced Fileset
name string Name of shared library for administrators

distributedMap > library > file

Description: Id of referenced File

Required: false

Data type:

Attribute name Data type Default value Description
name Path to a file Fully qualified filename

distributedMap > library > fileset

Description: Id of referenced Fileset

Required: false

Data type:

Attribute name Data type Default value Description
caseSensitive boolean true Boolean to indicate whether or not the search should be case sensitive (default: true).
dir Path to a directory ${server.config.dir} The base directory to search for files.
excludes string The comma or space separated list of file name patterns to exclude from the search results, by default no files are excluded.
includes string * The comma or space separated list of file name patterns to include in the search results (default: *).
scanInterval A period of time with millisecond precision 0 Scanning interval to check the fileset for changes as a long with a time unit suffix h-hour, m-minute, s-second, ms-millisecond (e.g. 2ms or 5s). Disabled (scanInterval=0) by default. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

distributedMap > library > folder

Description: Id of referenced folder

Required: false

Data type:

Attribute name Data type Default value Description
dir Path to a directory Directory or folder to be included in the library classpath for locating resource files

library

Shared Library

Attribute name Data type Default value Description
apiTypeVisibility string spec,ibm-api,api The types of API package this library's class loader will be able to see, as a comma-separated list of any combination of the following: spec, ibm-api, api, third-party.
description string Description of shared library for administrators
filesetRef List of references to top level fileset elements (comma-separated string). Id of referenced Fileset
id string A unique configuration ID.
name string Name of shared library for administrators

library > file

Description: Id of referenced File

Required: false

Data type:

Attribute name Data type Default value Description
name Path to a file Fully qualified filename

library > fileset

Description: Id of referenced Fileset

Required: false

Data type:

Attribute name Data type Default value Description
caseSensitive boolean true Boolean to indicate whether or not the search should be case sensitive (default: true).
dir Path to a directory ${server.config.dir} The base directory to search for files.
excludes string The comma or space separated list of file name patterns to exclude from the search results, by default no files are excluded.
includes string * The comma or space separated list of file name patterns to include in the search results (default: *).
scanInterval A period of time with millisecond precision 0 Scanning interval to check the fileset for changes as a long with a time unit suffix h-hour, m-minute, s-second, ms-millisecond (e.g. 2ms or 5s). Disabled (scanInterval=0) by default. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.

library > folder

Description: Id of referenced folder

Required: false

Data type:

Attribute name Data type Default value Description
dir Path to a directory Directory or folder to be included in the library classpath for locating resource files

Attribute name	Data type	Default value	Description
cacheProviderName	string	default	Configure an alternate cache provider for the Web Cache.
highThreshold	int Minimum: -1 Maximum: 100	-1	Specifies when the memory cache eviction policy starts. The threshold is expressed in terms of the percentage of the memory cache size in megabytes (MB).
id	string		A unique configuration ID.
jndiName	string	${id}	JNDI name for a cache instance.
libraryRef	A reference to top level library element (string).		Specifies a reference to a shared library.
lowThreshold	int Minimum: -1 Maximum: 100	-1	Specifies when the memory cache eviction policy ends. The threshold is expressed in terms of the percentage of the memory cache size in megabytes (MB).
memorySizeInEntries	int Minimum: 0	2000	Positive integer that defines the maximum number of entries that the cache can hold. Values are usually in the thousands. The minimum value is 100, with no set maximum value. The default value is 2000.
memorySizeInMB	int Minimum: -1	-1	Specifies a value for the maximum memory cache size in megabytes (MB).

Attribute name	Data type	Default value	Description
evictionPolicy	RANDOM SIZE	RANDOM	Eviction algorithm and thresholds that the disk cache uses to evict entries. When the disk size reaches a high threshold limit, the disk cache garbage collector wakes up and evicts randomly-selected (Random) or the largest (Size) entries on the disk until the disk size reaches a low threshold limit. RANDOM Random SIZE Size
flushToDiskOnStopEnabled	boolean	false	Set to true to have objects that are cached in memory saved to disk when the server stops. This value is ignored if Enable disk offload is set to false.
highThreshold	int Minimum: 0 Maximum: 100	80	Specifies when the eviction policy starts.
location	Path to a directory		Directory to use for disk offload.
lowThreshold	int Minimum: 0 Maximum: 100	70	Specifies when the eviction policy ends.
sizeInEntries	int Minimum: 0	100000	Specifies a value for the maximum disk cache size, in number of entries.
sizeInGB	int Minimum: 3	3	Specifies a value for the maximum disk cache size, in gigabytes (GB).

Attribute name	Data type	Default value	Description
apiTypeVisibility	string	spec,ibm-api,api	The types of API package this library's class loader will be able to see, as a comma-separated list of any combination of the following: spec, ibm-api, api, third-party.
description	string		Description of shared library for administrators
filesetRef	List of references to top level fileset elements (comma-separated string).		Id of referenced Fileset
name	string		Name of shared library for administrators

Attribute name	Data type	Default value	Description
caseSensitive	boolean	true	Boolean to indicate whether or not the search should be case sensitive (default: true).
dir	Path to a directory	${server.config.dir}	The base directory to search for files.
excludes	string		The comma or space separated list of file name patterns to exclude from the search results, by default no files are excluded.
includes	string	*	The comma or space separated list of file name patterns to include in the search results (default: *).
scanInterval	A period of time with millisecond precision	0	Scanning interval to check the fileset for changes as a long with a time unit suffix h-hour, m-minute, s-second, ms-millisecond (e.g. 2ms or 5s). Disabled (scanInterval=0) by default. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms. We can include multiple values in a single entry. For example, 1s500ms is equivalent to 1.5 seconds.