Developing applications that use JNDI

 

Developing applications that use JNDI

References to EJB homes and other artifacts such as data sources are bound to the WebSphere name space. These objects can be obtained through the JNDI interface. Before you can perform any JNDI operations, you need to get an initial context. You can use the initial context to look up objects bound to the WebSphere name space. These examples describe how to get an initial context and how to perform lookup operations.

In these examples, the default behavior of features specific to WebSphere's JNDI Context implementation is used.

WebSphere Application Server's JNDI context implementation includes special features. JNDI caching enhances performance of repeated lookup operations on the same objects. Name syntax options offer a choice of a name syntaxes, one optimized for typical JNDI clients, and one optimized for interoperability with CosNaming applications. Most of the time, the default behavior of these features is the preferred behavior. However, sometimes you should modify the behavior for specific situations.

JNDI caching and name syntax options are associated with a javax.naming.InitialContext instance. To select options for these features, set properties that are recognized by the WebSphere Application Server's initial context factory. To set JNDI caching or name syntax properties which will be visible to WebSphere Application Server's initial context factory, follow the following steps.

  1. Optional: Configure JNDI caches JNDI caching can greatly increase performance of JNDI lookup operations. By default, JNDI caching is enabled. In most situations, this default is the desired behavior. However, in specific situations, use the other JNDI cache options.

    Objects are cached locally as they are looked up. Subsequent lookups on cached objects are resolved locally. However, cache contents can become stale. This situation is not usually a problem, since most objects you look up do not change frequently. If you need to look up objects which change relatively frequently, change your JNDI cache options.

    JNDI clients can use several properties to control cache behavior. You can set properties:

    • From the command line by entering the actual string value. For example:
      java -Dcom.ibm.websphere.naming.jndicache.maxentrylife=1440 
      

    • In a jndi.properties file by creating a file named jndi.properties as a text file with the desired properties settings. For example:
      ...
      com.ibm.websphere.naming.jndicache.cacheobject=none ...

      Include the file as the beginning of the classpath, so that the class loader loads your copy of jndi.properties before any other copies.

    • Within a Java program by using the PROPS.JNDI_CACHE* Java constants, defined in the com.ibm.websphere.naming.PROPS file. The constant definitions follow:
      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 use the previous properties in a Java program, add the property setting to a hashtable and pass it to the InitialContext constructor as follows:

      java.util.Hashtable env = new java.util.Hashtable();
      ...
      
      // Disable caching env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_NONE); ...
      javax.naming.Context initialContext = new javax.naming.InitialContext(env);

  2. Optional: Specify the name syntax

    Most WebSphere applications use JNDI to look up EJB objects and do not need to look up objects bound by CORBA applications. Therefore, the default name syntax used for JNDI names is the most convenient. If your application needs to look up objects bound by CORBA applications, you may need to change your name syntax so that all CORBA CosNaming names can be represented.

    JNDI clients can set the name syntax by setting a property. The property setting is applied by the initial context factory when you instantiate a new java.naming.InitialContext object. Names specified in JNDI operations on the initial context are parsed according to the specified name syntax.

    You can set the property:

    • From the command line by entering the actual string value. For example:
       java -Dcom.ibm.websphere.naming.name.syntax=ins

    • In a jndi.properties file by creating a file named jndi.properties as a text file with the desired properties settings. For example:
      ...
      com.ibm.websphere.naming.name.syntax=ins ...
      Include the file as the beginning of the classpath, so that the class loader loads your copy of jndi.properties before any other copies.

    • Within a Java program by using the PROPS.NAME_SYNTAX* Java constants, defined in the com.ibm.websphere.naming.PROPS file. The constant definitions follow:
      public static final String NAME_SYNTAX =
          "com.ibm.websphere.naming.name.syntax";
      public static final String NAME_SYNTAX_JNDI = "jndi";
      public static final String NAME_SYNTAX_INS  = "ins";

      To use the previous properties in a Java program, add the property setting to a hashtable and pass it to the InitialContext constructor as follows:

      java.util.Hashtable env = new java.util.Hashtable();
      ...
      env.put(PROPS.NAME_SYNTAX, PROPS.NAME_SYNTAX_INS); // Set name syntax to INS
      ...
      javax.naming.Context initialContext = new javax.naming.InitialContext(env);




Sub-topics
Example: Getting the default initial context
Example: Getting an initial context by setting the provider URL property
Example: Setting the provider URL property to select a different root context as the initial context
Example: Looking up an EJB home with JNDI
Example: Looking up a JavaMail session with JNDI
JNDI interoperability considerations
JNDI caching
JNDI cache settings
Example: Controlling JNDI cache behavior from a program
JNDI name syntax
INS name syntax
JNDI to CORBA name mapping considerations
Example: Setting the syntax used to parse name strings

Related concepts
Naming
Name space logical view

Related tasks
Using naming

Related reference
JNDI support in WebSphere Application Server
Lookup names support in deployment descriptors and thin clients