peergroup.java

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

     * Load a module from a ModuleSpecID
     * <p/>
     * Advertisement is sought, compatibility is checked on all candidates
     * and load is attempted. The first one that is compatible and loads
     * successfully is initialized and returned.
     *
     * @param assignedID Id to be assigned to that module (usually its ClassID).
     * @param specID     The specID of this module.
     * @param where      May be one of: {@code Here}, {@code FromParent}, or
     *                   {@code 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
     *                   prospective parent (that is {@code 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,
     *                   {@code FromParent}), while applications may be sought more freely
     *                   ({@code Both}).
     * @return Module the new module, or null if no usable implementation was
     *         found.
     */
    public Module loadModule(ID assignedID, ModuleSpecID specID, int where);

    /**
     * Publish this group's Peer Group Advertisement. The Advertisement will be
     * published using the parent peer group's Discovery service.
     * <p/>
     * 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.
     *
     * @param name        The name of this group.
     * @param description The description of this group.
     * @throws IOException The publication could not be accomplished
     *                     because of a network or storage failure.
     */
    public void publishGroup(String name, String description) throws IOException;

    /*
     * Valuable application helpers: Various methods to instantiate
     * groups.
     */

    /**
     * Instantiate a peer group from the provided advertisement. This peer
     * group will be the parent of the newly instantiated peer group.
     * <p/>
     * The pgAdv itself may be all new and unpublished. Therefore, the two
     * typical uses of this routine are:
     * <p/>
     * <ul>
     * <li>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.</li>
     * <p/>
     * <li>Instantiating a group which advertisement has already been
     * discovered (therefore there is no need to find it by groupID
     * again).</li>
     * </ul>
     *
     * @param pgAdv The advertisement for the group to be instantiated.
     * @return PeerGroup the initialized (but not started) peergroup.
     * @throws PeerGroupException For problems instantiating the peer group.
     */
    public PeerGroup newGroup(Advertisement pgAdv) throws PeerGroupException;

    /**
     * Instantiates a peer group from its elementary pieces
     * and publishes the corresponding PeerGroupAdvertisement.
     * The pieces are: the groups implementation adv, the group id,
     * the name and description.
     * <p/>
     * The typical use of this routine is creating a whole new group based
     * on a newly created and possibly unpublished implementation adv.
     * <p/>
     * This is a convenience method equivalent to either:
     * <p/>
     * <pre>
     * newGrp = thisGroup.loadModule(gid, impl);
     * newGrp.publishGroup(name, description);
     * </pre>
     * or, but only if the implementation advertisement has been published:
     * <p/>
     * <pre>
     * newPGAdv = AdvertisementFactory.newAdvertisement(
     *                 PeerGroupAdvertisement.getAdvertisementType());
     * newPGAdv.setPeerGroupID(gid);
     * newPGAdv.setModuleSpecID(impl.getModuleSpecID());
     * newPGAdv.setName(name);
     * newPGAdv.setDescription(description);
     * newGrp = thisGroup.newGroup(newPGAdv);
     * </pre>
     *
     * @param gid         The ID of that group. If <code>null</code> then a new group ID
     *                    will be chosen.
     * @param impl        The advertisement of the implementation to be used.
     * @param name        The name of the group.
     * @param description A description of this group.
     * @return PeerGroup the initialized (but not started) peergroup.
     * @throws PeerGroupException Thrown if the group could not be instantiated.
     */
    public PeerGroup newGroup(PeerGroupID gid, Advertisement impl, String name, String description) throws PeerGroupException;

    /**
     * Instantiate a group from its Peer Group ID only. Use this when using a
     * group that has already been published and discovered.
     * <p/>
     * The typical uses of this routine are therefore:
     * <p/>
     * <ul>
     * <li>Instantiating a peer group which is assumed to exist and whose Peer
     * Group ID is already known.</li>
     * <p/>
     * <li>Creating a new peer group instance using an already published
     * Group advertisement, typically published for that purpose. All other
     * referenced advertisements must also be available.</li>
     * </ul>
     * <p/>
     * To create a group from a known implAdv, just use
     * {@link #loadModule(ID,Advertisement)} or even:<p>
     * <p/>
     * <code>
     * grp = new GroupSubClass();
     * grp.init(parentGroup, gid, impladv);
     * </code>
     * <p/>
     * then, <strong>REMEMBER TO PUBLISH THE GROUP IF IT IS ALL NEW.</strong>
     *
     * @param gid the groupID.
     * @return PeerGroup the initialized (but not started) peergroup.
     * @throws PeerGroupException Thrown if the group could not be instantiated.
     */
    public PeerGroup newGroup(PeerGroupID gid) throws PeerGroupException;

    /*
     * Shortcuts to the well-known services, in order to avoid calls to
     * {@link #lookupService(ID)}.
     */

    /**
     * Return the Rendezvous Service for this Peer Group. This service is
     * optional and may not be present in all groups.
     *
     * @return The Rendezvous Service for this Peer Group or <code>null</code>
     *         if there is no Rendezvous Service in this Peer Group.
     */
    public RendezVousService getRendezVousService();

    /**
     * Return the Endpoint Service for this Peer Group. This service is
     * present in every Peer Group.
     *
     * @return EndpointService The Endpoint Service for this Peer Group.
     */
    public EndpointService getEndpointService();

    /**
     * Return the Resolver Service for this Peer Group. This service is
     * present in every Peer Group.
     *
     * @return ResolverService The Resolver Service for this Peer Group.
     */
    public ResolverService getResolverService();

    /**
     * Return the Discovery Service for this Peer Group.
     *
     * @return The Discovery Service for this Peer Group or <code>null</code>
     *         if there is no PeerInfo Service in this Peer Group.
     */
    public DiscoveryService getDiscoveryService();

    /**
     * Return the PeerInfo Service for this Peer Group.
     *
     * @return The PeerInfo Service for this Peer Group or <code>null</code>
     *         if there is no PeerInfo Service in this Peer Group.
     */
    public PeerInfoService getPeerInfoService();

    /**
     * Return the Membership Service for this Peer Group. This service is
     * present in every Peer Group.
     *
     * @return MembershipService The Membership Service for this Peer Group.
     */
    public MembershipService getMembershipService();

    /**
     * Return the Pipe Service for this Peer Group.
     *
     * @return The Pipe Service for this Peer Group or <code>null</code> if
     *         there is no Pipe Service in this Peer Group.
     */
    public PipeService getPipeService();

    /**
     * Return the Access Service for this Peer Group. This service is
     * present in every Peer Group.
     *
     * @return AccessService The Access Service for this Peer Group.
     * @since JXTA 2.1
     */
    public AccessService getAccessService();

    // A few convenience methods. This information is available from the peer and peergroup advertisement.

    /**
     * Return the Peer Group ID of this Peer Group.
     *
     * @return PeerGroupId The Peer Group ID of this Peer Group.
     */
    public PeerGroupID getPeerGroupID();

    /**
     * Return the Peer ID by which this Peer is known within this Peer Group.
     *
     * @return the Peer ID by which this Peer is known within this Peer Group.
     */
    public PeerID getPeerID();

    /**
     * Return the Name of this group. This name is not canonical, meaning that
     * there may be other groups with the same name.
     *
     * @return String This groups's name or <code>null</code>  if no name was
     *         specified.
     */
    public String getPeerGroupName();

    /**
     * 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.
     *
     * @return String This peer's name or <code>null</code> if no name was
     *         specified.
     */
    public String getPeerName();

    /**
     * Returns the config advertisement for this peer in this group (if any).
     *
     * @return The advertisement or <code>null</code> if none is available.
     */
    public ConfigParams getConfigAdvertisement();

    /**
     * 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.
     * <p/>
     * This defines a peergroup implementation that can be used for
     * many purposes, and from which one may derive slightly different
     * peergroup implementations.
     * <p/>
     * This definition is always the same and has a well known ModuleSpecID.
     * It includes the basic service, no protocols and the shell for main
     * application.
     * <p/>
     * The user must remember to change the specID if the set of services
     * protocols or applications is altered before use.
     *
     * @return ModuleImplAdvertisement The new peergroup impl adv.
     * @throws Exception if an error occurs while creating the implementation advertisement
     */
    public ModuleImplAdvertisement getAllPurposePeerGroupImplAdvertisement() throws Exception;

    /**
     * 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.
     */
    public void unref();

    /**
     * Returns a weak interface object that represents this
     * group.
     * <p/>
     * 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.
     * <p/>
     * 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.
     * <p/>
     * 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.
     * <p/>
     * 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.
     * <p/>
     * 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.
     *
     * @return PeerGroup A weak interface object that represents this
     *         PeerGroup object.
     * @since JXTA 2.2
     */
    public PeerGroup getWeakInterface();

    /**
     * Returns the parent group of this group. Not all groups have parents and
     * some implementations may not reveal their parents.
     *
     * @return PeerGroup the parent group or <code>null</code> if a parent group
     *         if not available.
     * @since JXTA 2.3
     */
    public PeerGroup getParentGroup();

    /**
     * Returns the location of the parent of all items that this peer group is
     * using for persistently storing its preferences, cache, persistent store,
     * properties, etc. May be {@code null} if the peergroup has no defined
     * location for storing persistent data.
     *
     * @return The location of the parent of all persistent items stored by
     *         this peer group.
     * @since JXTA 2.3.7
     */
    public URI getStoreHome();    
}