JNDI cache settings

JNDI cache settings

Various JNDI cache property settings follow. Ensure that all property values are string values.

com.ibm.websphere.naming.jndicache.cachename

The name of the cache to associate with an initial context instance can be specified with this property.

It is possible to create multiple InitialContext instances, each operating on the namespace of a different name server. By default, objects from each bootstrap address are cached separately, since they each involve independent namespaces and name collisions could occur if they used the same cache. The provider URL specified when the initial context is created by default serves as the basis for the cache name. With this property, a JNDI client can specify a cache name. Valid options for cache names follow:

Valid options Resulting cache behavior
providerURL (default) Use the value for java.naming.provider.url property as the basis for the cache name. Cache names are based on the bootstrap host and port specified in the URL. The boostrap host is normalized to a fully qualfied name, if possible. For example, "corbaname:iiop:server1:2809#some/starting/context" and "corbaloc:iiop://server1" are normalized to the same cache name. If no provider URL is specified, a default cache name is used.
Any string Use the specified string as the cache name. Use any arbitrary string with a value other than "providerURL" as a cache name.

com.ibm.websphere.naming.jndicache.cacheobject

Turn caching on or off and clear an existing cache with this property.

By default, when an InitialContext is instantiated, it is associated with an existing cache or, if one does not exist, a new one is created. An existing cache is used with its existing contents. In some circumstances, this behavior is not desirable. For example, when objects that are looked up change frequently, they can become stale in the cache. Other options are available. The following table lists these other options along with the corresponding property value.

Valid values Resulting cache behavior
populated (default) Use a cache with the specified name. If the cache already exists, leave existing cache entries in the cache; otherwise, create a new cache.
cleared Use a cache with the specified name. If the cache already exists, clear all cache entries from the cache; otherwise, create a new cache.
none Do not cache. If this option is specified, the cache name is irrelevant. Therefore, this option will not disable a cache already associated with other InitialContext instances. The InitialContext that is instantiated is not associated with any cache.

com.ibm.websphere.naming.jndicache.maxcachelife

Impose a limit to the age of a cache with this property.

By default, cached objects remain in the cache for the life of the process or until cleared with the com.ibm.websphere.naming.jndicache.cacheobject property set to cleared. Enable a JNDI client to set the maximum life of a cache. This property differs from the maxentrylife property in that the entire cache is cleared when the cache lifetime is reached. The following table lists the various maxcachelife values and their affect on cache behavior:

In environments where WebSphere Application Server is running on a distributed platform cluster, and several WAS for z/OS member systems are running as a cluster, EJB workload management (WLM) failover on WAS for z/OS does not occur without making adjustments to the cache settings. Because interoperable object references (IORs) on WAS for z/OS are being workload managed, any pause in the WAS for z/OS results in all requests being dispatched to the surviving WebSphere Application for z/OS cluster. When the paused cluster member is resumed, only a very few requests (if any) are dispatched to this resumed cluster member, leading to an unbalanced system. The resumed cluster member has most of its CPU resources available, yet receives few (if any) requests to process, and as such, normal WLM processing does not occur after the paused system is resumed.

Proper workload balancing can continue by setting a global JNDI cache expiration time for the entire server to some reasonable time (for example, com.ibm.websphere.naming.jndicache.maxcachelife=3, which results in a three minute cache expiration time).

Valid values Resulting cache behavior
0 (default) Make the cache lifetime unlimited.
Positive integer Set the maximum lifetime of the entire cache, in minutes, to the specified value. When the maximum lifetime for the cache is reached, the next attempt to read any entry from the cache causes the cache to be cleared

com.ibm.websphere.naming.jndicache.maxentrylife

Impose a limit to the age of individual cache entries with this property.

By default, cached objects remain in the cache for the life of the process or until cleared with the com.ibm.websphere.naming.jndicache.cacheobject property set to cleared. Enable a JNDI client to set the maximum lifetime of individual cache entries. This property differs from the maxcachelife property in that individual entries are refreshed individually as their maximum lifetime reached. This might avoid any noticeable change in performance that might occur if the whole cache is cleared at once. The following table lists the various maxentrylife values and their effect on cache behavior:

Valid values Resulting cache behavior
0 (default) Lifetime of cache entries is unlimited.
Positive integer Set the maximum lifetime of individual cache entries, in minutes, to the specified value. When the maximum lifetime for an entry is reached, the next attempt to read the entry from the cache causes the individual cache entry to refresh.

Developing applications that use JNDI

Valid values	Resulting cache behavior
populated (default)	Use a cache with the specified name. If the cache already exists, leave existing cache entries in the cache; otherwise, create a new cache.
cleared	Use a cache with the specified name. If the cache already exists, clear all cache entries from the cache; otherwise, create a new cache.
none	Do not cache. If this option is specified, the cache name is irrelevant. Therefore, this option will not disable a cache already associated with other InitialContext instances. The InitialContext that is instantiated is not associated with any cache.

Valid values	Resulting cache behavior
0 (default)	Make the cache lifetime unlimited.
Positive integer	Set the maximum lifetime of the entire cache, in minutes, to the specified value. When the maximum lifetime for the cache is reached, the next attempt to read any entry from the cache causes the cache to be cleared

Valid values	Resulting cache behavior
0 (default)	Lifetime of cache entries is unlimited.
Positive integer	Set the maximum lifetime of individual cache entries, in minutes, to the specified value. When the maximum lifetime for an entry is reached, the next attempt to read the entry from the cache causes the individual cache entry to refresh.