peergroupinterface.java

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

/*
 * Copyright (c) 2002 Sun Microsystems, Inc.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *       Sun Microsystems, Inc. for Project JXTA."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact Project JXTA at http://www.jxta.org.
 *
 * 5. Products derived from this software may not be called "JXTA",
 *    nor may "JXTA" appear in their name, without prior written
 *    permission of Sun.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL SUN MICROSYSTEMS OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Project JXTA.  For more
 * information on Project JXTA, please see
 * <http://www.jxta.org/>.
 *
 * This license is based on the BSD license adopted by the Apache Foundation.
 *
 * $Id: PeerGroupInterface.java,v 1.3 2002/05/06 21:05:25 jice Exp $
 */

package net.jxta.impl.peergroup;

import net.jxta.peergroup.PeerGroup;
import net.jxta.discovery.DiscoveryService;
import net.jxta.document.Advertisement;
import net.jxta.document.Element;
import net.jxta.endpoint.EndpointService;
import net.jxta.exception.ServiceNotFoundException;
import net.jxta.exception.PeerGroupException;
import net.jxta.exception.ProtocolNotSupportedException;
// import net.jxta.exception.JxtaError;
import net.jxta.id.ID;
// import net.jxta.id.IDFactory;
import net.jxta.membership.MembershipService;
import net.jxta.peer.PeerID;
import net.jxta.peer.PeerInfoService;
import net.jxta.peergroup.PeerGroupID;
import net.jxta.pipe.PipeService;
import net.jxta.platform.JxtaLoader;
import net.jxta.platform.Module;
import net.jxta.platform.ModuleClassID;
import net.jxta.platform.ModuleSpecID;
import net.jxta.protocol.PeerAdvertisement;
import net.jxta.protocol.PeerGroupAdvertisement;
import net.jxta.protocol.ModuleImplAdvertisement;
import net.jxta.rendezvous.RendezVousService;
import net.jxta.resolver.ResolverService;
import net.jxta.service.Service;

import java.io.IOException;
// import java.net.URL;
// import java.net.MalformedURLException;
// import java.net.UnknownServiceException;
// import java.lang.ClassNotFoundException;

/**
 * PeerGroupInterface provides a pure interface object that permits
 * interaction with the actual PeerGroup implementation without giving
 * access to the real object. It also serves as a peergroup very-strong
 * reference. When the last such goes away, the peergroup terminates itself
 * despite the existence of aeternal strong references from the various
 * service's threads that would prevent it from ever being finalized.
 * The alternative: to give only weak references to threads seems impractical.
 */

class PeerGroupInterface implements RefPeerGroup {

    private GenericPeerGroup groupImpl;


    /**
     * Constructs an interface object that fron-ends a given
     * GenericPeerGroup.
     */
    PeerGroupInterface(GenericPeerGroup theRealThing) {
	groupImpl = theRealThing;
    }

    /**
     *  Initialize the application
     *  FIXME: This is meaningless for the interface object;
     * it is there only to satisfy the requirements of the
     * interface that we implement. Ultimately, the API should define
     * two levels of interfaces: one for the real service implementation
     * and one for the interface object. Right now it feels a bit heavy
     * to so that since the only different between the two would be
     * init() and may-be getName().
     * @param group PeerGroup this application is started from
     * @since   JXTA 1.0
     */

    public void init(PeerGroup pg, ID assignedID, Advertisement impl) {
    }

    /**
     * Normaly it is ALWAYS ignored. By definition, the interface object
     * protects the real object's start/stop methods from being called
     * However we have to make an exception for groups: even the creator
     * of a group does not have access to the real object. So the interface
     * has to forward startApp to the group, which is responsible for
     * ensuring that it is executedonly once (if needed).
     *
     * @param arg A table of strings arguments.
     * @return int status indication.
     */
    public int startApp(String[] arg) {
	return groupImpl.startApp(arg);
    }

    /**
     * This is here for temporary class hierarchy reasons.
     * it is ALWAYS ignored. By definition, the interface object
     * protects the real object's start/stop methods from being called
     *
     * In that case we have to make an exception. Most applications currently
     * assume that they do not share the group object and that they do refer
     * to the real object directly. They call stopApp to signify their
     * intention of no-longer using the group. Now that groups are shared,
     * we convert stopApp to unref for compatibility.
     * We could also just do nothing and let the interface be GC'd but
     * calling unref makes the group go away immediately if not shared,
     * which is what applications that call stopApp expect.
     */
    public void stopApp() {
	unref();
    }

    /**
     * Returns the advertisment for that service.
     *
     * @return Advertisement the advertisement.
     *
     * @version $Revision: 1.3 $
     * @since JXTA 1.0
     */
    public Advertisement getImplAdvertisement() {
        return groupImpl.getImplAdvertisement();
    }

    /**
     * returns an interface object that permits to use this
     * service without having access to the real object.
     *
     * Since THIS is already such an object, it could return itself.
     * However, we want the group to know about the number of interfaces
     * objects floating around, so, we'll have the group make a new one.
     * That way, applications which want to use unref() on interfaces can
     * avoid sharing interface objects by using getInterface() as a sort of
     * clone with the additional ref-counting semantics.
     * @return Service An interface object that implements
     * this service and nothing more.
     */

    public Service getInterface() {
	return groupImpl.getInterface();
    }

    /**
     * stopApp used to be the standard way of giving up on a group
     * instance, but now that goup instance can be shared, the standard
     * of letting go of a peer group is to stop referencing it.
     * Since the peergroup has permanent referers: the threads of the services
     * we need to use the interface object as a super-strong reference.
     * When an interface is finalized, it calls the group's unref method.
     * The unref method stopApps the group when the last reference is
     * gone. To accelerate the un-referencing of groups, applications may call
     * the interface's unref method, but that takes some dicipline since the
     * interface object becomes unusable after that. So, aware applications
     * that use it must also take care of always cloning the interface
     * object instead of sharing it.
     * For compatibility with current apps which call stopApp, we have the
     * interface's stopApp() do nothing as with all other interface objects.
     * An invoker that has a reference to the true group object can still
     * call its stopApp method with the usual result.
     */

    public void finalize() {
	// The user gave up on the group, may be without calling unref.
	// Call it, just in case. It will do the right thing if it has been
	// called already.
	unref();
    }

    /**
     * Can only be called once. After that the reference is no-longer usuable.
     */
    public void unref() {
	GenericPeerGroup theGrp;
	synchronized(this) {
	    if (groupImpl == null) return;
	    theGrp = groupImpl;
	    groupImpl = null;
	}
	theGrp.decRefCount();
    }

    /**
     * Returns the loader for this group.
     *
     * @return JxtaLoader The loader
     */
    public JxtaLoader getLoader() {
	return groupImpl.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.
     * 
     * @version $Revision: 1.3 $
     * @since JXTA 1.0
     */

    public boolean isRendezvous() {
	return groupImpl.isRendezvous();
    }

  
    
    /**
     * Ask a group for its group advertisement
     *
     * @return PeerGroupAdvertisement this Group's advertisement
     *
     * @version $Revision: 1.3 $
     * @since JXTA 1.0
     */
    
    public PeerGroupAdvertisement getPeerGroupAdvertisement() {
	return groupImpl.getPeerGroupAdvertisement();
    }

    /**
     * Ask a group for its peer advertisement on this peer.
     *
     * @return PeerAdvertisement this Peer X Group advertisement
     *
     * @version $Revision: 1.3 $
     * @since JXTA 1.0
     */
    
    public PeerAdvertisement getPeerAdvertisement() {
	return groupImpl.getPeerAdvertisement();
    }
    
    /**
     * Lookup for a service by name.
     *
     * @param name the service identifier.
     *
     * @return Service, the Service registered by that name
     *
     * @exception ServiceNotFoundException could not find the service requested
     *
     * @version $Revision: 1.3 $
     * @since JXTA 1.0    
     */
    
    public Service lookupService(ID name)
        throws ServiceNotFoundException {
	return groupImpl.lookupService(name);
    }
    
    /**
     * Evaluate if the given compatibility statement make the module
     * that bears it loadable by this group.
     *
     * @return boolean True if the statement is compatible.
     *
     * @version $Revision: 1.3 $
     * @since JXTA 1.0    
     */
    public boolean compatible(Element compat) {
	return groupImpl.compatible(compat);
    }

    /**
     * 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.
     *
     * @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.