Project JXTA

net.jxta.discovery
Interface Discovery

All Superinterfaces:
Application, Service

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, a call to getLocalAdvertisements can be made to retrieve results that have been found and added to the local group cache. 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 int GROUP
          Group type
static int PEER
          Peer type
 
Method Summary
 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
 void 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 remotePublish(Advertisement adv, int type)
          Remote Publish an advertisement
 
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
Method Detail

getRemoteAdvertisements

public void 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
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

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

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

Project JXTA