public class ServiceDiscoveryManager extends Object
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:
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
.
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.
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.
DiscoveryManagement
,
LookupCache
,
ServiceDiscoveryListener
,
ServiceDiscoveryEvent
,
ServiceRegistrar
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
|
  | 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
|
  | 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
|
  | 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
|
  | 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
|
  | 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
|
  | 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
|
  | 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: |
Logging
This implementation of
ServiceDiscoveryManager
uses the
Logger
named net.jini.lookup.ServiceDiscoveryManager
to
log information at the following logging levels:
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 |
HANDLED |
when a "gap" is encountered in an event sequence from a lookup service |
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 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. |
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 . |
public ServiceDiscoveryManager(DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr) throws IOException
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:
LookupCache
to locally store and manage discovered services so that
those services can be accessed quickly
LookupCache
to be notified when
services of interest are discovered
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:
net.jini.loader.pref
for details)
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
.
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.IOException
- because construction of a
ServiceDiscoveryManager
may initiate the multicast discovery
process which can throw an IOException
.DiscoveryManagement
,
RemoteEventListener
,
ServiceRegistrar
public ServiceDiscoveryManager(DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config) throws IOException, ConfigurationException
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
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
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 configurationDiscoveryManagement
,
RemoteEventListener
,
ServiceRegistrar
,
Configuration
,
ConfigurationException
public ServiceItem lookup(ServiceTemplate tmpl, ServiceItemFilter filter)
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.
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.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.ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)
,
ServiceTemplate
,
ServiceItemFilter
public ServiceItem lookup(ServiceTemplate tmpl, ServiceItemFilter filter, long waitDur) throws InterruptedException, RemoteException
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).
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
.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.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.ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)
,
ServiceTemplate
,
ServiceItemFilter
,
Thread
public LookupCache createLookupCache(ServiceTemplate tmpl, ServiceItemFilter filter, ServiceDiscoveryListener listener) throws RemoteException
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.
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.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.ServiceItemFilter
public DiscoveryManagement getDiscoveryManager()
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.DiscoveryManagement
public LeaseRenewalManager getLeaseRenewalManager()
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.ServiceDiscoveryManager
.LeaseRenewalManager
public void terminate()
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:
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.
IllegalStateException
.LookupCache
,
DiscoveryEvent
public ServiceItem[] lookup(ServiceTemplate tmpl, int maxMatches, ServiceItemFilter filter)
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.
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 referencesfilter
- 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.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.ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)
,
ServiceTemplate
,
ServiceItemFilter
public ServiceItem[] lookup(ServiceTemplate tmpl, int minMatches, int maxMatches, ServiceItemFilter filter, long waitDur) throws InterruptedException, RemoteException
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:
minMatches
parameter, in which case this method returns each of the services found
up to the value of the maxMatches
parameter
minMatches
parameter in which case this
method returns each of the services found up to the value of the
maxMatches
parameter
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).
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 foundmaxMatches
- this method will return no more than this number of
service referencesfilter
- 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
.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.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:
minMatches
parameter is non-positive
maxMatches
parameter is non-positive
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.ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)
,
ServiceTemplate
,
ServiceItemFilter
,
Thread
Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.