Project JXTA

net.jxta.discovery
Interface Discovery


public interface Discovery
extends Service

The jxta DiscoveryService Service provides asynchronous mechanism in jxta for discovering Peer Advertisements, Group Advertisements, and general jxta Advertisements (pipe, service, etc.). The scope of discovery can 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 Service the scope of the discovery is limited to the group. for example

A peer in the soccer group invokes the soccer group's DiscoveryService Service to discover pipe advertisements in the group, and is interested in a maximum of 10 Advertisements from each peer:

  discovery.getRemoteAdvertisements(null, discovery.ADV,
                                      null, null,10);

 
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 peers. DiscoveryService also provides a mechanism for publishing advertisements, so that they may be discovered. The rules to follow when publishing are 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 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. 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. 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. Message Format : A discovery Query
      <?xml version="1.0" standalone='yes'?>
       <DiscoveryQuery>
        <type>int</type>
        <threshold>int</threshold>
        <peeradv>peeradv</peeradv>
        <attribute>attribute</attribute>
        <value>attribute</value>
       </DiscoveryQuery>
 
A discovery Response <?xml version="1.0" standalone='yes'?> <DiscoveryResponse> <count>int<count> <type>int</type> <peeradv> adv </peeradv> <responses>adv</responses> ...... <responses>adv</responses> </DiscoveryResponse>

Since:
JXTA 1.0
See Also:
Service, Resolver, DiscoveryQueryMsg, DiscoveryResponseMsg, ResolverQueryMsg, ResolverResponseMsg

Field Summary
static int ADV
          DOC type
static long DEFAULT_EXPIRATION
          Default expiration time for advertisements.
static long DEFAULT_LIFETIME
           
static int GROUP
          Group type
static int PEER
          Peer type
 
Method Summary
 void addDiscoveryListener(DiscoveryListener listener)
          Add a discovery listener
 void flushAdvertisements(java.lang.String id, int type)
          flush stored Documents.
 java.util.Enumeration getLocalAdvertisements(int type, java.lang.String attribute, java.lang.String value)
          Retrieve Stored Peer, Group, and General Advertisements
 int getRemoteAdvertisements(java.lang.String peerid, int type, java.lang.String attribute, java.lang.String value, int threshold)
          This method discovers PeerAdvertisements, GroupAdvertisements and jxta Advertisements.
 void publish(Advertisement advertisement, int type)
          Publish an advertisement
 void publish(Advertisement adv, int type, long lifetime, long lifetimeForOthers)
          Publish an advertisement that will expire after a certain time.
 void remotePublish(Advertisement adv, int type)
          Remote Publish an advertisement
 void remotePublish(Advertisement adv, int type, long lifetime)
          Remote Publish an advertisement
 boolean removeDiscoveryListener(DiscoveryListener listener)
          remove a discovery listener
 
Methods inherited from interface net.jxta.service.Service
getAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Application
init, startApp, stopApp
 

Field Detail

PEER

public static final int PEER
Peer type

GROUP

public static final int GROUP
Group type

ADV

public static final int ADV
DOC type

DEFAULT_LIFETIME

public static final long DEFAULT_LIFETIME

DEFAULT_EXPIRATION

public static final long DEFAULT_EXPIRATION
Default expiration time for advertisements.
Method Detail

getRemoteAdvertisements

public int getRemoteAdvertisements(java.lang.String peerid,
                                   int type,
                                   java.lang.String attribute,
                                   java.lang.String value,
                                   int threshold)
This method discovers PeerAdvertisements, GroupAdvertisements and jxta Advertisements. jxta Advertisements are documents that describe pipes, services, etc. The discovery scope can be narrowed down firstly by Name and Value pair where the match is an exact match, secondly by setting a upper limit where the responding peer will not exceed. DiscoveryService can be performed in two ways 1. by specifying a null peerid, the discovery message is propagated on the local sub-net utilizing ip multicast. In addition to the multicast it is also propagated to rendezvous points. 2. by passing a peerid, the EndpointRouter will attempt to resolve destination peer's endpoints or route the message to other routers in attempt to reach the peer.
Parameters:
attribute - attribute name to narrow disocvery to
value - value of attribute to narrow disocvery to
threshold - the upper limit of responses from one peer
peerid - id of a peer, or "rendezvous" to connect to, if address is null
type - PEER, GROUP, ADV
Returns:
query ID for this discovery query
Since:
JXTA 1.0

getLocalAdvertisements

public java.util.Enumeration getLocalAdvertisements(int type,
                                                    java.lang.String attribute,
                                                    java.lang.String value)
                                             throws java.io.IOException
Retrieve Stored Peer, Group, and General Advertisements
Parameters:
type - PEER, GROUP, or ADV
attribute - attribute name to narrow the response to
value - value of the named attribute to narrow the response to
Returns:
Enumeration of stored advertisements/structured documents
Throws:
java.io.IOException - - If an I/O error occurs
Since:
JXTA 1.0

publish

public void publish(Advertisement advertisement,
                    int type)
             throws java.io.IOException
Publish an advertisement
Parameters:
advertisement - publish an adverisement within this group
type - PEER, GROUP, ADV
Throws:
java.io.IOException - - If an I/O error occurs
Since:
JXTA 1.0

publish

public void publish(Advertisement adv,
                    int type,
                    long lifetime,
                    long lifetimeForOthers)
             throws java.io.IOException
Publish an advertisement that will expire after a certain time. A node that finds this advertisement will hold it for about lifetimeForOthers milliseconds, while the peer that has originally published the advertisement will republish it about every lifetiemForOthers milliseconds, until lifetime expires.
Parameters:
advertisement - the advertisement
type - PEER, GROUP, ADV
lifetime - the amount of time this advertisement will live in my cache
lifetimeForOthers - the amount of time this advertisement will live in other people's caches.
Throws:
java.io.IOException - - If an I/O error occurs

remotePublish

public void remotePublish(Advertisement adv,
                          int type)
Remote Publish an advertisement
Parameters:
advertisement - publish an adverisement within this group
type - PEER, GROUP, ADV
Since:
JXTA 1.0

remotePublish

public void remotePublish(Advertisement adv,
                          int type,
                          long lifetime)
Remote Publish an advertisement
Parameters:
advertisement - publish an adverisement within this group
type - PEER, GROUP, ADV
lifetime - the amount of time to advise other nodes to hold this advertisement in their caches.
Since:
JXTA 1.0

flushAdvertisements

public void flushAdvertisements(java.lang.String id,
                                int type)
                         throws java.io.IOException
flush stored Documents.
Parameters:
id - Document ID, Peer ID, or PeerGroup ID
type - PEER, GROUP, ADV
Throws:
java.io.IOException - - If an I/O error occurs
Since:
JXTA 1.0

addDiscoveryListener

public void addDiscoveryListener(DiscoveryListener listener)
Add a discovery listener
Parameters:
DiscoveryListener - listener to receive discovery events

removeDiscoveryListener

public boolean removeDiscoveryListener(DiscoveryListener listener)
remove a discovery listener
Parameters:
DiscoveryListener - listener to remove
Returns:
true if the argument was a component of this vector; false otherwise

Project JXTA