Java Dynamic Management Kit 5.1 Tutorial

10.4 Java Naming and Directory Interface (JNDI) / LDAP Lookup Service

You can register RMI connectors or JMXMP connectors with a JNDI lookup service using an LDAP registry as a backend. This example performs the following operations:

The agent:
- Creates an MBean server
- Creates a connector server
- Registers the connector address with the LDAP server
The client:
- Gets a pointer to the JNDI/LDAP lookup service
- Looks for any connector servers registered in the JNDI/LDAP lookup service
- Creates a connector
- Retrieves information about the MBeans in the MBean server

The JNDI/LDAP lookup example is contained in the directory examplesDir/current/Lookup/ldap.

Note –

Some code provided in this example is specific to Sun's implementation of the Java 2 Platform, Standard Edition (J2SE) SDK 1.4. If you are not using Sun's implementation, you might need to adapt the code to your implementation.

10.4.1 Registering the Connector Server with the JNDI/LDAP Lookup Service

The following code extracts are taken from the Server class in the Jini Lookup Service examples directory.

Example 10–9 Creating Connector Servers for Registration in the JNDI/LDAP Lookup Service

public class Server { 
   public final static int JMX_DEFAULT_LEASE = 60; 
   private static boolean debug = false; 
   private final MBeanServer mbs; 
   public Server() { 
      mbs = MBeanServerFactory.createMBeanServer(); 
   } 
 
  public static DirContext getRootContext() throws NamingException { 
      final Hashtable env = new Hashtable(); 
 
      final String factory = 
        System.getProperty(Context.INITIAL_CONTEXT_FACTORY, 
                           "com.sun.jndi.ldap.LdapCtxFactory"); 
      final String ldapServerUrl = 
        System.getProperty(Context.PROVIDER_URL); 
      final String ldapUser = 
        System.getProperty(Context.SECURITY_PRINCIPAL, 
                           "cn=Directory Manager"); 
      final String ldapPasswd = 
        System.getProperty(Context.SECURITY_CREDENTIALS); 
      debug(Context.PROVIDER_URL + "=" + ldapServerUrl); 
      debug(Context.SECURITY_PRINCIPAL + "=" + ldapUser); 
      if (debug) { 
                  System.out.print(Context.SECURITY_CREDENTIALS + "="); 
                  final int len = (ldapPasswd==null)?0:ldapPasswd.length(); 
                  for (int i=0;i
                  for (int i=0;i<len;i++) System.out.print("*"); 
                  System.out.println(); 
      } 
      env.put(Context.INITIAL_CONTEXT_FACTORY,factory); 
      env.put(Context.SECURITY_PRINCIPAL, ldapUser); 
      if (ldapServerUrl != null) 
           env.put(Context.PROVIDER_URL, ldapServerUrl); 
      if (ldapPasswd != null) 
           env.put(Context.SECURITY_CREDENTIALS, ldapPasswd); 
      InitialContext root = new InitialLdapContext(env,null); 
      return (DirContext)(root.lookup("")); 
  } 
   
[...]

Example 10–9 shows the initial creation of an MBean server mbs, and the obtainment of a pointer to the root context of the LDAP directory tree in which the connector server address is to be registered. All the relevant LDAP access variables, such as the provider URL, the LDAP user name and the security credentials, are given here and passed into the environment map env. The environment map env is then passed as a parameter into a call to InitialLdapContext, from which the initial LDAP context is obtained.

Code that is not shown retrieves the agent name under which the connector will be registered in the LDAP server.

Example 10–10 Registering the Connector Server Address in the LDAP Registry

[...] 
 
public static void register(DirContext root, 
                           JMXServiceURL jmxUrl, 
                           String name) 
   throws NamingException, IOException { 
 
   final String mydn = System.getProperty("dn","cn="+name); 
 
   debug("dn: " + mydn ); 
 
   Object o = null; 
   try { 
       o = root.lookup(mydn); 
   } catch (NameNotFoundException n) { 
       Attributes attrs = new BasicAttributes(); 
       Attribute objclass = new BasicAttribute("objectClass"); 
       objclass.add("top"); 
       objclass.add("javaContainer"); 
       objclass.add("jmxConnector"); 
       attrs.put(objclass); 
       attrs.put("jmxAgentName", name); 
       o = root.createSubcontext(mydn,attrs); 
   } 
   if (o == null) throw new NameNotFoundException(); 
   final Attributes attrs = root.getAttributes(mydn); 
   final Attribute oc = attrs.get("objectClass"); 
   if (!oc.contains("jmxConnector")) { 
       final String msg = "The supplied node [" + mydn +  
         "] does not contain the jmxConnector objectclass"; 
       throw new NamingException(msg); 
   } 
    
   final Attributes newattrs = new BasicAttributes(); 
   newattrs.put("jmxAgentName",name); 
   newattrs.put("jmxServiceURL",jmxUrl.toString()); 
   newattrs.put("jmxAgentHost",InetAddress.getLocalHost().getHostName()); 
   newattrs.put("jmxProtocolType",jmxUrl.getProtocol()); 
   newattrs.put("jmxExpirationDate", 
                getExpirationDate(JMX_DEFAULT_LEASE)); 
   root.modifyAttributes(mydn,DirContext.REPLACE_ATTRIBUTE,newattrs); 
} 
 
[...]

Example 10–10 shows the registration of the JMX connector server service URL in the LDAP directory. The domain name in which the URL is registered can be passed on the command line through the dn System property, namely, -Ddn=mydn. If the dn system property is not specified, then you can use cn=name, in which name is the agent name. This is not mandatory, however.

The location in which the URL is registered is not important, because the client code never uses that DN directly, but instead performs an LDAP search to find the nodes that have an auxiliary JMX connector ObjectClass. What is important however, is that each URL is registered in its own LDAP node. How to name these nodes is left to the LDAP administrator. In this example, it is assumed that you have configured your LDAP server by creating a root context under which the node cn=name can be created, and that this root context has been passed to the LDAP initial context through the Context.PROVIDER_URL property (see Example 10–9).

The code shown above checks whether the node in which you will register the server URL already exists. If it does not, you try to create it (this will fail if the parent node does not exist). Since the ObjectClass is a simple auxiliary class, you can use the javaContainer ObjectClass as structural class if you need to create a new context. Once again, this is optional.

Any structural class to which the jmxConnector auxiliary class can be added is acceptable. It then checks whether the node in which you will register the server already has the jmxConnector auxiliary class. Otherwise, an exception is thrown.

At this point you are sure that the node in which you will register the URL exists, and has the appropriate jmxConnector auxiliary class. So you need only to replace the values of the attributes defined by the LDAP schema for JMX, (see jmx-schema.txt):

jmxServiceUrl: contains the String form of the server URL, as obtained from server.getAddress() after the server was started.
jmxAgentName: contains the JMX agent name.
jmxProtocolType: contains the JMX protocol type, as returned by jmxUrl.getProtocolType().
jmxAgentHost: contains the name of the agent host.
jmxExpirationDate: contains the date at which the URL will be considered obsolete.

Example 10–11 Registering the Connector Servers in the LDAP Server

[...] 
 
   public JMXConnectorServer rmi(String url) 
     throws IOException, JMException, 
        NamingException, ClassNotFoundException { 
 
     JMXServiceURL jurl = new JMXServiceURL(url); 
     final HashMap env = new HashMap(); 
     // Prepare the environment Map 
     
[...] 
 
     JMXConnectorServer rmis = 
        JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs); 
 
     final String agentName = System.getProperty("agent.name", 
                                                 "DefaultAgent"); 
     start(rmis,env,agentName); 
     return rmis; 
   } 
     
[...]

In Example 10–11, a new RMI connector server named rmis is created with the JMX service URL jurl and the appropriate LDAP properties passed to its environment map env. The connector server rmis is launched by calling JMXConnectorServer.start() and is registered in the LDAP server.

Subsequent code not shown here creates and registers a corresponding JMXMP connector server named jmxmp.

Example 10–12 Creating the JMX Connector Server

[...] 
 
    public void start(JMXConnectorServer server, Map env, String agentName) 
       throws IOException, NamingException { 
       server.start(); 
       final DirContext root=getRootContext(); 
       final JMXServiceURL address = server.getAddress(); 
       register(root,address,agentName); 
    } 
     
[...]

Example 10–12 shows the creation of a JMX connector server server, the obtainment of a pointer to the LDAP server root directory root and the creation of a URL for server named address. The root directory, the URL and an agent name are passed as parameters to register() and are registered in the LDAP server.

10.4.2 Looking up the Connector Servers with the JNDI/LDAP Lookup Service

The following code extract is taken from the Client class in the Jini Lookup Service examples directory.

Example 10–13 Looking up the Connector Servers with the JNDI/LDAP Lookup Service

[...] 
 
public class Client { 
 
   private static boolean debug = false; 
 
   public static void listAttributes(DirContext root, String dn) 
     throws NamingException { 
     final Attributes attrs = root.getAttributes(dn); 
     System.out.println("dn: " + dn); 
     System.out.println("attributes: " + attrs); 
   } 
    
   public static DirContext getRootContext() throws NamingException { 
      final Hashtable env = new Hashtable(); 
      // Prepare environment map 
      [...] 
       
      InitialContext root = new InitialLdapContext(env,null); 
      return (DirContext)(root.lookup("")); 
   } 
    
   // Confirm URL has not expired  
  [...]  
 
   public static List lookup(DirContext root, String protocolType, 
                             String name) 
      throws IOException, NamingException { 
      final ArrayList list = new ArrayList(); 
      String queryProtocol = 
         (protocolType==null)?"":"(jmxProtocolType="+protocolType+")"; 
      String query = 
          "(&" + "(objectClass=jmxConnector) " + 
          "(jmxServiceURL=*) " + 
          queryProtocol + 
          "(jmxAgentName=" + ((name!=null)?name:"*") + "))"; 
 
      SearchControls ctrls = new SearchControls(); 
      ctrls.setSearchScope(SearchControls.SUBTREE_SCOPE); 
      final NamingEnumeration results = root.search("", query, ctrls); 
      while (results.hasMore()) {  
           final SearchResult r = (SearchResult) results.nextElement(); 
           debug("Found node: " + r.getName()); 
           final Attributes attrs = r.getAttributes(); 
           final Attribute attr = attrs.get("jmxServiceURL"); 
           if (attr == null) continue; 
           final Attribute exp = attrs.get("jmxExpirationDate"); 
           if ((exp != null) && hasExpired((String)exp.get())) { 
               System.out.print(r.getName() + ": "); 
               System.out.println("URL expired since: " + exp.get()); 
               continue; 
           }   
           final String urlStr = (String)attr.get(); 
           if (urlStr.length() == 0) continue; 
 
    
           debug("Found URL: "+ urlStr); 
 
    
           final JMXServiceURL url = new JMXServiceURL(urlStr); 
           final JMXConnector conn = 
               JMXConnectorFactory.newJMXConnector(url,null); 
           list.add(conn); 
           if (debug) listAttributes(root,r.getName()); 
      } 
 
      return list; 
 
   }   
}

In Example 10–13, the Client firstly returns a pointer root to the LDAP directory DirContext, then it searches through the directory for object classes of the type jmxConnector. The service URL and expiry date attributes, attr and exp respectively, for the jmxConnector object classes are obtained, exp is checked to make sure that the URL has not expired and a call is made to JMXConnectorFactory to create a new connector conn. The connector conn is added to the list of connectors and is used to access the MBeans in the MBean server created by Server.

10.4.3 Running the JNDI/LDAP Lookup Service Example

In addition to the actions you performed in 10.1 Initial Configuration, before you can run the lookup service examples that use the JNDI/LDAP lookup service, you must perform some further initial actions that are specific to this example. You can then start looking up connectors using the JNDI/LDAP network technology.

When you run the examples, to help you keep track of which agent has been created with which connector and transport, the agent names include a letter suffix. For example, the agent from the example of an RMI connector over JRMP, without an external directory is called test-server-a.

To Set up the JNDI/LDAP Lookup Service Example

The following steps are required by all of the different connector/transport combinations you can run in this example.

Stop the LDAP server you started in 10.1 Initial Configuration.

Do this according to the type of LDAP server you are using.

Copy the JMX schema into your LDAP server's schema directory.

For example, if you are using Sun ONE Directory Server 5.0, you would type:
$ cp 60jmx-schema.ldif /var/ds5/slapd-hostname/config/schema
Otherwise, do this according to the type of LDAP server you are using.

Restart the LDAP server.

Do this according to the type of LDAP server you are using.

Define the root under which the Server will register its service URL.

You must provide the Server with the path to the domain component suffix dc=Test that you created in 10.1 Initial Configuration.
$ provider="ldap://$ldaphost:$ldapport/dc=Test"

Compile the Client and Server classes.

$ javac -d . -classpath classpath Server.java Client.java

To Run the JNDI/LDAP Lookup Service Example with an RMI Connector

This example demonstrates the use of the JNDI/LDAP lookup service to look up RMI connector servers that use RMI's default transport, JRMP, as well as the IIOP transport. In addition, as described in 10.1 Initial Configuration, different external directories are used to register the RMI connector stubs.

The combinations of transports and external directories demonstrated here are:

RMI connector over the JRMP transport, with:
- No external directory
- An RMI registry
- An LDAP registry
RMI connector over the IIOP transport, with:
- No external directory
- A CORBA naming service
- An LDAP registry

Perform the following steps to run the example:

Start the Server.

The command you use to start the Server varies according to which external directory you are using. You can start one or more of the following instances of Server with different transports and external registries before starting the Client.

RMI connector over JRMP, without an external directory:

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-a \
     -Durl="service:jmx:rmi://" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

debug is set to true to provide more complete screen output when the Server runs
The name of the agent to be created is test-server-a
The service URL specifies that the chosen connector is an RMI connector, running over the RMI default transport JRMP.

When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service.

RMI connector over JRMP, using an RMI registry as an external directory:

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-b \
     -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-b
The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub, server, is stored is the RMI registry you identified as jndirmi in 10.1 Initial Configuration

When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service.

RMI connector over JRMP, using LDAP as the external directory:

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-c \
     -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-c
The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in 10.1 Initial Configuration
The stub is registered in the Test domain component in the LDAP server.
The common name attribute principal and password credentials are given to gain access to the LDAP server.

When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service under the agent name test-server-c.

RMI connector over IIOP, without an external directory:

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-d \
     -Durl="service:jmx:iiop://" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-d
The service URL specifies the chosen connector as RMI connector over IIOP.

When the Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its automatically generated URL in the JNDI/LDAP lookup service.

RMI connector over IIOP, using CORBA naming as the external directory.

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-e \
     -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-e
The service URL specifies the chosen connector as RMI connector over IIOP. The external directory in which the RMI connector stub server is stored is the CORBA naming service you identified as jndiiiop in 10.1 Initial Configuration.

RMI connector over IIOP, using LDAP as the external directory.

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-f \
     -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-f
The service URL specifies the chosen connector as RMI over IIOP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in 10.1 Initial Configuration.
The stub is registered in the Test domain component in the LDAP server.
The common name attribute principal and password credentials are given to gain access to the LDAP server.

When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service under the agent name test-server-f.

Start the Client.

After starting the Server using the transport and external directory of your choice, start the Client:

$ java -classpath classpath -Ddebug=true \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Client

You will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.

To look up a specific agent, type the following command:

$ java -classpath classpath -Ddebug=true \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     -Dagent.name=agentName \
     jndi.Client

In the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.

To Run the JNDI/LDAP Lookup Service Example with a JMXMP Connector

This example demonstrates the use of the JNDI/LDAP lookup service to look up JMXMP connector servers.

Start the Server.

$ java -classpath classpath -Ddebug=true \
     -Dagent.name=test-server-g \
     -Durl="service:jmx:jmxmp://" \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Server &

In this command:

The name of the agent created is test-server-g
The service URL specifies the chosen connector as the JMXMP connector, running on the first available port.

When the Server is launched, you will see confirmation of the creation of the JMXMP connector, and the registration of its automatically generated URL in the JNDI/LDAP lookup service. JMXMP connector servers can be used alongside RMI connectors, and will be detected by the Client in exactly the same way as RMI connector servers.

Start the Client.

After starting the Server, start the Client:

$ $ java -classpath classpath -Ddebug=true \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jndi.Client

You will see output confirming the detection of the agents created by the Server and registered in the JNDI/LDAP lookup service. You will also see the identification and confirmation of the connection made to the agents.

To look up a specific agent, type the following command:

$ $ java -classpath classpath -Ddebug=true \
     -Djava.naming.provider.url="$provider" \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     -Dagent.name="agentName" \ 
     jndi.Client