|
Project JXTA | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.jxta.peergroup.LightWeightPeerGroup
LightWeightPeerGroup is a class intended to help building PeerGroup that can inherit one or more services from a parent PeerGroup. An LightWeightPeerGroup implements PeerGroup and is to be used like a PeerGroup by applications. This class is intended to be extended/implemented. Note: unlike implementations of peer groups that existed until JXTA 2.2, LightweightPeergroup permits to implement groups that borrow all or part of their services to a parent group. One needs to remember that peers in various such subgroups of a given parent groups may implicitly all share the same services if that is what the PeerGroup implementing LightWeightPeerGroup is doing. Please refer to the documentation of PeerGroups extending LightWeigthPeerGroup do understand which services are shared, and which are not.
Nested Class Summary |
Nested classes inherited from class net.jxta.peergroup.PeerGroup |
PeerGroup.GlobalRegistry |
Field Summary |
Fields inherited from interface net.jxta.platform.Module |
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_OK |
Constructor Summary | |
LightWeightPeerGroup(PeerGroupAdvertisement adv)
Constructor All classes that extend this class must invoke this constructor. |
Method Summary | |
boolean |
compatible(Element compat)
Return true if the provided compatibility statement is compatible with this group. |
AccessService |
getAccessService()
Return the Access Service for this Peer Group. This service is present in every Peer Group. |
ModuleImplAdvertisement |
getAllPurposePeerGroupImplAdvertisement()
Get an all purpose peerGroup ModuleImplAdvertisement that is compatible with this group. This impl adv can be used to create any group that relies only on the standard services. Or to derive other impl advs, using this impl advertisement as a basis. |
ConfigParams |
getConfigAdvertisement()
Returns the config advertisment for this peer in this group (if any). |
DiscoveryService |
getDiscoveryService()
Return the Discovery Service for this Peer Group. |
EndpointService |
getEndpointService()
Return the Endpoint Service for this Peer Group. This service is present in every Peer Group. |
ThreadGroup |
getHomeThreadGroup()
Returns the Thread Group in which threads for this peer group will live. This is currently used only for debugging purposes so that the source of a thread can be determined. |
Advertisement |
getImplAdvertisement()
Returns the advertisment for this service. |
Service |
getInterface()
Service objects are not manipulated directly to protect usage of the service. A Service interface is returned to access the service methods. |
JxtaLoader |
getLoader()
Returns the class loader for this group. |
MembershipService |
getMembershipService()
Return the Membership Service for this Peer Group. This service is present in every Peer Group. |
PeerGroup |
getParentGroup()
Returns the parent group of this group. Not all groups have parents and some implementations may not reveal their parents. |
PeerAdvertisement |
getPeerAdvertisement()
Return the PeerAdvertisement of the local Peer within this Peer Group. |
PeerGroupAdvertisement |
getPeerGroupAdvertisement()
Return the PeerGroupAdvertisement for this group. |
PeerGroupID |
getPeerGroupID()
Return the Peer Group ID of this Peer Group. |
String |
getPeerGroupName()
Return the Name of this group. This name is not canonical, meaning that there may be other groups with the same name. |
PeerID |
getPeerID()
Return the Peer ID by which this Peer is known within this Peer Group. |
PeerInfoService |
getPeerInfoService()
Return the PeerInfo Service for this Peer Group. |
String |
getPeerName()
Return the name of the local peer within this group. This name is not canonical, meaning that there may be other peers with the same name. |
PipeService |
getPipeService()
Return the Pipe Service for this Peer Group. |
RendezVousService |
getRendezVousService()
Return the Rendezvous Service for this Peer Group. This service is optional and may not be present in all groups. |
ResolverService |
getResolverService()
Return the Resolver Service for this Peer Group. This service is present in every Peer Group. |
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. |
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 transfering ownerhsip of the original. |
void |
init(PeerGroup group,
ID assignedID,
Advertisement implAdv)
Initialize the module, passing it its peer group and advertisement. Note: when subclassing one of the existing PeerGroup implementations (which implement Module), it may not be recommended to overload the init method. See the documentation of the PeerGroup class being subclassed. |
boolean |
isRendezvous()
Returns the whether the group member is a Rendezvous peer for the group. |
Module |
loadModule(ID assignedID,
Advertisement impl)
Load a module from a ModuleImplAdv. Compatibility is checked and load is attempted. If compatible and loaded successfuly, the resulting Module is initialized and returned. In most cases the other loadModule() method should be preferred, since unlike this one, it will seek many compatible implementation advertisements and try them all until one works. The home group of the new module (its parent group if the new module is a group) will be this group. |
Module |
loadModule(ID assignedID,
ModuleSpecID specID,
int where)
Load a module from a spec id. Advertisement is sought, compatibility is checked on all candidates and load is attempted. The first one that is compatible and loads successfuly is initialized and returned. |
Service |
lookupService(ID name)
Lookup for a service by name. |
Service |
lookupService(ID name,
int ignoredForNow)
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 normaly wrappers taylored 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: traditionaly, 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. |
PeerGroup |
newGroup(Advertisement pgAdv)
Instantiate a peer group from its given advertisement. This instantiator requires that the ModuleImplAdvertisment for the peer group and the ModuleImplAdvertisements for the group's services be available for discovery within the current group. The pgAdv itself may be all new and unpublished. Therefore, the two typical uses of this routine are:
PeerGroup.newGroup(PeerGroupID,Advertisement,String,String) |
PeerGroup |
newGroup(PeerGroupID gid)
Instantiate a group from its Peer Group ID only. Use this when using a group that has already been published and discovered. The typical uses of this routine are therefore:
PeerGroup.loadModule(ID,Advertisement) or even:
grp = new GroupSubClass();
grp.init(parentGroup, gid, impladv);
then, REMEMBER TO PUBLISH THE GROUP IF IT IS ALL NEW. |
PeerGroup |
newGroup(PeerGroupID gid,
Advertisement impl,
String name,
String description)
Instantiates a new group from its elementary pieces and publishes the corresponding PeerGroupAdvertisement. The pieces are: the groups implementation adv, the group id, the name and description. The typical use of this routine is creating a whole new group based on a newly created and possibly unpublished implementation adv. This is a convenience method equivalent to either: newGrp = thisGroup.loadModule(gid, impl); newGrp.publishGroup(name, description);or, but only if the implementation advertisement has been published: newPGAdv = AdvertisementFactory.newAdvertisement( PeerGroupAdvertisement.getAdvertisementType()); newPGAdv.setPeerGroupID(gid); newPGAdv.setModuleSpecID(impl.getModuleSpecID()); newPGAdv.setName(name); newPGAdv.setDescription(description); newGrp = thisGroup.newGroup(newPGAdv); |
void |
publishGroup(String name,
String description)
Publish this group's Peer Group Advertisment if it has not already been published. The Peer Group Advertisement is published into the Peer Group in which this group was instantiated, specifically the Peer Group whose newGroup() was called.
Calling this method is only useful if the group is being created
from scratch and the PeerGroup advertisement has not been
created beforehand. In such a case, the group has never been named or
described. Therefore this information has to be supplied here.
If this group has already been previously published, this method does
nothing. |
int |
startApp(String[] args)
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. |
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. |
void |
unref()
Explicitly notifies a group interface that it will no-longer be used (similar to dispose). Does nothing to a real group object, only has an effect on a group interface. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public LightWeightPeerGroup(PeerGroupAdvertisement adv)
adv
- PeerGroupAdvertisement of this LightWeightPeerGroup.
Note that only the PeerGroupID is used.Method Detail |
public void init(PeerGroup group, ID assignedID, Advertisement implAdv)
init
in interface Module
group
- The PeerGroup from which this Module can obtain services.
If this module is a Service, this is also the PeerGroup of which this
module is a service.assignedID
- Identity of Module within group.
modules can use it as a the root of their namespace to create
names that are unique within the group but predictible by the
same module on another peer. This is normaly the ModuleClassID
which is also the name under which the module is known by other
modules. For a group it is the PeerGroupID itself.
The parameters of a service, in the Peer configuration, are indexed
by the assignedID of that service, and a Service must publish its
run-time parameters in the Peer Advertisement under its assigned ID.implAdv
- The implementation advertisement for this
Module. It is permissible to pass null if no implementation
advertisement is available. This may happen if the
implementation was selected by explicit class name rather than
by following an implementation advertisement. Modules are not
required to support that style of loading, but if they do, then
their documentation should mention it.public int startApp(String[] args)
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.
startApp
in interface Module
args
- An array of Strings forming the parameters for this
Module.
Module.START_OK
, Module.START_AGAIN_PROGRESS
,
Module.START_AGAIN_STALLED
, which indicates partial or complete
success, or any other value (negative values are
recommended for future compatibility), which indicates failure.public void stopApp()
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.
stopApp
in interface Module
public Service getInterface()
getInterface
in interface Service
public Advertisement getImplAdvertisement()
getImplAdvertisement
in interface Service
public ThreadGroup getHomeThreadGroup()
getHomeThreadGroup
in interface PeerGroup
public JxtaLoader getLoader()
getLoader
in interface PeerGroup
public PeerGroup getParentGroup()
getParentGroup
in interface PeerGroup
null
if a parent group
if not available.public boolean isRendezvous()
isRendezvous
in interface PeerGroup
public PeerGroupAdvertisement getPeerGroupAdvertisement()
getPeerGroupAdvertisement
in interface PeerGroup
public PeerAdvertisement getPeerAdvertisement()
getPeerAdvertisement
in interface PeerGroup
public Service lookupService(ID name) throws ServiceNotFoundException
lookupService
in interface PeerGroup
name
- the service identifier.
ServiceNotFoundException
- could not find the service requestedpublic Service lookupService(ID name, int ignoredForNow) throws ServiceNotFoundException
lookupService
in interface PeerGroup
name
- the service identifierignoredForNow
- the index in the list of assigned IDs that match
that identifier.
ServiceNotFoundException
- Could not find the service requested.public Iterator getRoleMap(ID name)
getRoleMap
in interface PeerGroup
name
- The ModuleClassID for which the map is desired.
public boolean compatible(Element compat)
compatible
in interface PeerGroup
public Module loadModule(ID assignedID, Advertisement impl) throws ProtocolNotSupportedException, PeerGroupException
loadModule
in interface PeerGroup
assignedID
- Id to be assigned to that module (usually its ClassID).impl
- An implementation advertisement for that module.
PeerGroupException
- The module could not be loaded or initialized
ProtocolNotSupportedException
- The module is a protocol and
is disabled per the peer's configuration.public Module loadModule(ID assignedID, ModuleSpecID specID, int where)
loadModule
in interface PeerGroup
assignedID
- Id to be assigned to that module (usually its ClassID).specID
- The specID of this module.where
- May be one of: Here, FromParent, or Both, meaning that the
implementation advertisement will be searched in this group, its parent
or both. As a general guideline, the implementation advertisements of
a group should be searched in its propsective parent (that is Here), the
implementation advertisements of a group standard service should be
searched in the same group than where this group's advertisement was
found (that is, FromParent), while applications may be sought more
freely (Both).
public void publishGroup(String name, String description) throws IOException
newGroup()
was called.
Calling this method is only useful if the group is being created
from scratch and the PeerGroup advertisement has not been
created beforehand. In such a case, the group has never been named or
described. Therefore this information has to be supplied here.
If this group has already been previously published, this method does
nothing.
publishGroup
in interface PeerGroup
name
- The name of this group.description
- The description of this group.
IOException
- The publication could not be accomplished
because of a network or storage failure.public PeerGroup newGroup(Advertisement pgAdv) throws PeerGroupException
PeerGroup.newGroup(PeerGroupID,Advertisement,String,String)
newGroup
in interface PeerGroup
pgAdv
- The advertisement for the group to be instantiated.
PeerGroupException
- The group could not be instantated.public PeerGroup newGroup(PeerGroupID gid, Advertisement impl, String name, String description) throws PeerGroupException
newGrp = thisGroup.loadModule(gid, impl); newGrp.publishGroup(name, description);or, but only if the implementation advertisement has been published:
newPGAdv = AdvertisementFactory.newAdvertisement( PeerGroupAdvertisement.getAdvertisementType()); newPGAdv.setPeerGroupID(gid); newPGAdv.setModuleSpecID(impl.getModuleSpecID()); newPGAdv.setName(name); newPGAdv.setDescription(description); newGrp = thisGroup.newGroup(newPGAdv);
newGroup
in interface PeerGroup
gid
- The ID of that group. If null
then a new group ID
will be chosen.impl
- The advertisement of the implementation to be used.name
- The name of the group.description
- A description of this group.
PeerGroupException
- The group could ne be instantiated.public PeerGroup newGroup(PeerGroupID gid) throws PeerGroupException
PeerGroup.loadModule(ID,Advertisement)
or even:
grp = new GroupSubClass();
grp.init(parentGroup, gid, impladv);
then, REMEMBER TO PUBLISH THE GROUP IF IT IS ALL NEW.
newGroup
in interface PeerGroup
gid
- the groupID.
PeerGroupException
- The group could ne be instantated.public RendezVousService getRendezVousService()
getRendezVousService
in interface PeerGroup
null
if there is no Rendezvous Service in this Peer Group.public EndpointService getEndpointService()
getEndpointService
in interface PeerGroup
public ResolverService getResolverService()
getResolverService
in interface PeerGroup
public DiscoveryService getDiscoveryService()
getDiscoveryService
in interface PeerGroup
null
if there is no PeerInfo Service in this Peer Group.public PeerInfoService getPeerInfoService()
getPeerInfoService
in interface PeerGroup
null
if there is no PeerInfo Service in this Peer Group.public MembershipService getMembershipService()
getMembershipService
in interface PeerGroup
public PipeService getPipeService()
getPipeService
in interface PeerGroup
null
if
there is no Pipe Service in this Peer Group.public AccessService getAccessService()
getAccessService
in interface PeerGroup
public PeerGroupID getPeerGroupID()
getPeerGroupID
in interface PeerGroup
public PeerID getPeerID()
getPeerID
in interface PeerGroup
public String getPeerGroupName()
getPeerGroupName
in interface PeerGroup
null
if no name was
specified.public String getPeerName()
getPeerName
in interface PeerGroup
null
if no name was
specified.public ConfigParams getConfigAdvertisement()
getConfigAdvertisement
in interface PeerGroup
null
if none is available.public ModuleImplAdvertisement getAllPurposePeerGroupImplAdvertisement() throws Exception
getAllPurposePeerGroupImplAdvertisement
in interface PeerGroup
Exception
public void unref()
unref
in interface PeerGroup
public PeerGroup getWeakInterface()
getWeakInterface
in interface PeerGroup
|
JXTA J2SE | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |