Project JXTA

net.jxta.discovery
Interface DiscoveryService

All Superinterfaces:
Module, Service

public interface DiscoveryService
extends 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 discovery is limited to the group. For example :

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:

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

 

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.

Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at 30 second intervals

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 often stored in a persistent local cache. When a peer restarts 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.

See Also:
Service, ResolverService, DiscoveryQueryMsg, DiscoveryResponseMsg, ResolverQueryMsg, ResolverResponseMsg

Field Summary
static int ADV
          DiscoveryService type Advertisement
static long DEFAULT_EXPIRATION
          Default expiration time for advertisements.
static long DEFAULT_LIFETIME
          Default lifetime time for advertisements.
static int GROUP
          DiscoveryService type Group
static long INFINITE_LIFETIME
          infinite lifetime for advertisements.
static long NO_EXPIRATION
          Specifies that the advertisement will have no expiration and will be kept indefinitely.
static int PEER
          DiscoveryService type Peer
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_OK
 
Method Summary
 void addDiscoveryListener(DiscoveryListener listener)
          register a discovery listener, to notified on discovery events
 void flushAdvertisement(Advertisement adv)
          flush a stored Advertisement
 void flushAdvertisements(String id, int type)
          flushs stored Advertisement(s),
 long getAdvExpirationTime(Advertisement adv)
          Returns the maximum duration in milliseconds for which this document should be cached by those other than the publisher.
 long getAdvExpirationTime(ID id, int type)
          Returns the maximum duration in milliseconds for which this document should be cached by those other than the publisher.
 long getAdvLifeTime(Advertisement adv)
          Returns the maximum duration in milliseconds for which this document should be kept in local cache
 long getAdvLifeTime(ID id, int type)
          Returns the maximum duration in milliseconds for which this document should be kept in local cache
 Enumeration getLocalAdvertisements(int type, String attribute, String value)
          Retrieve Stored Peer, Group, and General Advertisements
 int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold)
          This method discovers PeerAdvertisements, GroupAdvertisements and other jxta Advertisements. jxta Advertisements are documents that describe pipes, services, etc.
 int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold, DiscoveryListener listener)
          This method discovers PeerAdvertisements, GroupAdvertisements and jxta Advertisements. jxta Advertisements are documents that describe pipes, services, etc.
 void publish(Advertisement advertisement)
          Publish an advertisement with a default lifetime of DEFAULT_LIFETIME and default expiration time for "others" of DEFAULT_EXPIRATION Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at a an implementation specified interval
 void publish(Advertisement advertisement, int type)
          Deprecated. Advertisement type is no longer required to publish an advertisement
 void publish(Advertisement adv, int type, long lifetime, long lifetimeForOthers)
          Deprecated. Advertisement type is no longer required to publish an advertisement
 void publish(Advertisement adv, long lifetime, long lifetimeForOthers)
          Publish an advertisement that will expire after a certain time.
 void remotePublish(Advertisement adv)
          Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller
 void remotePublish(Advertisement adv, int type)
          Deprecated. Advertisement type is no longer required to remote publish an advertisement
 void remotePublish(Advertisement adv, int type, long lifetime)
          Deprecated. Advertisement type is no longer required to remote publish an advertisement
 void remotePublish(Advertisement adv, long lifetime)
          Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime
 void remotePublish(String peerid, Advertisement adv)
          Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller
 void remotePublish(String peerid, Advertisement adv, int type)
          Deprecated. Advertisement type is no longer required to remote publish an advertisement
 void remotePublish(String peerid, Advertisement adv, int type, long lifetime)
          Deprecated. Advertisement type is no longer required to remote publish an advertisement
 void remotePublish(String peerid, Advertisement adv, long lifetime)
          Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime
 boolean removeDiscoveryListener(DiscoveryListener listener)
          remove a discovery listener
 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 

Field Detail

PEER

public static final int PEER
DiscoveryService type Peer

See Also:
Constant Field Values

GROUP

public static final int GROUP
DiscoveryService type Group

See Also:
Constant Field Values

ADV

public static final int ADV
DiscoveryService type Advertisement

See Also:
Constant Field Values

DEFAULT_LIFETIME

public static final long DEFAULT_LIFETIME
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.

See Also:
Constant Field Values

DEFAULT_EXPIRATION

public static final long DEFAULT_EXPIRATION
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.

See Also:
Constant Field Values

INFINITE_LIFETIME

public static final long INFINITE_LIFETIME
infinite lifetime for advertisements. The advertisement is valid forever. (well maybe it will expire when the sun burns out, but not before then).

See Also:
Constant Field Values

NO_EXPIRATION

public static final long NO_EXPIRATION
Specifies that the advertisement will have no expiration and will be kept indefinitely.

See Also:
Constant Field Values
Method Detail

getRemoteAdvertisements

public int getRemoteAdvertisements(String peerid,
                                   int type,
                                   String attribute,
                                   String value,
                                   int threshold)
This method discovers PeerAdvertisements, GroupAdvertisements and other 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. Discovery 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:
peerid - id of a peer, specifying null results in a propagate within the group
type - Discovery type PEER, GROUP, ADV
attribute - attribute name to narrow discovery to Valid values for this parameter are null (don't care), or exact element name in the advertisement of interest (e.g. "Name")
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 FooBar , a value of "*bar", "foo*", or "*ooB*", will return the Advertisement
threshold - the upper limit of responses from one peer threshold of 0, and type of PEER has a special behaviour peers respond with own adv only.
Returns:
query ID for this discovery query

getRemoteAdvertisements

public int getRemoteAdvertisements(String peerid,
                                   int type,
                                   String attribute,
                                   String value,
                                   int threshold,
                                   DiscoveryListener listener)
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. DiscoveryServiceImpl 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 discovery to Valid values for this parameter are null (don't care), or exact element name in the advertisement of interest (e.g. "Name")
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 FooBar , a value of "*bar", "foo*", or "*ooB*", will return the Advertisement
threshold - the upper limit of responses from one peer threshold of 0, and type of PEER has a special behaviour
peerid - id of a peer, specifying null results in a propagate within the group
type - Discovery type PEER, GROUP, ADV
listener - the listener which will be called back with found advertisements.
Returns:
query ID for this discovery query

getLocalAdvertisements

public Enumeration getLocalAdvertisements(int type,
                                          String attribute,
                                          String value)
                                   throws IOException
Retrieve Stored Peer, Group, and General Advertisements

Parameters:
type - Discovery type PEER, GROUP, ADV
attribute - attribute name to narrow discovery to Valid values for this parameter are null (don't care), or exact element name in the advertisement of interest (e.g. "Name")
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 FooBar , a value of "*bar", "foo*", or "*ooB*", will return the Advertisement
Returns:
Enumeration of stored advertisements/structured documents
Throws:
IOException - - If an I/O error occurs

publish

public void publish(Advertisement advertisement)
             throws IOException
Publish an advertisement with a default lifetime of DEFAULT_LIFETIME and default expiration time for "others" of DEFAULT_EXPIRATION Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at a an implementation specified interval

Parameters:
advertisement - publish an advertisement within this group
Throws:
IOException - - If an I/O error occurs

publish

public void publish(Advertisement advertisement,
                    int type)
             throws IOException
Deprecated. Advertisement type is no longer required to publish an advertisement

Publish an advertisement with a default lifetime of DEFAULT_LIFETIME and default expiration time for "others" of DEFAULT_EXPIRATION Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at a an implementation specified interval

Parameters:
advertisement - publish an advertisement within this group
type - Discovery type PEER, GROUP, ADV
Throws:
IOException - - If an I/O error occurs

publish

public void publish(Advertisement adv,
                    long lifetime,
                    long lifetimeForOthers)
             throws IOException
Publish an advertisement that will expire after a certain time. A node that finds this advertisement will hold it for about lifetimeForOthers milliseconds, or lifetime whichever is smaller Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at an implementation specified interval

Parameters:
lifetime - the amount of time this advertisement will live in my cache in milliseconds
lifetimeForOthers - the amount of time this advertisement will live in other people's caches in milliseconds.
adv - advertisement to publish
Throws:
IOException - - If an I/O error occurs

publish

public void publish(Advertisement adv,
                    int type,
                    long lifetime,
                    long lifetimeForOthers)
             throws IOException
Deprecated. Advertisement type is no longer required to publish an advertisement

Publish an advertisement that will expire after a certain time. A node that finds this advertisement will hold it for about lifetimeForOthers milliseconds, or lifetime whichever is smaller Advertisement indexes are shared with a rendezvous peer upon connect, and subsequent publications are shared at an implementation specified interval

Parameters:
type - Discovery type PEER, GROUP, ADV
lifetime - the amount of time this advertisement will live in my cache in milliseconds
lifetimeForOthers - the amount of time this advertisement will live in other people's caches in milliseconds.
adv - advertisement to publish
Throws:
IOException - - If an I/O error occurs

remotePublish

public void remotePublish(Advertisement adv,
                          int type)
Deprecated. Advertisement type is no longer required to remote publish an advertisement

Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller

Parameters:
type - Discovery type PEER, GROUP, ADV
adv - advertisement to publish

remotePublish

public void remotePublish(Advertisement adv)
Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller

Parameters:
adv - advertisement to publish

remotePublish

public void remotePublish(Advertisement adv,
                          int type,
                          long lifetime)
Deprecated. Advertisement type is no longer required to remote publish an advertisement

Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime

Parameters:
type - Discovery type PEER, GROUP, ADV
lifetime - the amount of time to advise other nodes to hold this advertisement in their caches.
adv - advertisement to publish

remotePublish

public void remotePublish(Advertisement adv,
                          long lifetime)
Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime

Parameters:
lifetime - the amount of time to advise other nodes to hold this advertisement in their caches.
adv - advertisement to publish

remotePublish

public void remotePublish(String peerid,
                          Advertisement adv,
                          int type)
Deprecated. Advertisement type is no longer required to remote publish an advertisement

Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller

Parameters:
peerid - id of a peer, specifying null results in a propagate within the group
type - Discovery type PEER, GROUP, ADV
adv - advertisement to publish

remotePublish

public void remotePublish(String peerid,
                          Advertisement adv)
Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a lifetime of Expiration time, or lifetime whichever is smaller

Parameters:
peerid - id of a peer, specifying null results in a propagate within the group
adv - advertisement to publish

remotePublish

public void remotePublish(String peerid,
                          Advertisement adv,
                          int type,
                          long lifetime)
Deprecated. Advertisement type is no longer required to remote publish an advertisement

Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime

Parameters:
peerid - id of a peer, specifying null results in a propagate within the group
type - Discovery type PEER, GROUP, ADV
lifetime - the amount of time to advise other nodes to hold this advertisement in their caches.
adv - advertisement to publish

remotePublish

public void remotePublish(String peerid,
                          Advertisement adv,
                          long lifetime)
Remote Publish an advertisement will attempt to remote publish adv on all configured transports, the Advertisement will carry a a expiration of lifetime

Parameters:
peerid - id of a peer, specifying null results in a propagate within the group
lifetime - the amount of time to advise other nodes to hold this advertisement in their caches.
adv - advertisement to publish

flushAdvertisement

public void flushAdvertisement(Advertisement adv)
                        throws IOException
flush a stored Advertisement

Parameters:
adv - Advertisement to remove
Throws:
IOException - - If an I/O error occurs

flushAdvertisements

public void flushAdvertisements(String id,
                                int type)
                         throws IOException
flushs stored Advertisement(s),

Parameters:
id - Document ID, Peer ID, or PeerGroup ID flushs all content of type "type"
type - Discovery type PEER, GROUP, ADV
Throws:
IOException - - If an I/O error occurs

getAdvExpirationTime

public long getAdvExpirationTime(ID id,
                                 int type)
Returns the maximum duration in milliseconds for which this document should be cached by those other than the publisher. This value is either the cache lifetime or the remaining lifetime of the document, whichever is less.

Parameters:
id - Document ID, Peer ID, or PeerGroup ID
type - Discovery type PEER, GROUP, ADV
Returns:
the relative time in milliseconds at which remote peers should refresh this document. -1 is returned if the file is not known or already expired

getAdvLifeTime

public long getAdvLifeTime(ID id,
                           int type)
Returns the maximum duration in milliseconds for which this document should be kept in local cache

Parameters:
id - Document ID, Peer ID, or PeerGroup ID
type - Discovery type PEER, GROUP, ADV
Returns:
the relative time in milliseconds at which remote peers should refresh this document. -1 is returned if the file is not known or already expired

getAdvExpirationTime

public long getAdvExpirationTime(Advertisement adv)
Returns the maximum duration in milliseconds for which this document should be cached by those other than the publisher. This value is either the cache lifetime or the remaining lifetime of the document, whichever is less.

Parameters:
adv - Advertisement
Returns:
the relative time in milliseconds at which remote peers should refresh this document. -1 is returned if the file is not known or already expired

getAdvLifeTime

public long getAdvLifeTime(Advertisement adv)
Returns the maximum duration in milliseconds for which this document should be kept in local cache

Parameters:
adv - Advertisement
Returns:
the relative time in milliseconds at which remote peers should refresh this document. -1 is returned if the file is not known or already expired

addDiscoveryListener

public void addDiscoveryListener(DiscoveryListener listener)
register a discovery listener, to notified on discovery events

Parameters:
listener - The feature to be added to the DiscoveryListener attribute

removeDiscoveryListener

public boolean removeDiscoveryListener(DiscoveryListener listener)
remove a discovery listener

Parameters:
listener - listener to be called back for discovery events
Returns:
true if the argument was a component of this vector; false otherwise

JXTA J2SE