Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

# 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. The class weblogic.jndi.WLInitialContextFactory provides an entry point for a client into the WebLogic name space. References to other JNDI interfaces in this document are to WebLogic's implementation of JNDI. You should also refer to the API reference materials available at JavaSoft's website for information on the standard JavaSoft spec. # 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 A client may access objects in the WebLogic framework by creating an InitialContext within the WebLogic name system, and then retrieving objects by name from within that system. The two basic operations are creating an initial context and looking up objects in the name space. The following sections discuss JNDI client operations for connecting to a specific server. While these concepts do apply in a clustered environment, you should also reference Using WebLogic JNDI from a client in a clustered environment for additional information on connecting to a cluster of servers. ### 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 The intent of WebLogic JNDI is to provide a naming service for J2EE services, specifically EJB, RMI, and JMS services. This does not mean that you cannot use the WebLogic JNDI to make your own objects accessible to JNDI clients, however you should have a good understanding of the implications of binding an object to the JNDI tree before doing so, particularly 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 WebLogic RMI is the enabling technology that allows clients to access EJBs and JMS services from a client in another JVM. As discussed in Using WebLogic RMI, RMI stubs marshal incoming calls from the client to the RMI server object. To make J2EE servcies available to a JNDI client, a server simply binds an object -- in this case, an RMI stub for a particular service -- into it's JNDI tree under a particular name. WebLogic Clusters extend WebLogic JNDI for a single server to one that contains all of the offerings provided by the cluster. This is done by replicating the bindings -- the RMI stubs -- bound in each server to all of the other servers in the cluster. When a client connects to a cluster, its is actually connected to one of the servers in the cluster. Since the JNDI tree for this server contains the stubs for all services offered by the other servers in the cluster in addition to its own services, the cluster appears to the client as one server hosting all of the cluster-wide services. When a new server joins a cluster, each server is responsible for sharing informing about its own services to the new server so that it may create its own copy of the "cluster-wide" tree. 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 When you bind a custom object into a JNDI tree within a cluster, your object will be handled just as described above. However, your object will likely have different characteristics than an RMI stub. Therefore the default behavior of WebLogic JNDI within a cluster may not be suitable for your situation. The following sections discuss some things you should consider before binding a custom object to a JNDI tree within a cluster. ### Who needs access to the object? Suppose your object only needs to be accessed by EJBs that are deployed on one server only. Obviously there would be no need to replicate this object throughout all of the servers in the cluster. In fact, you would specifically want to avoid doing so, to avoid any performance degradation due to unnecessary server-to-server cross-talk. In order to create a binding that is not replicated across servers, you must specify this option when creating the context that will be used to bind the object as shown in the example below:
      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
      }
Of course this means that you will need to explicitly obtain an initial context for this particular server when you need to use the object. If you connect to any other server in the cluster, the binding will not appear in the JNDI tree. 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. The approach you take will have an effect on your application's performance and the availability of the object as described in the following sections. ### Performance Relying on WebLogic JNDI to copy an object from one server to all of the other servers in a cluster can have an adverse effect on performance due to additional server-to-server cross-talk. The effect on performance will depend on the size of the object. If your object is large or dynamic in size, it is strongly advised to avoid this technique. Instead, you can use an approach similar to one described in Data caching example. ### Availability When using WebLogic JNDI to replicate bindings, the bound object will be handled as if it owned by the host server -- the server that initially bound the object to it's JNDI tree. If the host server fails, the object will be removed from all the servers in the cluster. While this is the appropriate behavior in cases where the bound object is an RMI stub referring back to the host server, it may not be the appropriate behavior for your object. This can have an adverse effect on the availability of your object. If the availability of your object is critical, you can use an approach similar to the one described in Data caching example. ### Data caching example A common task in Web applications is to cache data used by multiple objects for a period of time to avoid the overhead associated with data computation or connecting to another service. (For caching JDBC accessible data, you should use read-only entity EJBs. See BEA WebLogic Server Enterprise JavaBeans for more information.) 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 In some cases, it is desirable to have a service that appears only once in the cluster. This is accomplished by deploying the service on one machine only. For RMI objects, you can use the default behavior of WebLogic JNDI to replicate the binding (the RMI stub) and the single instance of your object will be accessible from all servers in the cluster. This is referred to as a pinned service. For non-RMI objects, make sure that you that you bind that object so that the binding is not replicated as described in Who needs access to the object?. In this case, you will need to explicitly connect to the host server to access the object. Alternatively, you can create an RMI object that is deployed on the same host server that can act as a proxy for your non-RMI object. The stub for the proxy can be replicated (using the default WebLogic JNDI behavior) allowing clients connected to any server in the cluster to access the non-RMI object via the RMI proxy. 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 In the sections above, we discuss how the JNDI binding for an object can appear in the JNDI tree for one server in the cluster or can be replicated to all of the servers in the cluster. If the object of interest is bound in only one server, you must explicitly connect to the host server by setting the Context.PROVIDER_URL property to the host server's URL when creating the initial context as described in Using WebLogic JNDI from a client. 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
        }
      }
An alternative method of specifying the initial point of contact with the cluster is to supply a comma-delimited list of DNS Server names or IP addresses, as shown in this code fragment:
      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