peergroup.java

jxta_src_2.41b jxta 2.41b 最新版源码 from www.jxta.org

     * implementation advertisements of a group should be searched in its 
     * propsective 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 usuable implementation was
     * found.
     */
    public Module loadModule(ID assignedID, ModuleSpecID specID, int where);
    
    /**
     * Publish this group's Peer Group Advertisment. 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:
     *
     * <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>
     *
     * <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>
     * <p/>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 The group could ne 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:
     *
     * <ul>
     *   <li>Instantiating a peer group which is assumed to exist and whose Peer
     *   Group ID is already known.</li>
     *
     *   <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 The group could ne be instantated.
     */
    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.
     *
     *  @since JXTA 2.1
     *
     *  @return AccessService The Access Service for this Peer Group.
     **/
    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 advertisment 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.
     */
    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 transfering ownerhsip 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.
     *
     * @since JXTA 2.3
     *
     * @return PeerGroup the parent group or <code>null</code> if a parent group
     * if not available.
     */
    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.
     *
     *  @since JXTA 2.3.7
     *
     *  @return The location of the parent of all persistent items stored by 
     *  this peer group.
     **/
    public URI getStoreHome();    
}