<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
               "http://docbook.org/xml/4.2/docbookx.dtd"
	       [
	       <!ENTITY copyright SYSTEM "copyright.xml">
	       ]>

<chapter label="Join Manager" id="13">
<title>
Join Manager
</title>

  <tocchap>
    <tocentry>
      Contents
    </tocentry>

    <toclevel1>
      <tocentry>
	<ulink url="#Join Manager"> Join Manager </ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#Jini 1.0 JoinManager"> Jini 1.0 JoinManager
	</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#Getting information from JoinManager"> Getting
	  information from JoinManager </ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#Summary"> Summary </ulink>
      </tocentry>
    </toclevel1>
  </tocchap>


<abstract>
<para>
Finding a lookup service involves a common series of steps.
Subequent interaction with them also involves common steps.
A join manager encapulates these into one convenience class for services.
</para>
</abstract>

<sect1>
<title id="Join Manager">
Join Manager
</title>

<para>
A service needs to locate lookup services and register the service
with them. Locating services can be done using the utility classes of
``Discovery Management''. As each lookup service is discovered, it then needs
to be registered, and the lease maintained. The class <code>JoinManager</code>
performs all of these tasks. There are two constructors
<programlisting>
public class JoinManager {
     public JoinManager(Object obj,
                        Entry[] attrSets,
                        ServiceIDListener callback,
                        DiscoveryManagement discoverMgr,
                        LeaseRenewalManager leaseMgr)    
            throws IOException;

     public JoinManager(Object obj,
                        Entry[] attrSets,
                        ServiceID serviceID,
                        DiscoveryManagement discoverMgr,
                        LeaseRenewalManager leaseMgr)    
            throws IOException;

     public JoinManager(Object obj,
                        Entry[] attrSets,
                        ServiceIDListener callback,
                        DiscoveryManagement discoverMgr,
                        LeaseRenewalManager leaseMgr,
                        Configuration config)    
            throws IOException,
                   ConfigurationException;

     public JoinManager(Object obj,
                        Entry[] attrSets,
                        ServiceID serviceID,
                        DiscoveryManagement discoverMgr,
                        LeaseRenewalManager leaseMgr,
                        Configuration config)    
            throws IOException,
                   ConfigurationException;
}
</programlisting>
The first of these is when the service is new and does not have a service id.
A <code>ServiceIDListener</code> can be added which can note and save the id.
The second form is used when the service already has an id. The other parameters
are for the service and its entry attributes, a <code>DiscoveryManagement</code>
object to set groups and unicast locators (typically this will be done using
a <code>LookupDiscoveryManager</code>) and a lease renewal manager.
The third and fourth constructors add a <code>Configuration</code> parameter
to the first and second constructors respectively.
</para>

<para>
The following example uses the first constructor to register a <code>FileClassifierImpl</code>.
There is no need for a <code>DiscoveryListener</code>, since the join manager
adds itself as a listener and handles the registration with the lookup service.
Note that a proxy has to be created using an <code>Exporter</code>, and then the proxy
is passed as the first parameter to the <code>JoinManager</code>.
<programlisting>
<?program "joinmgr/FileClassifierServer.java"?>
</programlisting>
</para>

<note id="new">
<para>
An Ant build, deploy and run file for this is
      <filename>joinmgr.FileClassifierServer.xml</filename>
      <programlisting>
	<?antFile "antBuildFiles/joinmgr.FileClassifierServer.xml"?>
      </programlisting>
</para>
</note>

<para>
There are a number of other methods in <code>JoinManager</code>, which allow
one to modify the state of a service registration.
</para>

</sect1>

<sect1>
<title id="Summary">
Summary
</title>
<para>
A <code>JoinManager</code> can be used by a server to simplify many of
the aspects of locating lookup services, registering one or more services
and renewing leases for them.
</para>
</sect1>

&copyright;
</chapter>
