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.
@param tmpl an instance of ServiceTemplate correspondingto 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.
@param filter an instance of ServiceItemFilter containingmatching 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.
@return a single instance of ServiceItem corresponding toa 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 net.jini.core.lookup.ServiceRegistrar#lookup
@see net.jini.core.lookup.ServiceTemplate
@see net.jini.lookup.ServiceItemFilter