New in Fix Pack 2

InfoCenter Home >
4: Developing applications >
4.3: Developing enterprise beans >
4.3.2: JNDI caching

4.3.2: JNDI caching

In IBM WebSphere Application Server Advanced Edition, JNDI context objects employ caching in order to increase the performance of JNDI lookup operations. Objects bound and looked up are cached in order to speed up subsequent lookups of those objects. Objects are cached as they are bound or initially looked up. Normally, JNDI clients should be able to simply use the default cache behavior. The following sections describe in detail cache behavior, and how JNDI clients can override default cache behavior if necessary.

Cache behavior

A cache is associated with an initial context when a javax.naming.InitialContext object is instantiated with the java.naming.factory.initial property set to:

com.ibm.ejs.ns.jndi.CNInitialContextFactory

CNInitialContextFactory searches the environment properties for a cache name, defaulting to the provider URL. If no provider URL is defined, a cache name of "iiop:///" is used. All instances of InitialContext which use a cache of a given name share the same cache instance.

After an association between an InitialContext instance and cache is established, the association does not change. A javax.naming.Context object returned from a lookup operation will inherit the cache association of the Context object on which the lookup was performed. Changing cache property values with the Context.addToEnvironment() or Context.removeFromEnvironment() method does not affect cache behavior. Properties affecting a given cache instance, however, may be changed with each InitialContext instantiation.

A cache is restricted to a process and does not persist past the life of the process. A cached object is returned from lookup operations until either the max cache life for the cache is reached, or the max entry life for the object's cache entry is reached.

After this time, a lookup on the object will cause the cache entry for the object to be refreshed. If a bind or rebind operation is executed on an object, the change will not be reflected in any caches other than the one associated with the context from which the bind or rebind was issued. This "stale data" scenario is most likely to happen when multiple processes are involved, since different processes do not share the same cache, and Context objects in all threads in a process will typically share the same cache instance for a given name service provider.

Usually, cached objects are relatively static entities, and objects becoming stale should not be a problem. However, timeout values can be set on cache entries or on a cache itself so that cache contents are periodically refreshed.

Cache properties

JNDI clients can use several properties to control cache behavior. These properties can be set in the JVM system environment or in the environment Hashtable passed to the InitialContext constructor.

Cache properties are evaluated when an InitialContext instance is created. The resulting cache association, including "none", cannot be changed. The "max life" cache properties affect the individual cache's behavior. If the cache already exists, cache behavior will be updated according to the new "max life" property settings. If no "max life" properties exist in the environment, the cache will assume default "max life" settings, irrespective of the previous settings. The various cache properties are described below. All property values must be string values.

  • com.ibm.websphere.naming.jndicache.cacheobject

    Caching is turned on or off with this property. Additionally, an existing cache can be cleared. Listed below are the valid values for this property and the resulting cache behavior:

    • "populated" (default): Use a cache with the specified name. If the cache already exists, leave existing cache entries in cache; otherwise, create a new cache.
    • "cleared": Use a cache with the specified name. If the cache already exists, clear all cache entries from 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 that is already associated with other InitialContext instances. The InitialContext being instantiated will not be associated with any cache.
  • com.ibm.websphere.naming.jndicache.cachename

    It is possible to create multiple InitialContext instances, each operating on the namespace of a different name service provider. By default, objects from each service provider 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 serves as the default cache name. With this property, a JNDI client can specify a cache name other than the provider URL.  Listed below are the valid options for cache names:

    • "providerURL" (default): Use the value for java.naming.provider.url property as the cache name. The default provider URL is "iiop:///". URLs are normalized by stripping off everything after the port. For example, "iiop://server1:900" and "iiop://server1:900/com/ibm/initCtx" are normalized to the same cache name.
    • Any string: Use the specified string as the cache name. Any arbitrary string with a value other than "providerURL" can be used as a cache name.
  • com.ibm.websphere.naming.jndicache.maxcachelife

    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". This property enables a JNDI client to set the maximum life of a cache as follows:

    • "0" (default): Make the cache lifetime unlimited.
    • Positive integer: Set the maximum lifetime of the cache, in minutes, to the specified value. When the maximum cache lifetime is reached, the cache is cleared before another cache operation is performed. The cache is repopulated as bind, rebind, and lookup operations are executed.
  • com.ibm.websphere.naming.jndicache.maxentrylife

    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". This property enables a JNDI client to set the maximum lifetime of individual cache entries as follows:

    • "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 will cause the entry to be refreshed.

Coding examples

import java.util.Hashtable;
import javax.naming.InitialContext;
import javax.naming.Context;

/*****
Caching discussed in this section pertains only to the WebSphere Advanced Edition
initial context factory. Assume the property, java.naming.factory.initial, is set
to "com.ibm.ejs.ns.CNInitialContextFactory" as a java.lang.System property.
*****/

Hashtable env;
Context ctx;

// To clear a cache:

env = new Hashtable();
env.put("com.ibm.websphere.naming.jndicache.cacheobject", "cleared");
ctx = new InitialContext(env);

// To set a cache's maximum cache lifetime to 60 minutes:

env = new Hashtable();
env.put("com.ibm.websphere.naming.jndicache.maxcachelife", "60");
ctx = new InitialContext(env);

// To turn caching off:

env = new Hashtable();
env.put("com.ibm.websphere.naming.jndicache.cacheobject", "none");
ctx = new InitialContext(env);

// To use caching and no caching:

env = new Hashtable();
env.put("com.ibm.websphere.naming.jndicache.cacheobject", "populated");
ctx = new InitialContext(env);
env.put("com.ibm.websphere.naming.jndicache.cacheobject", "none");
Context noCacheCtx = new InitialContext(env);

Object o;

// Use caching to look up home, since the home should rarely change.
o = ctx.lookup("com/mycom/MyEJBHome");
// Narrow, etc. ...

// Do not use cache if data is volatile.
o = noCacheCtx.lookup("com/mycom/VolatileObject");
// ...
Go to previous article: Late-breaking enterprise beans programming tips Go to next article: Using Java Message Service (JMS) resources

 

 
Go to previous article: Late-breaking enterprise beans programming tips Go to next article: Using Java Message Service (JMS) resources