New to Java? We'll help you get started with our revised beginner's tutorial, or our free online textbook.

	Get the latest Java books
h t t p : / /w w w . j a v a c o f f e e b r e a k . c o m /

Chapter 15: ClientLookupManager

Contents

• Introduction
• ServiceItemFilter
• Finding a Service Immediately
• Using a Filter
• Building a Cache of Services
  • Running the CachedClientLookup
• Monitoring Changes to the Cache

The class ClientLookupManager is only available in Jini 1.1. It performs client-side functions similar to that of JoinManager for services, and simplifies the tasks of finding services.

Both clients and services need to find lookup services. Both can do this using low-level core classes, or discovery utilities such as LookupDiscoveryManager. Once a lookup service is found, a service just needs to register with it and try to keep the lease alive for as long as it wants to. A service can make use of the JoinManager class for this.

Clients are a little more complex in their requirements:

1. A client may wish to use a service immediately or later
2. A client may want to use multiple services
3. A client will want to find services by their interface, but may also want to apply additional criteria, such as being a ``fast enough'' printer
4. A client may just wish to use a service if it is available at the time of request, but alternatively may want to be informed of new services becoming available and respond to this new availability (for example, a service browser)

The class ClientLookupManager is a utility class designed to help in the various possible cases that can occur. Due to the variety of these, it is more complex than JoinManager. Its interface includes

package net.jini.lookup;

public class ClientLookupManager {
    public ClientLookupManager(DiscoveryManagement discoveryMgr,
                               LeaseRenewalManager leaseMgr)
           throws IOException;

    LookupCache createLookupCache(ServiceTemplate tmpl,
                                  ServiceItemFilter filter,
                                  ServiceDiscoveryListener listener);

    ServiceItem[] lookup(ServiceTemplate tmpl,
                         int maxMatches, ServiceItemFilter filter);

    ServiceItem lookup(ServiceTemplate tmpl,
                       ServiceItemFilter filter);

    ServiceItem lookup(ServiceTemplate tmpl,
                       ServiceItemFilter filter, long wait);

    ServiceItem[] lookup(ServiceTemplate tmpl,
                         int minMaxMatch, int maxMatches,
                         ServiceItemFilter filter, long wait);

    void terminate();
}

Most methods of the client lookup manager require a ServiceItemFilter. This is a simple interface, designed to be an additional filter on the client side to help in finding services. The primary mechanisms for a client to find a service are to ask for an instance of an interface, possibly with additional entry attributes. This matching is performed on the lookup service, and only implements a form of exact pattern matching. It allows one to ask for a toaster that will handle two slices of toast exactly, but not for one which will toast two or more. To perform arbitrary boolean matching on the lookup service is a security issue, plus possibly a performance issue on the lookup service. The ServiceItemFilter allows additional boolean filtering to be performed on the client side, by client code, so these issues are local to the client only.

The interface is

package net.jini.lookup;

public interface ServiceItemFilter {
    boolean check(ServiceItem item);
}

Client-side filtering will not answer all of the problems of locating the ``best'' service. Some questions will still need to use other services which know ``local'' information such as distances in a building

The simplest scenario for a client is that it wants to find a service immediately, use it and then (perhaps) terminate. It will be prepared to wait a certain amount of time before giving up. All issues of discovery can be given to the ClientLookupManager, and finding a service can be given to a method such as lookup() with a wait parameter. The lookup() method will block until a suitable service is found or the time limit is reached. If the time limit is reached, a null object will be returned otherwise a non-null service object will be returned.

package client;

import common.FileClassifier;
import common.MIMEType;

import java.rmi.RMISecurityManager;
import net.jini.discovery.LookupDiscovery;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.lookup.ClientLookupManager;
import net.jini.core.lookup.ServiceItem;
import net.jini.lease.LeaseRenewalManager;

/**
 * ImmediateClientLookup.java
 */

public class ImmediateClientLookup {

    private static final long WAITFOR = 100000L;

    public static void main(String argv[]) {
	new ImmediateClientLookup();

        // stay around long enough to receive replies
        try {
            Thread.currentThread().sleep(2*WAITFOR);
        } catch(java.lang.InterruptedException e) {
            // do nothing
        }
    }

    public ImmediateClientLookup() {
	ClientLookupManager clientMgr = null;

	System.setSecurityManager(new RMISecurityManager());

        try {
            LookupDiscoveryManager mgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
	    clientMgr = new ClientLookupManager(mgr, 
						new LeaseRenewalManager());
	} catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
  
	Class [] classes = new Class[] {FileClassifier.class};
	ServiceTemplate template = new ServiceTemplate(null, classes, 
						       null);

	ServiceItem item = null;
	try {
	    item = clientMgr.lookup(template, 
				    null, /* no filter */ 
				    WAITFOR /* timeout */);
	} catch(Exception e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	if (item == null) {
	    // couldn't find a service in time
	    System.out.println("no service");
	    System.exit(1);
	}
	FileClassifier classifier = (FileClassifier) item.service;

	if (classifier == null) {
	    System.out.println("Classifier null");
	    System.exit(1);
	}

	// Now we have a suitable service, use it
	MIMEType type;
	try {
	    String fileName;
	    
	    fileName = "file1.txt";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	    
	    fileName = "file2.rtf";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	    
	    fileName = "file3.abc";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	} catch(java.rmi.RemoteException e) {
	    System.err.println(e.toString());
	}
	System.exit(0);
    }

    private void printType(String fileName, MIMEType type) {
	System.out.print("Type of " + fileName + " is ");
	if (type == null) {
	    System.out.println("null");
	} else {
	    System.out.println(type.toString());
	}
    }
} // ImmediateClientLookup

An example of an earlier chapter discussed how to select a printer with a speed greater than a certain value. This type of problem is well suited to the ClientLookupManager using a ServiceItemFilter.

package client;

import common.Printer;

import java.rmi.RMISecurityManager;
import net.jini.discovery.LookupDiscovery;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.lookup.ClientLookupManager;
import net.jini.core.lookup.ServiceItem;
import net.jini.lease.LeaseRenewalManager;
import net.jini.lookup.ServiceItemFilter;
/**
 * TestPrinterSpeedFilter.java
 */

public class TestPrinterSpeedFilter implements ServiceItemFilter {
    private static final long WAITFOR = 100000L;
    
    public TestPrinterSpeedFilter() {
	ClientLookupManager clientMgr = null;

	System.setSecurityManager(new RMISecurityManager());

        try {
            LookupDiscoveryManager mgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
	    clientMgr = new ClientLookupManager(mgr, 
						new LeaseRenewalManager());
	} catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }

        Class[] classes = new Class[] {Printer.class};

        ServiceTemplate template = new ServiceTemplate(null, classes, 
                                                       null);
 	ServiceItem item = null;
	try {
	    item = clientMgr.lookup(template, 
				    this, /* filter */ 
				    WAITFOR /* timeout */);
	} catch(Exception e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	if (item == null) {
	    // couldn't find a service in time
	    System.exit(1);
	}

	Printer printer = (Printer) item.service;
	// Now use the printer
	// ...
    }

    public boolean check(ServiceItem item) {
	// This is the filter
	Printer printer = (Printer) item.service;
	if (printer.getSpeed() > 24) {
	    return true;
	} else {
	    return false;
	}
    }

    public static void main(String[] args) {
	
	TestPrinterSpeed f = new TestPrinterSpeed();

        // stay around long enough to receive replies	
        try {
            Thread.currentThread().sleep(2*WAITFOR);
        } catch(java.lang.InterruptedException e) {
            // do nothing
        }
    }
    
} // TestPrinterSpeed

A client may wish to make use of a service multiple times. If it just found a suitable reference to a service, then before each use it would have to check that the reference was still valid, and if not, find another one. It may also want to use minor variants of a service, such as a fast printer one time, a slow one the next. While this management can be done easily enough for each case, the ClientLookupManager can supply a cache of services which will do it for you. This cache will look after monitoring lookup services to keep the cache as up-to-date as possible with services.

The cache is defined as an interface

package net.jini.lookup;
  
public interface LookupCache {
    public ServiceItem lookup(ServiceItemFilter filter);
    public ServiceItem[] lookup(ServiceItemFilter filter, 
                                int maxMatches);                                           
    public void addListener(ServiceDiscoveryListener l);
    public void removeListener(ServiceDiscoveryListener l); 
    public void discard(Object serviceReference);
    void terminate(); 
}

    LookupCache createLookupCache(ServiceTemplate tmpl,
                                  ServiceItemFilter filter,
                                  ServiceDiscoveryListener listener);

The LookupCache created by createLookupCache() takes a template for matching against interface and entry attributes. In addition it also takes a filter to perform additional client-side boolean filtering of services. The cache will then maintain a set of local references to services matching the template and passing the filter. Searching for a service can then be done by local methods LookupCache.lookup(). These can take an additional filter which can be used to further refine the set of services returned to the client.

There are versions of the ClientLookupManager.lookup() with a time parameter, which block until a service is found or the method times out. These methods do not use polling, but instead use event notification. This is because they are trying to find services based on remote calls to lookup services. The lookup() methods of LookupCache do not implement such a blocking call, because the methods run purely locally and it is reasonable to poll the cache for a short time if need be.

A version of the file classifier client that creates and examines the cache for suitable service is

package client;

import common.FileClassifier;
import common.MIMEType;

import java.rmi.RMISecurityManager;
import net.jini.discovery.LookupDiscovery;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.lookup.ClientLookupManager;
import net.jini.lookup.LookupCache;
import net.jini.core.lookup.ServiceItem;
import net.jini.lease.LeaseRenewalManager;

/**
 * CachedClientLookup.java
 */

public class CachedClientLookup {

    private static final long WAITFOR = 100000L;

    public static void main(String argv[]) {
	new CachedClientLookup();

        // stay around long enough to receive replies
        try {
            Thread.currentThread().sleep(WAITFOR);
        } catch(java.lang.InterruptedException e) {
            // do nothing
        }
    }

    public CachedClientLookup() {
	ClientLookupManager clientMgr = null;
	LookupCache cache = null;

	System.setSecurityManager(new RMISecurityManager());

        try {
            LookupDiscoveryManager mgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
	    clientMgr = new ClientLookupManager(mgr, 
						new LeaseRenewalManager());
	} catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
  
	Class [] classes = new Class[] {FileClassifier.class};
	ServiceTemplate template = new ServiceTemplate(null, classes, 
						       null);

	try {
	    cache = clientMgr.createLookupCache(template, 
						null, /* no filter */ 
						null /* no listener */);
	} catch(Exception e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	// loop till we find a service
	ServiceItem item = null;
	while (item == null) {
	    System.out.println("no service yet");
	    try {
		Thread.currentThread().sleep(1000);
	    } catch(java.lang.InterruptedException e) {
		// do nothing
	    }
	    // see if a service is there now
	    item = cache.lookup(null);
	}
	FileClassifier classifier = (FileClassifier) item.service;

	if (classifier == null) {
	    System.out.println("Classifier null");
	    System.exit(1);
	}

	// Now we have a suitable service, use it
	MIMEType type;
	try {
	    String fileName;
	    
	    fileName = "file1.txt";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	    
	    fileName = "file2.rtf";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	    
	    fileName = "file3.abc";
	    type = classifier.getMIMEType(fileName);
	    printType(fileName, type);
	} catch(java.rmi.RemoteException e) {
	    System.err.println(e.toString());
	}
	System.exit(0);
    }

    private void printType(String fileName, MIMEType type) {
	System.out.print("Type of " + fileName + " is ");
	if (type == null) {
	    System.out.println("null");
	} else {
	    System.out.println(type.toString());
	}
    }
} // CachedClientLookup

While it is okay to poll the local cache, the cache itself must get its contents from lookup services, and in general it is not okay to poll these since that involves possibly heavy network traffic. The cache itself gets its information by registering itself as a listener for service events from the lookup services. The lookup services will then call notify() on the cache listener. This call is a remote call from the remote lookup service to the local cache, done (probably) using an RMI stub. In fact, the Sun implementation of ClientLookupManager uses a nested class ClientLookupManager.LookupCacheImpl.LookupListener which has an RMI stub.

In order that the cache actually works, it is necessary to set the RMI codebase property java.rmi.server.codebase to a suitable location for the class files (such as an HTTP server), and to make sure that the class net/jini/lookup/ClientLookupManager$LookupCacheImpl$LookupListener_Stub.class is accessible from this codebase. The stub file may be found in the library lib/jini-ext.jar in the Jini 1.1 distribution. It has to be extracted from there and placed in the codebase (using e.g. unzip jini-ext.jar 'net/jini/lookup/ClientLookupManager$LookupCacheImpl$LookupListener_Stub.class' -d /home/WWW/htdocs/classes). Note that the specification just says this type of thing has to be done, but does not descend to details about the class name - that is left to the documentation of the ClientLookupManager as implemented by Sun. If another implementation is made of the Jini classes, then it would probably use a different remote class.

The cache uses remote events to monitor the state of lookup services. It includes a local mechanism to pass some of these changes onto a client by means of the ServiceDiscoveryListener interface

package net.jini.lookup;
interface ServiceDiscoveryListener {
    void serviceAdded(ServiceDiscoveryEvent event);
    void serviceChanged(ServiceDiscoveryEvent event);
    void serviceRemoved(ServiceDiscoveryEvent event);
}

package net.jini.lookup;

class ServiceDiscoveryEvent extends EventObject {
    ServiceItem getPostEventServiceItem();
    ServiceItem getPreEventServiceItem();
}

Clients are not likely to be interested in all events generated by lookup services, even for services in which they are interested. For example, if a new service registers itself with ten lookup services, they will all generate transition events from NO_MATCH to MATCH, but the client will usually only be interested in seeing the first of these - the other nine are just repeated information. Similarly, if a service's lease expires from one lookup service, then that doesn't matter much; but if it expires from all lookup services that the client knows of, then it does matter as the service is no longer available to it. The cache consequently prunes events so that the client gets information about the real services rather than information about the lookup services.

In the chapter on ``Events'' an example was given on monitoring changes to services from a lookup service viewpoint, reporting each change to lookup services. A client-oriented view is just to monitor changes in services themselves, which can be done easily using ServiceDiscoveryEvent's:

package client;

import java.rmi.RMISecurityManager;
import net.jini.discovery.LookupDiscovery;
import net.jini.lookup.ServiceDiscoveryListener;
import net.jini.lookup.ServiceDiscoveryEvent;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.core.lookup.ServiceItem;
import net.jini.lookup.ClientLookupManager;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.lease.LeaseRenewalManager;
import net.jini.lookup.LookupCache;

/**
 * ServiceMonitor.java
 */

public class ServiceMonitor implements ServiceDiscoveryListener {

    public static void main(String argv[]) {
	new ServiceMonitor();

        // stay around long enough to receive replies
        try {
            Thread.currentThread().sleep(100000L);
        } catch(java.lang.InterruptedException e) {
            // do nothing
        }
    }

    public ServiceMonitor() {
        ClientLookupManager clientMgr = null;
        LookupCache cache = null;

	System.setSecurityManager(new RMISecurityManager());

        try {
            LookupDiscoveryManager mgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
            clientMgr = new ClientLookupManager(mgr, 
                                                new LeaseRenewalManager());
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
  
        ServiceTemplate template = new ServiceTemplate(null, null, 
                                                       null);
        try {
            cache = clientMgr.createLookupCache(template, 
                                                null, /* no filter */ 
                                                this /* listener */);
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    // methods for ServiceDiscoveryListener
    public void serviceAdded(ServiceDiscoveryEvent evt) {
	// evt.getPreEventServiceItem() == null
	ServiceItem postItem = evt.getPostEventServiceItem();
	System.out.println("Service appeared: " +
			   postItem.service.getClass().toString());
    }

    public void serviceChanged(ServiceDiscoveryEvent evt) {
	ServiceItem preItem = evt.getPostEventServiceItem();
	ServiceItem postItem = evt.getPreEventServiceItem() ;
	System.out.println("Service changed: " +
			   postItem.service.getClass().toString());
    }
    public void serviceRemoved(ServiceDiscoveryEvent evt) {
	// evt.getPostEventServiceItem() == null
	ServiceItem preItem = evt.getPreEventServiceItem();
	System.out.println("Service disappeared: " +
			   preItem.service.getClass().toString());
    }
    
} // ServiceMonitor

The client lookup manager can handle a variety of common situations that arise as clients need to find services under different situations.

Back to main