Develop applications that use JNDI

References to EJB homes and other artifacts such as data sources are bound to the WAS name space. These objects can be obtained through JNDI. Before we can perform any JNDI operations, we need to get an initial context. Use the initial context to look up objects bound to the name space.

The following examples describe how to get an initial context and how to perform lookup operations.

• Getting the default initial context
• Getting an initial context by setting the provider URL property
• Set the provider URL property to select a different root context as the initial context
• Looking up an EJB home with JNDI

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

The WAS 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 WAS initial context factory. To set JNDI caching or name syntax properties which will be visible to the initial context factory, do the following:

 

1. Set 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. to look up objects which change relatively frequently, change your JNDI cache options.

   JNDI clients can use several properties to control cache behavior. We 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 the 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);
     

   Example: Controlling JNDI cache behavior from a program

   Following are examples that illustrate how we can use JNDI cache properties to achieve the desired cache behavior. Cache properties take effect when an InitialContext object is constructed.

   import java.util.Hashtable;
    import javax.naming.InitialContext;
    import javax.naming.Context;
    import com.ibm.websphere.naming.PROPS;
   
   /*****
    Caching discussed in this section pertains to the WebSphere Application  Server initial context factory. Assume the property,  java.naming.factory.initial, is set to
    "com.ibm.websphere.naming.WsnInitialContextFactory" as a
    java.lang.System property.
   *****/
    Hashtable env;
    Context ctx;
   
   
   // To clear a cache:
    env = new Hashtable();
    env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_CLEARED);
    ctx = new InitialContext(env);
   
   
   // To set a cache's maximum cache lifetime to 60 minutes:
    env = new Hashtable();
    env.put(PROPS.JNDI_CACHE_MAX_LIFE, "60");
    ctx = new InitialContext(env);
   
   
   // To turn caching off:
    env = new Hashtable();
    env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_NONE);
    ctx = new InitialContext(env);
   
   
   // To use caching and no caching:
    env = new Hashtable();
    env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_POPULATED);
    ctx = new InitialContext(env);
    env.put(PROPS.JNDI_CACHE_OBJECT, PROPS.JNDI_CACHE_OBJECT_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");
   
   // ...
   

   Example: Looking up a Java Mail session with JNDI

   The following example shows a lookup of a Java Mail resource:

   // Get the initial context as shown above
   ... Session session =
        (Session) initialContext.lookup("java:comp/env/mail/MailSession");
   

2. Specify the name syntax

   INS syntax is designed for JNDI clients that need to interoperate with CORBA applications. This syntax allows a JNDI client to make the proper mapping to and from a CORBA name. INS syntax is very similar to the JNDI syntax with the additional special character, dot (.). Dots are used to delimit the id and kind fields in a name component. A dot is interpreted literally when it is escaped. Only one unescaped dot is allowed in a name component. A name component with a non-empty id field and empty kind field is represented with only the id field value and must not end with an unescaped dot. An empty name component (empty id and empty kind field) is represented with a single unescaped dot. An empty string is not a valid name component representation.

   JNDI name syntax is the default syntax and is suitable for typical JNDI clients. This syntax includes the following special characters: forward slash (/) and backslash (\). Components in a name are delimited by a forward slash. The backslash is used as the escape character. A forward slash is interpreted literally if it is escaped, that is, preceded by a backslash. Similarly, a backslash is interpreted literally if it is escaped.

   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 the application needs to look up objects bound by CORBA applications, you may need to change the 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.

   We can set the property:

   • From a command line, enter the actual string value. For example:

     java -Dcom.ibm.websphere.naming.name.syntax=ins
     

   • Create 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 at the beginning of the classpath, so that the class loader loads the copy of jndi.properties before any other copies.

   • Use the PROPS.NAME_SYNTAX* Java constants, defined in the com.ibm.websphere.naming.PROPS file, in a Java program. 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);
     

   Example: Setting the syntax used to parse name strings

   The name syntax property can be passed to the InitialContext constructor through its parameter, in the System properties, or in a jndi.properties file. The initial context and any contexts looked up from that initial context parse name strings based on the specified syntax.

   The following example shows how to set the name syntax to make the initial context parse name strings according to INS syntax.

   ...
    import java.util.Hashtable;
    import javax.naming.Context;
    import javax.naming.InitialContext;
    import com.ibm.websphere.naming.PROPS;
   
    
   // WebSphere naming constants
   ... 
   Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, "com.ibm.websphere.naming.WsnInitialContextFactory");
    env.put(Context.PROVIDER_URL, ...);
    env.put(PROPS.NAME_SYNTAX, PROPS.NAME_SYNTAX_INS);
    Context initialContext = new InitialContext(env);
   
   // 
   The following name maps to a CORBA name component as follows:
   
   //    id = "a.name", kind = "in.INS.format"
   
   // The unescaped dot is used as the delimiter.
   
   // Escaped dots are interpreted literally. 
   java.lang.Object o = initialContext.lookup("a\\.name.in\\.INS\\.format");
   ...
   

   INS name syntax requires that embedded periods (.) in a name such as in.INS.format be escaped using a backslash character (\). In a Java String literal, a backslash character (\) must be escaped with another backslash character (\\).

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 or business interface with JNDI
JNDI interoperability considerations
JNDI caching
JNDI cache settings
JNDI to CORBA name mapping considerations

 

Related concepts

Naming
Namespace logical view

 

Related tasks

Use naming

 

Related

JNDI support in WAS
Lookup names support in deployment descriptors and thin clients