peergroup.java

jxme的一些相关程序,主要是手机上程序开发以及手机和计算机通信的一些程序资料,程序编译需要Ant支持

	 * 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.
	 *
	 * @param ID Id to be assigned to that module (usually its ClassID).
	 * @param impl An implementation advertisement for that module.
	 * @exception ProtocolNotSupportedException The module is a protocol and
	 * is disabled per the peer's configuration.
	 * @exception PeerGroupException The module could not be loaded or initialized
	 * 
	 * @return Module the module loaded and initialized.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public Module loadModule(ID assignedID, Advertisement impl)
	throws ProtocolNotSupportedException, PeerGroupException;

	/**
	 * 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.
	 *
	 * @param ID Id to be assigned to that module (usually its ClassID).
	 * @param specID The specID of this module.
	 * @param 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).
	 *
	 * @return Module the new module, or null if no usuable implementation was
	 * found.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public Module loadModule(ID assignedID, ModuleSpecID specID, int where);

	/**
	 * 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.
	 *
	 * @param name The name of this group.
	 * @param Description The description of this group.
	 * @exception IOException The publication could not be accomplished
	 * because of a network or storage failure.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public void publishGroup(String name, String description)
	throws IOException;


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

	/**
	 * 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);
	 *
	 * @param pgAdv The advertisement of that group.
	 * @return PeerGroup the initialized (but not started) peergroup.
	 *
	 * @exception PeerGroupException The group could ne be instantated.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public PeerGroup newGroup(Advertisement pgAdv)
	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);
	 *
	 * @param gid The ID of that group.
	 * @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.
	 * @exception PeerGroupException The group could ne be instantated.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public PeerGroup newGroup(PeerGroupID gid, Advertisement impl,
	                          String name, String description)
	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.
	 *
	 * @param gid the groupID.
	 * @return PeerGroup the initialized (but not started) peergroup.
	 * @exception PeerGroupException The group could ne be instantated.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public PeerGroup newGroup(PeerGroupID gid)
	throws PeerGroupException;


	/*
	 * shortcuts to the well-known services, in order to avoid calls to lookup.
	 */

	/**
	 * @return RendezVousService an object implementing the RendezVousService service for
	 * this group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public RendezVousService getRendezVousService();

	/**
	 * @return EndpointService an object implementing the EndpointService service for this
	 * group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public EndpointService getEndpointService();

	/**
	 * @return ResolverService an object implementing the ResolverService service for this
	 * group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public ResolverService getResolverService();

	/**
	 * @return DiscoveryService an object implementing the DiscoveryService service for this
	 * group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public DiscoveryService getDiscoveryService();

	/**
	 * @return PeerInfoService an object implementing the PeerInfoService service for this
	 * group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public PeerInfoService getPeerInfoService();

	/**
	 * @return MembershipService an object implementing the MembershipService service for
	 * this group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public MembershipService getMembershipService();

	/**
	 * @return PipeService an object implementing the PipeService service for this
	 * group.
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0    
	 */
	public PipeService getPipeService();

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

	/**
	 * Tell the ID of this group.
	 *
	 * @return PeerGroupId this Group's ID
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0
	 */

	public PeerGroupID getPeerGroupID();

	/**
	 * Tell the ID of this peer in this group.
	 * @return PeerId this peer's ID
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0
	 */

	public PeerID getPeerID();

	/**
	 * Tell the Name of this group.
	 * @return String this group's name
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0
	 */

	public String getPeerGroupName();

	/**
	 * Tell the Name of this peer in this group.
	 * @return String this peer's name
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0
	 */

	public String getPeerName();

	/**
	 * Returns the config advertisment for this peer in this group (if any).
	 *
	 * @return Advertisement the advertisement.
	 *
	 * @version $Revision: 1.40 $
	 * @since JXTA 1.0 
	 */
	public Advertisement getConfigAdvertisement();

	/**
	 * 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.
	 *
	 * @version $Revision: 1.40 $
	 * @return ModuleImplAdvertisement the 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();
}