peergroup.java

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

/*
 * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
 *  
 *  The Sun Project JXTA(TM) Software License
 *  
 *  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 Sun Microsystems, Inc. for JXTA(TM) technology." 
 *     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.
 *  
 *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United 
 *  States and other countries.
 *  
 *  Please see the license information page at :
 *  <http://www.jxta.org/project/www/license.html> for instructions on use of 
 *  the license in source files.
 *  
 *  ====================================================================
 *  
 *  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. 
 */

package net.jxta.peergroup;


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.exception.PeerGroupException;
import net.jxta.exception.ProtocolNotSupportedException;
import net.jxta.exception.ServiceNotFoundException;
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 java.io.IOException;
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;


/**
 * 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.
 * <p/>
 * 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 * 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 * 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<PeerGroup>> registry = new HashMap<ID, Reference<PeerGroup>>(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<PeerGroup> 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<PeerGroup>(pg));
            return true;
        }

        /**
         * Unregisters a group instance (normally 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 credential).
         * @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<PeerGroup> ref = registry.get(gid);

            if (ref == null) {
                return false;
            }

            PeerGroup found = 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. The instance should be {@link PeerGroup#unref()}ed when it is
         * no longer needed.
         *
         * @param gid the id of the group of which an instance is wanted.
         * @return the group, or {@code null} if no instance exists.
         */
        public synchronized PeerGroup lookupInstance(PeerGroupID gid) {

            Reference<PeerGroup> ref = registry.get(gid);

            if (ref == null) {
                return null;
            }

            PeerGroup pg = 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 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 {@code null} if no instance exists.
         */
        synchronized PeerGroup getInstance(PeerGroupID gid) {

            Reference<PeerGroup> ref = registry.get(gid);

            if (ref == null) {
                return null;
            }

            PeerGroup pg = ref.get();

            if (pg == null) {
                // Dead instance. remove from table.
                registry.remove(gid);
                return null;
            }

            return pg;
        }

        /**
         * 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<PeerGroup> ref = registry.get(gid);

            if (ref == null) {
                return false;
            }

            PeerGroup pg = 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, no-matter the total length.
     */

    /**
     * Prefix string for all of the Well Known IDs declared 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.create(URI.create(WK_ID_PREFIX + "0000000105"));

    /**
     * Well known module class identifier: resolver service
     */
    public final static ModuleClassID resolverClassID = 
            ModuleClassID.create(URI.create(WK_ID_PREFIX + "0000000205"));

    /**
     * Well known module class identifier: discovery service
     */
    public final static ModuleClassID discoveryClassID =