Example: Getting the default initial context
There are various ways for a program to get the default initial context.
The following example gets the default initial context. Note that no provider URL is passed to the javax.naming.InitialContext constructor.
... import javax.naming.Context; import javax.naming.InitialContext; ... Context initialContext = new InitialContext(); ...
The default initial context returned depends the runtime environment of the Java™ Naming and Directory Interface (JNDI) client. Following are the initial contexts returned in the various environments:
- Thin client
- The initial context is the server root context of the server running on the local host at port 2809.
- Pure client
- The initial context is the context specified by the java.naming.provider.url
property passed to launchClient command with the -CCD command line
parameter. The context usually is the server root context of the server
at the address specified in the URL, although it is possible to construct
a corbaname or corbaloc URL which resolves to some other context.
If no provider URL is specified, it is the server root context of the server running on the host and port specified by the
-CCproviderURL
, or-CCBootstrapHost
and-CCBootstrapPort
command line parameters. The default host is the local host, and the default port is 2809. - Server process
- The initial context is the server root context for that process.
Even though no provider URL is explicitly specified in the previous example, the InitialContext constructor might find a provider URL defined in other places that it searches for property settings.
Users of properties which affect ORB initialization should read the rest of this section for a deeper understanding of exactly how initial contexts are obtained.
Determining which server is used to obtain the initial context
WebSphere® Application Server name
servers are CORBA CosNaming name servers, and the product provides
a CosNaming JNDI plug-in implementation for JNDI clients to perform
naming operations on product namespaces. The CosNaming plug-in implementation
is selected through a JNDI property that is passed to the InitialContext
constructor. This property is java.naming.factory.initial
,
and it specifies the initial context factory implementation to use
to obtain an initial context. The factory returns a javax.naming.Context
instance, which is part of its implementation.
The initial context
factory, com.ibm.websphere.naming.WsnInitialContextFactory
,
is typically used by applications to perform JNDI operations. The WebSphere Application Server runtime environment
is set up to use this initial context factory if one is not specified
explicitly by the JNDI client. When the initial context factory is
invoked, an initial context is obtained. The following paragraphs
explain how the initial context factory obtains the initial context
in client and server environments.
- Registration of initial references in server processes
Every WebSphere Application Server has an ORB used to receive and dispatch invocations on objects running in that server. Services running in the server process can register initial references with the ORB. Each initial reference is registered under a key, which is a string value. An initial reference can be any CORBA object. WebSphere Application Server name servers register several initial contexts as initial references under predefined keys. Each name server initial reference is an instance of the interface org.omg.CosNaming.NamingContext.
- Obtaining initial references in pure client processes
Pure JNDI clients, that is, JNDI clients which are not running in a WebSphere Application Server process, also have an ORB instance. This client ORB instance can be passed to the InitialContext constructor, but typically the initial context factory creates and initializes the client ORB instance transparently. A client ORB can be initialized with initial references, but the initial references most likely resolve to objects running in some server. The initial context factory does not define any default initial references when it initializes an ORB. If the
resolve_initial_references
method is invoked on the client ORB when no initial references have been configured, the method invocation fails. This condition is typical for pure client processes. To obtain an initial NamingContext reference, the initial context factory must invokestring_to_object
with an IIOP type CORBA object URL, such ascorbaloc:iiop:myhost:2809
. The URL specifies the address of the server from which to obtain the initial context. The host and port information is extracted from the provider URL passed to the InitialContext constructor.If no provider URL is defined, the WebSphere Application Server initial context factory uses the default provider URL of
corbaloc:iiop:localhost:2809
.If no provider URL is defined, the WebSphere Application Server initial context factory uses the default provider URL of
corbaloc:iiop:your.server.name:2809
.The
string_to_object
ORB method resolves the URL and communicates with the target server ORB to obtain the initial reference. - Obtaining initial references in server processes
If the JNDI client is running in a WebSphere Application Server process, the initial context factory obtains a reference to the server ORB instance if the JNDI client does not provide an ORB instance. Typically, JNDI clients running in server processes use the server ORB instance; that is, they do not pass an ORB instance to the InitialContext constructor. The name server which is running in the server process sets a provider URL as a java.lang.System property to serve as the default provider URL for all JNDI clients in the process. This default provider URL is
corbaloc:rir:/NameServiceServerRoot
. This URL resolves to the server root context for that server. (The URL is equivalent to invokingresolve_initial_references
on the ORB with a key of NameServiceServerRoot. The name server registers the server root context as an initial reference under that key.) - Understanding the legacy ORB protocol
Releases previous to WebSphere Application Server Version 5 used a different ORB implementation, which used a legacy protocol in contrast with the Interoperable Name Service (INS) protocol now used. This change has affected the implementation of the initial context factory. Certain types of pure clients can experience different behavior when getting initial JNDI contexts as compared to previous releases of WebSphere Application Server. This behavior is discussed in more detail later in this section.
The following ORB properties are used with the legacy ORB protocol for ORB initialization and are now deprecated:
- com.ibm.CORBA.BootstrapHost
- com.ibm.CORBA.BootstrapPort
The new INS ORB is different in a major respect, in that it exhibits no default behavior if no initial references are defined.
In the legacy ORB, the bootstrap host and port values defaulted to
localhost
and900
.In the legacy ORB, the bootstrap host and port values defaulted to
your.server.name
and900
.All initial references were obtained from the server running on the bootstrap host and port. So, if the ORB user provided no bootstrap host and port, all initial references are resolved from the server running on the local host at port 900. The INS ORB has no concept of bootstrap host or bootstrap port. All initial references are defined independently. That is, different initial references could resolve to different servers. If
ORB.resolve_initial_references
is invoked with a key such that the ORB is not initialized with an initial reference having that key, the call fails.In releases previous to Version 5, the initial context factory invoked
resolve_initial_references
on the ORB in the absence of any provider URL. This action succeeded if a name server at the default bootstrap host and port was running. In the current release, with the INS ORB, this would fail. (Actually, the ORB would fall back to the legacy protocol during the deprecation period, but when the legacy protocol is no longer supported, the operation would fail.)The initial context factory now uses a default provider URL of
corbaloc:iiop:localhost:2809
, and invokesstring_to_object
with the provider URL.The initial context factory now uses a default provider URL of
corbaloc:iiop:your.server.name:2809
, and invokesstring_to_object
with the provider URL.This operation preserves the behavior that pure clients in previous releases experienced when they set no ORB bootstrap properties or provider URL. However, this different initial context factory implementation changes the behavior experienced by certain legacy pure clients, which do not specify a provider URL:
- Clients which set the ORB bootstrap properties previously listed when getting an initial context.
- Clients which supply their own ORB instance to the InitialContext constructor.
There are two ways to circumvent this change of behavior:
- Always specify an IIOP type provider URL. This approach does not
depend on the bootstrap host and port properties and continues to
work when support for the bootstrap host and port properties is removed.
For example, you can express bootstrap host and port property values
of
myHost
and2809
, respectively, ascorbaloc:iiop:myHost:2809
. - Use an rir type provider URL:
- Specify
corbaloc:rir:/NameServiceServerRoot
if the ORB is initialized to use a Version 5 server as the bootstrap server. - Specify
corbaname:rir:/NameService#domain/legacyRoot
if the ORB is initialized to use a Version 4.0.x server as the bootstrap server. - Specify
corbaloc:rir:/NameService
if the ORB is initialized to use a server other than a Version 5 or 4.0.x server as the bootstrap server.
URLs of this type are equivalent to invoking
resolve_initial_references
on the ORB with the specified key. If the bootstrap host and port properties are being used to initialize the ORB, this approach will not work when the bootstrap and host properties are no longer supported. - Specify
- The InitialContext constructor search order for JNDI properties
If the code snippet shown at the beginning of this section is executed by an application, the bootstrap server depends on the value of the property, java.naming.provider.url.
If the property is not set (in server processes the default value is set as a system property), the default host of
localhost
and default port of2809
are used as the address of the server from which to obtain the initial context.If the property is not set (in server processes the default value is set as a system property), the default host of
your.server.name
and default port of2809
are used as the address of the server from which to obtain the initial context.The JNDI specification describes where the InitialContext constructor looks for java.naming.provider.url property settings, but briefly, the property is picked up from the following places in the order shown:
- InitialContext constructor
- This does not apply to the previous example because the example uses the empty InitalContext constructor.
- System environment
- You can add JNDI properties to the system environment as an option on the Java command invocation and by program code. The recommended way to set the provider URL in the system environment is as an option supplied to the Java command invocation. Setting the provider URL in this manner is not temporal, so that getting a default initial context will always yield the same result. It is generally recommended that program code not set the provider URL property in the system environment because as a side-effect, this could adversely affect other, possibly unrelated, code running elsewhere in the same process.
- jndi.properties file
- There may be many jndi.properties files that are within the scope of the class loader in effect. All jndi.properties files are used for setting JNDI properties, but the provider URL setting is determined by the first jndi.properties file returned by the class loader.