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 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 WAS v9 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 WAS 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 WAS 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. WAS 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.

• Obtain initial references in pure client processes

  Pure JNDI clients, that is, JNDI clients which are not running in a WAS 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 invoke string_to_object with an IIOP type CORBA object URL, such as corbaloc: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.

  (UNIX) (Windows) (ZOS) If no provider URL is defined, the WAS initial context factory uses the default provider URL of corbaloc:iiop:localhost:2809.

  (iSeries) If no provider URL is defined, the WAS 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.

• Obtain initial references in server processes

  If the JNDI client is running in a WAS 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 invoking resolve_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 WAS v5 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 WAS. 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.

  (UNIX) (Windows) (ZOS) In the legacy ORB, the bootstrap host and port values defaulted to localhost and 900.

  (iSeries) In the legacy ORB, the bootstrap host and port values defaulted to your.server.name and 900.

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

  (UNIX) (Windows) (ZOS) The initial context factory now uses a default provider URL of corbaloc:iiop:localhost:2809, and invokes string_to_object with the provider URL.

  (iSeries) The initial context factory now uses a default provider URL of corbaloc:iiop:your.server.name:2809, and invokes string_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, we can express bootstrap host and port property values of myHost and 2809, respectively, as corbaloc:iiop:myHost:2809.

  • Use an rir type provider URL:

    • Specify corbaloc:rir:/NameServiceServerRoot if the ORB is initialized to use a v5 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 v5 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.

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

  (UNIX) (Windows) (ZOS) 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 of 2809 are used as the address of the server from which to obtain the initial context.

  (iSeries) If the property is not set (in server processes the default value is set as a system property), the default host of our.server.name and default port of 2809 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

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

Developing applications that use JNDI

Initial context support

Example: Getting an initial context by setting the provider URL property