References to enterprise bean (EJB) homes and other artifacts
such as data sources are bound to the WebSphere® Application Server name space. These
objects can be obtained through Java™ Naming
and Directory Interface (JNDI). 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 name space.
About this task
The following examples describe how to get an initial
context and how to perform lookup operations.
In these examples, the default behavior of features specific
to the WebSphere Application Server JNDI
Context implementation is used.
The WebSphere Application Server 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 initial context
factory. To set JNDI caching or name syntax properties which will
be visible to the initial context factory, do the following:
- 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
...
If you use this technique, be aware that other instances
of the jndi.properties file might exist in the classpath, and might
contain conflicting property settings. Property settings are determined
by the order in which the classloader picks up the jndi.properties
files. There is no way to control the order that the classloader
uses to locate files in the classpath. WebSphere Application Server
does not initially contain or create any jndi.properties files that
set the com.ibm.websphere.naming.jndicache.cacheobject property.
- 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
you 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 JavaMail session with
JNDI
The following example shows a lookup of a JavaMail
resource:
// Get the initial context as shown above
...
Session session =
(Session) initialContext.lookup("java:comp/env/mail/MailSession");
- Optional: 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 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 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
...
If you use this technique, be aware that other instances
of the jndi.properties file might exist in the classpath, and might
contain conflicting property settings. Property settings are determined
by the order in which the classloader picks up the jndi.properties
files. There is no way to control the order that the classloader
uses to locate files in the classpath. WebSphere Application Server
does not initially contain or create any jndi.properties files that
set the com.ibm.websphere.naming.name.syntax property.
- 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 (\\).
Optional: Disable host
name normalization References to host names, IP addresses,
and localhost in provider URLs are typically
normalized. The format of a normalized host name is the fully-qualified
form of the host name. Host name normalization improves system efficiency
because it enables the same JNDI cache to be used for a given bootstrap
host regardless of the format of the reference in the provider URL.
For example, host name normalization enables the same JNDI cache
to be used for myhost, myhost.mydomain.com,
and localhost references if all of these references
refer to the same host.
Because normalized host names are cached,
subsequent normalizations execute more quickly. In some network environments,
domain name lookup data changes dynamically, causing the cached host
name normalization data to become stale. In such environments, you
might need to disable hostname normalization. When you disable host
normalization, host name and IP addresses are used as is. References
to localhost typically resolve to the loopback
address, 127.0.0.1.
JNDI clients can disable host name normalization
by setting a property. The property setting is applied by the initial
context factory when you instantiate a new java.naming.InitialContext
object.
Use one of the following techniques to
set this property:
- You can enter the actual string value from a command line. For
example:
java -Dcom.ibm.websphere.naming.hostname.normalizer=...none...
- You can create a file named jndi.properties as a text file with
the desired properties settings. For example:
...
com.ibm.websphere.naming.hostname.normalizer=...none...
...
If you use this technique, be aware that other instances
of the jndi.properties file might exist in the classpath, and might
contain conflicting property settings. Property settings are determined
by the order in which the classloader picks up the jndi.properties
files. There is no way to control the order that the classloader
uses to locate files in the classpath. WebSphere Application Server
does not initially contain or create any jndi.properties files that
set the com.ibm.websphere.naming.hostname.normalizer property.
- You can use the PROPS.HOSTNAME_NORMALIZER* Java constants in a
Java program. These Java constants are defined in the com.ibm.websphere.naming.PROPS
file. Following are the constant definitions to specify if you use
this technique:
public static final String HOSTNAME_NORMALIZER =
"com.ibm.websphere.naming.hostname.normalizer";
public static final String HOSTNAME_NORMALIZER_NONE = "...none...;
To
use these definitions in a Java program, add the property setting
to a hashtable and pass it to the InitialContext constructor:
java.util.Hashtable env = new java.util.Hashtable();
...
env.put(PROPS.HOSTNAME_NORMALIZER, PROPS.HOSTNAME_NORMALIZER_NONE);
// Disable hostname normalization
...
javax.naming.Context initialContext =
new javax.naming.InitialContext(env);
Example: Disabling host name normalization
You
can pass the host name normalizer property to the InitialContext constructor
through the InitialContext constructor parameter in the system properties
file, or in a jndi.properties file. The initial context and any future
contexts looked up from that initial context use this property setting.
The following example shows how to disable host name normalization.
...
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.HOSTNAME_NORMALIZER, PROPS.HOSTNAME_NORMALIZER_NONE);
Context initialContext = new InitialContext(env);
java.lang.Object o = initialContext.lookup(...);
...