Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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.

  • | `cacheTaskManager`
  --- | ---
  | Type: | `TaskManager`
  | Default: | `new `TaskManager`(10, (15*1000), 1.0f)`
  | 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 task manager created for each cache. The default manager creates a maximum of 10 threads, waits 15 seconds before removing idle threads, and uses a load factor of 1.0 when determining whether to create a new thread. For each cache that is created in this utility, a single, separate instance of this task manager will be retrieved and employed by that cache. This object should not be shared with other components in the application that employs this utility.

  • | `discardTaskManager`
  --- | ---
  | Type: | `TaskManager`
  | Default: | `new `TaskManager`(10, (15*1000), 1.0f)`
  | 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. The default manager creates a maximum of 10 threads, waits 15 seconds before removing idle threads, and uses a load factor of 1.0 when determining whether to create a new thread. For each cache that is created in this utility, a single, separate instance of this task manager 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 `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`

  Logging

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

  `net.jini.lookup.ServiceDiscoveryManager`
  Level | Description
  --- | ---
  `INFO` | when any exception occurs while querying a lookup service, or upon applying a filter to the results of such a query
  `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
  `INFO` | when any exception occurs while attempting to prepare a proxy
  `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
  `INFO` | upon failure of the lease renewal process
  `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
  `FINER` | upon failure of the lease cancellation process
  `FINEST` | whenever any task is started
  `FINEST` | whenever any task completes successfully
  `FINEST` | whenever a lookup cache is created
  `FINEST` | whenever a lookup cache is terminated
  `FINEST` | whenever a proxy is prepared
  `FINEST` | when an exception (that is, `IllegalStateException`) occurs while unexporting a cache's remote event listener while the cache is being terminated

  See the `LogManager` class for one way to use the logging level `HANDLED` in standard logging configuration files.

Constructor Summary
`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
`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.
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.

  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.

  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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved