|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--jgroup.jini.JoinManager
A goal of any well-behaved service is to advertise the facilities and functions it provides by requesting residency within at least one lookup service. Making such a request of a lookup service is known as registering with, or "joining", a lookup service. To demonstrate this good behavior, a service must comply with both the multicast discovery protocol and the unicast discovery protocol in order to discover the lookup services it is interested in joining. The service must also comply with the join protocol to register with the desired lookup services.
In order for a service to maintain its residency in the lookup services it has joined, the service must provide for the coordination, systematic renewal, and overall management of all leases on that residency. In addition to handling all discovery and join duties, as well as managing all leases on lookup service residency, the service must also provide for the coordination and management of any attribute sets with which it may have registered with the lookup services in which it resides.
This class performs all of the functions related to discovery, joining,
service lease renewal, and attribute management which is required of a
well-behaved service. Each of these activities is intimately involved
with the maintenance of a service's residency in one or more lookup
services (the service's join state), thus the name JoinManager
.
This class should be employed by services, not clients. The use of this class in a wide variety of services can help minimize the work resulting from having to repeatedly implement this required functionality in each service. Note that this class is not remote. Services that wish to use this class will create an instance of this class in the service's address space to manage the entity's join state locally.
net.jini.discovery.DiscoveryManagement
,
net.jini.lease.LeaseRenewalManager
Inner Class Summary | |
private class |
JoinManager.addAttributesTask
|
private class |
JoinManager.DiscardProxyTask
|
private class |
JoinManager.DiscMgrListener
|
private class |
JoinManager.LeaseExpireNotifyTask
|
private class |
JoinManager.modifyAttributesTask
|
private class |
JoinManager.ProxyReg
|
private class |
JoinManager.RegisterTask
|
private class |
JoinManager.setAttributesTask
|
private static interface |
JoinManager.Task
|
private class |
JoinManager.TaskThread
|
Field Summary | |
private boolean |
bCreateDiscMgr
|
private boolean |
bTerminated
|
private net.jini.lookup.ServiceIDListener |
callback
|
private jgroup.jini.DiscoveryManagement |
discMgr
|
private JoinManager.DiscMgrListener |
discMgrListener
|
private java.util.ArrayList |
joinSet
|
private jgroup.jini.LeaseRenewalManager |
leaseRenewalMgr
|
private java.util.ArrayList |
listeners
|
private net.jini.core.entry.Entry[] |
lookupAttr
|
private jgroup.jini.ServiceItem |
serviceItem
|
private java.util.ArrayList |
task
|
private JoinManager.TaskThread |
taskThread
|
Constructor Summary | |
JoinManager(java.lang.Object obj,
net.jini.core.entry.Entry[] attrSets,
jgroup.jini.ServiceID serviceID,
jgroup.jini.DiscoveryManagement discoverMgr,
jgroup.jini.LeaseRenewalManager leaseMgr)
Constructs an instance of this class that will register the service, using the supplied service ID, with the lookup services indicated through the discoveryMgr parameter. |
|
JoinManager(java.lang.Object obj,
net.jini.core.entry.Entry[] attrSets,
net.jini.lookup.ServiceIDListener callback,
jgroup.jini.DiscoveryManagement discoverMgr,
jgroup.jini.LeaseRenewalManager leaseMgr)
Constructs an instance of this class that will notify the service when a service ID is assigned by a lookup service with which the service is registered. |
Method Summary | |
void |
addAttributes(net.jini.core.entry.Entry[] attrSets)
Associates a new set of attributes with the service, in addition to the service's current set of attributes. |
void |
addAttributes(net.jini.core.entry.Entry[] attrSets,
boolean checkSC)
Associates a new set of attributes with the service, in addition to the service's current set of attributes. |
private void |
addJoinSet(JoinManager.ProxyReg reg)
|
private net.jini.core.lookup.ServiceRegistrar[] |
buildServiceRegistrar(java.util.ArrayList set)
|
private void |
createJoinManager(jgroup.jini.ServiceID serviceID,
java.lang.Object obj,
net.jini.core.entry.Entry[] attrSets,
net.jini.lookup.ServiceIDListener callback,
jgroup.jini.LeaseRenewalManager leaseMgr)
|
private void |
createTaskThread(JoinManager.Task t)
|
private void |
discardedNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
java.util.ArrayList notifies)
|
private void |
discoveredNotifyListener(net.jini.discovery.DiscoveryListener l,
java.util.ArrayList set)
|
private void |
discoveredNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
java.util.ArrayList notifies)
|
(package private) JoinManager.ProxyReg |
findReg(net.jini.core.lookup.ServiceRegistrar proxy)
|
net.jini.core.entry.Entry[] |
getAttributes()
Returns an array containing the set of attributes currently associated with the service. |
jgroup.jini.DiscoveryManagement |
getDiscoveryManager()
Returns the instance of DiscoveryManagement that was
either passed into the constructor, or that was created as a result
of null being input to that parameter. |
net.jini.core.lookup.ServiceRegistrar[] |
getJoinSet()
Returns an array of ServiceRegistrar objects, each
corresponding to a lookup service with which the service is currently
registered (joined). |
jgroup.jini.LeaseRenewalManager |
getLeaseRenewalManager()
Returns the instance of the LeaseRenewalManager class
that was either passed into the constructor, or that was created
as a result of null being input to that parameter. |
void |
modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates,
net.jini.core.entry.Entry[] attrSets)
Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the
ServiceRegistration class. |
void |
modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates,
net.jini.core.entry.Entry[] attrSets,
boolean checkSC)
Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the
ServiceRegistration class. |
private void |
notifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
java.util.ArrayList notifies,
boolean bDiscovered)
|
private void |
removeJoinSet(JoinManager.ProxyReg reg)
|
void |
setAttributes(net.jini.core.entry.Entry[] attrSets)
Replaces the service's current set of attributes with a new set of attributes. |
void |
terminate()
Performs cleanup duties related to the termination of the lookup service discovery event mechanism, as well as the lease and thread management performed by the JoinManager . |
Methods inherited from class java.lang.Object |
|
Field Detail |
private net.jini.lookup.ServiceIDListener callback
private net.jini.core.entry.Entry[] lookupAttr
private jgroup.jini.ServiceItem serviceItem
private final java.util.ArrayList joinSet
private final java.util.ArrayList listeners
private final java.util.ArrayList task
private JoinManager.TaskThread taskThread
private jgroup.jini.LeaseRenewalManager leaseRenewalMgr
private jgroup.jini.DiscoveryManagement discMgr
private JoinManager.DiscMgrListener discMgrListener
private boolean bTerminated
private boolean bCreateDiscMgr
Constructor Detail |
public JoinManager(java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, net.jini.lookup.ServiceIDListener callback, jgroup.jini.DiscoveryManagement discoverMgr, jgroup.jini.LeaseRenewalManager leaseMgr) throws java.io.IOException
obj
- a reference to the service requesting the services
of this class.attrSets
- array of Entry
consisting of the
attribute sets with which to register the service.callback
- a reference to an object that implements the
ServiceIDListener
interface, which
will be sent an event containing the service ID
assigned to the service by the lookup service.discoverMgr
- a reference to an object that implements the
DiscoveryManagement
interface which
this class will use to manage the service's
discovery duties. If null
is input
to this argument, an instance of the utility class
LookupDiscoveryManager
will be used to
listen for events announcing the discovery of only
those lookup services that are members of the public
group.leaseMgr
- an instance of the LeaseRenewalManager
utility class. If null
is input
to this argument, an instance of the
LeaseRenewalManager
class will be
created, initially managing no leases. This
feature allows a service that employs the
JoinManager
to use either a single
entity to manage all of its leases, or to use
separate entities: one to manage the leases
unrelated to the join process, and one to manage the
leases that result from the join process and which
are accessible only within thejava.io.IOException
- because construction of this class may
initiate the discovery process, which can throw an
IOException
when socket allocation occurs.ServiceIDListener
,
net.jini.discovery.DiscoveryManagement
,
net.jini.discovery.LookupDiscoveryManager
,
net.jini.lease.LeaseRenewalManager
public JoinManager(java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, jgroup.jini.ServiceID serviceID, jgroup.jini.DiscoveryManagement discoverMgr, jgroup.jini.LeaseRenewalManager leaseMgr) throws java.io.IOException
discoveryMgr
parameter. This constructor is
typically used by services that have already been assigned a service
ID (possibly by the service provider itself or as a result of a prior
registration with some lookup service), and which may or may not have
been pre-configured to join lookup services identified by group or by
specific location.
Note that this form of the constructor applies the same semantics
to the attrSets
, discoveryMgr
, and
leaseMgr
parameters as is applied by the first form
of the constructor.
obj
- a reference to the service requesting the services
of this class.attrSets
- array of Entry
consisting of the
attribute sets with which to register the service.serviceID
- an instance of ServiceID
with which to
register the service with all desired lookup servicesdiscoverMgr
- a reference to an object that implements the
DiscoveryManagement
interface which
this class will use to manage the service's
discovery duties. If null
is input
to this argument, an instance of the utility class
LookupDiscoveryManager
will be used to
listen for events announcing the discovery of only
those lookup services that are members of the public
group.leaseMgr
- an instance of the LeaseRenewalManager
utility class. If null
is input
to this argument, an instance of the
LeaseRenewalManager
class will be
created, initially managing no leases. This
feature allows a service that employs the
JoinManager
to use either a single
entity to manage all of its leases, or to use
separate entities: one to manage the leases
unrelated to the join process, and one to manage the
leases that result from the join process and which
are accessible only within thejava.io.IOException
- because construction of this class may
initiate the discovery process, which can throw an
IOException
when socket allocation occurs.net.jini.core.lookup.ServiceID
,
net.jini.discovery.DiscoveryManagement
,
net.jini.discovery.LookupDiscoveryManager
,
net.jini.lease.LeaseRenewalManager
Method Detail |
private void discoveredNotifyListener(net.jini.discovery.DiscoveryListener l, java.util.ArrayList set)
private net.jini.core.lookup.ServiceRegistrar[] buildServiceRegistrar(java.util.ArrayList set)
private void createJoinManager(jgroup.jini.ServiceID serviceID, java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, net.jini.lookup.ServiceIDListener callback, jgroup.jini.LeaseRenewalManager leaseMgr) throws java.io.IOException
public jgroup.jini.DiscoveryManagement getDiscoveryManager()
DiscoveryManagement
that was
either passed into the constructor, or that was created as a result
of null
being input to that parameter.
The object returned by this method encapsulates the mechanism by which
either the JoinManager
or the entity itself can set
discovery listeners and discard previously discovered lookup services
when they are found to be unavailable.
DiscoveryManagement
interface
that was either passed into the constructor, or that was
created as a result of null
being input to that
parameter.net.jini.discovery.DiscoveryManagement
,
net.jini.discovery.LookupDiscoveryManager
public jgroup.jini.LeaseRenewalManager getLeaseRenewalManager()
LeaseRenewalManager
class
that was either passed into the constructor, or that was created
as a result of null
being input to that parameter.
The object returned by this method manages the leases requested and
held by the JoinManager
. Although it may also manage
leases unrelated to the join process that are requested and held by
the service itself, the leases with which the JoinManager
is concerned are the leases that correspond to the service registration
requests made with each lookup service the service wishes to join.
LeaseRenewalManager
class
that was either passed into the constructor, or that was
created as a result of null
being input to that
parameter.net.jini.discovery.DiscoveryManagement
,
net.jini.lease.LeaseRenewalManager
public net.jini.core.lookup.ServiceRegistrar[] getJoinSet()
ServiceRegistrar
objects, each
corresponding to a lookup service with which the service is currently
registered (joined). If there are no lookup services with which the
service is currently registered, this method returns the empty array.
This method returns a new array upon each invocation.ServiceRegistrar
, each
corresponding to a lookup service with which the service is
currently registeredServiceRegistrar
public net.jini.core.entry.Entry[] getAttributes()
Entry
consisting of the
set of attributes with which the service is registered in
each lookup service that it has joinedEntry
,
setAttributes(net.jini.core.entry.Entry[])
public void addAttributes(net.jini.core.entry.Entry[] attrSets)
An invocation of this method with duplicate elements in the
attrSets
parameter (where duplication means attribute
equality as defined by calling the MarshalledObject.equals
method on field values) is equivalent to performing the invocation
with the duplicates removed from that parameter.
Note that because there is no guarantee that attribute propagation
will have completed upon return from this method, services that
invoke this method must take care not to modify the contents of the
attrSets
parameter. Doing so could cause the service's
attribute state to be corrupted or inconsistent on a subset of the
lookup services with which the service is registered as compared with
the state reflected on the remaining lookup services. It is for this
reason that the effects of modifying the contents of the
attrSets
parameter, after this method is invoked, are
undefined.
attrSets
- array of Entry
consisting of the
attribute sets with which to augment the service's
current set of attributesjava.lang.NullPointerException
- this exception occurs when
either null
is input to the attrSets
parameter, or one or more of the elements of the
attrSets
parameter is null
.Entry
public void addAttributes(net.jini.core.entry.Entry[] attrSets, boolean checkSC)
An invocation of this method with duplicate elements in the
attrSets
parameter (where duplication means attribute
equality as defined by calling the MarshalledObject.equals
method on field values) is equivalent to performing the invocation
with the duplicates removed from that parameter.
Note that because there is no guarantee that attribute propagation
will have completed upon return from this method, services that
invoke this method must take care not to modify the contents of the
attrSets
parameter. Doing so could cause the service's
attribute state to be corrupted or inconsistent on a subset of the
lookup services with which the service is registered as compared with
the state reflected on the remaining lookup services. It is for this
reason that the effects of modifying the contents of the
attrSets
parameter, after this method is invoked, are
undefined.
A service typically employs this version of addAttributes
to prevent clients or other services from attempting to add what are
referred to as "service controlled attributes" to the service's set.
A service controlled attribute is an attribute that implements the
ServiceControlled
marker interface.
Consider a printer service. With printers, there are often times error
conditions, that only the printer can detect (for example, a paper
jam or a toner low condition). To report conditions such as these to
interested parties, the printer typically adds an attribute to its
attribute set, resulting in an event being sent that notifies clients
that have registered interest in such events. When the condition is
corrected, the printer would then remove the attribute from its set
by invoking the modifyAttributes
method in the appropriate
manner.
Attributes representing conditions that only the service can know about
or control are good candidates for being defined as service controlled
attributes. That is, the service provider (the developer of the printer
service for example) would define the attributes that represent
conditions such as those just described to implement the
ServiceControlled
marker interface. Thus, when other
entities attempt to add new attributes, services that wish to employ
such service controlled attributes should ultimately invoke only this
version of addAttributes
(with the checkSC
parameter set to true
), resulting in a
SecurityException
if any of the attributes being added
happen to be service controlled attributes. In this way, only the
printer itself would be able to set a "paper jammed" or "toner low"
attribute, not some arbitrary client.
attrSets
- array of Entry
consisting of the
attribute sets with which to augment the service's
current set of attributescheckSC
- boolean
flag indicating whether the
elements of the set of attributes to add should be
checked to determine if they are service controlled
attributesjava.lang.NullPointerException
- this exception occurs when
either null
is input to the attrSets
parameter, or one or more of the elements of the
attrSets
parameter is null
.java.lang.SecurityException
- this exception occurs when
the checkSC
parameter is true
, and
at least one of the attributes to be added is an instance
of the ServiceControlled
marker interface.Entry
,
net.jini.lookup.entry.ServiceControlled
public void setAttributes(net.jini.core.entry.Entry[] attrSets)
An invocation of this method with duplicate elements in the
attrSets
parameter (where duplication means attribute
equality as defined by calling the MarshalledObject.equals
method on field values) is equivalent to performing the invocation
with the duplicates removed from that parameter.
Note that because there is no guarantee that attribute propagation
will have completed upon return from this method, services that
invoke this method must take care not to modify the contents of the
attrSets
parameter. Doing so could cause the service's
attribute state to be corrupted or inconsistent on a subset of the
lookup services with which the service is registered as compared with
the state reflected on the remaining lookup services. It is for this
reason that the effects of modifying the contents of the
attrSets
parameter, after this method is invoked, are
undefined.
attrSets
- array of Entry
consisting of the
attribute sets with which to replace the service's
current set of attributesjava.lang.NullPointerException
- this exception occurs when
at least one of the elements of the attrSets
parameter is null
.Entry
,
getAttributes()
public void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates, net.jini.core.entry.Entry[] attrSets)
modifyAttributes
method of the
ServiceRegistration
class.
The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.
Note that if the length of the array containing the templates does
not equal the length of the array containing the modifications, an
IllegalArgumentException
will be thrown and propagated
through this method.
Note also that because there is no guarantee that attribute propagation
will have completed upon return from this method, services that
invoke this method must take care not to modify the contents of the
attrSets
parameter. Doing so could cause the service's
attribute state to be corrupted or inconsistent on a subset of the
lookup services with which the service is registered as compared with
the state reflected on the remaining lookup services. It is for this
reason that the effects of modifying the contents of the
attrSets
parameter, after this method is invoked, are
undefined.
attrSetTemplates
- array of Entry
used to identify
which elements to modify from the service's
current set of attributesattrSets
- array of Entry
containing the
actual modifications to make in the matching
sets found using the
attrSetTemplates
parameterjava.lang.IllegalArgumentException
- this exception occurs when
the array containing the templates does not equal the length
of the array containing the modifications.Entry
,
net.jini.core.lookup.ServiceRegistration#modifyAttributes
public void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates, net.jini.core.entry.Entry[] attrSets, boolean checkSC)
modifyAttributes
method of the
ServiceRegistration
class.
The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.
Note that if the length of the array containing the templates does
not equal the length of the array containing the modifications, an
IllegalArgumentException
will be thrown and propagated
through this method.
Note also that because there is no guarantee that attribute propagation
will have completed upon return from this method, services that
invoke this method must take care not to modify the contents of the
attrSets
parameter. Doing so could cause the service's
attribute state to be corrupted or inconsistent on a subset of the
lookup services with which the service is registered as compared with
the state reflected on the remaining lookup services. It is for this
reason that the effects of modifying the contents of the
attrSets
parameter, after this method is invoked, are
undefined.
A service typically employs this version of
modifyAttributes
to prevent clients or other services
from attempting to modify what are referred to as "service controlled
attributes" in the service's set. A service controlled attribute is an
attribute that implements the ServiceControlled
marker
interface.
Attributes representing conditions that only the service can know about
or control are good candidates for being defined as service controlled
attributes. When other entities attempt to modify a service's
attributes, if the service wishes to employ such service controlled
attributes, the service should ultimately invoke only this version
of modifyAttributes
(with the checkSC
parameter set to true
), resulting in a
SecurityException
if any of the attributes being modified
happen to be service controlled attributes.
attrSetTemplates
- array of Entry
used to identify
which elements to modify from the service's
current set of attributesattrSets
- array of Entry
containing the
actual modifications to make in the matching
sets found using the
attrSetTemplates
parametercheckSC
- boolean
flag indicating whether the
elements of the set of attributes to modify
should be checked to determine if they are
service controlled attributesjava.lang.IllegalArgumentException
- this exception occurs when
the array containing the templates does not equal the length
of the array containing the modifications.java.lang.SecurityException
- this exception occurs when
the checkSC
parameter is true
, and
at least one of the attributes to be modified is an instance
of the ServiceControlled
marker interface.Entry
,
net.jini.core.lookup.ServiceRegistration#modifyAttributes
,
net.jini.lookup.entry.ServiceControlled
public void terminate()
JoinManager
. This
method will cancel all of the service's managed leases that were
granted by the lookup services with which the service is registered,
and will terminate all threads that have been created.
Note that if the discovery manager employed by the instance of this class that is being terminated was created by the instance itself, this method will terminate all discovery processing being performed by that manager object on behalf of the service; otherwise, the discovery manager supplied by the service is still valid.
Whether an instance of the LeaseRenewalManager
class was
supplied by the service or created by the JoinManager
itself, any reference to that object obtained by the service prior to
termination will still be valid after termination.
Note also this class makes certain concurrency guarantees with respect
to an invocation of the terminate method while other method invocations
are in progress. The termination process will not begin until
completion of all invocations of the methods defined in the public
interface of this class. Furthermore, once the termination process has
begun, no further remote method invocations will be made by this class,
and all other method invocations made on this class will not return
until the termination process has completed.
Upon completion of the termination process, the semantics of all
current and future method invocations on the instance of this class
that was just terminated are undefined; although the reference to the
LeaseRenewalManager
object employed by that instance
of JoinManager
is still valid.
private void createTaskThread(JoinManager.Task t)
private void addJoinSet(JoinManager.ProxyReg reg)
private void removeJoinSet(JoinManager.ProxyReg reg)
private void discoveredNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies)
private void discardedNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies)
private void notifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies, boolean bDiscovered)
JoinManager.ProxyReg findReg(net.jini.core.lookup.ServiceRegistrar proxy)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |