discoveryservice.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.discovery;


import java.io.IOException;
import java.util.Enumeration;

import net.jxta.document.Advertisement;
import net.jxta.id.ID;
import net.jxta.service.Service;


/**
 * Provides an asynchronous mechanism for discovering Advertisement (Peers,
 * Groups, Pipes, Modules, etc.). The scope of discovery queries can be 
 * controlled by specifying a name and attribute pair, and/or a threshold. 
 * The threshold is an upper limit the requesting peer specifies for 
 * responding peers not to exceed. Each JXTA Peer Group has an instance of 
 * a DiscoveryService. The scope of discovery is limited to the group. For 
 * example :
 *
 * <p/>A peer in the soccer group invokes the soccer group's DiscoveryService
 * to discover pipe advertisements for the Score tracker service in the group,
 * and is interested in a maximum of 10 Advertisements from each peer:
 * <pre>
 *  discovery.getRemoteAdvertisements(null, discovery.ADV,
 *                                    "Name", "Score tracker*", 10, null);
 *
 * </pre>
 *
 * <p/>In the above example, peers that are part of the soccer group would
 * respond. After a getRemoteAdvertisements call is made and the peers respond,
 * a call to getLocalAdvertisements can be made to retrieve results that have
 * been found and added to the local group cache. Alternately, a call to
 * addDiscoveryListener() will provide asynchronous notification of discovered
 * advertisements.
 *
 * <p/>When an Advertisement is published, it is stored, and indexed in the 
 * peer's local cache. The Advertisement indexes are also shared with 
 * Rendezvous peers. Advertisement indexes may not be shared with other
 * peers immediately, but may be updated as part of a periodic process. The
 * Discovery Service currently updates remote indexes every 30 seconds.
 *
 * <p/>It is important to note that what is shared with the rendezvous peer is  
 * the index and expiration of the advertisement, not the advertisement. The
 * indexes are republished whenever the peer establishes a new connection with 
 * a different rendezvous peer.
 *
 * <p/>Distributed index garbage collection. A rendezvous peer will GC indexes for
 * a specific peer when it receive a disconnect message, or it has determined
 * that a peer is no longer reachable, the latter action is a lazy GC and is
 * triggered by messenger creation failures which results in a mark and sweep at
 * a future point in time.
 *
 * <p/>DiscoveryService also provides a mechanism for publishing advertisements,
 * so that they may be discovered. The rules to follow when publishing are:
 *
 *  <ul>
 *    <li>
 *    Use the current discovery service to publish advertisements private to the
 *    group.
 * <pre>discovery.publish(adv);
 * </pre></li>
 *
 *    <li>Use the parent's discovery to publish advertisements that public outside
 *    of the group. Example : a peer would like publish the "soccer" group in the
 *    NetPeerGroup
 * <pre>
 *        parent=soccerGroup.getParent();
 *        discovery= parent.getDiscoveryService()
 *        discovery.publish(adv);
 * </pre></li>
 *  </ul>
 *
 * <p/>The threshold can be utilized in peer discovery in situations where a peer
 * is only interested in other peers, and not about additional peers they may
 * know about. To achieve this effect for peer discovery set the Threshold to
 * <code>0</code> (zero).
 *
 * <p/>Advertisements are often stored in a persistent local cache. This cache 
 * can improve performance and responsiveness by retaining advertisements 
 * between restarts.
 *
 *@see        net.jxta.service.Service
 *@see        net.jxta.resolver.ResolverService
 *@see        net.jxta.protocol.DiscoveryQueryMsg
 *@see        net.jxta.protocol.DiscoveryResponseMsg
 *@see        net.jxta.protocol.ResolverQueryMsg
 *@see        net.jxta.protocol.ResolverResponseMsg
 */
public interface DiscoveryService extends Service {
    
    /**
     * Discovery type Peer
     */
    public final static int PEER = 0;
    
    /**
     * Discovery type Group
     */
    public final static int GROUP = 1;
    
    /**
     *  Discovery type Advertisement
     */
    public final static int ADV = 2;
    
    /**
     * Default lifetime time for advertisements. This is the maximum
     * amount of time which the advertisement will remain valid. If the
     * advertisement remains valid after this time, then the creator will
     * need to republish the advertisement.
     */
    public final static long DEFAULT_LIFETIME = 1000L * 60L * 60L * 24L * 365L;
    
    /**
     *  Default expiration time for advertisements. This is the amount of
     *  time which advertisements will live in caches. After this time, the
     *  advertisement should be refreshed from the source.
     */
    public final static long DEFAULT_EXPIRATION = 1000L * 60L * 60L * 2L;
    
    /**
     *  Infinite lifetime for advertisements. The advertisement is valid
     *  forever. (well maybe it will expire when the sun burns out, but not
     *  before then).
     */
    public final static long INFINITE_LIFETIME = Long.MAX_VALUE;
    
    /**
     *  Specifies that the advertisement will have no expiration and will be
     *  kept indefinitely.
     */
    public final static long NO_EXPIRATION = Long.MAX_VALUE;
    
    /**
     *  Discover advertisements from remote peers. This does not normally 
     *  provide an exhaustive search. Instead it provides a "best efforts" 
     *  search which will provide a selection of advertisements of matching the 
     *  search criteria. The selection of advertisements returned may be random 
     *  or predictable depending upon the network configuration and no 
     *  particular behaviour should be assumed. In general the narrower the
     *  query specified the more exhaustive the responses will be. 
     * 
     *  <p/>Discovery can be performed in two ways : <ul>
     *      <li>With a <tt>null</tt> peerid - The discovery query is
     *      propagated on via the Rendezvous Service and via local sub-net
     *      utilizing IP multicast.</li>
     *      <li>With a provided peerid - The discovery query is forwarded to the
     *      specified peer.</li>
     *  </ul>
     *
     *  <p/>The scope of advertisements returned can be narrowed by specifying
     *  an {@code attribute} and {@code value} pair. The {@code attribute} is
     *  a case-sensitive string matching the name of an Advertisement XML tag
     *  who's values will be matched by the {@code value}.  Only a limited number
     *  of Advertisement XML fields are indexed. {@link
     *  net.jxta.document.Advertisement#getIndexFields()} will return the 
     *  fields on which you may query for a particular Advertisement type. 
     * 
     *  <p/>The {@code value} is a case-insensitive string who's value is
     *  matched against the values of {@code attribute} fields of Advertisements.
     *  The {@code} value may be of several forms :
     *  <ul>
     *      <li>{@code null} - Don't care. All advertisements with the matching
     *      {@code attribute} will be returned.</li>
     *      <li>exact value - Only advertisements with an {@code attribute}
     *      field who's value exactly matches the string {@code value} will be
     *      returned.</li>
     *      <li>wild card - Only advertisements with an {@code attribute}
     *      field who's value matches the wild card expression {@code value} 
     *      will be returned. eg. The following expressions all match against
     *      "FooBar":
     *      <ul>
     *          <li>{@code foO*}</li>
     *          <li>{@code *Bar}</li>
     *          <li>{@code *oBA*}</li>
     *      </ul></li>
     *  </ul>
     * 
     * @param peerid If provided the query will be forwarded to the specified
     *      peer. If {@code null} then the query will be propagated through the
     *      network to peers with matching Advertisements.
     * @param type Discovery type; <tt>PEER</tt>, <tt>GROUP</tt> or <tt>ADV</tt>.
     * @param  attribute indexed element name (see advertisement(s) for a
     *       list of indexed fields. A null attribute indicates any advertisement
     *       of specified type
     * @param  value      value of attribute to narrow discovery to. Valid values for
     *      this parameter are null (don't care), Exact value, or use of wild
     *      card(s) (e.g. if a Advertisement defines <Name>FooBar</name> , a value
     *      of "*bar", "foo*", or "*ooB*", will return the Advertisement
     * @param  threshold  The maximum number of matching advertisements which
     *      be returned by each responding peer. A {@code threshold} of 0, and 
     *      {@code type} of {@code PEER} has a special behaviour.
     * @return query ID for this discovery query.
     */
    public int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold);
    
    /**