discoveryservice.java

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

/*
 *  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: DiscoveryService.java,v 1.2 2002/03/04 20:17:34 echtcherbina Exp $
 */
package net.jxta.discovery;

import java.io.IOException;
import java.util.Enumeration;
import net.jxta.document.Advertisement;

import net.jxta.service.Service;

/**
 *  The jxta DiscoveryService provides an asynchronous mechanism for discovering
 *  Peer Advertisements, Group Advertisements, and other general jxta
 *  Advertisements (pipe, service, etc.). The scope of discovery can be
 *  controlled by specifying name and attribute pair, and 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 the 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 in the group, and is interested in a maximum of
 *  10 Advertisements from each peer: <pre>
 *  discovery.getRemoteAdvertisements(null, discovery.ADV,
 *                                      null, null,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>
 *
 *  DiscoveryService also provides a mechanism for publishing advertisements, so
 *  that they may be discovered. The rules to follow when publishing are
 *
 *  <ultype-disc>
 *    <li> <p>
 *
 *    use the current discovery service to publish advertisements private to the
 *    group. <pre>
 *        discovery.publish(adv,discovery.ADV);
 * </pre>
 *    <li> <p>
 *
 *    use the parent's discovery to publish advertisements that public outside
 *    of the group. e.g. peer A would like publish the soccer group in the
 *    NetPeerGroup <pre>
 *        parent=soccerGroup.getParent();
 *        discovery= parent.getDiscoveryService()
 *        discovery.publish(adv,discovery.ADV);
 * </pre>
 *  </ul>
 *  <pe>
 *
 *  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 0
 *  <p/>
 *
 *  Advertisements are stored in a persist ant local cache. When a peers boots
 *  up the same cache is referenced. this is an area where several optimizations
 *  can take place, and intelligence about discovery patterns, etc. <p/>
 *
 *  Another feature of discovery is automatic discovery, a peer initiates a
 *  discovery message by including it's own Advertisement in the discovery
 *  message, which also can be viewed as a announcement. <p/>
 *
 *  Another feature of discovery is a learning about other rendezvous, i.e. when
 *  discovery comes across a peer advertisement of a rendezvous peer it passes
 *  the information down to the endpoint router. <p/>
 *
 *  Message Format : <p/>
 *
 *  A discovery Query <p/>
 *
 *  <pre>
 *      &lt;?xml version="1.0" ?&gt;
 *       &lt;DiscoveryQuery&gt;
 *        &lt;Type&gt;int&lt;/Type&gt;
 *        &lt;Threshold&gt;int&lt;/Threshold&gt;
 *        &lt;PeerAdv&gt;peeradv&lt;/PeerPdv&gt;
 *        &lt;Attr&gt;attribute&lt;/Attr&gt;
 *        &lt;Value&gt;value&lt;/Value&gt;
 *       &lt;/DiscoveryQuery&gt;
 * </pre> <p/>
 *
 *  A discovery Response <p/>
 *
 *  <pre>
 *      &lt;?xml version="1.0"?&gt;
 *       &lt;DiscoveryResponse&gt;
 *        &lt;Count&gt;int&lt;Count&gt;
 *        &lt;Type&gt;int&lt;/Type&gt;
 *        &lt;PeerAdv&gt; adv &lt;/PeerAdv&gt;
 *        &lt;Attr&gt; attribute &lt;/Attr&gt;
 *        &lt;Value&gt; value &lt;/Aalue&gt;
 *        &lt;Response Expiration="expiration" &gt;adv&lt;/Response&gt;
 *        ......
 *        &lt;Response Expiration="expiration" &gt;adv&lt;/Response&gt;
 *      &lt;/DiscoveryResponse&gt;
 * </pre>
 *
 *@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
 *@since      JXTA 1.0
 */

public interface DiscoveryService extends Service {

	/**
	 *  DiscoveryService type Peer
	 */

	public final static int PEER = 0;

	/**
	 *  DiscoveryService type Group
	 */

	public final static int GROUP = 1;

	/**
	 *  DiscoveryService type Advertisement
	 */

	public final static int ADV = 2;
	/**
	 *  Default lifetime time for advertisements.
	 */
	public final static long DEFAULT_LIFETIME = 1000 * 60 * 60 * 24 * 365;
	/**
	 *  Default expiration time for advertisements.