Project JXTA

net.jxta.impl.peergroup
Class RefCountPeerGroupInterface

java.lang.Object
  extended by net.jxta.impl.peergroup.PeerGroupInterface
      extended by net.jxta.impl.peergroup.RefCountPeerGroupInterface
All Implemented Interfaces:
PeerGroup, Module, Service

 class RefCountPeerGroupInterface
extends PeerGroupInterface

RefCountPeerGroupInterface is a PeerGroupInterface object that also serves as a peergroup very-strong reference. When the last such goes away, the peergroup terminates itself despite the existence of aeternal strong references from the various service's threads that would prevent it from ever being finalized. The alternative: to give only weak references to threads seems impractical.


Nested Class Summary
 
Nested classes/interfaces inherited from interface net.jxta.peergroup.PeerGroup
PeerGroup.GlobalRegistry
 
Field Summary
 
Fields inherited from class net.jxta.impl.peergroup.PeerGroupInterface
groupImpl
 
Fields inherited from interface net.jxta.peergroup.PeerGroup
accessClassID, allPurposePeerGroupSpecID, applicationClassID, Both, DEFAULT_EXPIRATION, DEFAULT_LIFETIME, discoveryClassID, endpointClassID, FromParent, globalRegistry, Here, httpProtoClassID, membershipClassID, peerGroupClassID, peerinfoClassID, pipeClassID, proxyClassID, refAccessSpecID, refDiscoverySpecID, refEndpointSpecID, refHttpProtoSpecID, refMembershipSpecID, refNetPeerGroupSpecID, refPeerinfoSpecID, refPipeSpecID, refPlatformSpecID, refProxySpecID, refRelayProtoSpecID, refRendezvousSpecID, refResolverSpecID, refRouterProtoSpecID, refShellSpecID, refStartNetPeerGroupSpecID, refTcpProtoSpecID, refTlsProtoSpecID, relayProtoClassID, rendezvousClassID, resolverClassID, routerProtoClassID, tcpProtoClassID, tlsProtoClassID, WK_ID_PREFIX
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_OK
 
Constructor Summary
RefCountPeerGroupInterface(GenericPeerGroup theRealThing)
          Constructs an interface object that front-ends a given PeerGroup object.
RefCountPeerGroupInterface(GenericPeerGroup theRealThing, Map roleMap)
           
 
Method Summary
 void finalize()
          stopApp used to be the standard way of giving up on a group instance, but now that goup instance can be shared, the standard of letting go of a peer group is to stop referencing it.
 Service getInterface()
          

Since THIS is already such an object, it could return itself.

 Iterator getRoleMap(ID name)
          
 PeerGroup getWeakInterface()
           Returns a weak interface object that refers to this interface object rather than to the group directly.
 Service lookupService(ID name)
          
 Service lookupService(ID name, int roleIndex)
          
 int startApp(String[] arg)
          Normaly it is ignored.
 void stopApp()
          This is here for temporary class hierarchy reasons.
 void unref()
          Can only be called once.
 
Methods inherited from class net.jxta.impl.peergroup.PeerGroupInterface
compatible, getAccessService, getAllPurposePeerGroupImplAdvertisement, getConfigAdvertisement, getDiscoveryService, getEndpointService, getHomeThreadGroup, getImplAdvertisement, getLoader, getMembershipService, getParentGroup, getPeerAdvertisement, getPeerGroupAdvertisement, getPeerGroupID, getPeerGroupName, getPeerID, getPeerInfoService, getPeerName, getPipeService, getRendezVousService, getResolverService, init, isRendezvous, loadModule, loadModule, newGroup, newGroup, newGroup, publishGroup
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RefCountPeerGroupInterface

RefCountPeerGroupInterface(GenericPeerGroup theRealThing)
Constructs an interface object that front-ends a given PeerGroup object.


RefCountPeerGroupInterface

RefCountPeerGroupInterface(GenericPeerGroup theRealThing,
                           Map roleMap)
Method Detail

startApp

public int startApp(String[] arg)
Normaly it is ignored. By definition, the interface object protects the real object's start/stop methods from being called However we have to make an exception for groups: even the creator of a group does not have access to the real object. So the interface has to forward startApp to the group, which is responsible for ensuring that it is executed only once (if needed).

Specified by:
startApp in interface Module
Overrides:
startApp in class PeerGroupInterface
Parameters:
arg - A table of strings arguments.
Returns:
int status indication.

stopApp

public void stopApp()
This is here for temporary class hierarchy reasons. it is normaly ignored. By definition, the interface object protects the real object's start/stop methods from being called In that case we have to make an exception. Most applications currently assume that they do not share the group object and that they do refer to the real object directly. They call stopApp to signify their intention of no-longer using the group. Now that groups are shared, we convert stopApp to unref for compatibility. We could also just do nothing and let the interface be GC'd but calling unref makes the group go away immediately if not shared, which is what applications that call stopApp expect.

Specified by:
stopApp in interface Module
Overrides:
stopApp in class PeerGroupInterface

getInterface

public Service getInterface()

Since THIS is already such an object, it could return itself. However, we want the group to know about the number of interfaces objects floating around, so, we'll have the group make a new one. That way, applications which want to use unref() on interfaces can avoid sharing interface objects by using getInterface() as a sort of clone with the additional ref-counting semantics.

Specified by:
getInterface in interface Service
Overrides:
getInterface in class PeerGroupInterface
Returns:
Service An interface object that implements this service and nothing more.

getWeakInterface

public PeerGroup getWeakInterface()
Returns a weak interface object that refers to this interface object rather than to the group directly. The reason for that is that we want the owner of this interface object to be able to invalidate all weak interface objects made out of this interface object, without them keeping a reference to the group object, and without necessarily having to terminate the group.

Specified by:
getWeakInterface in interface PeerGroup
Overrides:
getWeakInterface in class PeerGroupInterface
Returns:
PeerGroup A weak interface object that implements this group and nothing more.

finalize

public void finalize()
stopApp used to be the standard way of giving up on a group instance, but now that goup instance can be shared, the standard of letting go of a peer group is to stop referencing it. Since the peergroup has permanent referers: the threads of the services we need to use the interface object as a super-strong reference. When an interface is finalized, it calls the group's unref method. The unref method stopApps the group when the last reference is gone. To accelerate the un-referencing of groups, applications may call the interface's unref method, but that takes some dicipline since the interface object becomes unusable after that. So, aware applications that use it must also take care of always cloning the interface object instead of sharing it. For compatibility with current apps which call stopApp, we have the interface's stopApp() do nothing as with all other interface objects. An invoker that has a reference to the true group object can still call its stopApp method with the usual result.

Overrides:
finalize in class Object

unref

public void unref()
Can only be called once. After that the reference is no-longer usuable.

Specified by:
unref in interface PeerGroup
Overrides:
unref in class PeerGroupInterface

lookupService

public Service lookupService(ID name)
                      throws ServiceNotFoundException

Specified by:
lookupService in interface PeerGroup
Overrides:
lookupService in class PeerGroupInterface
Throws:
ServiceNotFoundException

lookupService

public Service lookupService(ID name,
                             int roleIndex)
                      throws ServiceNotFoundException

Specified by:
lookupService in interface PeerGroup
Overrides:
lookupService in class PeerGroupInterface
Throws:
ServiceNotFoundException

getRoleMap

public Iterator getRoleMap(ID name)

Specified by:
getRoleMap in interface PeerGroup
Overrides:
getRoleMap in class PeerGroupInterface

JXTA J2SE