net.jini.discovery
Class LookupDiscoveryManager.ProxyReg

java.lang.Object
  extended by net.jini.discovery.LookupDiscoveryManager.ProxyReg
Enclosing class:
LookupDiscoveryManager

private final class LookupDiscoveryManager.ProxyReg
extends Object

Wrapper class in which each instance corresponds to a lookup service that has been discovered via either group discovery, locator discovery, or both. Note that each element of the set of discovered registrars managed by this LookupDiscoveryManager (referred to as the "managed set of registrars" or simply, the "managed set"), is actually an instance of this class.


Field Summary
private  boolean bDiscarded
          Indicates whether the registrar referenced by this class is currently in the process of being discarded.
 boolean commDiscard
          Special-purpose flag used in the discard process.
private  int from
          Integer restricted to the values 0, 1, 2, and 3.
 String[] memberGroups
          The groups to which the discovered registrar belongs
 ServiceRegistrar proxy
          The discovered registrar to be managed
 
Constructor Summary
LookupDiscoveryManager.ProxyReg(ServiceRegistrar proxy, String[] memberGroups, int from)
          Constructs an instance of this wrapper class.
 
Method Summary
 void addFrom(int from)
          Sets the appropriate bit in the 'from' variable to indicate the mechanism or mechanisms through which the registrar referenced by this class was discovered (group discovery, locator discovery, or both).
 void discard()
          Discards the registrar referenced in this class from either the LookupDiscovery or LookupLocatorDiscovery utility employed by this LookupDiscoveryManager.
 boolean equals(Object obj)
           
 int getFrom()
          Accessor method that returns the value of the 'from' variable.
 String[] getMemberGroups()
          Accessor method that returns the String array containing the names of the groups to which the registrar referenced in this class belongs.
 int hashCode()
           
 boolean isDiscarded()
          Accessor method that returns the value of the boolean variable bDiscarded.
 boolean removeFrom(int from)
          Un-sets the appropriate bit in the 'from' variable to remove the indication that the registrar referenced by this class was discovered via the mechanism identified by the input parameter.
 void setMemberGroups(String[] newMemberGroups)
          Modifier method that changes the set of member groups - stored in this class and associated with the registrar referenced in this class - to the given set of member groups.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

proxy

public ServiceRegistrar proxy
The discovered registrar to be managed


memberGroups

public String[] memberGroups
The groups to which the discovered registrar belongs


commDiscard

public boolean commDiscard
Special-purpose flag used in the discard process. This flag is only relevant to LocatorDiscoveryListener.discarded. This flag is set to true only when the method LookupDiscoveryManager.discard is called by the client. A true value for this flag indicates to LocatorDiscoveryListener.discarded that the registrar referenced by a given discarded event was discarded because the registrar was determined to be unreachable (a "communication discard"). A false value for this flag indicates to LocatorDiscoveryListener.discarded that the registrar was discarded due to lost interest in the registrar's locator (a "no-interest discard"). This flag is necessary because the locators of the discovered registrars are not retrieved and stored with the registrars and their member groups. The locators are not retrieved because to do so would require a remote call which is viewed as undesirable here since such a call cannot be guaranteed to complete in a timely fashion. Without the locator of the discarded registrar, the LocatorDiscoveryListener.discarded method cannot determine if the discarded event received from the LookupLocatorDiscovery is a communication discard or a no-interest discard. It is important for that method to be able to make such a determination because the action taken by that discarded method is dependent on that determination. For more information, refer to the API documentation (generated by the javadoc tool) of the LocatorDiscoveryListener.discarded method. Note that the mechanism that uses this flag assumes that neither the LookupDiscovery utility nor the LookupLocatorDiscovery utility employed by this LookupDiscoveryManager are accessible outside of this LookupDiscoveryManager. If either were accessible, then there would be no way to guarantee that a value of true in this flag is equivalent to a communication discard.


from

private int from
Integer restricted to the values 0, 1, 2, and 3. Each value represents a bit (or set of bits) that, when set, indicates the mechanism (group discovery, locator discovery, or both) through which the registrar referenced by the current instance of this class (proxy) has currently been (or not been) discovered. That is, if from = 0 (no bits set) ==> discovered by neither group nor locator = 1 (bit 0 set) ==> discovered by only group discovery = 2 (bit 1 set) ==> discovered by only locator discovery = 3 (bits 1&2 set) ==> discovered by both group and locator


bDiscarded

private boolean bDiscarded
Indicates whether the registrar referenced by this class is currently in the process of being discarded. This flag is used to prevent access, or inadvertent modifications to, the discovered state of registrars that are in the process of being discarded, but which have not yet been removed from the managed set.

Constructor Detail

LookupDiscoveryManager.ProxyReg

public LookupDiscoveryManager.ProxyReg(ServiceRegistrar proxy,
                                       String[] memberGroups,
                                       int from)
Constructs an instance of this wrapper class.

Parameters:
proxy - reference to a registrar that has been newly discovered or re-discovered
memberGroups - the groups to which the discovered registrar belongs
from - indicates the mechanism by which the registrar was discovered (group or locator discovery). The only values which are valid for this parameter are FROM_GROUP or FROM_LOCATOR.
Method Detail

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

addFrom

public void addFrom(int from)
Sets the appropriate bit in the 'from' variable to indicate the mechanism or mechanisms through which the registrar referenced by this class was discovered (group discovery, locator discovery, or both). This method is typically called during the discovery process; and the value input should always be either FROM_GROUP or FROM_LOCATOR.


removeFrom

public boolean removeFrom(int from)
Un-sets the appropriate bit in the 'from' variable to remove the indication that the registrar referenced by this class was discovered via the mechanism identified by the input parameter. If, after un-setting the appropriate bit, the 'from' variable is equal to 0 (indicating the registrar was previously discovered by neither group nor locator discovery), this method returns true; otherwise it returns false, which indicates that the registrar was still discovered by the "opposite" mechanism from that identified by the input parameter. This method is typically called during the discard process; and the value input should always be either FROM_GROUP or FROM_LOCATOR.


getFrom

public int getFrom()
Accessor method that returns the value of the 'from' variable. The value returned indicates the mechanism or mechanisms through which the registrar referenced by this class was previously discovered (group discovery, locator discovery, or both).

Returns:
int representing either group discovery (1), or locator discovery (2), or both (3).

discard

public void discard()
Discards the registrar referenced in this class from either the LookupDiscovery or LookupLocatorDiscovery utility employed by this LookupDiscoveryManager. The utility from which that registrar is discarded is dependent on whether the registrar was previously discovered via group or both group and locator discovery, or via locator discovery alone. This method enables a mechanism for sequentially "chaining" the discard process of the LookupDiscovery utility with the discard process of the LookupLocatorDiscovery. That is, rather than discarding the registrar from both utilities at the same time, by invoking this method, the registrar will be discarded from only one of those utilities. Then when the discarded event is received by the listener registered with the utility from which the registrar was discarded, the listener - based on the current discovered state of the registrar - determines whether to: discard the registrar from the other utility, send a discarded event out to the client's listener, or simply update state and do nothing more. This chaining mechanism helps to present a single event source to the client listeners. That is, even though the two discovery utilities used internally by this LookupDiscoveryManager operate independently, sending discarded events to the group discovery listener and/or the locator discovery listener, this chaining mechanism enables the coordination of those separate events so that only one event is sent to the client listeners, even though multiple events may have been received here. Although this chaining mechanism is helpful in coordinating the discarded events received from the LookupDiscovery and LookupLocatorDiscovery utilities, the actual reason it must be used is due to the fact that LookupDiscovery can send a certain type of discarded event - referred to as "passive communication discard"; whereas LookupLocatorDiscovery cannot. Recall that LookupDiscovery monitors the registrars it has discovered for reachability, whereas LookupLocatorDiscovery does not. When the LookupDiscovery sends a passive communication discard because it has determined that one of its registrars has become unreachable, if that registrar was also discovered via locator discovery, it is necessary to discard the registrar from the LookupLocatorDiscovery as well. In that case, this method is called to create a discard chain which ultimately will result in the registrar being discarded from the LookupLocatorDiscovery.


isDiscarded

public boolean isDiscarded()
Accessor method that returns the value of the boolean variable bDiscarded.


getMemberGroups

public String[] getMemberGroups()
Accessor method that returns the String array containing the names of the groups to which the registrar referenced in this class belongs.


setMemberGroups

public void setMemberGroups(String[] newMemberGroups)
Modifier method that changes the set of member groups - stored in this class and associated with the registrar referenced in this class - to the given set of member groups.



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.