peergroup.java

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

/*
 * Copyright (c) 2001 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: PeerGroup.java,v 1.65 2006/07/06 19:50:29 bondolo Exp $
 */

package net.jxta.peergroup;

import java.lang.ref.Reference;
import java.lang.ref.WeakReference;
import java.net.URI;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;

import java.io.IOException;

import net.jxta.access.AccessService;
import net.jxta.discovery.DiscoveryService;
import net.jxta.document.Advertisement;
import net.jxta.document.Element;
import net.jxta.endpoint.EndpointService;
import net.jxta.id.ID;
import net.jxta.membership.MembershipService;
import net.jxta.peer.PeerID;
import net.jxta.peer.PeerInfoService;
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.ConfigParams;
import net.jxta.protocol.ModuleImplAdvertisement;
import net.jxta.protocol.PeerAdvertisement;
import net.jxta.protocol.PeerGroupAdvertisement;
import net.jxta.rendezvous.RendezVousService;
import net.jxta.resolver.ResolverService;
import net.jxta.service.Service;

import net.jxta.exception.PeerGroupException;
import net.jxta.exception.ProtocolNotSupportedException;
import net.jxta.exception.ServiceNotFoundException;


/**
 * Peer groups are formed as a collection of peers that have agreed upon a
 * common set of services. Each peer group is assigned a unique peer group ID
 * and a peer group advertisement. The peer group advertisement contains a
 * ModuleSpecID which refers to a module specification for this peer group.
 *
 * <p>The peer group specification mandates each of the group services (membership,
 * discovery, resolver, etc). Implementations of that specification are
 * described by ModuleImplAdvertisements which are identified by the group's
 * ModuleSpecID. Implementations are responsible for providing the services mandated
 * by the specification.
 *
 * The java reference implementation achieves this by loading additional Modules 
 * which ModuleSpecIDs are listed by the group implementation advertisement.
 *
 * <p>In order to fully participate in a group, a peer may need to authenticate
 * with the group using the peer group membership service.
 *
 * @see         net.jxta.peergroup.PeerGroupID
 * @see         net.jxta.service.Service
 * @see         net.jxta.peergroup.PeerGroupFactory
 * @see         net.jxta.protocol.PeerGroupAdvertisement
 * @see         net.jxta.protocol.ModuleImplAdvertisement
 * @see         net.jxta.platform.ModuleSpecID
 * @see         net.jxta.platform.ModuleClassID
 **/
public interface PeerGroup extends Service {
    
    /**
     * Look for needed ModuleImplAdvertisement in this group.
     */
    public final static int Here = 0;
    
    /**
     * Look for needed ModuleImplAdvertisement in the parent group of this group.
     */
    public final static int FromParent = 1;
    
    /**
     * Look for needed ModuleImplAdvertisement in both this group and its parent.
     */
    public final static int Both = 2;
    
    /**
     * Default life time for group advertisements in the publisher's cache.
     * (a year)
     */
    // without casting to long we lose precision
    public final static long   DEFAULT_LIFETIME = (long) 1000 * (long) 3600 * (long) 24 * (long) 365L;
    
    /**
     * Default expiration time for discovered group advertisements. (2 weeks)
     */
    // without casting to long we lose precision
    public final static long   DEFAULT_EXPIRATION = (long) 1000 * (long) 3600 * (long) 24 * (long) 14L;
    
    /**
     * Global registry of instantiated peer groups. We allow only a single 
     * PeerGroup instance for a specific PeerGroupID within the context of the
     * classloader JXTA is loaded into.
     */
    static class GlobalRegistry {
        
        private final Map<ID,Reference> registry = new HashMap(8);
        
        /**
         * Registers a new instance.
         *
         * @param gid the ID of the group of which an instance is being registered.
         * @param pg the group instance being registered.
         * @return false if the instance could not be registered because there
         * was already such an instance registered.
         */
        public synchronized boolean registerInstance(PeerGroupID gid, PeerGroup pg) {
            
            Reference ref = registry.get(gid);
            
            if ((ref != null) && (ref.get() != null)) {
                return false;
            }
            
            // If the ref is a dead instance, we can also replace it.
            registry.put(gid, new WeakReference(pg));
            return true;
        }
        
        /**
         * Unregisters a group instance (normaly because the group is being
         * stopped.
         *
         * @param gid the ID of the group of which an instance is unregistered.
         * @param pg the group instance itself (serves as a creadential).
         * @return false if the group could not be unregistered because no such
         * registration (exact ID, exact object) was not found.
         */
        public synchronized boolean unRegisterInstance(PeerGroupID gid, PeerGroup pg) {
            
            Reference ref = registry.get(gid);
            
            if (ref == null) {
                return false;
            }
            
            PeerGroup found = (PeerGroup) ref.get();
            
            if (found == null) {
                // Dead instance. Remove from table.
                registry.remove(gid);
                return false;
            }
            
            // Note the use of "!=", not "!equals()"
            if (pg != found) {
                return false;
            }
            
            registry.remove(gid);
            return true;
        }
        
        /**
         * Returns a running instance of the peergroup with given ID if any
         * exists.
         *
         * @param gid the id of the group of which an instance is wanted.
         * @return the group, or null if no instance exists.
         */
        public synchronized PeerGroup lookupInstance(PeerGroupID gid) {
            
            Reference ref = registry.get(gid);
            
            if (ref == null) {
                return null;
            }
            
            PeerGroup pg = (PeerGroup) ref.get();
            
            if (pg == null) {
                // Dead instance. remove from table.
                registry.remove(gid);
                return null;
            }
            
            // Returns an interface object. Therefore a module that got the
            // peergroup through lookup cannot unregister it if the group
            // protects itself by returning an interface object different from
            // the group object. In general only the group itself can
            // unregister when being torn down. Unregistration will also be
            // automatic if the grp object is GC'ed (the references are weak
            // references).
            return (PeerGroup) pg.getInterface();
        }
        
        /**
         *  Returns {@code true} if there is a registered peergroup of the
         *  specified ID.
         *
         * @param gid the id of the group of which an instance is wanted.
         * @return {@code} true if the peergroup is currently registered
         * otherwise false;
         */
        public synchronized boolean registeredInstance(PeerGroupID gid) {
            
            Reference ref = registry.get(gid);
            
            if (ref == null) {
                return false;
            }
            
            PeerGroup pg = (PeerGroup) ref.get();
            
            if (pg == null) {
                // Dead instance. remove from table.
                registry.remove(gid);
                return false;
            }
            
            return true;
        }
    }
    
    /**
     * Well known classes for the basic services.
     *
     * <p/>FIXME: we should make a "well-known ID" encoding implementation that
     * has its own little name space of human readable names...later.
     * To keep their string representation shorter, we put our small spec
     * or role pseudo unique ID at the front of the second UUID string.
     * Base classes do not need an explicit second UUID string because it is
     * all 0.
     *
     * <p/>The type is always the last two characters, nomatter the total length.
     */
    
    /**
     *  Prefix string for all of the Well Known IDs declated in this interface.
     **/
    static final String WK_ID_PREFIX = ID.URIEncodingName + ":" + ID.URNNamespace + ":uuid-DeadBeefDeafBabaFeedBabe";
    
    /**
     * Well known module class identifier: peer group
     */
    public final static ModuleClassID peerGroupClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000105"));
    
    /**
     * Well known module class identifier: resolver service
     */
    public final static ModuleClassID resolverClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000205"));
    
    /**
     * Well known module class identifier: discovery service
     */
    public final static ModuleClassID discoveryClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000305"));
    
    /**
     * Well known module class identifier: pipe service
     */
    public final static ModuleClassID pipeClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000405"));
    
    /**
     * Well known module class identifier: membership service
     */
    public final static ModuleClassID membershipClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000505"));
    
    /**
     * Well known module class identifier: rendezvous service
     */
    public final static ModuleClassID rendezvousClassID = (ModuleClassID)
            ID.create(URI.create(WK_ID_PREFIX + "0000000605"));
    
    /**
     * Well known module class identifier: peerinfo service
     */
    public final static ModuleClassID peerinfoClassID = (ModuleClassID)