Using WebLogic JNDI

I. Introduction

Overview of JNDI in the WebLogic Framework

WebLogic JNDI architecture

II. The WebLogic JNDI API

WebLogic JNDI API reference

Overview of the WebLogic JNDI API

III. Implementing with WebLogic JNDI

Using WebLogic JNDI from a client

Creating a Context

Properties that affect the context creation

Creating a Context using a Hashtable

Creating a Context using a WebLogic Environment object

Creating a Context from within a server-side object

Associating a principal with a thread

Looking up an object

Using JNDI in a distributed application environment

Making an object available by binding it to a name

IV. Setting up ACLs for JNDI in the WebLogic Realm

V. WebLogic JNDI in a clustered environment

J2EE Services

Making your own objects available in a clustered environment

Who needs access to the object?

Performance

Availability

Data caching example

Exactly-once-per-cluster services

Using WebLogic JNDI from a client in a clustered environment

Other related documents

Installing WebLogic (non-Windows)

Installing WebLogic (Windows)

Writing a WebLogic client application

Writing a server-side application

Using WebLogic Server Clusters

Developers Guides

API Reference Manual

Code examples

Glossary

Overview of JNDI in the WebLogic Framework

In the enterprise, naming and directory services -- the ability of your application to locate an object or service that may be anywhere on the network -- play an important part in building a distributed application. Particularly in a clustered environment, where clients may connect arbitrarily to any machine, the environment must have a naming service that can be depended upon to locate any service object requested no matter its physical location.

JNDI is a standard Java interface for accessing distributed services and data by name. It provides a portable, unified interface for services that need naming and directory services. The JNDI specification was defined independently of any specific naming or directory service implementation, but a developer can use it to access different, multiple naming and directory services such as LDAP, NDS, and NIS (YP). The JNDI specification also includes a specification for a service provider interface (SPI). The SPI provides a way for naming and directory service providers to make their services available through the JNDI interface.

WebLogic JNDI is a multitier implementation of the Java Naming and Directory Interface. Through WebLogic's implementation of the JNDI specification, introduced with version 3.0, a client can access any JNDI service provider that is accessible to the WebLogic Server. This effectively gives clients seamless access to enterprise services without any knowledge of physical location.

JNDI distinguishes between naming services and directory services:

• A naming service provides a mechanism to name objects (bind) and retrieve objects by name (lookup).

• A directory service is a naming service that also allows for attributes to be associated with each object and provides a way to retrieve an object based on its attributes rather than its name (search).

There are numerous JNDI service providers. For an up-to-date listing of server providers, see JNDI 1.2 Service Providers. WebLogic JNDI also implements a naming provider that allows clients to access WebLogic services.

This document assumes a basic understanding of naming and directory services and of the JNDI specification, which is available from JavaSoft. Included in this document is an overview and implementation guide for WebLogic's implementation of JNDI within the WebLogic framework.

WebLogic JNDI architecture

WebLogic's implementation of JNDI supplies methods to give clients access to the WebLogic name services, methods to make objects available in the WebLogic name system, and methods to retrieve objects from the WebLogic name system.

WebLogic clusters are supported by a replicated cluster-wide JNDI tree that provides access to both replicated and pinned RMI and EJB objects. While the naming service representing the cluster appears to the client as a single global tree, the tree containing the cluster-wide services is actually replicated across each server in the cluster. For more information see WebLogic JNDI in a clustered environment.

The integrated naming service provided by WebLogic JNDI may be used by many other WebLogic services. WebLogic RMI, for example, can bind and access remote objects by both the standard RMI methods as well as by JNDI methods.

The WebLogic JNDI API

WebLogic's implementation of JNDI is based on the JavaSoft JNDI 1.2 and SPI specifications, available from JavaSoft. This document assumes knowledge of the specification and the use of the JNDI javadocs from JavaSoft, available online at JavaSoft. In addition, WebLogic JNDI provides some minor extensions to the API as shown below.

WebLogic JNDI API reference

Package weblogic.jndi

Class java.lang.Object
    Class weblogic.jndi.Environment
    Interface weblogic.jndi.WLContext
    Class weblogic.jndi.WLInitialContextFactory

Overview of the WebLogic JNDI API

The WLInitialContextFactory creates instances of the WebLogic JNDI provider. Use this to create an InitialContext that refers to a WebLogic naming service.

You use WebLogic JNDI services for two purposes:

• To get access to named objects. First you obtain a Context, and then you use that Context to retrieve named objects. This document covers this in the section, Using WebLogic JNDI from a client. Note that "client" in this sense may mean any consumer of JNDI services.

• To name and bind objects J2EE services to make them available to others. In general, any client that has access to a name system can retrieve any object in it. To make objects available to clients of a name system, the object is bound to a name in the naming tree. In most cases, services are bound to the JNDI tree as a result of deployment. For example, when you deploy an EJB, the home gets bound into the tree automatically under the name defined in its deployment properties. When you define a JMS queue or topic, its gets bound to the JNDI tree automatically. In other cases, as with RMI objects, the application programmer is required to explicitly bind the object into the JNDI tree. This is discussed in the section, Using JNDI in a distributed application environment.

Implementing with WebLogic JNDI

Using WebLogic JNDI from a client

Creating a Context

Properties that affect the context creation

Creating a Context using a Hashtable

Creating a Context using a WebLogic Environment object

Creating a Context from within a server-side object

Looking up an object

Using JNDI in a distributed application environment

Making an object available by binding it to a name

Using WebLogic JNDI from a client

Creating a Context

weblogic.jndi.WLInitialContextFactory

weblogic.jndi.Environment

To access a JNDI service provider using WebLogic JNDI, you create an InitialContext and pass it a context factory, which creates the context for a certain provider. In the WebLogic case, you will use the WebLogic context factory, weblogic.jndi.WLInitialContextFactory, as an argument. Once the context is created, it provides client access to naming services within a naming system, through a WebLogic as name service provider. To create a WebLogic context from a client, you must minimally specify this factory as the initial context factory, and the URL of a WebLogic Server in the JNDI environment as properties passed to the constructor of the InitialContext.

There are two processes for creating an initial context. One uses a Hashtable for setting properties, and the other uses a WebLogic Environment object to pass properties to the initial context. Both methods require setting property values. We'll discuss the properties first, and then explain how those properties get set in two methods of creating a context:

Creating a context using a Hashtable

Creating a context using a WebLogic Environment object

We'll also show how to create a context for use with server-side objects that will operate exclusively within the same VM as the server:

Creating a context from within a server-side object

Properties that affect the context creation

You will need to set parameters to create a Context. The initial context factory uses the various properties to customize your InitialContext for a specific environment. You can set these properties either by using a Hashtable or by using the setXXX() methods associated with WebLogic Environment object.

The following is a list of some of the more important properties (name/value pairs) used to determine how the WLInitialContext factory creates the Context. Set them either using a Hashtable, or using setXXX() methods in the WebLogic Environment class. For a complete listing of available properties see the JavaDoc in your JDK for java.naming.Context and weblogic.jndi.WLInitialContextFactory (for WebLogic-specific properties).

• java.naming.provider.url. Set the URL of the service provider with the property name java.naming.provider.url. (In the example, we use the constant Context.PROVIDER_URL for this property name.) This property value should specify the WebLogic Server that will provide the name service. Value defaults to t3://localhost:7001.

• java.naming.security.principal. (In the example, we use the constant Context.SECURITY_PRINCIPAL for this property name.) Set the value for this property name to specify the identity of the principal (user) for security purposes. Value defaults to "guest" unless the thread has already been associated with a principal. See Associating a principal with a thread.

• java.naming.security.credentials. (In the example, we use the constant Context.SECURITY_CREDENTIALS for this property name.) Set the value for this property name to specify the password for the principal, or, alternatively, an Object that implements the weblogic.security.acl.UserInfo interface, with the property java.naming.security.credentials. If you pass a UserInfo object in this property, the property java.naming.security.principal is ignored. Value defaults to "guest" unless the thread has already been associated with a principal. See Associating a principal with a thread.

You can use the same properties on either a client or a server. If on the server, a local Context will be used. If on a client or another server, the Context will delegate to a remote Context running on the server specified by the java.naming.provider.url property.

The following code illustrates how to obtain an InitialContext for the WebLogic naming service, using the properties java.naming.factory.initial (for which we substitute the constant Context.INITIAL_CONTEXT_FACTORY) and java.naming.provider.url (for which we substitute the constant Context.PROVIDER_URL):

  Context ctx = null;
  Hashtable ht = new Hashtable();
  ht.put(Context.INITIAL_CONTEXT_FACTORY,
         "weblogic.jndi.WLInitialContextFactory");
  ht.put(Context.PROVIDER_URL,
         "t3://localhost:7001");

  try {
    ctx = new InitialContext(ht);
    // Use the context in your program
  }
  catch (NamingException e) {
    // a failure occurred
  }
  finally {
    try {ctx.close();}
    catch (Exception e) {
      // a failure occurred
    }
  }
  

Note that you should always close a context when you have finished working with it, just as you close database and client connections and other finite resources. We recommend that you do so in a finally{} block, and that you wrap your close() method in a try{} block. If you attempt to close a Context that was never instantiated because of some other error, your program will throw an Exception that you should catch and deal with.

There are additional methods of specifying properties when creating an initial context. For more information, see the Configuration section of JavaSoft's Java Naming and Directory Interface Application Programming Interface document.

There are other WebLogic-specific properties that you set to configure security parameters and that affect how objects are bound into the cluster-wide JNDI tree. Note that bindings may or may not be replicated across the JNDI tree of each server within the cluster. Properties such as this are identified by constants in the weblogic.jndi.WLContext class. There is more on JNDI-related clustering issues in Using WebLogic JNDI in a clustered environment.

Creating a Context using a Hashtable

You can create an InitialContext with a Hashtable in which you have put several properties (name/value pairs) that are used during the creation of the Context.

Initially, you pass the Hashtable to the constructor for InitialContext; at that point, the property java.naming.factory.initial is used to choose how the initial Context will be created. (In these examples, we use the constants found in the Context class for all property names.) To use WebLogic JNDI, you must always set this property to weblogic.jndi.WLInitialContextFactory, which identifies the factory that will actually create your Context. This part of the creation of an InitialContext is invariable.

You set this property using the property name java.naming.factory.initial. Note that in this example, we use the constant Context.INITIAL_CONTEXT_FACTORY. This property (name/value pair) specifies the factory used for creating the context. To gain access to WebLogic naming services, you must specify this property as weblogic.jndi.WLInitialContextFactory.

This completes the first step in the creation of a Context, using the property java.naming.factory.initial, which you set to weblogic.jndi.WLInitialContext. Then the WLInitialContextFactory.getInitialContext() uses other Hashtable name/value pairs to complete the creation of the Context.

Creating a Context using a WebLogic Environment object

weblogic.jndi.Environment

The simplest way to create an initial context is by using a WebLogic Environment object. Although the Environment object is WebLogic-specific, it offers you two really nice advantages: a set of defaults, which cuts down on the code you have to write, and some convenience "setter" methods that provide compile-type type-safety.

The type-safety setXXX() methods can save you time both writing and debugging. Now that you understand all about properties that are passed to the initial context, you can see that setting up these properties requires a lot of typing, and, in the end, those property names and values are just Strings that you might have mistyped or misnamed. The Environment object reduces the chance you will make such mistakes.

The Environment comes with a set of defaults:

• If you do not set an initial context factory, the default is to use WLInitialContextFactory.
• If you do not set a principal and password, the default is to use guest/guest unless the thread has already been associated with a principal. See Associating a principal with a thread.
• If you do not set a server URL, the default is to use "t3://localhost:7001".

This means that if you want to set up an initial context with these defaults, you can just write:

  Environment env = new Environment();
  Context ctx = env.getInitialContext();

Or if, for example, you want to set just a server to a DNS name for client cluster access, you might write:

  Environment env = new Environment();
  env.setProviderURL("t3://myweblogiccluster.com:7001");
  Context ctx = env.getInitialContext();

Creating a context from within a server-side object

You may also need to create a Context from an object that is instantiated in the WebLogic Server's VM, like an EJB or RMI object. There are a couple of considerations for server-side use; you do not need to specify things like provider URL, because this is already known to the VM creating the context. Username and password are required only if you want to sign in as a specific user. Server-side contexts will, of course, run in the context of the server itself.

To create a context from within a server-side object, all you need to do is new InitialContext, for example:

  Context ctx = new InitialContext();

You do not need to specify a factory, or a provider URL; by default, the context will be created as a WebLogic context and will connect to the local naming service.

Associating a principal with a thread

In order to perform work that requires authentication or access control, you must associate a principal, or user, with the thread that will perform the work. To do so, create a context with the appropriate principal and credential property values as described in the sections above. To disassociate a principal with the thread, close the context.

When a thread is associated with a principal, that principal becomes the default for the thread. If any contexts are subsequently created without principal or credential properties, the principal associated with the thread will remain unchanged.

While it is technically possible to share a single context among multiple threads, passing a context to another thread does not associate the principal used in creating the context with the new thread. The only way to associate a principal with a new thread is to create a new context within that thread. In addition, a context can only be closed within the thread with which it was created. For these reasons, it is strongly suggested that all work performed with a given context be handled in the same thread.

A thread may be associated with only one principal at any given time. If multiple contexts are created within a single thread without closing any contexts, the thread will be associated with the principal used in the last context created. principal information is stored with the thread in a stack. If the last context is closed, the thread becomes associated with the principal used in creating previous context, and so on.

Looking up an object

Once you have obtained a Context, you can use it to look up and retrieve named objects. You look up an object by the name under which it was bound when it was first placed in the name system.

The following code retrieves an Enterprise Java Bean named "SeviceBean":

  try { 
    ServiceBean bean = (ServiceBean)ctx.lookup("ejb.serviceBean");
  }
  catch (NameNotFoundException e) {
    // binding does not exist
  }
  catch (NamingException e) {
    // a failure occurred
  }

Using JNDI in a distributed application environment

For an object to be useable in a distributed environment, it must be bound to a name in the name system so that clients of the name system have an unambiguous way to ask for a reference to the object. Then a client calls the Context.lookup() method with the name as an argument, and is returned an object.

JNDI provides several ways to hook into the object retrieval machinery so that the implementor of a naming service can control what object is ultimately returned to the client performing a lookup. Objects can be stored as references (which encapsulate a factory for reconstructing the object on retrieval). It is also possible to specify an object factory that will be given the opportunity to transform objects retrieved from a naming service.

When a client retrieves an object from the naming service, the object should be useable in a meaningful way. If the client retrieves a Printer object, for example, the client should be able to use this object to print.

In a distributed environment, this requires that objects returned by lookup can be transported from the server to the client in a form that preserves their functionality. For simple objects that have no state, this can be achieved by returning an object that is serializable (that is, that implements java.io.Serializable). Whenever the lookup() method returns a serializable object to a client, the client actually receives a copy of the original object.

Practically, when binding from the client, only Remote objects or simple serializable Objects that represent values can be bound to a name (in effect, a replacement for calls to RMI's Naming.bind()).

See Making your own objects available in a clustered environment for information specific to clustered environments.

Making an object available by binding it to a name

After an object is bound to a name in a name system, any client that has access to that name system can retrieve it. This implies that all objects bound in the name system should be useable in a distributed environment; that is, the object that one client "binds" into the naming tree must be useable by any clients that can look it up.

At the least, such a concept of usability requires that the bound object be serializable. (In some cases, the object must also have a remote component, which we cover in the next section).

Here we illustrate the simplest case of making an object available to clients of a name system in a distributed environment, by demonstrating how to bind a string in the WebLogic name space. Because String implements java.io.Serializable, any client that looks up the object will get a copy of the string.

  try {
    ctx.bind("testMessage", "this is a test");
  }
  catch (NamingException e) {
    // a failure occurred
  }

Setting up ACLs for JNDI in the WebLogic Realm

ACL: weblogic.jndi.jndiName

WebLogic controls access to internal resources like JNDI through ACLs set up in the WebLogic Realm. Entries for ACLs in the WebLogic Realm are listed as properties in the weblogic.properties file. The access control list name for JNDI is weblogic.jndi.jndiName, where jndiName is the name of an object or service.

You can set the Permissions "lookup", "modify", and "list" for JNDI by entering a property in the properties file. If you do not set an ACL for JNDI, all permissions are by default granted to everyone.

Here is a breakdown of how these permissions map to actual JNDI methods:

• lookup controls calls to lookup() and lookupLink()

• list controls calls to list() and listBindings()

• modify controls calls to bind(), rebind(), rename(), createSubcontext(), destroySubcontext()

In the first two examples, we illustrate how you might set ACLs for looking up or modifying RMI objects. Peter, Brown, and Eric can look up and use RMI objects, but only the system user can change RMI objects.

The third example shows how you might set an ACL for listing bound objects in the "myapps" context. Only Peter, Brown, and Eric can obtain a list of objects bound to the "myapps" context.

Example:
weblogic.allow.lookup.weblogic.jndi.weblogic.rmi=peter,brown,eric weblogic.allow.modify.weblogic.jndi.weblogic.rmi=system weblogic.allow.list.weblogic.jndi.myapps=peter,brown,eric

WebLogic JNDI in a clustered environment

In the following sections, we will discuss how WebLogic JNDI is implemented in a clustered environment and some approaches you can take for making your own objects available to JNDI clients.

J2EE services

A clustered service provides failover and load-balancing. In order to be clustered, a service must be deployed on multiple servers and bound to the same name within the JNDI tree. With clustered services, special clusterable stubs use the chosen algorithm for load balancing and failover. For additional information see Using WebLogic Clusters.

In a clustered environment, WebLogic JNDI is designed specifically to work efficiently with RMI stubs. There are two characteristics of RMI stubs that have a major impact on how WebLogic JNDI is implemented in a clustered environment:

• RMI stubs are relatively small. This allows WebLogic JNDI to replicate stubs across all servers with little overhead in terms of server-to-server cross-talk.
• RMI stubs serve as a proxy for a server object. While stubs are replicated across servers, the actual service is provided by a server object hosted on only one of the servers. If that server goes down, the service offered by the server object is no longer available. For this reason, if the host server -- the server that initially bound the object to it's JNDI tree -- fails, the binding for the object will be removed from all other servers in the cluster.

Making your own objects available in a clustered environment

Who needs access to the object?

  Hashtable ht = new Hashtable();
  //turn off binding replication
  ht.put(WLContext.REPLICATE_BINDINGS, "false");
  try { 
    Context ctx = new InitialContext(ht);
    //bind the object
    ctx.bind("my_object", MyObect);
  } catch (NamingException ne) {
    //failure occured
  }

If your object needs to be accessible from any server in the cluster, there are two main approaches you can take:

• Rely on WebLogic JNDI's default behavior of replicating JNDI bindings to replicate your object across all servers.
• Deploy the object on each server in the cluster without replicating the JNDI bindings.

Performance

Availability

Data caching example

Suppose you have designed a simple, non-RMI, data caching object that performs well on single server and you would like to use this same object within a cluster of servers. If you simply bound the data caching object in the JNDI tree of one of the servers, WebLogic JNDI will, by default, copy the object to each of the other servers in the cluster. It is important to note that since this is not an RMI object, what you are binding into the JNDI tree (and copying to the other servers) is the object itself, not a stub that refers to a single instance of the object hosted on one of the servers. For the reasons explained above, it is often desirable to avoid using WebLogic JNDI's binding replication to copy large objects with high availability requirements to all of the servers in a cluster.

As an alternative, you can deploy a separate instance of the data caching object on each of the servers. When binding to each server's JNDI tree, you should make sure to turn off binding replication as described in Who needs access to the object?. In this architecture, each server will have a copy of the object, but you will avoid copying large amounts of data from server to server.

Each instance should maintain its own logic for when it needs to refresh its cache independently of the other data cache objects in the cluster. For example, suppose a client accesses the data cache on one server. It is the first time the caching object has been accessed, so it computes or obtains the information and saves a copy of the information for future requests. Now suppose another client connects to the cluster to perform the same task as the first client only this time the connection is made to a different server in the cluster. If this the first time this particular data caching object has been accessed, it will need to compute the information regardless of whether other data caching objects in the cluster already have the information cached. Of course, for any future requests, this instance of the data cache object will be able to refer to the information it has saved.

Exactly-once-per-cluster services

This architecture for an exactly-once-per-cluster service presents an additional challenge for services with high availability requirements. Since WebLogic Clusters' failover feature relies on having multiple deployments of each clustered service, failover for an exactly-once-per-cluster service will not be available. For services that require high availability, it is suggested that you implement a hardware, High-Availability (HA) framework for the host server. This will allow the server to be restarted in the event of a failure with a minimal amount of disruption to service availability.

Using WebLogic JNDI from a client in a clustered environment

However, in most cases, the object of interest is either a clustered service or a pinned service. This means that a stub for the service will appear in the JNDI tree for each server in the cluster. In this case, the client need not name a specific WebLogic Server to provide its naming service. In fact, it is best to simply request that a WebLogic Cluster provide naming service, in which case WebLogic's context factory can choose whichever WebLogic Server in the cluster seems most appropriate for the client. Currently, a naming service provider is chosen within WebLogic using DNS round-robining.

The context that is returned to a client of clustered services is, in general, implemented as a failover stub that can transparently change the naming service provider in the event of a communication or other failure with the selected WebLogic Server.

Here's an example of how a client uses the cluster's naming service. The hostname specified as part of the provider URL is the DNS name for the cluster that can be defined by the weblogic.cluster.name property. This command-line property is set when starting the cluster and maps to the list of hosts providing naming service in this cluster. For more information see Administering WebLogic Clusters.

In the example below, we are using the cluster name "acmeCluster" to connect to any of the servers in the cluster. The resulting context is replicated so that it can transparently failover to any WebLogic Server in the cluster.

  Hashtable ht = new Hashtable();
  ht.put(Context.INITIAL_CONTEXT_FACTORY,
         "weblogic.jndi.WLInitialContextFactory");
  ht.put(Context.PROVIDER_URL, "t3://acmeCluster:7001");
  try {
    Context ctx = new InitialContext(ht);
    // Do the client's work
  }
  catch (NamingException ne) {
    // A failure occurred
  }
  finally {
    try {ctx.close();}
    catch (Exception e) {
      // a failure occurred
    }
  }

  ht.put(Context.PROVIDER_URL, "t3://acme1,acme2,acme3:7001");

Notice that all the servers must be listening on the same port, as specified at the end of the URL.

Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.
Last updated 03/03/2000