net.jxta.peergroup
Interface PeerGroup

All Superinterfaces:

Module, Service

public interface PeerGroup

extends Service

Peer groups are formed as a collection of peers that have agreed upon a common set of services. Each peer group is assigned a unique peer group ID and a peer group advertisement. The peer group advertisement contains a ModuleSpecID which refers to a module specification for this peer group.

The peer group specification mandates each of the group services (membership, discovery, resolver, etc). Implementations of that specification are described by ModuleImplAdvertisements which are identified by the group's ModuleSpecID. Implementations are responsible for providing the services mandated by the specification. The java reference implementation achieves this by loading additional Modules which ModuleSpecIDs are listed by the group implementation advertisement.

In order to participate in a group, a peer needs to join the group using the peer group membership service.

JXTA comes with two subclasses of peer groups:

• Platform: this is used to represent the World group. Every peer, when booting, becomes part of this group. This group provides the minimum core services needed to find and instantiate other groups on a peer. Platform has the privilege of assigning a new ID to the peer, if it does not already have one. The World group's ID is invariant.
• StdPeergroup: this is currently used to implement all other kinds of peer groups. The first such group that is instantiated after booting is known as The Net Peer Group. When Platform starts it may optionaly search for The Net Peer Group on the local network and, if found, instantiate it. Otherwise a default configuration of The Net Peer Group is instanciated. A non-default configuration of The Net Peer Group may be set-up by the administrator in charge of the network domain inside which the peer is booting. The Net Peer Group is discovered via the DiscoveryService protocol. Many such groups may be configured by an administrator.
  StdPeergroup may also be used to implement User-defined peer groups: Users can create new peer groups which use their own set of customized services.

Since:

JXTA 1.0

Version:

$Revision: 1.41 $

See Also:

PeerGroupID, Service, PeerGroupFactory, PeerGroupAdvertisement, ModuleImplAdvertisement, ModuleSpecID, ModuleClassID

Inner Class Summary

static class	PeerGroup.GlobalRegistry
static class	PeerGroup.IdMaker An inner class used to create static well-known identifiers.

Field Summary

static ModuleSpecID	allPurposePeerGroupSpecID Well known group specification identifier: an all purpose peer group specification.
static ModuleClassID	applicationClassID Well known module class identifier: application
static int	Both Look for needed ModuleImplAdvertisement in both this group and its parent.
static long	DEFAULT_EXPIRATION Default expiration time for discovered group advertisements.
static long	DEFAULT_LIFETIME Default life time for group advertisements in the publisher's cache.
static ModuleClassID	discoveryClassID Well known module class identifier: discovery service
static ModuleClassID	endpointClassID Well known module class identifier: endpoint service
static int	FromParent Look for needed ModuleImplAdvertisement in the parent group of this group.
static PeerGroup.GlobalRegistry	globalRegistry
static int	Here Look for needed ModuleImplAdvertisement in this group.
static ModuleClassID	httpProtoClassID Well known module class identifier: http protocol
static ModuleClassID	membershipClassID Well known module class identifier: membership service
static ModuleClassID	peerGroupClassID Well known module class identifier: peer group
static ModuleClassID	peerinfoClassID Well known module class identifier: peerinfo service
static ModuleClassID	pipeClassID Well known module class identifier: pipe service
static ModuleClassID	proxyClassID Well known module class identifier: ProxyService
static ModuleSpecID	refDiscoverySpecID Well known service specification identifier: the standard discovery
static ModuleSpecID	refEndpointSpecID Well known service specification identifier: the standard endpoint
static ModuleSpecID	refHttpProtoSpecID Well known endpoint protocol specification identifier: the standard http endpoint protocol
static ModuleSpecID	refMembershipSpecID Well known service specification identifier: the standard membership
static ModuleSpecID	refNetPeerGroupSpecID Well known group specification identifier: the Network Peer Group
static ModuleSpecID	refPeerinfoSpecID Well known service specification identifier: the standard peerinfo
static ModuleSpecID	refPipeSpecID Well known service specification identifier: the standard pipe
static ModuleSpecID	refPlatformSpecID Well known group specification identifier: the platform
static ModuleSpecID	refProxySpecID Well known application: the Proxy
static ModuleSpecID	refRendezvousSpecID Well known service specification identifier: the standard rendezvous
static ModuleSpecID	refResolverSpecID Well known service specification identifier: the standard resolver
static ModuleSpecID	refRouterProtoSpecID Well known endpoint protocol specification identifier: the standard router
static ModuleSpecID	refShellSpecID Well known application: the shell
static ModuleSpecID	refStartNetPeerGroupSpecID Well known main application of the platform: startNetPeerGroup.
static ModuleSpecID	refTcpProtoSpecID Well known endpoint protocol specification identifier: the standard tcp endpoint protocol
static ModuleSpecID	refTlsProtoSpecID Well known endpoint protocol specification identifier: the standard tls endpoint protocol
static ModuleClassID	rendezvousClassID Well known module class identifier: rendezvous service
static ModuleClassID	resolverClassID Well known module class identifier: resolver service
static ModuleClassID	routerProtoClassID Well known module class identifier: router protocol
static ModuleClassID	tcpProtoClassID Well known module class identifier: tcp protocol
static ModuleClassID	tlsProtoClassID Well known module class identifier: tlsProtocol

Method Summary

boolean	compatible(Element compat) Evaluate if the given compatibility statement make the module that bears it loadable by this group.
ModuleImplAdvertisement	getAllPurposePeerGroupImplAdvertisement() Get an allPurpose peerGroup ModuleImplAdvertisement compatible with this group.
Advertisement	getConfigAdvertisement() Returns the config advertisment for this peer in this group (if any).
DiscoveryService	getDiscoveryService()
EndpointService	getEndpointService()
JxtaLoader	getLoader() Returns the loader for this group.
MembershipService	getMembershipService()
PeerAdvertisement	getPeerAdvertisement() Ask a group for its peer advertisement on this peer.
PeerGroupAdvertisement	getPeerGroupAdvertisement() Ask a group for its group advertisement
PeerGroupID	getPeerGroupID() Tell the ID of this group.
java.lang.String	getPeerGroupName() Tell the Name of this group.
PeerID	getPeerID() Tell the ID of this peer in this group.
PeerInfoService	getPeerInfoService()
java.lang.String	getPeerName() Tell the Name of this peer in this group.
PipeService	getPipeService()
RendezVousService	getRendezVousService()
ResolverService	getResolverService()
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.
Module	loadModule(ID assignedID, ModuleSpecID specID, int where) Load a module from a spec id.
Service	lookupService(ID name) Lookup for a service by name.
PeerGroup	newGroup(Advertisement pgAdv) Instantiate a group from its given advertisement Use this when a published implAdv for the groupSubclass can be discovered.
PeerGroup	newGroup(PeerGroupID gid) Instantiate a group from its groupID only.
PeerGroup	newGroup(PeerGroupID gid, Advertisement impl, java.lang.String name, java.lang.String description) Convenience method, instantiate a group from its elementary pieces and publish the corresponding PeerGroupAdvertisement.
void	publishGroup(java.lang.String name, java.lang.String description) Force publication of this group if hasn't been done already.
void	unref()

Methods inherited from interface net.jxta.service.Service

getImplAdvertisement, getInterface

Methods inherited from interface net.jxta.platform.Module

init, startApp, stopApp

Field Detail

Here

public static final int Here

Look for needed ModuleImplAdvertisement in this group.

FromParent

public static final int FromParent

Look for needed ModuleImplAdvertisement in the parent group of this group.

Both

public static final int Both

Look for needed ModuleImplAdvertisement in both this group and its parent.

DEFAULT_LIFETIME

public static final long DEFAULT_LIFETIME

Default life time for group advertisements in the publisher's cache. (a year)

DEFAULT_EXPIRATION

public static final long DEFAULT_EXPIRATION

Default expiration time for discovered group advertisements. (2 weeks)

peerGroupClassID

public static final ModuleClassID peerGroupClassID

Well known module class identifier: peer group

resolverClassID

public static final ModuleClassID resolverClassID

Well known module class identifier: resolver service

discoveryClassID

public static final ModuleClassID discoveryClassID

Well known module class identifier: discovery service

pipeClassID

public static final ModuleClassID pipeClassID

Well known module class identifier: pipe service

membershipClassID

public static final ModuleClassID membershipClassID

Well known module class identifier: membership service

rendezvousClassID

public static final ModuleClassID rendezvousClassID

Well known module class identifier: rendezvous service

peerinfoClassID

public static final ModuleClassID peerinfoClassID

Well known module class identifier: peerinfo service

endpointClassID

public static final ModuleClassID endpointClassID

Well known module class identifier: endpoint service

tcpProtoClassID

public static final ModuleClassID tcpProtoClassID

Well known module class identifier: tcp protocol

httpProtoClassID

public static final ModuleClassID httpProtoClassID

Well known module class identifier: http protocol

routerProtoClassID

public static final ModuleClassID routerProtoClassID

Well known module class identifier: router protocol

applicationClassID

public static final ModuleClassID applicationClassID

Well known module class identifier: application

tlsProtoClassID

public static final ModuleClassID tlsProtoClassID

Well known module class identifier: tlsProtocol

proxyClassID

public static final ModuleClassID proxyClassID

Well known module class identifier: ProxyService

refPlatformSpecID

public static final ModuleSpecID refPlatformSpecID

Well known group specification identifier: the platform

refNetPeerGroupSpecID

public static final ModuleSpecID refNetPeerGroupSpecID

Well known group specification identifier: the Network Peer Group

refResolverSpecID

public static final ModuleSpecID refResolverSpecID

Well known service specification identifier: the standard resolver

refDiscoverySpecID

public static final ModuleSpecID refDiscoverySpecID

Well known service specification identifier: the standard discovery

refPipeSpecID

public static final ModuleSpecID refPipeSpecID

Well known service specification identifier: the standard pipe

refMembershipSpecID

public static final ModuleSpecID refMembershipSpecID

Well known service specification identifier: the standard membership

refRendezvousSpecID

public static final ModuleSpecID refRendezvousSpecID

Well known service specification identifier: the standard rendezvous

refPeerinfoSpecID

public static final ModuleSpecID refPeerinfoSpecID

Well known service specification identifier: the standard peerinfo

refEndpointSpecID

public static final ModuleSpecID refEndpointSpecID

Well known service specification identifier: the standard endpoint

refTcpProtoSpecID

public static final ModuleSpecID refTcpProtoSpecID

Well known endpoint protocol specification identifier: the standard tcp endpoint protocol

refHttpProtoSpecID

public static final ModuleSpecID refHttpProtoSpecID

Well known endpoint protocol specification identifier: the standard http endpoint protocol

refRouterProtoSpecID

public static final ModuleSpecID refRouterProtoSpecID

Well known endpoint protocol specification identifier: the standard router

refTlsProtoSpecID

public static final ModuleSpecID refTlsProtoSpecID

Well known endpoint protocol specification identifier: the standard tls endpoint protocol

allPurposePeerGroupSpecID

public static final ModuleSpecID allPurposePeerGroupSpecID

Well known group specification identifier: an all purpose peer group specification. The java reference implementation implements it with the StdPeerGroup class and all the standard platform services and no endpoint protocols.

refStartNetPeerGroupSpecID

public static final ModuleSpecID refStartNetPeerGroupSpecID

Well known main application of the platform: startNetPeerGroup.

refShellSpecID

public static final ModuleSpecID refShellSpecID

Well known application: the shell

refProxySpecID

public static final ModuleSpecID refProxySpecID

Well known application: the Proxy

globalRegistry

public static final PeerGroup.GlobalRegistry globalRegistry

Method Detail

getLoader

public JxtaLoader getLoader()

Returns the loader for this group.

Returns:

JxtaLoader The loader

isRendezvous

public boolean isRendezvous()

Returns the whether the group member is a Rendezvous peer for the group

Returns:

boolean true if the peer is a rendezvous for the group.

Since:

JXTA 1.0

getPeerGroupAdvertisement

public PeerGroupAdvertisement getPeerGroupAdvertisement()

Ask a group for its group advertisement

Returns:

PeerGroupAdvertisement this Group's advertisement

Since:

JXTA 1.0

getPeerAdvertisement

public PeerAdvertisement getPeerAdvertisement()

Ask a group for its peer advertisement on this peer.

Returns:

PeerAdvertisement this Peer X Group advertisement

Since:

JXTA 1.0

lookupService

public Service lookupService(ID name)
                      throws ServiceNotFoundException

Lookup for a service by name.

Parameters:

name - the service identifier.

Returns:

Service, the Service registered by that name

Throws:

ServiceNotFoundException - could not find the service requested

Since:

JXTA 1.0

compatible

public boolean compatible(Element compat)

Evaluate if the given compatibility statement make the module that bears it loadable by this group.

Returns:

boolean True if the statement is compatible.

Since:

JXTA 1.0

loadModule

public Module loadModule(ID assignedID,
                         Advertisement impl)
                  throws ProtocolNotSupportedException,
                         PeerGroupException

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.

Parameters:

ID - Id to be assigned to that module (usually its ClassID).

impl - An implementation advertisement for that module.

Returns:

Module the module loaded and initialized.

Throws:

ProtocolNotSupportedException - The module is a protocol and is disabled per the peer's configuration.

PeerGroupException - The module could not be loaded or initialized

Since:

JXTA 1.0

loadModule

public 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.

Parameters:

ID - 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).

Returns:

Module the new module, or null if no usuable implementation was found.

Since:

JXTA 1.0

publishGroup

public void publishGroup(java.lang.String name,
                         java.lang.String description)
                  throws java.io.IOException

Force publication of this group if hasn't been done already. Calling this routine is only usefull 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 published, this method does nothing.

Parameters:

name - The name of this group.

Description - The description of this group.

Throws:

java.io.IOException - The publication could not be accomplished because of a network or storage failure.

Since:

JXTA 1.0

newGroup

public PeerGroup newGroup(Advertisement pgAdv)
                   throws PeerGroupException

Instantiate a group from its given advertisement Use this when a published implAdv for the groupSubclass can be discovered. The pgAdv itself may be all new and unpublished. Therefore, the two typical uses of this routine are: - Creating an all new group with a new ID while using an existing and published implementation. (Possibly a new one published for that purpose). The information should first be gathered in a new PeerGroupAdvertisement which is then passed to this method. - Instantiating a group which advertisement has already been discovered (therefore there is no need to find it by groupID again). To create a group from a known implAdv, use newGroup(gid, impladv, name, description);

Parameters:

pgAdv - The advertisement of that group.

Returns:

PeerGroup the initialized (but not started) peergroup.

Throws:

PeerGroupException - The group could ne be instantated.

Since:

JXTA 1.0

newGroup

public PeerGroup newGroup(PeerGroupID gid,
                          Advertisement impl,
                          java.lang.String name,
                          java.lang.String description)
                   throws PeerGroupException

Convenience method, instantiate a group from its elementary pieces and publish 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 equivalent to either: newGrp = thisGroup.loadModule(gid, impl); newGrp.publishGroup(name, description); or, but only if the implementation adv has been published: newPGAdv = AdvertisementFactory.newAdvertisement( new MimeMediaType("text", "xml")), PeerGroupAdvertisement.getAdvertisementType()); newPGAdv.setPeerGroupID(gid); newPGAdv.setModuleSpecID(impl.getModuleSpecID()); newPGAdv.setName(name); newPGAdv.setDescription(description); newGrp = thisGroup.newGroup(newPGAdv);

Parameters:

gid - The ID of that group.

impl - The advertisement of the implementation to be used.

name - The name of the group.

description - A description of this group.

Returns:

PeerGroup the initialized (but not started) peergroup.

Throws:

PeerGroupException - The group could ne be instantated.

Since:

JXTA 1.0

newGroup

public PeerGroup newGroup(PeerGroupID gid)
                   throws PeerGroupException

Instantiate a group from its groupID only. Use this when using a group that has already been published and discovered. The typical uses of this routine are therefore: - instantiating a group which is assumed to exist and which GID is known. - creating a new group using an already published advertisement. Typically published for that purpose. All other implied advertisements must also have been published beforehand if they did not exist. To create a group from a known implAdv, just use loadModule(gid, implAdv, config) or even: grp = new GroupSubClass(); grp.init(parentGroup, gid, impladv, config); then, REMEMBER TO PUBLISH THE GROUP IF IT IS ALL NEW.

Parameters:

gid - the groupID.

Returns:

PeerGroup the initialized (but not started) peergroup.

Throws:

PeerGroupException - The group could ne be instantated.

Since:

JXTA 1.0

getRendezVousService

public RendezVousService getRendezVousService()

Returns:

RendezVousService an object implementing the RendezVousService service for this group.

Since:

JXTA 1.0

getEndpointService

public EndpointService getEndpointService()

Returns:

EndpointService an object implementing the EndpointService service for this group.

Since:

JXTA 1.0

getResolverService

public ResolverService getResolverService()

Returns:

ResolverService an object implementing the ResolverService service for this group.

Since:

JXTA 1.0

getDiscoveryService

public DiscoveryService getDiscoveryService()

Returns:

DiscoveryService an object implementing the DiscoveryService service for this group.

Since:

JXTA 1.0

getPeerInfoService

public PeerInfoService getPeerInfoService()

Returns:

PeerInfoService an object implementing the PeerInfoService service for this group.

Since:

JXTA 1.0

getMembershipService

public MembershipService getMembershipService()

Returns:

MembershipService an object implementing the MembershipService service for this group.

Since:

JXTA 1.0

getPipeService

public PipeService getPipeService()

Returns:

PipeService an object implementing the PipeService service for this group.

Since:

JXTA 1.0

getPeerGroupID

public PeerGroupID getPeerGroupID()

Tell the ID of this group.

Returns:

PeerGroupId this Group's ID

Since:

JXTA 1.0

getPeerID

public PeerID getPeerID()

Tell the ID of this peer in this group.

Returns:

PeerId this peer's ID

Since:

JXTA 1.0

getPeerGroupName

public java.lang.String getPeerGroupName()

Tell the Name of this group.

Returns:

String this group's name

Since:

JXTA 1.0

getPeerName

public java.lang.String getPeerName()

Tell the Name of this peer in this group.

Returns:

String this peer's name

Since:

JXTA 1.0

getConfigAdvertisement

public Advertisement getConfigAdvertisement()

Returns the config advertisment for this peer in this group (if any).

Returns:

Advertisement the advertisement.

Since:

JXTA 1.0

getAllPurposePeerGroupImplAdvertisement

public ModuleImplAdvertisement getAllPurposePeerGroupImplAdvertisement()
                                                                throws java.lang.Exception

Get an allPurpose peerGroup ModuleImplAdvertisement 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 one as a basis.

Returns:

ModuleImplAdvertisement the adv.

unref

public void unref()