JNDI 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 that is passed to the InitialContext constructor.

Set properties in the following ways:

• Through the command line: To set properties through the command line, enter the actual string value as indicated in this example:

  java -Dcom.ibm.websphere.naming.jndicache.maxentrylife=1440 MyProgram
  

• In a file: To set properties in a file, create a text file listing the properties. For example:

  ...
  com.ibm.websphere.naming.jndicache.cacheobject=none
  ...
  

• Within a program: To set properties in a Java program, use the following PROPS.JNDI_CACHE* Java constants, defined in the com.ibm.websphere.naming.PROPS class:

  import com.ibm.websphere.naming.PROPS;
  
  ...
  
  public static final String JNDI_CACHE_OBJECT = 
    "com.ibm.websphere.naming.jndicache.cacheobject";
  public static final String JNDI_CACHE_OBJECT_NONE      = "none";
  public static final String JNDI_CACHE_OBJECT_POPULATED = "populated";
  public static final String JNDI_CACHE_OBJECT_CLEARED   = "cleared";
  public static final String JNDI_CACHE_OBJECT_DEFAULT   = JNDI_CACHE_OBJECT_POPULATED;
  
  public static final String JNDI_CACHE_NAME = 
    "com.ibm.websphere.naming.jndicache.cachename";
  public static final String JNDI_CACHE_NAME_DEFAULT = "providerURL";
  
  public static final String JNDI_CACHE_MAX_LIFE = 
    "com.ibm.websphere.naming.jndicache.maxcachelife";
  public static final int    JNDI_CACHE_MAX_LIFE_DEFAULT = 0;
  
  public static final String JNDI_CACHE_MAX_ENTRY_LIFE = 
  "com.ibm.websphere.naming.jndicache.maxentrylife";
  public static final int    JNDI_CACHE_MAX_ENTRY_LIFE_DEFAULT = 0;
  

  To set a property in your program, enter the following:

  env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_NONE). 
   // Sets a property to a value
  

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, regardless 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. The valid values for this property and the resulting cache behavior are listed below.

  • "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.

  Note: You must include the quotation marks when specifying any of the above property values.

• 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. The valid option for cache names are listed below.

  • "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:2809" and "iiop://server1:2809/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.

  Note: You must include the quotation marks when specifying any of the above property values.

• 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 performed.

  Note: You must include the quotation marks when specifying any of the above property values.

• 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.

  Note: You must include the quotation marks when specifying any of the above property values.