net.jini.lookup

Class ServiceDiscoveryManager

java.lang.Object

net.jini.lookup.ServiceDiscoveryManager

public class ServiceDiscoveryManager
extends Object

The ServiceDiscoveryManager class is a helper utility class that any client-like entity can use to "discover" services registered with any number of lookup services of interest. On behalf of such entities, this class maintains - as much as possible - up-to-date state information about both the lookup services the entity wishes to query, and the services the entity wishes to acquire and use. By maintaining current service state information, the entity can implement efficient mechanisms for service access and usage.

There are three basic usage patterns for this class. In order of importance and typical usage, those patterns are:

• The entity requests that the ServiceDiscoveryManager create a cache (an instance of LookupCache) which will asynchronously "discover", and locally store, references to services that match criteria defined by the entity; services which are registered with one or more lookup services managed by the ServiceDiscoveryManager on behalf of the entity. The cache can be viewed as a set of service references that the entity can access locally as needed through one of the public, non-remote methods provided in the cache's interface. Thus, rather than making costly remote queries of multiple lookup services at the point in time when the entity needs the service, the entity can simply make local queries on the cache for the services that the cache acquired and stored at a prior time. An entity should employ this pattern when the entity must make frequent queries for multiple services. By populating the cache with multiple instances of the desired services, redundancy in the availability of those services can be provided. Thus, if an instance of a service is found to be unavailable when needed, the entity can execute a local query on the cache rather than one or more remote queries on the lookup services to acquire an instance that is available. To employ this pattern, the entity invokes the method createLookupCache.
• The entity can register with the event mechanism provided by the ServiceDiscoveryManager. This event mechanism allows the entity to request that it be notified when a service of interest is discovered for the first time, or has encountered a state change such as removal from all lookup services, or attribute set changes. Although interacting with a local cache of services in the way described in the first pattern can be very useful to entities that need frequent access to multiple services, some client-like entities may wish to interact with the cache in a reactive manner. For example, an entity such as a service browser typically wishes to be notified of the arrival of new services of interest as well as any changes in the state of the current services in the cache. In these situations, polling for such changes is usually viewed as undesirable. If the cache were to also provide an event mechanism with notification semantics, the needs of entities that employ either pattern can be satisfied. To employ this pattern, the entity must create a cache and supply it with an instance of the ServiceDiscoveryListener interface that will receive instances of ServiceDiscoveryEvent when events of interest, related to the services in the cache, occur.
• The entity, through the public API of the ServiceDiscoveryManager, can directly query the lookup services managed by the ServiceDiscoveryManager for services of interest; employing semantics similar to the semantics employed in a typical lookup service query made through the ServiceRegistrar interface. Such queries will result in a remote call being made at the same time the service is needed (unlike the first pattern, in which remote calls typically occur prior to the time the service is needed). This pattern may be useful to entities needing to find services on an infrequent basis, or when the cost of making a remote call is outweighed by the overhead of maintaining a local cache (for example, due to limited resources). Although an entity that needs to query lookup service(s) can certainly make such queries through the ServiceRegistrar interface, the ServiceDiscoveryManager provides a broad API with semantics that are richer than the semantics of the lookup methods provided by the ServiceRegistrar. This API encapsulates functionality that many client-like entities may find more useful when managing both the set of desired lookup services, and the service queries made on those lookup services. To employ this pattern, the entity simply instantiates this class with the desired parameters, and then invokes the appropriate version of the lookup method when the entity wishes to acquire a service that matches desired criteria.

All three mechanisms just described - local queries on the cache, service discovery notification, and remote lookups - employ the same template-matching scheme as that employed in the ServiceRegistrar interface. Additionally, each mechanism allows the entity to supply an object referred to as a filter; an instance of ServiceItemFilter. A filter is a non-remote object that defines additional matching criteria that the ServiceDiscoveryManager applies when searching for the entity's services of interest. Employing a filter is particularly useful to entities that wish to extend the capabilities of the standard template-matching scheme.

In addition to (or instead of) employing a filter to apply additional matching criteria to candidate service proxies initially found through template matching, filters can also be used to extend the selection process so that only proxies that are safe to use are returned to the entity. To do this, the entity would use the ServiceItemFilter interface to supply the ServiceDiscoveryManager or LookupCache with a filter that, when applied to a candidate proxy, performs a set of operations that is referred to as proxy preparation. As described in the documentation for ProxyPreparer, proxy preparation typically includes operations such as, verifying trust in the proxy, specifying client constraints, and dynamically granting necessary permissions to the proxy.

Note that this utility class is not remote. Clients and services that wish to use this class will create an instance of this class in their own address space to manage the state of discovered services and their associated lookup services locally.

Author:

Sun Microsystems, Inc.

See Also:

DiscoveryManagement, LookupCache, ServiceDiscoveryListener, ServiceDiscoveryEvent, ServiceRegistrar

Implementation Specifics:

The following implementation-specific items are discussed below:

• Configuring ServiceDiscoveryManager
• Logging

Configuring ServiceDiscoveryManager

This implementation of ServiceDiscoveryManager supports the following configuration entries; where each configuration entry name is associated with the component name net.jini.lookup.ServiceDiscoveryManager. Note that the configuration entries specified here are specific to this implementation of ServiceDiscoveryManager. Unless otherwise stated, each entry is retrieved from the configuration only once per instance of this utility, where each such retrieval is performed in the constructor.

It is important to note that in addition to allowing a client of this utility to request - through the public API - the creation of a cache that is used externally by the client, this utility also creates instances of the cache that are used internally by the utility itself. As such, in addition to the configuration entries that are used only in this utility (and not in any cache), and the configuration entries that are retrieved during the construction of each new cache (and used by only that cache), there are configuration entries specified below that are retrieved once during the construction of this utility, but which are shared with, and used by, the caches that are created.

•	cacheExecutorService
	Type:	ExecutorService
	Default:	new ThreadPoolExecutor( 10, 10, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory( "SDM lookup cache", false ))
	Description:	The object that pools and manages the various threads executed by each of the lookup caches created by this utility. There is one such ExecutorService created for each cache. For each cache that is created in this utility, a single, separate instance of this ExecutorService will be retrieved and employed by that cache. This object should not be shared with other components in the application that employs this utility.

•	discardExecutorService
	Type:	ExecutorService
	Default:	new ThreadPoolExecutor( 10, 10, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory( "SDM discard timer", false ))
	Description:	The object that pools and manages the threads, executed by a cache, that wait on verification events after a previousy discovered service has been discarded. For each cache that is created in this utility, a single, separate instance of this ExecutorService will be retrieved and employed by that cache. This object should not be shared with other components in the application that employs this utility.

•	discardWait
	Type:	long
	Default:	2*(5*60*1000)
	Description:	The value used to affect the behavior of the mechanism that handles the service discard problem described in this utility's specification. This item allows each entity that uses this utility to define how long (in milliseconds) to wait for verification from the lookup service(s) that a discarded service is actually down before committing or un-committing a requested service discard. The current implementation of this utility defaults to waiting 10 minutes (twice the maximum lease duration granted by the Reggie implementation of the lookup service). Note that this item is used only by the caches (both internal and external) that are created by this utility, and not by the utility itself.

•	discoveryManager
	Type:	DiscoveryManagement
	Default:	new LookupDiscoveryManager( new java.lang.String[] {""}, new LookupLocator[0], null, config)
	Description:	The object used to manage the discovery processing performed by this utility. This entry will be retrieved from the configuration only if no discovery manager is specified in the constructor. Note that this object should not be shared with other components in the application that employs this utility. This item is used only by the service discovery manager, and not by any cache that is created.

•	eventLeasePreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for the leases returned when a cache registers with the event mechanism of any of the discovered lookup services. This item is used only by the caches (both internal and external) that are created by this utility, and not by the utility itself. Currently, no methods of the returned proxy are invoked by this utility.

•	eventListenerExporter
	Type:	Exporter
	Default:	new BasicJeriExporter( TcpServerEndpoint.getInstance(0), new BasicILFactory(), false, false)
	Description:	Exporter for the remote event listener that each cache supplies to the lookup services whose event mechanisms those caches register with. Note that for each cache that is created in this utility, a single, separate instance of this exporter will be retrieved and employed by that cache. Note also that the default exporter defined here will disable distributed garbage collection (DGC) for the server endpoint associated with the exported listener, and the listener backend (the "impl") will be strongly referenced. This means that the listener will not "go away" unintentionally. Additionally, that exporter also sets the keepAlive flag to false to allow the VM in which this utility runs to "go away" when desired; and not be kept alive simply because the listener is still exported.

•	leaseManager
	Type:	LeaseRenewalManager
	Default:	new LeaseRenewalManager(config)
	Description:	The object used to manage any event leases returned to a cache that has registered with the event mechanism of the various discovered lookup services. This entry will be retrieved from the configuration only if no lease renewal manager is specified in the constructor. This item is used only by the caches (both internal and external) that are created by this utility, and not by the utility itself.

•	registrarPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for the proxies to the lookup services that are discovered and used by this utility. This item is used only by the service discovery manager, and not by any cache that is created. The following methods of the proxy returned by this preparer are invoked by this utility: lookup notify

•	bootstrapPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for bootstrap proxy results returned by lookup services that are discovered and used by this utility. This item is used only by the service discovery manager, and not by any cache that is created. The following methods of the proxy returned by this preparer are invoked by this utility: lookup notify

•	useInsecureLookup
	Type:	Boolean
	Default:	new Boolean.FALSE()
	Description:	When true, ServiceDiscoveryManager and LookupCache use net.jini.core.lookup.ServiceRegistrar#lookup(net.jini.core.lookup.ServiceTemplate, int) instead of {@link net.jini.core.lookup.ServiceRegistrar#lookUp(net.jini.core.lookup.ServiceTemplate, int) to perform service discovery.

Logging

This implementation of ServiceDiscoveryManager uses the {@link Logger} named net.jini.lookup.ServiceDiscoveryManager to log information at the following logging levels:

net.jini.lookup.ServiceDiscoveryManager

Level	Description
{@link java.util.logging.Level#INFO INFO}	when any exception occurs while querying a lookup service, or upon applying a filter to the results of such a query
{@link java.util.logging.Level#INFO INFO}	when any exception occurs while attempting to register with the event mechanism of a lookup service, or while attempting to prepare the lease on the registration with that event mechanism
{@link java.util.logging.Level#INFO INFO}	when any exception occurs while attempting to prepare a proxy
{@link java.util.logging.Level#INFO INFO}	when an IllegalStateException occurs while discarding a lookup service proxy after logging a failure that has occurred in one of the tasks executed by this utility
{@link java.util.logging.Level#INFO INFO}	upon failure of the lease renewal process
{@link org.apache.river.logging.Levels#HANDLED HANDLED}	when an exception occurs because a remote call to a lookup service has been interrupted as a result of the termination of a cache
{@link org.apache.river.logging.Levels#HANDLED HANDLED}	when a "gap" is encountered in an event sequence from a lookup service
{@link java.util.logging.Level#FINER FINER}	upon failure of the lease cancellation process
{@link java.util.logging.Level#FINEST FINEST}	whenever any task is started
{@link java.util.logging.Level#FINEST FINEST}	whenever any task completes successfully
{@link java.util.logging.Level#FINEST FINEST}	whenever a lookup cache is created
{@link java.util.logging.Level#FINEST FINEST}	whenever a lookup cache is terminated
{@link java.util.logging.Level#FINEST FINEST}	whenever a proxy is prepared
{@link java.util.logging.Level#FINEST FINEST}	when an exception (that is, IllegalStateException) occurs while unexporting a cache's remote event listener while the cache is being terminated

See the {@link org.apache.river.logging.LogManager} class for one way to use the logging level {@link org.apache.river.logging.Levels#HANDLED HANDLED} in standard logging configuration files.

Constructor Summary

Constructors

Constructor and Description
ServiceDiscoveryManager(DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr) Constructs an instance of ServiceDiscoveryManager which will, on behalf of the entity that constructs this class, discover and manage a set of lookup services, as well as discover and manage sets of services registered with those lookup services.
ServiceDiscoveryManager(DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config) Constructs an instance of this class, which is configured using the items retrieved through the given Configuration, that will, on behalf of the entity that constructs this class, discover and manage a set of lookup services, as well as discover and manage sets of services registered with those lookup services.

Method Summary

Modifier and Type	Method and Description
LookupCache	createLookupCache(ServiceTemplate tmpl, ServiceItemFilter filter, ServiceDiscoveryListener listener) The createLookupCache method allows the client-like entity to request that the ServiceDiscoveryManager create a new managed set (or cache) and populate it with services, which match criteria defined by the entity, and whose references are registered with one or more of the lookup services the entity has targeted for discovery.
DiscoveryManagement	getDiscoveryManager() The getDiscoveryManager method will return an object that implements the DiscoveryManagement interface.
LeaseRenewalManager	getLeaseRenewalManager() The getLeaseRenewalManager method will return an instance of the LeaseRenewalManager class.
ServiceItem[]	lookup(ServiceTemplate tmpl, int minMatches, int maxMatches, ServiceItemFilter filter, long waitDur) Queries each available lookup service in the managed set for service(s) that match the input criteria.
ServiceItem[]	lookup(ServiceTemplate tmpl, int maxMatches, ServiceItemFilter filter) Queries each available lookup service in the managed set for service(s) that match the input criteria.
ServiceItem	lookup(ServiceTemplate tmpl, ServiceItemFilter filter) Queries each available lookup service in the set of lookup services managed by the ServiceDiscoveryManager (the managed set) for a service reference that matches criteria defined by the entity that invokes this method.
ServiceItem	lookup(ServiceTemplate tmpl, ServiceItemFilter filter, long waitDur) Queries each available lookup service in the managed set for a service that matches the input criteria.
void	terminate() The terminate method performs cleanup duties related to the termination of the event mechanism for lookup service discovery, the event mechanism for service discovery, and the cache management duties of the ServiceDiscoveryManager.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceDiscoveryManager

public ServiceDiscoveryManager(DiscoveryManagement discoveryMgr,
                               LeaseRenewalManager leaseMgr)
                        throws IOException

Constructs an instance of ServiceDiscoveryManager which will, on behalf of the entity that constructs this class, discover and manage a set of lookup services, as well as discover and manage sets of services registered with those lookup services. The entity indicates which lookup services to discover and manage through the parameters input to this constructor.

As stated in the class description, this class has three usage patterns:

• the entity uses a LookupCache to locally store and manage discovered services so that those services can be accessed quickly
• the entity registers with the event mechanism provided by a LookupCache to be notified when services of interest are discovered
• the entity uses the ServiceDiscoveryManager to perform remote queries of the lookup services, employing richer semantics than that provided through the standard ServiceRegistrar interface

Although the first two usage patterns emphasize the use of a cache object, that cache is acquired only through an instance of the ServiceDiscoveryManager class.

It is important to note that some of the methods of this class (createLookupCache and the blocking versions of lookup to be exact) can throw a RemoteException when invoked. This is because each of these methods may attempt to register with the event mechanism of at least one lookup service, a process that requires a remote object (a listener) to be exported to the lookup service(s). Both the process of registering with a lookup service's event mechanism and the process of exporting a remote object are processes that can result in a RemoteException.

In order to facilitate the exportation of the remote listener just described, the ServiceDiscoveryManager class instantiates an inner class that implements the RemoteEventListener interface. Although this class defines, instantiates, and exports this remote listener, it is the entity's responsibility to provide a mechanism for any lookup service to acquire the proxy to the exported listener. One way to do this is to configure this utility to export the listener using the Jini(TM) Extensible Remote Invocation (Jini ERI) communication framework. When the listener is exported to use Jini ERI, and no proxy customizations (such as a custom invocation handler or transport endpoint) are used, no other action is necessary to make the proxy to the listener available to the lookup service(s) with which that listener is registered.

The default exporter for this utility will export the remote event listener under Jini ERI, specifying that the port and object ID with which the listener is to be exported should be chosen by the Jini ERI framework, not the deployer.

If it is required that the remote event listener be exported under JRMP instead of Jini ERI, then the entity that employs this utility must specify this in its configuration. For example, the entity's configuration would need to contain something like the following:

 import net.jini.jrmp.JrmpExporter;

 application.configuration.component.name {
    .......
    .......
    // configuration items specific to the application
    .......
    .......
 }//end application.configuration.component.name

 net.jini.lookup.ServiceDiscoveryManager {

    serverExporter = new JrmpExporter();

 }//end net.jini.lookup.ServiceDiscoveryManager
 

It is important to note that when the remote event listener is exported under JRMP, unlike Jini ERI, the JRMP remote communication framework does not provide a mechanism that automatically makes the listener proxy available to the lookup service(s) with which the listener is registered; the deployer of the entity, or the entity itself, must provide such a mechanism.

When exported under JRMP, one of the more common mechanisms for making the listener proxy available to the lookup service(s) with which the listener is registered consists of the following:

• store the necessary class files in a JAR file
• make the class files in the JAR file preferred (see net.jini.loader.pref for details)
• run an HTTP server to serve up the JAR file to any requesting lookup service
• advertise the location of that JAR file by setting the java.rmi.server.codebase property of the entity to "point" at the JAR file

For example, suppose an application consists of an entity that intends to use the ServiceDiscoveryManager will run on a host named myHost. And suppose that the down-loadable JAR file named sdm-dl.jar that is provided in the distribution is located in the directory /files/jini/lib, and will be served by an HTTP server listening on port 8082. If the application is run with its codebase property set to -Djava.rmi.server.codebase="http://myHost:8082/sdm-dl.jar", the lookup service(s) should then be able to access the remote listener exported under JRMP by the ServiceDiscoveryManager on behalf of the entity.

If a mechanism for lookup services to access the remote listener exported by the ServiceDiscoveryManager is not provided (either by the remote communication framework itself, or by some other means), the remote methods of the ServiceDiscoveryManager - the methods involved in the two most important usage patterns of that utility - will be of no use.

This constructor takes two arguments: an object that implements the DiscoveryManagement interface and a reference to a LeaseRenewalManager object. The constructor throws an IOException because construction of a ServiceDiscoveryManager may initiate the multicast discovery process, a process that can throw an IOException.

Parameters:

discoveryMgr - the DiscoveryManagement implementation through which notifications that indicate a lookup service has been discovered or discarded will be received. If the value of the argument is null, then an instance of the LookupDiscoveryManager utility class will be constructed to listen for events announcing the discovery of only those lookup services that are members of the public group.

leaseMgr - the LeaseRenewalManager to use. A value of null may be passed as the LeaseRenewalManager argument. If the value of the argument is null, an instance of the LeaseRenewalManager class will be created, initially managing no Lease objects.

Throws:

IOException - because construction of a ServiceDiscoveryManager may initiate the multicast discovery process which can throw an IOException.

See Also:

DiscoveryManagement, RemoteEventListener, ServiceRegistrar

ServiceDiscoveryManager

public ServiceDiscoveryManager(DiscoveryManagement discoveryMgr,
                               LeaseRenewalManager leaseMgr,
                               Configuration config)
                        throws IOException,
                               ConfigurationException

Constructs an instance of this class, which is configured using the items retrieved through the given Configuration, that will, on behalf of the entity that constructs this class, discover and manage a set of lookup services, as well as discover and manage sets of services registered with those lookup services. Through the parameters input to this constructor, the client of this utility indicates which lookup services to discover and manage, and how it wants the utility additionally configured.

For a more details, refer to the description of the alternate constructor of this class.

This constructor takes three arguments: an object that implements the DiscoveryManagement interface, a reference to an instance of the LeaseRenewalManager class, and a Configuration object. The constructor throws an IOException because construction of a ServiceDiscoveryManager may initiate the multicast discovery process, a process that can throw an IOException. The constructor also throws a ConfigurationException when an exception occurs while retrieving an item from the given Configuration

Parameters:

discoveryMgr - the DiscoveryManagement implementation through which notifications that indicate a lookup service has been discovered or discarded will be received. If the value of the argument is null, then an instance of the LookupDiscoveryManager utility class will be constructed to listen for events announcing the discovery of only those lookup services that are members of the public group.

leaseMgr - the LeaseRenewalManager to use. A value of null may be passed as the LeaseRenewalManager argument. If the value of the argument is null, an instance of the LeaseRenewalManager class will be created, initially managing no Lease objects.

config - the Configuration

Throws:

IOException - because construction of a ServiceDiscoveryManager may initiate the multicast discovery process which can throw an IOException.

ConfigurationException - indicates an exception occurred while retrieving an item from the given Configuration

NullPointerException - if null is input for the configuration

See Also:

DiscoveryManagement, RemoteEventListener, ServiceRegistrar, Configuration, ConfigurationException

Method Detail

lookup

public ServiceItem lookup(ServiceTemplate tmpl,
                          ServiceItemFilter filter)

Queries each available lookup service in the set of lookup services managed by the ServiceDiscoveryManager (the managed set) for a service reference that matches criteria defined by the entity that invokes this method. The semantics of this method are similar to the semantics of the lookup method provided by the ServiceRegistrar interface; employing the same template-matching scheme. Additionally, this method allows any entity to supply an object referred to as a filter. Such an object is a non-remote object that defines additional matching criteria that the ServiceDiscoveryManager applies when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of standard template-matching.

Entities typically employ this method when they need infrequent access to services, and when the cost of making remote queries is outweighed by the overhead of maintaining a local cache (for example, because of resource limitations).

This version of lookup returns a single instance of ServiceItem corresponding to one of possibly many service references that satisfy the matching criteria. If multiple services matching the input criteria happen to exist, it is arbitrary as to which reference is actually returned. It is for this reason that entities that invoke this method typically care only that a service is returned, not which service.

Note that, unlike other versions of lookup provided by the ServiceDiscoveryManager, this version does not block. That is, this version will return immediately upon failure (or success) to find a service matching the input criteria. It is important to understand this characteristic because there is a common usage scenario that can cause confusion when this version of lookup is used but fails to discover the expected service of interest. Suppose an entity creates a service discovery manager and then immediately calls this version of lookup, which simply queries the currently discovered lookup services for the service of interest. If the discovery manager employed by the service discovery manager has not yet disovered any lookup services (thus, there are no lookup services to query) the method will immediately return a value of null. This can be confusing when one verifies that such a service of interest has indeed been started and registered with the existing lookup service(s). To address this issue, one of the blocking versions of lookup could be used instead of this version, or the entity could simply wait until the discovery manager has been given enough time to complete its own (lookup) discovery processing.

Parameters:

tmpl - an instance of ServiceTemplate corresponding to the object to use for template-matching when searching for desired services. If null is input to this parameter, this method will use a wildcarded template (will match all services) when performing template-matching. Note that the effects of modifying contents of this parameter before this method returns are unpredictable and undefined.

filter - an instance of ServiceItemFilter containing matching criteria that should be applied in addition to the template-matching employed when searching for desired services. If null is input to this parameter, then only template-matching will be employed to find the desired services.

Returns:

a single instance of ServiceItem corresponding to a reference to a service that matches the criteria represented in the input parameters; or null if no matching service can be found. Note that if multiple services matching the input criteria exist, it is arbitrary as to which reference is returned.

See Also:

ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate), ServiceTemplate, ServiceItemFilter

lookup

public ServiceItem lookup(ServiceTemplate tmpl,
                          ServiceItemFilter filter,
                          long waitDur)
                   throws InterruptedException,
                          RemoteException

Queries each available lookup service in the managed set for a service that matches the input criteria. The semantics of this method are similar to the semantics of the lookup method provided by the ServiceRegistrar interface; employing the same template-matching scheme. Additionally, this method allows any entity to supply an object referred to as a filter. Such an object is a non-remote object that defines additional matching criteria that the ServiceDiscoveryManager applies when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of standard template-matching.

This version of lookup returns a single instance of ServiceItem corresponding to one of possibly many service references that satisfy the matching criteria. If multiple services matching the input criteria happen to exist, it is arbitrary as to which reference is actually returned. It is for this reason that entities that invoke this method typically care only that a service is returned, not which service.

Note that this version of lookup provides a blocking feature that is controlled through the waitDur parameter. That is, this version will not return until either a service that matches the input criteria has been found, or the amount of time contained in the waitDur parameter has passed. If, while waiting for the service of interest to be found, the entity decides that it no longer wishes to wait the entire period for this method to return, the entity may interrupt this method by invoking the interrupt method from the Thread class. The intent of this mechanism is to allow the entity to interrupt this method in the same way it would a sleeping thread.

Entities typically employ this method when they need infrequent access to services, are willing (or forced) to wait for those services to be found, and consider the cost of making remote queries for those services is outweighed by the overhead of maintaining a local cache (for example, because of resource limitations).

Parameters:

tmpl - an instance of ServiceTemplate corresponding to the object to use for template-matching when searching for desired services. If null is input to this parameter, this method will use a wildcarded template (will match all services) when performing template-matching. Note that the effects of modifying contents of this parameter before this method returns are unpredictable and undefined.

filter - an instance of ServiceItemFilter containing matching criteria that should be applied in addition to the template-matching employed when searching for desired services. If null is input to this parameter, then only template-matching will be employed to find the desired services.

waitDur - the amount of time (in milliseconds) to wait before ending the "search" and returning null. If a non-positive value is input to this parameter, then this method will not wait; it will simply query the available lookup services and return a matching service reference or null.

Returns:

a single instance of ServiceItem corresponding to a reference to a service that matches the criteria represented in the input parameters; or null if no matching service can be found. Note that if multiple services matching the input criteria exist, it is arbitrary as to which reference is returned.

Throws:

InterruptedException - this exception occurs when the entity interrupts this method by invoking the interrupt method from the Thread class.

RemoteException - typically, this exception occurs when a RemoteException occurs either as a result of an attempt to export a remote listener, or an attempt to register with the event mechanism of a lookup service.

See Also:

ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate), ServiceTemplate, ServiceItemFilter, Thread

createLookupCache

public LookupCache createLookupCache(ServiceTemplate tmpl,
                                     ServiceItemFilter filter,
                                     ServiceDiscoveryListener listener)
                              throws RemoteException

The createLookupCache method allows the client-like entity to request that the ServiceDiscoveryManager create a new managed set (or cache) and populate it with services, which match criteria defined by the entity, and whose references are registered with one or more of the lookup services the entity has targeted for discovery.

This method returns an object of type LookupCache. Through this return value, the entity can query the cache for services of interest, manage the cache's event mechanism for service discoveries, or terminate the cache.

An entity typically uses the object returned by this method to provide local storage of, and access to, references to services that it is interested in using. Entities needing frequent access to numerous services will find the object returned by this method quite useful because acquisition of those service references is provided through local method invocations. Additionally, because the object returned by this method provides an event mechanism, it is also useful to entities wishing to simply monitor, in an event-driven manner, the state changes that occur in the services of interest.

Although not required, a common usage pattern for entities that wish to use the LookupCache class to store and manage "discovered" services is to create a separate cache for each service type of interest.

Parameters:

tmpl - template to match. It uses template-matching semantics to identify the service(s) to acquire from lookup services in the managed set. If this value is null, it is the equivalent of passing a ServiceTemplate constructed with all null arguments (all wildcards).

filter - used to apply additional matching criteria to any ServiceItem found through template-matching. If this value is null, no additional filtering will be applied beyond the template-matching.

listener - object that will receive notifications when services matching the input criteria are discovered for the first time, or have encountered a state change such as removal from all lookup services or attribute set changes. If this value is null, the cache resulting from that invocation will send no such notifications.

Returns:

LookupCache used to query the cache for services of interest, manage the cache's event mechanism for service discoveries, or terminate the cache.

Throws:

RemoteException - typically, this exception occurs when a RemoteException occurs as a result of an attempt to export the remote listener that receives service events from the lookup services in the managed set.

See Also:

ServiceItemFilter

getDiscoveryManager

public DiscoveryManagement getDiscoveryManager()

The getDiscoveryManager method will return an object that implements the DiscoveryManagement interface. The object returned by this method provides the ServiceDiscoveryManager with the ability to set discovery listeners and to discard previously discovered lookup services when they are found to be unavailable.

Returns:

DiscoveryManagement implementation

See Also:

DiscoveryManagement

getLeaseRenewalManager

public LeaseRenewalManager getLeaseRenewalManager()

The getLeaseRenewalManager method will return an instance of the LeaseRenewalManager class. The object returned by this method manages the leases requested and held by the ServiceDiscoveryManager. In general, these leases correspond to the registrations made by the ServiceDiscoveryManager with the event mechanism of each lookup service in the managed set.

Returns:

LeaseRenewalManager for this instance of the ServiceDiscoveryManager.

See Also:

LeaseRenewalManager

terminate

public void terminate()

The terminate method performs cleanup duties related to the termination of the event mechanism for lookup service discovery, the event mechanism for service discovery, and the cache management duties of the ServiceDiscoveryManager.

For each instance of LookupCache created and managed by the ServiceDiscoveryManager, the terminate method will do the following:

• Either remove all listener objects registered for receipt of DiscoveryEvent objects or, if the discovery manager employed by the ServiceDiscoveryManager was created by the ServiceDiscoveryManager itself, terminate all discovery processing being performed by that manager object on behalf of the entity.

• Cancel all event leases granted by each lookup service in the managed set of lookup services.

• Un-export all remote listener objects registered with each lookup service in the managed set.

• Terminate all threads involved in the process of retrieving and storing references to discovered services of interest.

Calling any method after the termination will result in an IllegalStateException.

See Also:

LookupCache, DiscoveryEvent

lookup

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

Queries each available lookup service in the managed set for service(s) that match the input criteria. The semantics of this method are similar to the semantics of the lookup method provided by the ServiceRegistrar interface; employing the same template-matching scheme. Additionally, this method allows any entity to supply an object referred to as a filter. Such an object is a non-remote object that defines additional matching criteria that the ServiceDiscoveryManager applies when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of standard template-matching.

Entities typically employ this method when they need infrequent access to multiple instances of services, and when the cost of making remote queries is outweighed by the overhead of maintaining a local cache (for example, because of resource limitations).

This version of lookup returns an array of instances of ServiceItem in which each element corresponds to a service reference that satisfies the matching criteria. The number of elements in the returned set will be no greater than the value of the maxMatches parameter, but may be less.

Note that this version of lookup does not provide a blocking feature. That is, this version will return immediately with whatever number of service references it can find, up to the number indicated in the maxMatches parameter. If no services matching the input criteria can be found on the first attempt, an empty array is returned. It is important to understand this characteristic because there is a common usage scenario that can cause confusion when this version of lookup is used but fails to discover any instances of the expected service of interest. Suppose an entity creates a service discovery manager and then immediately calls this version of lookup, which simply queries the currently discovered lookup services for the service of interest. If the discovery manager employed by the service discovery manager has not yet discovered any lookup services (thus, there are no lookup services to query) the method will immediately return an empty array. This can be confusing when one verifies that instance(s) of such a service of interest have indeed been started and registered with the existing lookup service(s). To address this issue, one of the blocking versions of lookup could be used instead of this version, or the entity could simply wait until the discovery manager has been given enough time to complete its own (lookup) discovery processing.

Parameters:

tmpl - an instance of ServiceTemplate corresponding to the object to use for template-matching when searching for desired services. If null is input to this parameter, this method will use a wildcarded template (will match all services) when performing template-matching. Note that the effects of modifying contents of this parameter before this method returns are unpredictable and undefined.

maxMatches - this method will return no more than this number of service references

filter - an instance of ServiceItemFilter containing matching criteria that should be applied in addition to the template-matching employed when searching for desired services. If null is input to this parameter, then only template-matching will be employed to find the desired services.

Returns:

an array of instances of ServiceItem where each element corresponds to a reference to a service that matches the criteria represented in the input parameters; or an empty array if no matching service can be found.

See Also:

ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate), ServiceTemplate, ServiceItemFilter

lookup

public ServiceItem[] lookup(ServiceTemplate tmpl,
                            int minMatches,
                            int maxMatches,
                            ServiceItemFilter filter,
                            long waitDur)
                     throws InterruptedException,
                            RemoteException

Queries each available lookup service in the managed set for service(s) that match the input criteria. The semantics of this method are similar to the semantics of the lookup method provided by the ServiceRegistrar interface; employing the same template-matching scheme. Additionally, this method allows any entity to supply an object referred to as a filter. Such an object is a non-remote object that defines additional matching criteria that the ServiceDiscoveryManager applies when searching for the entity's services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of standard template-matching.

This version of lookup returns an array of instances of ServiceItem in which each element corresponds to a service reference that satisfies the matching criteria. The number of elements in the returned set will be no greater than the value of the maxMatches parameter, but may be less.

Note that this version of lookup provides a blocking feature that is controlled through the waitDur parameter in conjunction with the minMatches and the maxMatches parameters. This method will not return until one of the following occurs:

• the number of matching services found on the first attempt is greater than or equal to the value of the minMatches parameter, in which case this method returns each of the services found up to the value of the maxMatches parameter
• the number of matching services found after the first attempt (that is, after the method enters the "wait state") is at least as great as the value of the minMatches parameter in which case this method returns each of the services found up to the value of the maxMatches parameter
• the amount of time that has passed since this method entered the wait state exceeds the value of the waitDur parameter, in which case this method returns all of the currently discovered services

The purpose of the minMatches parameter is to allow the entity to balance its need for multiple matching service references with its need to minimize the time spent in the wait state; time that most would consider wasted if an acceptable number of matching service references were found, but this method continued to wait until the end of the designated time period.

If, while waiting for the minimum number of desired services to be discovered, the entity decides that it no longer wishes to wait the entire period for this method to return, the entity may interrupt this method by invoking the interrupt method from the Thread class. The intent of this mechanism is to allow the entity to interrupt this method in the same way it would a sleeping thread.

Entities typically employ this method when they need infrequent access to multiple instances of services, are willing (or forced) to wait for those services to be found, and consider the cost of making remote queries for those services is outweighed by the overhead of maintaining a local cache (for example, because of resource limitations).

Parameters:

tmpl - an instance of ServiceTemplate corresponding to the object to use for template-matching when searching for desired services. If null is input to this parameter, this method will use a wildcarded template (will match all services) when performing template-matching. Note that the effects of modifying contents of this parameter before this method returns are unpredictable and undefined.

minMatches - this method will immediately exit the wait state and return once this number of service references is found

maxMatches - this method will return no more than this number of service references

filter - an instance of ServiceItemFilter containing matching criteria that should be applied in addition to the template-matching employed when searching for desired services. If null is input to this parameter, then only template-matching will be employed to find the desired services.

waitDur - the amount of time (in milliseconds) to wait before ending the "search" and returning an empty array. If a non-positive value is input to this parameter, then this method will not wait; it will simply query the available lookup services and return whatever matching service reference(s) it could find, up to maxMatches.

Returns:

an array of instances of ServiceItem where each element corresponds to a reference to a service that matches the criteria represented in the input parameters; or an empty array if no matching service can be found within the time allowed.

Throws:

InterruptedException - this exception occurs when the entity interrupts this method by invoking the interrupt method from the Thread class.

IllegalArgumentException - this exception occurs when one of the following conditions is satisfied:

• the minMatches parameter is non-positive
• the maxMatches parameter is non-positive
• the value of maxMatches is less than the value of minMatches

RemoteException - typically, this exception occurs when a RemoteException occurs either as a result of an attempt to export a remote listener, or an attempt to register with the event mechanism of a lookup service.

See Also:

ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate), ServiceTemplate, ServiceItemFilter, Thread