test

Java Dynamic Management Kit 5.1 Tutorial

10.3 Jini Lookup Service

The purpose of this example is to demonstrate how a connector client can find and connect to a connector server that has registered with the Jini lookup service. This example performs the following operations:

The Jini lookup service example is contained in the directory examplesDir/current/Lookup/jini.

Note –

These examples assume that you are already familiar with the Jini network technology. The documentation for the Jini network technology is available at http://wwws.sun.com/software/jini/specs/index.html. You can download the Jini network technology from the Sun Microsystems Community Source Licensing page, at http://wwws.sun.com/software/communitysource/jini/download.html. This example has been implemented using the Jini Technology Starter Kit Version 1.2.1_001.

10.3.1 Registering the Connector Server with the Jini Lookup Service

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

Example 10–6 Creating Connector Servers for Registration in the Jini Lookup Service

public class Server { 
   private final MBeanServer mbs; 
   private static boolean debug = false; 
   public Server() { 
     mbs = MBeanServerFactory.createMBeanServer(); 
   } 
 
  public JMXConnectorServer rmi(String url) 
      throws IOException, JMException, ClassNotFoundException { 
      JMXServiceURL jurl = new JMXServiceURL(url); 
      final HashMap env = new HashMap(); 
      // Environment map attributes 
     [...] 
     JMXConnectorServer rmis = 
        JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs); 
 
     final String agentName = System.getProperty("agent.name", 
                                                 "DefaultAgent"); 
 
     start(rmis,env,agentName); 
 
     return rmis; 
   } 
    
[...]

Example 10–6 shows the creation of an MBean server mbs. As was the case for the SLP examples, the JMX service URL and the agent name are passed to Server when it is launched at the command line.

We then see the creation of an RMI connector server named rmis, using the system properties defined by the environment map env and the address jurl. The RMI connector server rmis is started. The RMI connector server address will be registered in the Jini lookup service under the name agentName. Subsequent code not shown here creates a corresponding JMXMP connector server named jmxmp, that will also be registered with the Jini lookup service, as shown in the following code extract.

Example 10–7 Registering the Connector Server with the Jini Lookup Service

public void start(JMXConnectorServer server, Map env, String agentName) 
      throws IOException, ClassNotFoundException { 
      server.start(); 
      final ServiceRegistrar registrar=getRegistrar(); 
      final JMXConnector proxy = server.toJMXConnector(env); 
      register(registrar,proxy,agentName); 
   } 
    
   public static ServiceRegistrar getRegistrar() 
      throws IOException, ClassNotFoundException, 
         MalformedURLException { 
      final String jurl = 
         System.getProperty("jini.lookup.url","jini://localhost"); 
      final LookupLocator lookup = new LookupLocator(jurl); 
      final ServiceRegistrar registrar = lookup.getRegistrar(); 
      if (registrar instanceof Administrable) 
          debug("Registry is administrable."); 
      return registrar; 
   } 
    
   public static ServiceRegistration register(ServiceRegistrar registrar, 
                                              JMXConnector proxy, 
                                              String name) 
      throws IOException { 
      Entry[] serviceAttrs = new Entry[] { 
              new net.jini.lookup.entry.Name(name) 
                       }; 
		        
      System.out.println("Registering proxy: AgentName=" + name ); 
      debug("" + proxy); 
      ServiceItem srvcItem = new ServiceItem(null, proxy, serviceAttrs); 
      ServiceRegistration srvcRegistration = 
             registrar.register(srvcItem, Lease.ANY); 
      debug("Registered ServiceID: " + 
                              srvcRegistration.getServiceID().toString()); 
      return srvcRegistration; 
   }

Example 10–7 shows the creation of a connector server named server with the environment map env and the service URL jurl. The connector server instance server then gets a pointer to the Jini lookup service by calling the Jini lookup service method LookupLocator.getRegistrar().

The connector server is registered in the Jini lookup service in the form of a proxy, using the Jini lookup service locator registrar and the agent name under which the connector server will be registered. The proxy is in fact a client stub for the connector server, obtained by a call to the toJMXConnector() method of JMXConnectorServer.

The registration itself is performed by a call to the register() method of the Jini lookup service class ServiceRegistrar, with an array of service items.

10.3.2 Looking up the Connector Server with the Jini Lookup Service

The following code extract is taken from the Client class in the Jini lookup service examples directory.

Example 10–8 Looking up the Connector Server with the Jini Lookup Service

public class Client { 
 
   private static boolean debug = false; 
   public static ServiceRegistrar getRegistrar() 
       throws IOException, ClassNotFoundException, MalformedURLException { 
       final String jurl = 
                  System.getProperty("jini.lookup.url","jini://localhost"); 
       final LookupLocator lookup = new LookupLocator(jurl); 
       final ServiceRegistrar registrar = lookup.getRegistrar(); 
       if (registrar instanceof Administrable) 
               debug("Registry is administrable."); 
       return registrar; 
 } 
 
   public static List lookup(ServiceRegistrar registrar, 
           String name) throws IOException { 
       final ArrayList list = new ArrayList(); 
       final Class[] classes = new Class[] {JMXConnector.class}; 
       final Entry[] serviceAttrs = new Entry[] { 
           new net.jini.lookup.entry.Name(name) 
   }; 
    
   ServiceTemplate template = 
        new ServiceTemplate(null,classes,serviceAttrs); 
   ServiceMatches matches = 
        registrar.lookup(template, Integer.MAX_VALUE); 
   for(int i = 0; i < matches.totalMatches; i++) { 
        debug("Found Service: " + matches.items[i].serviceID); 
        if (debug) { 
           if (matches.items[i].attributeSets != null) { 
                   final Entry[] attrs = matches.items[i].attributeSets; 
                   for (int j = 0; j < attrs.length ; j++) { 
                       debug("Attribute["+j+"]=" + attrs[j]); 
               } 
           } 
        } 
 
 
        if(matches.items[i].service != null) { 
            JMXConnector c = (JMXConnector)(matches.items[i].service); 
            debug("Found a JMXConnector: " + c); 
            list.add(c); 
        } 
   } 
   return list; 
} 
 
[...]

Example 10–8 shows how the connector client obtains a pointer to the Jini lookup service with a call to lookup.getRegistrar(). The client then obtains the list of the connectors registered as entries in the Jini lookup service with the agent name name. Unlike in the SLP example, the agent name you pass to Client when it is launched must be either an exact match of an existing agent name, or null, in which case the Jini lookup service will look up all the agents.

Once the list of connectors has been obtained, in code that is not shown here, the client connects to the MBean server started by Server, and retrieves the list of all the MBeans registered in it.

10.3.3 Running the Jini 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 Jini lookup service, you must perform some further initial actions that are specific to this example. You can then start looking up connectors using the Jini network technology, in conjunction with the two connectors supported by Java DMK.

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 Jini Lookup Service Example

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

  1. For your convenience when compiling and running the example classes, define some additional environment variables.

    In addition to the common environment variables that you set in 10.1 Initial Configuration you can add the path to the Jini lookup service. The directory where you have installed the Jini networking technology is referred to as jini_dir.


    $ JINI_HOME=jini_dir
$ JINI_LIB=$JINI_HOME/lib

  2. Define the classp environment variable.

    In addition to the JAR files for the Java DMK runtime, the JMX specification and the JMX Remote API, this example requires the JAR files for the Jini lookup services core and extensions.


    $ classp=$JINI_LIB/jini-core.jar:$JINI_LIB/jini-ext.jar:classpath

  3. Create ajava.policy file.

    Thejava.policy file is a Java technology security policy file. A template java.policy file for is provided in the same directory as the classes for this example. You must complete the file to include all the necessary paths for your system. You must also rename the file from java.policy.template to java.policy.

  4. Create a jini.properties file.

    A properties file for UNIX platforms is provided in the same directory as the classes for this example. If you are not running a UNIX platform, you can obtain a properties file for your platform in the following directory:


    jini_dir/example/launcher/jini12_platform.properties

  5. Update the jini.properties file.

    You must complete the file to include all the necessary paths, host names and port numbers for your system. Even if you are not running a UNIX platform, you can use the template provided as a guide.

  6. Start the Jini networking technology StartService.


    $ java -cp $JINI_LIB/jini-examples.jar 
 com.sun.jini.example.launcher.StartService &

    This will open the StartService graphical user interface.

  7. Load your jini.properties file into StartService.

    Click on File, Open Property File and then select your properties file from within examplesDir/current/Lookup/jini.

  8. Start the Jini lookup services.

    Start the required Jini lookup services by clicking on the Run tab and then pressing the START button for each of the following:

    • RMID

    • WebServer

    • Reggie

    • LookupBrowser

  9. Compile the Client and Server classes.


    $ javac -d . -classpath $classp Server.java Client.java
To Run the Jini Lookup Service Example With an RMI Connector

This example demonstrates the use of the Jini 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:

  1. 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 .:$classp -Ddebug=true \
     -Dagent.name=test-server-a \
     -Durl="service:jmx:rmi://" \
     -Djava.security.policy=java.policy \
     jini.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 Jini lookup service.

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


      $ java -classpath .:$classp -Ddebug=true \
     -Dagent.name=test-server-b \
     -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \
     -Djava.security.policy=java.policy \
     jini.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 Jini lookup service.

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


      $ java -classpath .:$classp -Ddebug=true \
     -Dagent.name=test-server-c \
     -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \
     -Djava.security.policy=java.policy \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jini.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 Jini lookup service under the agent name test-server-c.

    • RMI connector over IIOP, without an external directory:


      $ java -classpath .:$classp -Ddebug=true \
     -Dagent.name=test-server-d \
     -Durl="service:jmx:iiop://" \
     -Djava.security.policy=java.policy \
     jini.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 Jini lookup service.

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


      $ java -classpath .:$classp -Ddebug=true \
     -Dagent.name=test-server-e \
     -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \
     -Djava.security.policy=java.policy \
     jini.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 .:$classp -Ddebug=true \
     -Dagent.name=test-server-f \
     -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \
     -Djava.security.policy=java.policy \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     jini.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 Jini lookup service under the agent name test-server-f.

  2. Start the Client.

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


    $ java -classpath .:$classp -Ddebug=true \
     -Djava.security.policy=java.policy \
     jini.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 .:$classp -Ddebug=true \
     -Djava.security.policy=java.policy \
     -Dagent.name="agentName" \ 
     jini.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 Jini Lookup Service Example With a JMXMP Connector

This example demonstrates the use of the Jini lookup service to look up JMXMP connector servers.

  1. Start the Server.


    $ java -classpath .:$classp -Ddebug=true \
     -Dagent.name=test-server-g \
     -Durl="service:jmx:jmxmp://" \
     -Djava.security.policy=java.policy \
     jini.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 Jini 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.

  2. Start the Client.

    After starting the Server, start the Client: 


    $ java -classpath .:$classp -Ddebug=true \
     -Djava.security.policy=java.policy \
     jini.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 .:$classp -Ddebug=true \  
  -Djava.security.policy=java.policy \
  -Dagent.name="agentName" \ 
  jini.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.