You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by bu...@apache.org on 2010/12/24 21:26:27 UTC
svn commit: r781463 [4/5] -
/websites/staging/river/trunk/content/river/doc/api/net/jini/lookup/
Added: websites/staging/river/trunk/content/river/doc/api/net/jini/lookup/ServiceDiscoveryManager.html
==============================================================================
--- websites/staging/river/trunk/content/river/doc/api/net/jini/lookup/ServiceDiscoveryManager.html (added)
+++ websites/staging/river/trunk/content/river/doc/api/net/jini/lookup/ServiceDiscoveryManager.html Fri Dec 24 20:26:27 2010
@@ -0,0 +1,1600 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--NewPage-->
+<HTML>
+<HEAD>
+<!-- Generated by javadoc (build 1.5.0_15) on Mon Mar 08 17:46:23 EST 2010 -->
+<TITLE>
+ServiceDiscoveryManager (Apache River v2.1.2-SNAPSHOT API Documentation)
+</TITLE>
+
+<META NAME="keywords" CONTENT="net.jini.lookup.ServiceDiscoveryManager class">
+
+<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
+
+<SCRIPT type="text/javascript">
+function windowTitle()
+{
+ parent.document.title="ServiceDiscoveryManager (Apache River v2.1.2-SNAPSHOT API Documentation)";
+}
+</SCRIPT>
+<NOSCRIPT>
+</NOSCRIPT>
+
+</HEAD>
+
+<BODY BGCOLOR="white" onload="windowTitle();">
+
+
+<!-- ========= START OF TOP NAVBAR ======= -->
+<A NAME="navbar_top"><!-- --></A>
+<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
+<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
+<TR>
+<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
+<A NAME="navbar_top_firstrow"><!-- --></A>
+<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
+ <TR ALIGN="center" VALIGN="top">
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
+ <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/ServiceDiscoveryManager.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
+ <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
+ </TR>
+</TABLE>
+</TD>
+<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
+</EM>
+</TD>
+</TR>
+
+<TR>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryListener.html" title="interface in net.jini.lookup"><B>PREV CLASS</B></A>
+ <A HREF="../../../net/jini/lookup/ServiceIDListener.html" title="interface in net.jini.lookup"><B>NEXT CLASS</B></A></FONT></TD>
+<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
+ <A HREF="../../../index.html?net/jini/lookup/ServiceDiscoveryManager.html" target="_top"><B>FRAMES</B></A>
+ <A HREF="ServiceDiscoveryManager.html" target="_top"><B>NO FRAMES</B></A>
+ <SCRIPT type="text/javascript">
+ <!--
+ if(window==top) {
+ document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
+ }
+ //-->
+</SCRIPT>
+<NOSCRIPT>
+ <A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
+</NOSCRIPT>
+
+
+</FONT></TD>
+</TR>
+<TR>
+<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
+ SUMMARY: NESTED | FIELD | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD>
+<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
+DETAIL: FIELD | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD>
+</TR>
+</TABLE>
+<A NAME="skip-navbar_top"></A>
+<!-- ========= END OF TOP NAVBAR ========= -->
+
+<HR>
+<!-- ======== START OF CLASS DATA ======== -->
+<H2>
+<FONT SIZE="-1">
+net.jini.lookup</FONT>
+<BR>
+Class ServiceDiscoveryManager</H2>
+<PRE>
+<A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html" title="class or interface in java.lang">java.lang.Object</A>
+ <IMG SRC="../../../resources/inherit.gif" ALT="extended by "><B>net.jini.lookup.ServiceDiscoveryManager</B>
+</PRE>
+<HR>
+<DL>
+<DT><PRE>public class <B>ServiceDiscoveryManager</B><DT>extends <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html" title="class or interface in java.lang">Object</A></DL>
+</PRE>
+
+<P>
+The <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ There are three basic usage patterns for this class. In order of
+ importance and typical usage, those patterns are:
+ <p>
+ <ul>
+ <li> The entity requests that the <code>ServiceDiscoveryManager</code>
+ create a cache (an instance of
+ <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A>) 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 <code>ServiceDiscoveryManager</code> 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 <i>frequent</i>
+ 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
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#createLookupCache(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, net.jini.lookup.ServiceDiscoveryListener)"><CODE>createLookupCache</CODE></A>.
+ <li> The entity can register with the event mechanism provided by the
+ <code>ServiceDiscoveryManager</code>. 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
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryListener.html" title="interface in net.jini.lookup"><CODE>ServiceDiscoveryListener</CODE></A> interface that will receive instances of
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryEvent.html" title="class in net.jini.lookup"><CODE>ServiceDiscoveryEvent</CODE></A>
+ when events of interest, related to the services in the cache, occur.
+ <li> The entity, through the public API of the
+ <code>ServiceDiscoveryManager</code>, can directly query the lookup
+ services managed by the <code>ServiceDiscoveryManager</code> for
+ services of interest; employing semantics similar to the semantics
+ employed in a typical lookup service query made through the
+ <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A>
+ 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 <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A>
+ interface, the <code>ServiceDiscoveryManager</code> provides a broad
+ API with semantics that are richer than the semantics of the
+ <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#lookup(net.jini.core.lookup.ServiceTemplate)"><CODE>lookup</CODE></A> methods
+ provided by the <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A>. 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
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter)"><CODE>lookup</CODE></A>
+ method when the entity wishes to acquire a service that matches
+ desired criteria.
+ </ul>
+ <p>
+ 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
+ <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A> interface.
+ Additionally, each mechanism allows the entity to supply an object
+ referred to as a <i>filter</i>; an instance of
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A>. A filter
+ is a non-remote object that defines additional matching criteria that the
+ <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ 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 <i>safe</i> to use are returned
+ to the entity. To do this, the entity would use the
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A> interface to
+ supply the <code>ServiceDiscoveryManager</code> or
+ <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A> with a filter that,
+ when applied to a candidate proxy, performs a set of operations that
+ is referred to as <i>proxy preparation</i>. As described in the
+ documentation for <A HREF="../../../net/jini/security/ProxyPreparer.html" title="interface in net.jini.security"><CODE>ProxyPreparer</CODE></A>, proxy
+ preparation typically includes operations such as, verifying trust
+ in the proxy, specifying client constraints, and dynamically granting
+ necessary permissions to the proxy.
+ <p>
+ 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.
+<P>
+
+<P>
+<DL>
+<DT><B>Author:</B></DT>
+ <DD>Sun Microsystems, Inc.</DD>
+<DT><B>See Also:</B><DD><A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery"><CODE>DiscoveryManagement</CODE></A>,
+<A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A>,
+<A HREF="../../../net/jini/lookup/ServiceDiscoveryListener.html" title="interface in net.jini.lookup"><CODE>ServiceDiscoveryListener</CODE></A>,
+<A HREF="../../../net/jini/lookup/ServiceDiscoveryEvent.html" title="class in net.jini.lookup"><CODE>ServiceDiscoveryEvent</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A><DT><B>Implementation Specifics:</B></DT>
+ <DD><!-- Implementation Specifics -->
+
+ The following implementation-specific items are discussed below:
+ <ul><li> <a href="#sdmConfigEntries">Configuring ServiceDiscoveryManager</a>
+ <li> <a href="#sdmLogging">Logging</a>
+ </ul>
+
+ <a name="sdmConfigEntries">
+ <p>
+ <b><font size="+1">Configuring ServiceDiscoveryManager</font></b>
+ <p>
+ </a>
+
+ This implementation of <code>ServiceDiscoveryManager</code> supports
+ the following configuration entries; where each configuration entry
+ name is associated with the component name
+ <code>net.jini.lookup.ServiceDiscoveryManager</code>. Note that the
+ configuration entries specified here are specific to this implementation
+ of <code>ServiceDiscoveryManager</code>. 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.
+ <p>
+ 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.
+
+
+ <a name="cacheTaskManager">
+ <table summary="Describes the cacheTaskManager configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>cacheTaskManager</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../com/sun/jini/thread/TaskManager.html" title="class in com.sun.jini.thread"><CODE>TaskManager</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code>new
+ <A HREF="../../../com/sun/jini/thread/TaskManager.html#TaskManager()"><CODE>TaskManager</CODE></A>(10, (15*1000), 1.0f)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ </table>
+
+ <a name="discardTaskManager">
+ <table summary="Describes the discardTaskManager configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>discardTaskManager</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../com/sun/jini/thread/TaskManager.html" title="class in com.sun.jini.thread"><CODE>TaskManager</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code>new
+ <A HREF="../../../com/sun/jini/thread/TaskManager.html#TaskManager()"><CODE>TaskManager</CODE></A>(10, (15*1000), 1.0f)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ </table>
+
+ <a name="discardWait">
+ <table summary="Describes the discardWait
+ configuration entry" border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>discardWait</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <code>long</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code>2*(5*60*1000)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> The value used to affect the behavior of the mechanism
+ that handles the <i>service discard problem</i> 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.
+ </table>
+
+ <a name="discoveryManager">
+ <table summary="Describes the discoveryManager configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>discoveryManager</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery"><CODE>DiscoveryManagement</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code> new
+ <A HREF="../../../net/jini/discovery/LookupDiscoveryManager.html#LookupDiscoveryManager(java.lang.String[], net.jini.core.discovery.LookupLocator[], net.jini.discovery.DiscoveryListener, net.jini.config.Configuration)"><CODE>LookupDiscoveryManager</CODE></A>(
+ new java.lang.String[] {""},
+ new <A HREF="../../../net/jini/core/discovery/LookupLocator.html" title="class in net.jini.core.discovery"><CODE>LookupLocator</CODE></A>[0],
+ null, config)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ </table>
+
+ <a name="eventLeasePreparer">
+ <table summary="Describes the eventLeasePreparer configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>eventLeasePreparer</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../net/jini/security/ProxyPreparer.html" title="interface in net.jini.security"><CODE>ProxyPreparer</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code>new <A HREF="../../../net/jini/security/BasicProxyPreparer.html" title="class in net.jini.security"><CODE>BasicProxyPreparer</CODE></A>()
+ </code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ <p>
+ Currently, no methods of the returned proxy are invoked by
+ this utility.
+ </table>
+
+ <a name="eventListenerExporter">
+ <table summary="Describes the eventListenerExporter configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>eventListenerExporter</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../net/jini/export/Exporter.html" title="interface in net.jini.export"><CODE>Exporter</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code> new
+ <A HREF="../../../net/jini/jeri/BasicJeriExporter.html#BasicJeriExporter(net.jini.jeri.ServerEndpoint, net.jini.jeri.InvocationLayerFactory, boolean, boolean)"><CODE>BasicJeriExporter</CODE></A>(
+ <A HREF="../../../net/jini/jeri/tcp/TcpServerEndpoint.html#getInstance(int)"><CODE>TcpServerEndpoint.getInstance</CODE></A>(0),<br>
+            
+            
+ new <A HREF="../../../net/jini/jeri/BasicILFactory.html" title="class in net.jini.jeri"><CODE>BasicILFactory</CODE></A>(),<br>
+            
+            
+ false, false)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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
+ <code>keepAlive</code> flag to <code>false</code> 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.
+ </table>
+
+ <a name="leaseManager">
+ <table summary="Describes the leaseManager configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>leaseManager</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease"><CODE>LeaseRenewalManager</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code> new
+ <A HREF="../../../net/jini/lease/LeaseRenewalManager.html#LeaseRenewalManager(net.jini.config.Configuration)"><CODE>LeaseRenewalManager</CODE></A>(config)</code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ </table>
+
+ <a name="registrarPreparer">
+ <table summary="Describes the registrarPreparer configuration entry"
+ border="0" cellpadding="2">
+ <tr valign="top">
+ <th scope="col" summary="layout"> <font size="+1">•</font>
+ <th scope="col" align="left" colspan="2"> <font size="+1">
+ <code>registrarPreparer</code></font>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Type: <td> <A HREF="../../../net/jini/security/ProxyPreparer.html" title="interface in net.jini.security"><CODE>ProxyPreparer</CODE></A>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Default: <td> <code>new <A HREF="../../../net/jini/security/BasicProxyPreparer.html" title="class in net.jini.security"><CODE>BasicProxyPreparer</CODE></A>()
+ </code>
+
+ <tr valign="top"> <td>   <th scope="row" align="right">
+ Description:
+ <td> 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.
+ <p>
+ The following methods of the proxy returned by this preparer are
+ invoked by this utility:
+ <ul>
+ <li><A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#lookup(net.jini.core.lookup.ServiceTemplate)"><CODE>lookup</CODE></A>
+ <li><A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#notify(net.jini.core.lookup.ServiceTemplate, int, net.jini.core.event.RemoteEventListener, java.rmi.MarshalledObject, long)"><CODE>notify</CODE></A>
+ </ul>
+
+ </table>
+
+ <a name="sdmLogging">
+ <p>
+ <b><font size="+1">Logging</font></b>
+ <p>
+ </a>
+
+ This implementation of <code>ServiceDiscoveryManager</code> uses the
+ <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Logger.html" title="class or interface in java.util.logging"><CODE>Logger</CODE></A> named <code>net.jini.lookup.ServiceDiscoveryManager</code>
+ to log information at the following logging levels: <p>
+
+ <table border="1" cellpadding="5"
+ summary="Describes the information logged by ServiceDiscoveryManager,
+ and the levels at which that information is logged">
+
+
+ <caption halign="center" valign="top">
+ <b><code>net.jini.lookup.ServiceDiscoveryManager</code></b>
+ </caption>
+
+ <tr> <th scope="col"> Level</th>
+ <th scope="col"> Description</th>
+ </tr>
+
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#INFO" title="class or interface in java.util.logging"><CODE>INFO</CODE></A></td>
+ <td>
+ when any exception occurs while querying a lookup service, or upon
+ applying a filter to the results of such a query
+ </td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#INFO" title="class or interface in java.util.logging"><CODE>INFO</CODE></A></td>
+ <td>
+ 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
+ </td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#INFO" title="class or interface in java.util.logging"><CODE>INFO</CODE></A></td>
+ <td>when any exception occurs while attempting to prepare a proxy</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#INFO" title="class or interface in java.util.logging"><CODE>INFO</CODE></A></td>
+ <td>
+ when an <code>IllegalStateException</code> occurs while discarding
+ a lookup service proxy after logging a failure that has occurred in
+ one of the tasks executed by this utility
+ </td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#INFO" title="class or interface in java.util.logging"><CODE>INFO</CODE></A></td>
+ <td>upon failure of the lease renewal process</td>
+ </tr>
+ <tr>
+ <td><A HREF="../../../com/sun/jini/logging/Levels.html#HANDLED"><CODE>HANDLED</CODE></A></td>
+ <td>
+ when an exception occurs because a remote call to a lookup service
+ has been interrupted as a result of the termination of a cache
+ </td>
+ </tr>
+ <tr>
+ <td><A HREF="../../../com/sun/jini/logging/Levels.html#HANDLED"><CODE>HANDLED</CODE></A></td>
+ <td>
+ when a "gap" is encountered in an event sequence from a lookup service
+ </td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINER" title="class or interface in java.util.logging"><CODE>FINER</CODE></A></td>
+ <td>upon failure of the lease cancellation process</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>whenever any task is started</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>whenever any task completes successfully</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>whenever a lookup cache is created</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>whenever a lookup cache is terminated</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>whenever a proxy is prepared</td>
+ </tr>
+ <tr>
+ <td><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html#FINEST" title="class or interface in java.util.logging"><CODE>FINEST</CODE></A></td>
+ <td>
+ when an exception (that is, <code>IllegalStateException</code>)
+ occurs while unexporting a cache's remote event listener while the
+ cache is being terminated
+ </td>
+ </tr>
+ </table>
+ <p>
+ See the <A HREF="../../../com/sun/jini/logging/LogManager.html" title="class in com.sun.jini.logging"><CODE>LogManager</CODE></A> class for one way to use
+ the logging level <A HREF="../../../com/sun/jini/logging/Levels.html#HANDLED"><CODE>HANDLED</CODE></A> in
+ standard logging configuration files.
+ <p></DD>
+</DL>
+<HR>
+
+<P>
+
+<!-- ======== CONSTRUCTOR SUMMARY ======== -->
+
+<A NAME="constructor_summary"><!-- --></A>
+<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
+<B>Constructor Summary</B></FONT></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#ServiceDiscoveryManager(net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager)">ServiceDiscoveryManager</A></B>(<A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A> discoveryMgr,
+ <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A> leaseMgr)</CODE>
+
+<BR>
+ Constructs an instance of <code>ServiceDiscoveryManager</code> 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.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#ServiceDiscoveryManager(net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager, net.jini.config.Configuration)">ServiceDiscoveryManager</A></B>(<A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A> discoveryMgr,
+ <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A> leaseMgr,
+ <A HREF="../../../net/jini/config/Configuration.html" title="interface in net.jini.config">Configuration</A> config)</CODE>
+
+<BR>
+ Constructs an instance of this class, which is configured using the
+ items retrieved through the given <code>Configuration</code>, 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.</TD>
+</TR>
+</TABLE>
+
+<!-- ========== METHOD SUMMARY =========== -->
+
+<A NAME="method_summary"><!-- --></A>
+<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
+<B>Method Summary</B></FONT></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup">LookupCache</A></CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#createLookupCache(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, net.jini.lookup.ServiceDiscoveryListener)">createLookupCache</A></B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryListener.html" title="interface in net.jini.lookup">ServiceDiscoveryListener</A> listener)</CODE>
+
+<BR>
+ The <code>createLookupCache</code> method allows the client-like
+ entity to request that the <code>ServiceDiscoveryManager</code>
+ 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.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A></CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#getDiscoveryManager()">getDiscoveryManager</A></B>()</CODE>
+
+<BR>
+ The <code>getDiscoveryManager</code> method will return an
+ object that implements the <code>DiscoveryManagement</code>
+ interface.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A></CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#getLeaseRenewalManager()">getLeaseRenewalManager</A></B>()</CODE>
+
+<BR>
+ The <code>getLeaseRenewalManager</code> method will return an
+ instance of the <code>LeaseRenewalManager</code> class.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A>[]</CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, int, int, net.jini.lookup.ServiceItemFilter, long)">lookup</A></B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ int minMatches,
+ int maxMatches,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ long waitDur)</CODE>
+
+<BR>
+ Queries each available lookup service in the managed set for service(s)
+ that match the input criteria.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A>[]</CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, int, net.jini.lookup.ServiceItemFilter)">lookup</A></B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ int maxMatches,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter)</CODE>
+
+<BR>
+ Queries each available lookup service in the managed set for service(s)
+ that match the input criteria.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A></CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter)">lookup</A></B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter)</CODE>
+
+<BR>
+ Queries each available lookup service in the set of lookup services
+ managed by the <code>ServiceDiscoveryManager</code> (the <i>managed
+ set</i>) for a service reference that matches criteria defined by the
+ entity that invokes this method.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A></CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, long)">lookup</A></B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ long waitDur)</CODE>
+
+<BR>
+ Queries each available lookup service in the managed set for a service
+ that matches the input criteria.</TD>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
+<CODE> void</CODE></FONT></TD>
+<TD><CODE><B><A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#terminate()">terminate</A></B>()</CODE>
+
+<BR>
+ The <code>terminate</code> 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
+ <code>ServiceDiscoveryManager</code>.</TD>
+</TR>
+</TABLE>
+ <A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
+<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
+<TH ALIGN="left"><B>Methods inherited from class java.lang.<A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html" title="class or interface in java.lang">Object</A></B></TH>
+</TR>
+<TR BGCOLOR="white" CLASS="TableRowColor">
+<TD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#clone()" title="class or interface in java.lang">clone</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#equals(java.lang.Object)" title="class or interface in java.lang">equals</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#finalize()" title="class or interface in java.lang">finalize</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#getClass()" title="class or interface in java.lang">getClass</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#hashCode()" title="class or interface in java.lang">hashCode</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#notify()" title="class or interface in java.lang">notify</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#notifyAll()" title="class or interface in java.lang">notifyAll</A>, <A HREF="http://
java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#toString()" title="class or interface in java.lang">toString</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#wait()" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#wait(long)" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#wait(long, int)" title="class or interface in java.lang">wait</A></CODE></TD>
+</TR>
+</TABLE>
+
+<P>
+
+<!-- ========= CONSTRUCTOR DETAIL ======== -->
+
+<A NAME="constructor_detail"><!-- --></A>
+<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
+<B>Constructor Detail</B></FONT></TH>
+</TR>
+</TABLE>
+
+<A NAME="ServiceDiscoveryManager(net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager)"><!-- --></A><H3>
+ServiceDiscoveryManager</H3>
+<PRE>
+public <B>ServiceDiscoveryManager</B>(<A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A> discoveryMgr,
+ <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A> leaseMgr)
+ throws <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/io/IOException.html" title="class or interface in java.io">IOException</A></PRE>
+<DL>
+<DD>Constructs an instance of <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ As stated in the class description, this class has three usage patterns:
+ <p>
+ <ul>
+ <li> the entity uses a <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A> to locally store and manage discovered services
+ so that those services can be accessed quickly
+ <li> the entity registers with the event mechanism provided by a
+ <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A> to be notified
+ when services of interest are discovered
+ <li> the entity uses the <code>ServiceDiscoveryManager</code> to
+ perform remote queries of the lookup services, employing richer
+ semantics than that provided through the standard
+ <A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A>
+ interface
+ </ul>
+ <p>
+ Although the first two usage patterns emphasize the use of a cache
+ object, that cache is acquired only through an instance of the
+ <code>ServiceDiscoveryManager</code> class.
+ <p>
+ It is important to note that some of the methods of this class
+ (<A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#createLookupCache(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, net.jini.lookup.ServiceDiscoveryListener)"><CODE>createLookupCache</CODE></A> and the <i>blocking</i> versions of
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryManager.html#lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter)"><CODE>lookup</CODE></A> to
+ be exact) can throw a <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi"><CODE>RemoteException</CODE></A> 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 <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi"><CODE>RemoteException</CODE></A>.
+ <p>
+ In order to facilitate the exportation of the remote listener
+ just described, the <code>ServiceDiscoveryManager</code> class
+ instantiates an inner class that implements the
+ <A HREF="../../../net/jini/core/event/RemoteEventListener.html" title="interface in net.jini.core.event"><CODE>RemoteEventListener</CODE></A>
+ interface. Although this class defines, instantiates, and exports this
+ remote listener, <i>it is the entity's responsibility</i> 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 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.
+ <p>
+ The <a href="#eventListenerExporter">default exporter</a> 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.
+ <p>
+ 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:
+ <p>
+ <blockquote>
+ <pre>
+ 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
+ </pre>
+ </blockquote>
+ <p>
+ It is important to note that when the remote event listener is exported
+ under JRMP, unlike Jini ERI, the JRMP remote communication framework
+ does <b><i>not</i></b> 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.
+ <p>
+ 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:
+ <p>
+ <ul><li> store the necessary class files in a JAR file
+ <li> make the class files in the JAR file <i>preferred</i>
+ (see <A HREF="../../../net/jini/loader/pref/package-summary.html"><CODE>net.jini.loader.pref</CODE></A> for details)
+ <li> run an HTTP server to serve up the JAR file to any requesting
+ lookup service
+ <li> advertise the location of that JAR file by setting the
+ <code>java.rmi.server.codebase</code> property of the entity
+ to "point" at the JAR file
+ </ul>
+ <p>
+ For example, suppose an application consists of an entity that intends
+ to use the <code>ServiceDiscoveryManager</code> will run on a host named
+ <b><i>myHost</i></b>. And suppose that the <i>down-loadable</i> JAR
+ file named <b><i>sdm-dl.jar</i></b> that is provided in the
+ distribution is located in the directory <b><i>/files/jini/lib</i></b>,
+ and will be served by an HTTP server listening on port
+ <b><i>8082</i></b>. If the application is run with its codebase
+ property set to
+ <code>-Djava.rmi.server.codebase="http://myHost:8082/sdm-dl.jar"</code>,
+ the lookup service(s) should then be able to access the remote listener
+ exported under JRMP by the <code>ServiceDiscoveryManager</code> on
+ behalf of the entity.
+ <p>
+ If a mechanism for lookup services to access the remote listener
+ exported by the <code>ServiceDiscoveryManager</code> is not provided
+ (either by the remote communication framework itself, or by some other
+ means), the remote methods of the <code>ServiceDiscoveryManager</code>
+ - the methods involved in the two most important usage patterns of
+ that utility - will be of no use.
+ <p>
+ This constructor takes two arguments: an object that implements the
+ <code>DiscoveryManagement</code> interface and a reference to a
+ <code>LeaseRenewalManager</code> object. The constructor throws an
+ <code>IOException</code> because construction of a
+ <code>ServiceDiscoveryManager</code> may initiate the multicast
+ discovery process, a process that can throw an
+ <code>IOException</code>.
+<P>
+<DL>
+<DT><B>Parameters:</B><DD><CODE>discoveryMgr</CODE> - the <code>DiscoveryManagement</code>
+ implementation through which notifications
+ that indicate a lookup service has been
+ discovered or discarded will be received.
+ If the value of the argument is <code>null</code>,
+ then an instance of the
+ <code>LookupDiscoveryManager</code> utility
+ class will be constructed to listen for events
+ announcing the discovery of only those lookup
+ services that are members of the public group.<DD><CODE>leaseMgr</CODE> - the <code>LeaseRenewalManager</code> to use. A
+ value of <code>null</code> may be passed as the
+ <code>LeaseRenewalManager</code> argument. If
+ the value of the argument is <code>null</code>,
+ an instance of the
+ <code>LeaseRenewalManager</code> class will be
+ created, initially managing no
+ <code>Lease</code> objects.
+<DT><B>Throws:</B>
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/io/IOException.html" title="class or interface in java.io">IOException</A></CODE> - because construction of a
+ <code>ServiceDiscoveryManager</code> may initiate
+ the multicast discovery process which can throw
+ an <code>IOException</code>.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery"><CODE>DiscoveryManagement</CODE></A>,
+<A HREF="../../../net/jini/core/event/RemoteEventListener.html" title="interface in net.jini.core.event"><CODE>RemoteEventListener</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A></DL>
+</DL>
+<HR>
+
+<A NAME="ServiceDiscoveryManager(net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager, net.jini.config.Configuration)"><!-- --></A><H3>
+ServiceDiscoveryManager</H3>
+<PRE>
+public <B>ServiceDiscoveryManager</B>(<A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A> discoveryMgr,
+ <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A> leaseMgr,
+ <A HREF="../../../net/jini/config/Configuration.html" title="interface in net.jini.config">Configuration</A> config)
+ throws <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/io/IOException.html" title="class or interface in java.io">IOException</A>,
+ <A HREF="../../../net/jini/config/ConfigurationException.html" title="class in net.jini.config">ConfigurationException</A></PRE>
+<DL>
+<DD>Constructs an instance of this class, which is configured using the
+ items retrieved through the given <code>Configuration</code>, 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.
+ <p>
+ For a more details, refer to the description of the alternate
+ constructor of this class.
+ <p>
+ This constructor takes three arguments: an object that implements the
+ <code>DiscoveryManagement</code> interface, a reference to an instance
+ of the <code>LeaseRenewalManager</code> class, and a
+ <code>Configuration</code> object. The constructor throws an
+ <code>IOException</code> because construction of a
+ <code>ServiceDiscoveryManager</code> may initiate the multicast
+ discovery process, a process that can throw an
+ <code>IOException</code>. The constructor also throws a
+ <code>ConfigurationException</code> when an exception occurs while
+ retrieving an item from the given <code>Configuration</code>
+<P>
+<DL>
+<DT><B>Parameters:</B><DD><CODE>discoveryMgr</CODE> - the <code>DiscoveryManagement</code>
+ implementation through which notifications
+ that indicate a lookup service has been
+ discovered or discarded will be received.
+ If the value of the argument is <code>null</code>,
+ then an instance of the
+ <code>LookupDiscoveryManager</code> utility
+ class will be constructed to listen for events
+ announcing the discovery of only those lookup
+ services that are members of the public group.<DD><CODE>leaseMgr</CODE> - the <code>LeaseRenewalManager</code> to use. A
+ value of <code>null</code> may be passed as the
+ <code>LeaseRenewalManager</code> argument. If
+ the value of the argument is <code>null</code>,
+ an instance of the
+ <code>LeaseRenewalManager</code> class will be
+ created, initially managing no
+ <code>Lease</code> objects.
+<DT><B>Throws:</B>
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/io/IOException.html" title="class or interface in java.io">IOException</A></CODE> - because construction of a
+ <code>ServiceDiscoveryManager</code> may initiate
+ the multicast discovery process which can throw
+ an <code>IOException</code>.
+<DD><CODE><A HREF="../../../net/jini/config/ConfigurationException.html" title="class in net.jini.config">ConfigurationException</A></CODE> - indicates
+ an exception occurred while retrieving an item from the given
+ <code>Configuration</code>
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/NullPointerException.html" title="class or interface in java.lang">NullPointerException</A></CODE> - if <code>null</code> is input
+ for the configuration<DT><B>See Also:</B><DD><A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery"><CODE>DiscoveryManagement</CODE></A>,
+<A HREF="../../../net/jini/core/event/RemoteEventListener.html" title="interface in net.jini.core.event"><CODE>RemoteEventListener</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html" title="interface in net.jini.core.lookup"><CODE>ServiceRegistrar</CODE></A>,
+<A HREF="../../../net/jini/config/Configuration.html" title="interface in net.jini.config"><CODE>Configuration</CODE></A>,
+<A HREF="../../../net/jini/config/ConfigurationException.html" title="class in net.jini.config"><CODE>ConfigurationException</CODE></A></DL>
+</DL>
+
+<!-- ============ METHOD DETAIL ========== -->
+
+<A NAME="method_detail"><!-- --></A>
+<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
+<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
+<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
+<B>Method Detail</B></FONT></TH>
+</TR>
+</TABLE>
+
+<A NAME="lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter)"><!-- --></A><H3>
+lookup</H3>
+<PRE>
+public <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A> <B>lookup</B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter)</PRE>
+<DL>
+<DD>Queries each available lookup service in the set of lookup services
+ managed by the <code>ServiceDiscoveryManager</code> (the <i>managed
+ set</i>) 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 <code>lookup</code> method provided
+ by the <code>ServiceRegistrar</code> interface; employing the same
+ template-matching scheme. Additionally, this method allows any entity
+ to supply an object referred to as a <i>filter</i>. Such an object is
+ a non-remote object that defines additional matching criteria that the
+ <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ 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).
+ <p>
+ This version of <code>lookup</code> returns a <i>single</i> instance
+ of <code>ServiceItem</code> 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 <i>a</i>
+ service is returned, not <i>which</i> service.
+ <p>
+ Note that, unlike other versions of <code>lookup</code> provided
+ by the <code>ServiceDiscoveryManager</code>, this version does not
+ <i>block</i>. 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 <code>lookup</code> 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 <code>lookup</code>,
+ 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 <code>null</code>. 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 <code>lookup</code> 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.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>tmpl</CODE> - an instance of <code>ServiceTemplate</code> corresponding
+ to the object to use for template-matching when searching
+ for desired services. If <code>null</code> is input to
+ this parameter, this method will use a <i>wildcarded</i>
+ 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.<DD><CODE>filter</CODE> - an instance of <code>ServiceItemFilter</code> containing
+ matching criteria that should be applied in addition to
+ the template-matching employed when searching for desired
+ services. If <code>null</code> is input to this parameter,
+ then only template-matching will be employed to find the
+ desired services.
+<DT><B>Returns:</B><DD>a single instance of <code>ServiceItem</code> corresponding to
+ a reference to a service that matches the criteria represented
+ in the input parameters; or <code>null</code> 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.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#lookup(net.jini.core.lookup.ServiceTemplate)"><CODE>ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup"><CODE>ServiceTemplate</CODE></A>,
+<A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="lookup(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, long)"><!-- --></A><H3>
+lookup</H3>
+<PRE>
+public <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A> <B>lookup</B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ long waitDur)
+ throws <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/InterruptedException.html" title="class or interface in java.lang">InterruptedException</A>,
+ <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi">RemoteException</A></PRE>
+<DL>
+<DD>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 <code>lookup</code> method provided by
+ the <code>ServiceRegistrar</code> interface; employing the same
+ template-matching scheme. Additionally, this method allows any entity
+ to supply an object referred to as a <i>filter</i>. Such an object is
+ a non-remote object that defines additional matching criteria that the
+ <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ This version of <code>lookup</code> returns a <i>single</i> instance
+ of <code>ServiceItem</code> 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 <i>a</i>
+ service is returned, not <i>which</i> service.
+ <p>
+ Note that this version of <code>lookup</code> provides a
+ <i>blocking</i> feature that is controlled through the
+ <code>waitDur</code> 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 <code>waitDur</code>
+ 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 <code>Thread</code>
+ class. The intent of this mechanism is to allow the entity to interrupt
+ this method in the same way it would a sleeping thread.
+ <p>
+ 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).
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>tmpl</CODE> - an instance of <code>ServiceTemplate</code> corresponding
+ to the object to use for template-matching when searching
+ for desired services. If <code>null</code> is input to
+ this parameter, this method will use a <i>wildcarded</i>
+ 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.<DD><CODE>filter</CODE> - an instance of <code>ServiceItemFilter</code> containing
+ matching criteria that should be applied in addition
+ to the template-matching employed when searching for
+ desired services. If <code>null</code> is input to this
+ parameter, then only template-matching will be employed
+ to find the desired services.<DD><CODE>waitDur</CODE> - the amount of time (in milliseconds) to wait before
+ ending the "search" and returning <code>null</code>.
+ 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 <code>null</code>.
+<DT><B>Returns:</B><DD>a single instance of <code>ServiceItem</code> corresponding to
+ a reference to a service that matches the criteria represented
+ in the input parameters; or <code>null</code> 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.
+<DT><B>Throws:</B>
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/InterruptedException.html" title="class or interface in java.lang">InterruptedException</A></CODE> - this exception occurs when the
+ entity interrupts this method by invoking the interrupt method
+ from the <code>Thread</code> class.
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi">RemoteException</A></CODE> - 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.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#lookup(net.jini.core.lookup.ServiceTemplate)"><CODE>ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup"><CODE>ServiceTemplate</CODE></A>,
+<A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A>,
+<A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Thread.html" title="class or interface in java.lang"><CODE>Thread</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="createLookupCache(net.jini.core.lookup.ServiceTemplate, net.jini.lookup.ServiceItemFilter, net.jini.lookup.ServiceDiscoveryListener)"><!-- --></A><H3>
+createLookupCache</H3>
+<PRE>
+public <A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup">LookupCache</A> <B>createLookupCache</B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ <A HREF="../../../net/jini/lookup/ServiceDiscoveryListener.html" title="interface in net.jini.lookup">ServiceDiscoveryListener</A> listener)
+ throws <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi">RemoteException</A></PRE>
+<DL>
+<DD>The <code>createLookupCache</code> method allows the client-like
+ entity to request that the <code>ServiceDiscoveryManager</code>
+ 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.
+ <p>
+ This method returns an object of type <code>LookupCache</code>.
+ 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.
+ <p>
+ 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.
+ <p>
+ Although not required, a common usage pattern for entities that
+ wish to use the <code>LookupCache</code> class to store and manage
+ "discovered" services is to create a separate cache for each service
+ type of interest.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>tmpl</CODE> - 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
+ <code>null</code>, it is the equivalent of passing a
+ <code>ServiceTemplate</code> constructed with all
+ <code>null</code> arguments (all wildcards).<DD><CODE>filter</CODE> - used to apply additional matching criteria to any
+ <code>ServiceItem</code> found through template-matching.
+ If this value is <code>null</code>, no additional filtering
+ will be applied beyond the template-matching.<DD><CODE>listener</CODE> - 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 <code>null</code>, the cache resulting from
+ that invocation will send no such notifications.
+<DT><B>Returns:</B><DD>LookupCache used to query the cache for services of
+ interest, manage the cache's event mechanism for service
+ discoveries, or terminate the cache.
+<DT><B>Throws:</B>
+<DD><CODE><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi">RemoteException</A></CODE> - 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.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="getDiscoveryManager()"><!-- --></A><H3>
+getDiscoveryManager</H3>
+<PRE>
+public <A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery">DiscoveryManagement</A> <B>getDiscoveryManager</B>()</PRE>
+<DL>
+<DD>The <code>getDiscoveryManager</code> method will return an
+ object that implements the <code>DiscoveryManagement</code>
+ interface. The object returned by this method provides the
+ <code>ServiceDiscoveryManager</code> with the ability to set
+ discovery listeners and to discard previously discovered lookup
+ services when they are found to be unavailable.
+<P>
+<DD><DL>
+
+<DT><B>Returns:</B><DD>DiscoveryManagement implementation<DT><B>See Also:</B><DD><A HREF="../../../net/jini/discovery/DiscoveryManagement.html" title="interface in net.jini.discovery"><CODE>DiscoveryManagement</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="getLeaseRenewalManager()"><!-- --></A><H3>
+getLeaseRenewalManager</H3>
+<PRE>
+public <A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease">LeaseRenewalManager</A> <B>getLeaseRenewalManager</B>()</PRE>
+<DL>
+<DD>The <code>getLeaseRenewalManager</code> method will return an
+ instance of the <code>LeaseRenewalManager</code> class. The
+ object returned by this method manages the leases requested and
+ held by the <code>ServiceDiscoveryManager</code>. In general, these
+ leases correspond to the registrations made by the
+ <code>ServiceDiscoveryManager</code> with the event mechanism of
+ each lookup service in the managed set.
+<P>
+<DD><DL>
+
+<DT><B>Returns:</B><DD>LeaseRenewalManager for this instance of the
+ <code>ServiceDiscoveryManager</code>.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/lease/LeaseRenewalManager.html" title="class in net.jini.lease"><CODE>LeaseRenewalManager</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="terminate()"><!-- --></A><H3>
+terminate</H3>
+<PRE>
+public void <B>terminate</B>()</PRE>
+<DL>
+<DD>The <code>terminate</code> 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
+ <code>ServiceDiscoveryManager</code>.
+ <p>
+ For each instance of <code>LookupCache</code> created and
+ managed by the <code>ServiceDiscoveryManager</code>, the
+ <code>terminate</code> method will do the following:
+ <ul>
+ <li>Either remove all listener objects registered for receipt
+ of <code>DiscoveryEvent</code> objects or, if the discovery
+ manager employed by the <code>ServiceDiscoveryManager</code> was
+ created by the <code>ServiceDiscoveryManager</code> itself,
+ terminate all discovery processing being performed by that
+ manager object on behalf of the entity.
+ <p>
+ <li>Cancel all event leases granted by each lookup service in
+ the managed set of lookup services.
+ <p>
+ <li>Un-export all remote listener objects registered with each
+ lookup service in the managed set.
+ <p>
+ <li>Terminate all threads involved in the process of retrieving
+ and storing references to discovered services of interest.
+ </ul>
+ Calling any method after the termination will result in an
+ <code>IllegalStateException</code>.
+<P>
+<DD><DL>
+<DT><B>See Also:</B><DD><A HREF="../../../net/jini/lookup/LookupCache.html" title="interface in net.jini.lookup"><CODE>LookupCache</CODE></A>,
+<A HREF="../../../net/jini/discovery/DiscoveryEvent.html" title="class in net.jini.discovery"><CODE>DiscoveryEvent</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="lookup(net.jini.core.lookup.ServiceTemplate, int, net.jini.lookup.ServiceItemFilter)"><!-- --></A><H3>
+lookup</H3>
+<PRE>
+public <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A>[] <B>lookup</B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ int maxMatches,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter)</PRE>
+<DL>
+<DD>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 <code>lookup</code> method provided by
+ the <code>ServiceRegistrar</code> interface; employing the same
+ template-matching scheme. Additionally, this method allows any entity
+ to supply an object referred to as a <i>filter</i>. Such an object is
+ a non-remote object that defines additional matching criteria that the
+ <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ 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).
+ <p>
+ This version of <code>lookup</code> returns an <i>array</i> of instances
+ of <code>ServiceItem</code> 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 <code>maxMatches</code> parameter, but may be less.
+ <p>
+ Note that this version of <code>lookup</code> does not provide a
+ <i>blocking</i> feature. That is, this version will return immediately
+ with whatever number of service references it can find, up to
+ the number indicated in the <code>maxMatches</code> 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 <code>lookup</code> 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 <code>lookup</code>, 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 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 <code>lookup</code> 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.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>tmpl</CODE> - an instance of <code>ServiceTemplate</code>
+ corresponding to the object to use for
+ template-matching when searching for desired services.
+ If <code>null</code> is input to this parameter,
+ this method will use a <i>wildcarded</i> 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.<DD><CODE>maxMatches</CODE> - this method will return no more than this number of
+ service references<DD><CODE>filter</CODE> - an instance of <code>ServiceItemFilter</code>
+ containing matching criteria that should be applied
+ in addition to the template-matching employed when
+ searching for desired services. If <code>null</code>
+ is input to this parameter, then only
+ template-matching will be employed to find the
+ desired services.
+<DT><B>Returns:</B><DD>an array of instances of <code>ServiceItem</code> 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.<DT><B>See Also:</B><DD><A HREF="../../../net/jini/core/lookup/ServiceRegistrar.html#lookup(net.jini.core.lookup.ServiceTemplate)"><CODE>ServiceRegistrar.lookup(net.jini.core.lookup.ServiceTemplate)</CODE></A>,
+<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup"><CODE>ServiceTemplate</CODE></A>,
+<A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup"><CODE>ServiceItemFilter</CODE></A></DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="lookup(net.jini.core.lookup.ServiceTemplate, int, int, net.jini.lookup.ServiceItemFilter, long)"><!-- --></A><H3>
+lookup</H3>
+<PRE>
+public <A HREF="../../../net/jini/core/lookup/ServiceItem.html" title="class in net.jini.core.lookup">ServiceItem</A>[] <B>lookup</B>(<A HREF="../../../net/jini/core/lookup/ServiceTemplate.html" title="class in net.jini.core.lookup">ServiceTemplate</A> tmpl,
+ int minMatches,
+ int maxMatches,
+ <A HREF="../../../net/jini/lookup/ServiceItemFilter.html" title="interface in net.jini.lookup">ServiceItemFilter</A> filter,
+ long waitDur)
+ throws <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/InterruptedException.html" title="class or interface in java.lang">InterruptedException</A>,
+ <A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/RemoteException.html" title="class or interface in java.rmi">RemoteException</A></PRE>
+<DL>
+<DD>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 <code>lookup</code> method provided by
+ the <code>ServiceRegistrar</code> interface; employing the same
+ template-matching scheme. Additionally, this method allows any entity
+ to supply an object referred to as a <i>filter</i>. Such an object is
+ a non-remote object that defines additional matching criteria that the
+ <code>ServiceDiscoveryManager</code> 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.
+ <p>
+ This version of <code>lookup</code> returns an <i>array</i> of instances
+ of <code>ServiceItem</code> 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 <code>maxMatches</code> parameter, but may be less.
+ <p>
+ Note that this version of <code>lookup</code> provides a
+ <i>blocking</i> feature that is controlled through the
[... 159 lines stripped ...]