LDAP stands for the Lightweight Directory Access Protocol which provides both a naming and a directory service. LDAP evolved from the X.500 Directory Access Protocol, where it originally only provided the TCP/IP front end for DAP. The X.500 DAP is based on the OSI model for networking. LDAP provided the interface to TCP/IP clients. Gradually, LDAP and DAP merged into the standalone entity now known simply as LDAP which is considered a “lightweight” implementation of the Directory Access Protocol.

LDAP now runs as a standalone service. It must be configured with a back-end database that is used for persistent storage of the bindings and attributes. The schema of the database is organized as a hierarchical tree structure, also commonly referred to as the Directory Information Tree (DIT). Each element in the tree has a unique name, called its distinguished name. The distinguished name is constructed by concatenating the name of each element up to the root of the tree. An example of the LDAP tree structure is shown in Figure 14.2.

Figure 14.2. The LDAP tree structure is a graphical representation of the distinguished names.

From the elements in Figure 14.2, you can see that the LDAP distinguished name for the RemoteObject is "cn=RemoteObject,dc=weblogic,dc=com". Each element of the distinguished name is a node in the tree. This example contains three elements separated by commas which follows the syntax of an LDAP distinguished name. Each element must match an attribute type that is defined in a schema that the LDAP server was configured to install.

The syntax for an individual element in the distinguished name is:

<attribute>=<name>

The <attribute> must match an attribute from the schema. The <name> is any name of your choosing to uniquely identify the entry.

The configuration of the LDAP server specifies a base distinguished name in the hierarchical tree for each back-end database that it is configured to use. All elements below the base are physically stored in the corresponding back-end database. The LDAP server configuration also defines a root distinguished name which is used to control access to the server. The root distinguished name is password protected.

Because LDAP is a directory service, each element in the tree may have a list of attributes. Again, the attributes must match the schema that is defined for the LDAP server. In the case of J2EE applications, the JNDI name is bound to a serialized Java object that represents the remote interface; no directory attributes are used.

WebLogic Server is compatible with any LDAP server that is LDAP v2 compliant. For example, the following LDAP servers have been tested with WebLogic:

The RMI registry is the naming service used by Java Remote Method Invocation. It maintains the bindings between a name and the object that implements the remote interface. The RMI registry is accessed from RMI clients using the JNDI API or the java.rmi.Naming class.

The entries in the RMI registry are created by the RMI remote object which binds the name to the remote object that it is implementing. The RMI client looks up the name in the RMI registry to retrieve the remote interface. The Java 2 Standard Edition includes the executable “rmiregistry” that implements the registry for RMI.

The Common Object Services (COS) Name Server is the naming service for CORBA. It maintains the bindings between a name and a CORBA server. The COS Name Server is accessed using the JNDI API or the classes in the org.omg. CosNaming.NamingContext package. Listing 14.1 shows an example of locating a CORBA server named “Hello” using the classes in the org.omg.CosNaming and org.omg.CosNaming.NamingContextPackage packages.

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;

// get a reference to the Hello server from CORBA
public void findHelloServer()
{
  org.omg.CORBA.Object objRef =
    orb.resolve_initial_references("NameService");
  NamingContext ncRef = NamingContextHelper.narrow(objRef);

  // resolve the Object Reference in Naming
  NameComponent nc = new NameComponent("Hello", "");
  NameComponent path[] = {nc};
  Hello helloRef = helloHelper.narrow(ncRef.resolve(path));
}

The COS naming service can also be accessed using JNDI. The advantage of using JNDI is to better achieve portability. Rather than being locked into CORBA, writing the code using JNDI provides the flexibility to attach to a different naming service without significant modification to the code.

WebLogic Server’s implementation of a JNDI naming service serves as an in-memory repository and lookup service for all hosted J2EE objects and services, such as:

For example, in a J2EE application, a JavaServer Page (JSP) or servlet is typically the client of the Enterprise Java Bean (EJB); thus, it performs the lookup operation using JNDI to retrieve the client-side interface to the EJB. An entity EJB also uses JNDI to lookup the DataSource and UserTransaction objects to communicate with a database.

However, since the JNDI objects are stored in-memory, the JNDI service should not be used as a database. The objective of JNDI is to store Java objects to support repetitive lookups only. Storing large objects, such as a file, using JNDI would not only require a large amount of memory, but would also be a burden on the network.

The Structure of the WebLogic Naming Service—The JNDI Tree

In order to bind and lookup objects using JNDI in WebLogic Server, you must understand the internal structure of WebLogic Server’s naming service, also referred to as the JNDI tree.

The structure of the WebLogic JNDI tree is illustrated in Figure 14.3, where:

Figure 14.3. The Internal Structure of the WebLogic Server’s JNDI Tree.

• A Context (C) represents a node in the tree and is bound to other contexts or objects. A context bound to another context is known as a subcontext. For example, given a DNS domain Bea.COM, the DNS domain Bea is a subcontext of COM.

• Objects (O) are bound to a context and represent the leaves in a JNDI tree. Examples of objects include EJB Home interface objects, DataSource objects and factory objects for creating connections to JMS topics. A binding associates an object with a name with its relative context. Hence, each Context can be asked to find an object within its branch of the tree by giving the object’s name relative to its context.

• The Root Context (RC) is the uppermost context of the JNDI tree.

• The Initial Context (IC) serves as the starting point for all future JNDI tree searches (object lookups), similar to when you select your current directory on a file system.

The WebLogic Server binds J2EE services into the JNDI tree as part of the installation. In addition, the WebLogic container binds the local and remote home interfaces of EJBs into the JNDI tree when enterprise applications are deployed. The installed J2EE services can be viewed on the WebLogic Administrator Console using the following steps:

1. Connect to the WebLogic Administrator Console with a web browser. If the web browser is being run on the same system as the WebLogic Application Server, the URL is typically http://localhost:7001/console.

2. The frame on the left side is the navigation tree to select the available services. In the navigation tree, open the Servers folder in the domain that is installed. This folder contains the list of configured servers. Right-click on a server name and select the “View JNDI tree” menu item.

3. The JNDI tree for the selected server opens in a new browser window. An example of the JNDI tree viewer is shown in Figure 14.4, which shows the default JNDI bind names and objects under the weblogic context.

   

   Figure 14.4. The bind names and objects in the JNDI tree can be viewed from the WebLogic Administrator Console.

You can also use the WebLogic.Admin utility to view the JNDI bindings in your WebLogic Server using the following syntax:

java weblogic.Admin [-url URL] -username username -password password LIST context

where:

• URL specifies the listen address of the WebLogic Server that is the target of the command. The format for the URL is hostname:port; for example the default is localhost:7001.

• username specifies the username to access the target WebLogic Server for the command.

• password specifies the password associated with the username to access the target WebLogic Server for the command.

• LIST specifies the command to list the JNDI tree node bindings.

• context specifies the JNDI context for lookup, for example, weblogic, weblogic.ejb, or javax.

For example, in the following weblogic.Admin statement, the user wls, who has a password of einstein, requests a list of the node bindings in the context named weblogic:

java weblogic.Admin -url localhost:7001 -username wls -password einstein LIST weblogic

The output for this statement is shown in Figure 14.5.

Figure 14.5. Using the weblogic.Admin utility to view the WebLogic JNDI bindings.

Tip

If a JNDI lookup fails, you can use the WebLogic Administrator Console to “View the JNDI tree” and verify that the attributes of the bound object match the name you are trying to lookup.

The InitialContextFactory class for the LDAP SPI is com.sun.jndi.ldap.LdapCtxFactory. The PROVIDER_URL is constructed with a protocol, hostname, and port. The protocol is ldap, and the hostname is the name of the host where the LDAP server is running. If the LDAP server is running on the same system as the Java application, you can use localhost as the hostname. The default port for LDAP is 389, but the LDAP server may be running on another port. A sample PROVIDER_URL for LDAP is

ldap://localhost:389

The example in Listing 14.2 creates a javax.naming.Context for the LDAP SPI. The context environment specifies com.sun.jndi.ldap.LdapCtxFactory as the InitialContextFactory. The PROVIDER_URL defines the hostname and port of the LDAP server. The SECURITY_AUTHENTICATION, SECURITY_PRINCIPAL, and SECURITY_CREDENTIALS are used to authorize access to the root distinguished node of the LDAP database.

/** Create JNDI Context for LDAP
    @param    rootDN    LDAP root distinguished name
    @param rootPW    LDAP root password
    @returns JNDI Context
    @exception NamingException
*/
private Context createLdapContext(
    String rootDN,
    String rootPW )
    throws NamingException
{
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory" );
    env.put( Context.PROVIDER_URL, "ldap://localhost:389" );
    env.put( Context.SECURITY_AUTHENTICATION, "simple" );
    env.put( Context.SECURITY_PRINCIPAL, rootDN );
    env.put( Context.SECURITY_CREDENTIALS, rootPW );
    Context ctx = new InitialContext( env );
    return ctx;
}

The InitialContextFactory class for the RMI SPI is com.sun.jndi.rmi.registry.RegistryContextFactory. The PROVIDER_URL is constructed with a protocol, hostname, and port. The protocol is rmi, and the hostname is the name of the host where the rmiregistry is running. If the rmiregistry is running on the same system as the Java application, you can use localhost as the hostname. The default port for RMI is 1099, but the rmiregistry may be running on another port. A sample PROVIDER_URL for RMI is

rmi://localhost:1099

The example in Listing 14.3 creates a javax.naming.Context for the RMI SPI. The context environment specifies com.sun.jndi.rmi_registry.RegistryContextFactory as the InitialContextFactory. The PROVIDER_URL defines the hostname and port of the RMI server. The context environment for RMI requires the RMISecurityManager to be specified.

/** Create JNDI Context for RMI
    @returns JNDI Context
    @exception NamingException
*/
private Context createRmiContext()
    throws NamingException
{
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.rmi.registry.RegistryContextFactory" );
    env.put( Context.PROVIDER_URL, "rmi://localhost:1099" );
    env.put( "java.naming.rmi.security.manager", "RMISecurityManager" );
    Context ctx = new InitialContext( env );
    return ctx;
}

The InitialContextFactory class for the COS SPI is com.sun.jndi.cosnaming.CNCtxFactory. The PROVIDER_URL for the Common Object Services is slightly more complex than the other Service Provider Interfaces. The URL is constructed with a protocol, hostname, port, and the name of the CosNaming service. For COS, the URL is used to configure the root-naming context and/or the Object Request Broker (ORB). The protocol can be either iiop or iiopname. The iiop protocol specifies a single hostname, and the iiopname protocol specifies an addr_list, which is a list of hostnames. The default port for iiop is 900, and the default port for iiopname is 9999. Examples of the two forms for the PROVIDER_URL are:

iiop://localhost:900/<cosnaming_name>
iiopname://<addr_list>:9999/<cosnaming_name>

The example in Listing 14.4 creates a javax.naming.Context for the COS SPI. The context environment specifies com.sun.jndi.cosnaming.CNContextFactory as the InitialContextFactory. The PROVIDER_URL defines the hostname and port of the CosNaming service. The COS SPI does not specify SECURITY_CREDENTIALS as it uses the Java Security Manager.

/** Create JNDI Context for COS
    @returns JNDI Context
    @exception NamingException
*/
private Context createCosContext()
    throws NamingException
{
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.cosnaming.CNCtxFactory" );
    env.put( Context.PROVIDER_URL, "iiop://localhost:900" );
    Context ctx = new InitialContext( env );
    return ctx;
}

permission java.net.SocketPermission "host[:port]", "connect";

The InitialContextFactory class for the WebLogic SPI is weblogic.jndi.WLInitialContextFactory. The URL is constructed with a protocol, hostname, and port. The protocol is t3, and the hostname is the name of the host where WebLogic Server is running. If WebLogic Server is running on the same system as the Java application, you can use localhost as the hostname. The default port for the WebLogic name service is 7001, but it may be running on another port. A sample PROVIDER_URL for the WebLogic name service is

t3://localhost:7001

/** Create JNDI Context for WebLogic
    @param    user        User in WebLogic Server security realm
    @param password    Password for user
    @returns JNDI Context
    @exception NamingException
*/
private Context createWebLogicContext(
    String user,
    String password )
{
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory" );
    env.put( Context.PROVIDER_URL, "t3://localhost:7001" );
    env.put( Context.SECURITY_AUTHENTICATION, "simple" );
    env.put( Context.SECURITY_PRINCIPAL, user );
    env.put( Context.SECURITY_CREDENTIALS, password );
    Context ctx = new InitialContext( env );
    return ctx;
}

/** Create JNDI Context for WebLogic
    @param  user        User in WebLogic Server security realm
    @param  password    Password for user
    @returns JNDI Context
    @exception NamingException
*/
private Context createWebLogicContext(
    String user,
    String password )
{
  try {
    // Create the WebLogic Environment
    // use default value: WLInitialContextFactory, "t3://localhost:7001,
    Environment env = new Environment();
    env.setSecurityPrincipal( user );
    env.setSecurityCredentials( password );
    // in this case, we get the InitialContext from the Environment object
    Context ctx = env.getInitialContext();
    // use ctx to lookup JNDI services
  } catch( NamingException x ) {
    System.err.println( x.toString() );
  }
}

After the context is created, the lookup() method is used to locate an object by name, errors are handled with exceptions. The NameNotFoundException is thrown if the name is not found in the naming service. The NamingException is thrown if there was a communication failure with the naming service. Listing 14.7 retrieves an EJB named MySessionBean from the Context created for WebLogic Server.

try {
    // create the Context first...
    // use ctx to lookup an EJB named MySessionBean
    MySessionBean msb = (MySessionBean)ctx.lookup( "ejb.mySessionBean" );
    // use MySessionBean here
} catch( NameNotFoundException x ) {
    System.err.println( "ejb.mySessionBean was not found" );
} catch( NamingException x ) {
    System.err.println( x.toString() );
}

It is important to close the Context after the client is finished using it. By doing so, you release the resources that were created for the Context. A finally block is recommended to ensure the Context is closed whether or not an exception is thrown. The structure of using the finally block to close the context is shown in Listing 14.8.

Context ctx = null;
try {
    // create the Context
    ctx = new InitialContext();

    // use the Context

} catch( NamingException x ) {
    System.err.println( x.toString() );
} catch( Exception x ) {
    System.err.println( "unexpected exception: " + x );
} finally {
    try {
        if( ctx != null )
          ctx.close();
    } catch( Exception x ) {
        System.err.println( "failed to close Context: " + x );
    }
}

In this section, you learn how to bind an object with a JNDI naming service. The binding is created using the bind() or rebind() methods of the Context object.

Follow these steps to bind an object with a JNDI naming service:

The parameters to the Context method bind() are a name as a String and an object. You must use the rebind() method to force the new object to be bound to a name that already exists. You use the unbind() method to remove the binding from the service provider. The parameter to unbind() is the bound name. All JNDI Context methods throw NamingException to indicate that a failure occurred while trying to communicate with the naming service. Listing 14.9 shows an example of binding a pinned object with the WebLogic naming service.

private void pinObject( String name, Object obj ) {
  try {
    Hashtable env = new Hashtable();
    // pin the object
    env.put( WLContext.REPLICATE_BINDINGS, "false" );
    Context ctx = new InitialContext( env );
    // bind the object
    ctx.bind( name, obj );
  } catch( NamingException x )
    System.err.println( "Failed to bind " + name + ": " + x );
  }
}

The heart of a J2EE application is the EJB. The clients of the EJB use JNDI to look up the home interface. The home interface is then used to create an instance of the remote interface for the EJB. With EJB, the name to look up is the same as the name of the home interface class. Listing 14.10 shows an example of an EJB client using JNDI to look up the home interface.

Context ctx = null;
try {
  ctx = new InitialContext();
  MyEjbHome home = null;
  Object homeObj = ctx.lookup("MyEjbHome");
  home = (MyEjbHome)javax.rmi.PortableRemoteObject.narrow(homeObj, MyEjbHome.class);
}
catch (NamingException e) {
  e.printStackTrace();
}
catch( NamingException x ) {
  System.err.println( x.toString() );
}

The configuration of JMS includes connection factories and distributed destinations, each of which have a JNDI name. The connection factories enable JMS clients to create JMS connections. The distributed destinations are the JMS Queues and Topics.

Chapter 15 describes the details of JMS Queue Producer/Consumer and JMS Topic Producer/Consumer. Here, you see how to use JNDI to retrieve these services from the WebLogic naming service. The ConnectionFactory, Queue, and Topic are all retrieved by performing a JNDI lookup. The name of the default JMS connection factory is the full class name weblogic.jms.ConnectionFactory. The JNDI name for the Queue and Topic is manually administered through the WebLogic Server Console as part of the configuration for JMS. The client of the JMS Queue uses JNDI to look up the name, as shown in Listing 14.11.

try {
Context ctx = new InitialContext();
QueueConnectionFactory qcf = (QueueConnectionFactory)ctx.lookup(
"weblogic.jms.ConnectionFactory" );
Queue queue = (Queue)ctx.lookup( "MyJmsQueue" );
QueueConnection qc = qcf.createQueueConnection();
// use the QueueConnection and message queue
    } catch( NamingException x ) {
        System.err.println( x.toString() );
    }

The JMS Topic Producer and Consumer use JNDI in a similar manner as the preceding Queue example, as shown in Listing 14.12.

try {
Context ctx = new InitialContext();
TopicConnectionFactory tcf = (TopicConnectionFactory)ctx.lookup(
"weblogic.jms.ConnectionFactory" );
Topic topic = (Topic)ctx.lookup( "MyJmsTopic" );
TopicConnection tc = qcf.createTopicConnection();
// use the QueueConnection and message queue
    } catch( NamingException x ) {
        System.err.println( x.toString() );
    }

Chapter 16, “Managing Java Transactions Using JTA,” describes the advantages of using JDBC DataSources over the DriverManager. With WebLogic Server, the DataSource is bound to the naming service using the WebLogic Administrator Console. The client of the DataSource uses JNDI to look up the name, as shown in Listing 14.13.

try {
Context ctx = new InitialContext();
DataSource ds = (DataSource)ctx.lookup( "MyJDBCDataSource" );
Connection con = ds.getConnection( DATABASE_USER, DATABASE_PASSWORD );
    } catch( NamingException x ) {
        System.err.println( x.toString() );
    }

The UserTransaction object is covered in Chapter 16. In this case, there is no manual administration of the JNDI name; it is simply the full class name, javax.transaction.UserTransaction. The client that performs distributed transactions uses JNDI to look up the UserTransaction object, as shown in Listing 14.14.

try {
    Context ctx = new InitialContext();
    UserTransaction tx =
        (UserTransaction)ctx.lookup( "javax.transaction.UserTransaction" );
    tx.begin();    // start transaction
    // locate DataSource, establish connection, execute operations, close connections
    tx.commit();    // commit transactions
} catch( Exception x ) {
    System.err.println( "error has occurred" );
    try {
        tx.rollback();
    } catch( javax.transaction.SystemException se ) { }
}