peergroup.java

JXTA&#8482 is a set of open, generalized peer-to-peer (P2P) protocols that allow any networked devi

            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000305"));

    /**
     * Well known module class identifier: pipe service
     */
    public final static ModuleClassID pipeClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000405"));

    /**
     * Well known module class identifier: membership service
     */
    public final static ModuleClassID membershipClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000505"));

    /**
     * Well known module class identifier: rendezvous service
     */
    public final static ModuleClassID rendezvousClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000605"));

    /**
     * Well known module class identifier: peerinfo service
     */
    public final static ModuleClassID peerinfoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000705"));

    /**
     * Well known module class identifier: endpoint service
     */
    public final static ModuleClassID endpointClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000805"));

    // FIXME: EndpointProtocols should probably all be of the same class
    // and of different specs and roles... But we'll take a shortcut for now.

    /**
     * Well known module class identifier: tcp protocol
     */
    public final static ModuleClassID tcpProtoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000905"));

    /**
     * Well known module class identifier: http protocol
     */
    public final static ModuleClassID httpProtoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000A05"));

    /**
     * Well known module class identifier: router protocol
     */
    public final static ModuleClassID routerProtoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000B05"));

    /**
     * Well known module class identifier: application
     */
    public final static ModuleClassID applicationClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000C05"));

    /**
     * Well known module class identifier: tlsProtocol
     */
    public final static ModuleClassID tlsProtoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000D05"));

    /**
     * Well known module class identifier: ProxyService
     */
    public final static ModuleClassID proxyClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000E05"));

    /**
     * Well known module class identifier: RelayProtocol
     */
    public final static ModuleClassID relayProtoClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000F05"));

    /**
     * Well known module class identifier: AccessService
     */
    public final static ModuleClassID accessClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000001005"));

    /**
     * Well known group specification identifier: the platform
     */
    public final static ModuleSpecID refPlatformSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000010106"));

    /**
     * Well known group specification identifier: the Network Peer Group
     */
    public final static ModuleSpecID refNetPeerGroupSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000010206"));

    /**
     * Well known service specification identifier: the standard resolver
     */
    public final static ModuleSpecID refResolverSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000020106"));

    /**
     * Well known service specification identifier: the standard discovery
     */
    public final static ModuleSpecID refDiscoverySpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000030106"));

    /**
     * Well known service specification identifier: the standard pipe service
     */
    public final static ModuleSpecID refPipeSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000040106"));

    /**
     * Well known service specification identifier: the standard membership
     */
    public final static ModuleSpecID refMembershipSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000050106"));

    /**
     * Well known service specification identifier: the standard rendezvous
     */
    public final static ModuleSpecID refRendezvousSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000060106"));

    /**
     * Well known service specification identifier: the standard peerinfo
     */
    public final static ModuleSpecID refPeerinfoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000070106"));

    /**
     * Well known service specification identifier: the standard endpoint
     */
    public final static ModuleSpecID refEndpointSpecID =
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000080106"));

    /**
     * Well known endpoint protocol specification identifier: the standard
     * tcp endpoint protocol
     */
    public final static ModuleSpecID refTcpProtoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000090106"));

    /**
     * Well known endpoint protocol specification identifier: the standard
     * http endpoint protocol
     */
    public final static ModuleSpecID refHttpProtoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000A0106"));

    /**
     * Well known endpoint protocol specification identifier: the standard
     * router
     */
    public final static ModuleSpecID refRouterProtoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000B0106"));

    /**
     * Well known endpoint protocol specification identifier: the standard
     * tls endpoint protocol
     */
    public final static ModuleSpecID refTlsProtoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000D0106"));

    /**
     * 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.
     */
    public final static ModuleSpecID allPurposePeerGroupSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000010306"));

    /**
     * Well known application: the shell
     */
    public final static ModuleSpecID refShellSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000C0206"));

    /**
     * Well known application: the Proxy
     */
    public final static ModuleSpecID refProxySpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000E0106"));

    /**
     * Well known endpoint protocol specification identifier: the standard
     * relay endpoint protocol
     */
    public final static ModuleSpecID refRelayProtoSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "0000000F0106"));

    /**
     * Well known access specification identifier: the standard
     * access service
     */
    public final static ModuleSpecID refAccessSpecID = 
            ModuleSpecID.create(URI.create(WK_ID_PREFIX + "000000100106"));

    /**
     * The global registry of Peer Group instances. Operations involving the
     * instantiation or orderly shutdown of Peer Groups should synchronize upon
     * this object.
     */
    final static GlobalRegistry globalRegistry = new GlobalRegistry();

    /**
     * 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.
     *
     * @return ThreadGroup
     */
    public ThreadGroup getHomeThreadGroup();

    /**
     * Returns the class loader for this group.
     *
     * @return JxtaLoader The JXTA Class loader used by this group.
     */
    public JxtaLoader getLoader();

    /**
     * Returns the whether the group member is a Rendezvous peer for the group.
     *
     * @return boolean true if the peer is a rendezvous for the group.
     */
    public boolean isRendezvous();

    /**
     * Return the PeerGroupAdvertisement for this group.
     *
     * @return PeerGroupAdvertisement this Group's advertisement.
     */
    public PeerGroupAdvertisement getPeerGroupAdvertisement();

    /**
     * Return the PeerAdvertisement of the local Peer within this Peer Group.
     *
     * @return the PeerAdvertisement of the local Peer within this Peer Group.
     */
    public PeerAdvertisement getPeerAdvertisement();

    /**
     * Lookup for a service by name.
     *
     * @param name the service identifier.
     * @return Service, the Service registered by that name
     * @throws ServiceNotFoundException could not find the service requested
     */
    public Service lookupService(ID name) throws ServiceNotFoundException;

    /**
     * Lookup for a service by class ID and index in a map.
     * <p/>
     * 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.
     * <p/>
     * 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.
     *
     * @param name      the service identifier
     * @param roleIndex the index in the list of assigned IDs that match
     *                  that identifier.
     * @return Service, the corresponding Service
     * @throws ServiceNotFoundException Could not find the service requested.
     * @since JXTA 2.3.1
     */
    public Service lookupService(ID name, int roleIndex) throws ServiceNotFoundException;

    /**
     * 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.
     *
     * @param name The ModuleClassID for which the map is desired.
     * @return Iterator An iterator on a collection of the IDs to which the given ID maps.
     * @since JXTA 2.3.1
     */
    public Iterator getRoleMap(ID name);

    /**
     * Return true if the provided compatibility statement is compatible with this group.
     *
     * @param compat compatibility element
     * @return boolean True if the statement is compatible.
     */
    public boolean compatible(Element compat);

    /**
     * Load a Module from a ModuleImplAdv.
     * <p/>
     * Compatibility is checked and load is attempted. If compatible and
     * loaded successfully, 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.
     *
     * @param assignedID Id to be assigned to that module (usually its ClassID).
     * @param impl       An implementation advertisement for that module.
     * @return Module the module loaded and initialized.
     * @throws ProtocolNotSupportedException The implementation described by the
     *                                       advertisement is incompatible with this peer. The module cannot be loaded.
     * @throws PeerGroupException            The module could not be loaded or initialized
     */
    public Module loadModule(ID assignedID, Advertisement impl) throws ProtocolNotSupportedException, PeerGroupException;

    /**