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, 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_DISABLED, 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
 Service getInterface()
          Service objects are not manipulated directly to protect usage of the service.
 Iterator getRoleMap(ID name)
          Returns the map of the assigned IDs currently associated with the given ModuleClassID by this PeerGroup object.
 PeerGroup getWeakInterface()
          Returns a weak interface object that represents this group.
 Service lookupService(ID name)
          Lookup for a service by name.
 Service lookupService(ID name, int roleIndex)
          Lookup for a service by class ID and index in a map.
 int startApp(String[] arg)
          Complete any remaining initialization of the module.
 void stopApp()
          Stop a module.
 void unref()
          Can only be called once.
 
Methods inherited from class net.jxta.impl.peergroup.PeerGroupInterface
compatible, equals, getAccessService, getAllPurposePeerGroupImplAdvertisement, getConfigAdvertisement, getDiscoveryService, getEndpointService, getHomeThreadGroup, getImplAdvertisement, getLoader, getMembershipService, getParentGroup, getPeerAdvertisement, getPeerGroupAdvertisement, getPeerGroupID, getPeerGroupName, getPeerID, getPeerInfoService, getPeerName, getPipeService, getRendezVousService, getResolverService, getStoreHome, init, isRendezvous, loadModule, loadModule, newGroup, newGroup, newGroup, publishGroup, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RefCountPeerGroupInterface

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

Parameters:
theRealThing - the peer group

RefCountPeerGroupInterface

RefCountPeerGroupInterface(GenericPeerGroup theRealThing,
                           Map roleMap)
Method Detail

startApp

public int startApp(String[] arg)
Complete any remaining initialization of the module. The module should be fully functional after startApp() is completed. That is also the opportunity to supply arbitrary arguments (mostly to applications).

If this module is a PeerGroup service, it may be invoked several times depending on its return value.

This is here for class hierarchy reasons. It is normaly ignored. By definition, the interface object protects the real object's start/stop methods from being called.

Normally 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()
Stop a module. This may be called any time after init() completes and should not assume that startApp() has been called or completed.

The Module cannot be forced to comply, but in the future we might be able to deny it access to anything after some timeout.

This is here for class hierarchy reasons. It is normaly ignored. By definition, the interface object protects the real object's start/stop methods from being called.

This is here for temporary class hierarchy reasons. it is normally 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()
Service objects are not manipulated directly to protect usage of the service. A Service interface is returned to access the service methods.

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 represents this group.

A weak interface object has no life-cycle privileges over the group that it represents and therefore its users have no accountability. A weak interface object is safe to give away but holds no promise of sustained validity.

Whatever code gave away a weak interface object retains the power of terminating the group object from which it was obtained, thereby making the weak interface object invalid.

A weak interface object is immutable; its unref and stopApp methods do nothing. Its validity is exactly that of the group or interface object from which it was obtained.

A weak interface object can be obtained from an interface object, or from a real group object, or from a weak interface object. In the later case, the object returned may be the original weak interface object since such objects are immutable.

Whatever code obtains a weak interface object from a group object or regular interface object, remains entirely liable for invoking unref on the initial object before discarding it. Giving away a weak interface object is not equivalent to transferring ownership of the original.

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.

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
Lookup for a service by name.

Specified by:
lookupService in interface PeerGroup
Overrides:
lookupService in class PeerGroupInterface
Parameters:
name - the service identifier.
Returns:
Service, the Service registered by that name
Throws:
ServiceNotFoundException - could not find the service requested

lookupService

public Service lookupService(ID name,
                             int roleIndex)
                      throws ServiceNotFoundException
Lookup for a service by class ID and index in a map.

More than one service in a group may be of a given ModuleClass. However each of them has a unique assigned ID which serves as the index in the map of services. In most cases, there is only one service of each given Module Class, and the ID of that Module Class is the assigned ID. Otherwise, the group may have a list of existing assigned ID per base class. This routine may be used to retrieve services of the given Module Class and index in that list. In the absence of a mapping, index 0 is still valid and corresponds to the service which assigned ID is exactly the given ID. Group objects with a map are normally wrappers tailored specially by the loader of a module (often the group itself) in order to provide a map appropriate for that module. Modules that do not use more than one service of a given base class normally never need to call this method; lookupService(ID) is equivalent to lookupService(ID, 0) and will transparently remap index 0 to whatever the group's structure defines as the default for the invoking service.

Note: traditionally, the given ID is expected to be a base Module Class ID, and the assigned ID of a Module is a Class ID of the same base class with a role suffix to make it unique. If the given ID already contains a role suffix, there may exist an entry for it in the map anyway, if not (which is the expected use pattern), then only index 0 exists and the given ID is used whole and untranslated.

Specified by:
lookupService in interface PeerGroup
Overrides:
lookupService in class PeerGroupInterface
Parameters:
name - the service identifier
roleIndex - the index in the list of assigned IDs that match that identifier.
Returns:
Service, the corresponding Service
Throws:
ServiceNotFoundException - Could not find the service requested.

getRoleMap

public Iterator getRoleMap(ID name)
Returns the map of the assigned IDs currently associated with the given ModuleClassID by this PeerGroup object. The IDs are returned in the order of their index in the map. So the first ID returned will be identical to what would be returned by the lookup method for the given ID and index 0. If there is no explicit such map, this method will return a singleton containing the given ID as this is the default mapping. There is no guarantee that any of the returned IDs correspond to an actually registered service. This method only maps IDs.

Specified by:
getRoleMap in interface PeerGroup
Overrides:
getRoleMap in class PeerGroupInterface
Parameters:
name - The ModuleClassID for which the map is desired.
Returns:
Iterator An iterator on a collection of the IDs to which the given ID maps.

JXSE