JXTA

net.jxta.discovery
Interface DiscoveryService

All Superinterfaces:
Module, Service

public interface DiscoveryService
extends 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 :

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:

  discovery.getRemoteAdvertisements(null, discovery.ADV,
                                    "Name", "Score tracker*", 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.

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.

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.

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.

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 (zero).

Advertisements are often stored in a persistent local cache. This cache can improve performance and responsiveness by retaining advertisements between restarts.

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

Field Summary
static int ADV
          Discovery type Advertisement
static long DEFAULT_EXPIRATION
          Default expiration time for advertisements.
static long DEFAULT_LIFETIME
          Default lifetime time for advertisements.
static int GROUP
          Discovery 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
          Discovery type Peer
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Method Summary
 void addDiscoveryListener(DiscoveryListener listener)
          Register a Discovery listener.
 void flushAdvertisement(Advertisement adv)
          Removes the specified Advertisement from the cache of locally stored Advertisements.
 void flushAdvertisements(String id, int type)
          Removes the specified Advertisement from the cache of locally stored Advertisements.
 long getAdvExpirationTime(Advertisement adv)
          Returns the maximum duration in milliseconds for which this document will be cached by peers other than the publisher.
 long getAdvExpirationTime(ID id, int type)
          Returns the maximum duration in milliseconds for which this document will be cached by peers 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<Advertisement> getLocalAdvertisements(int type, String attribute, String value)
          Retrieve locally stored Advertisements.
 int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold)
          Discover advertisements from remote peers.
 int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold, DiscoveryListener listener)
          Discover advertisements from remote peers.
 void publish(Advertisement adv)
          Publish an Advertisement.
 void publish(Advertisement adv, long lifetime, long expiration)
          Publish an Advertisement.
 void remotePublish(Advertisement adv)
          Publish an Advertisement via propagation to other peers on the network.
 void remotePublish(Advertisement adv, long expiration)
          Publish an Advertisement via propagation to other peers on the network.
 void remotePublish(String peerid, Advertisement adv)
          Publish an Advertisement to another peer on the network.
 void remotePublish(String peerid, Advertisement adv, long expiration)
          Publish an Advertisement to another peer on the network.
 boolean removeDiscoveryListener(DiscoveryListener listener)
          Remove a Discovery listener which was previously registered with getRemoteAdvertisements() or addDiscoveryListener().
 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 

Field Detail

PEER

static final int PEER
Discovery type Peer

See Also:
Constant Field Values

GROUP

static final int GROUP
Discovery type Group

See Also:
Constant Field Values

ADV

static final int ADV
Discovery type Advertisement

See Also:
Constant Field Values

DEFAULT_LIFETIME

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

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

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

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

int getRemoteAdvertisements(String peerid,
                            int type,
                            String attribute,
                            String value,
                            int threshold)
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.

Discovery can be performed in two ways :

The scope of advertisements returned can be narrowed by specifying an attribute and value pair. The attribute is a case-sensitive string matching the name of an Advertisement XML tag who's values will be matched by the value. Only a limited number of Advertisement XML fields are indexed. Advertisement.getIndexFields() will return the fields on which you may query for a particular Advertisement type.

The value is a case-insensitive string who's value is matched against the values of attribute fields of Advertisements. The value may be of several forms :

Parameters:
peerid - If provided the query will be forwarded to the specified peer. If null then the query will be propagated through the network to peers with matching Advertisements.
type - Discovery type; PEER, GROUP or ADV.
attribute - indexed element name (see advertisement(s) for a list of indexed fields. A null attribute indicates any advertisement of specified type
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 maximum number of matching advertisements which be returned by each responding peer. A threshold of 0, and type of PEER has a special behaviour.
Returns:
query ID for this discovery query.

getRemoteAdvertisements

int getRemoteAdvertisements(String peerid,
                            int type,
                            String attribute,
                            String value,
                            int threshold,
                            DiscoveryListener listener)
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.

Discovery can be performed in two ways :

The scope of advertisements returned can be narrowed by specifying an attribute and value pair. The attribute is a case-sensitive string matching the name of an Advertisement XML tag who's values will be matched by the value. Only a limited number of Advertisement XML fields are indexed. Advertisement.getIndexFields() will return the fields on which you may query for a particular Advertisement type.

The value is a case-insensitive string who's value is matched against the values of attribute fields of Advertisements. The value may be of several forms :

Parameters:
peerid - If provided the query will be forwarded to the specified peer. If null then the query will be propagated through the network to peers with matching Advertisements.
type - Discovery type; PEER, GROUP or ADV.
attribute - indexed element name (see Advertisement(s) for a list of indexed fields. A null attribute indicates any advertisement of specified type
value - value of attribute to narrow discovery to. Valid values for this parameter or 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 maximum number of matching advertisements which be returned by each responding peer. A threshold of 0, and type of PEER has a special behaviour.
listener - The listener which will be called when advertisement which match this query are discovered or null if no callback is desired.
Returns:
query ID for this discovery query.

getLocalAdvertisements

Enumeration<Advertisement> getLocalAdvertisements(int type,
                                                  String attribute,
                                                  String value)
                                                  throws IOException
Retrieve locally stored Advertisements. This is an exhaustive search of the locally cached results. All valid known matching results will be returned.

Parameters:
type - Discovery type; PEER, GROUP or ADV.
attribute - indexed element name (see Advertisement(s) for a list of indexed fields. null indicates any advertisement of specified type
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.
Throws:
IOException - Thrown if an error occurs during retrieval.

publish

void publish(Advertisement adv)
             throws IOException
Publish an Advertisement. The Advertisement will expire automatically on the local peer after DEFAULT_LIFETIME and will expire on other peers after DEFAULT_EXPIRATION.

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 publishes index updates every 30 seconds.

Parameters:
adv - The Advertisement to publish.
Throws:
IOException - When an error occurs during Advertisement publication.

publish

void publish(Advertisement adv,
             long lifetime,
             long expiration)
             throws IOException
Publish an Advertisement. The Advertisement will expire automatically after the specified time. A peer that discovers this advertisement will hold it for about expiration or lifetime milliseconds, whichever is smaller.

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 publishes index updates every 30 seconds.

Parameters:
adv - The Advertisement to publish.
lifetime - Duration in relative milliseconds that this advertisement will exist.
expiration - Duration in relative milliseconds that this advertisement will be cached by other peers.
Throws:
IOException - When an error occurs during Advertisement publication.

remotePublish

void remotePublish(Advertisement adv)
Publish an Advertisement via propagation to other peers on the network. This does not result in the advertisement being stored locally. The Advertisement will be published with an expiration time of DEFAULT_EXPIRATION.

Parameters:
adv - Advertisement to publish.

remotePublish

void remotePublish(Advertisement adv,
                   long expiration)
Publish an Advertisement via propagation to other peers on the network. This does not result in the advertisement being stored locally.

Parameters:
adv - The Advertisement to publish.
expiration - Duration in relative milliseconds that this Advertisement will be cached by other peers.

remotePublish

void remotePublish(String peerid,
                   Advertisement adv)
Publish an Advertisement to another peer on the network. This does not result in the advertisement being stored locally. The Advertisement will be published with an expiration time of DEFAULT_EXPIRATION.

Parameters:
peerid - The ID of a peer, specifying null results in propagation within the group.
adv - The Advertisement to publish.

remotePublish

void remotePublish(String peerid,
                   Advertisement adv,
                   long expiration)
Publish an Advertisement to another peer on the network. This does not result in the advertisement being stored locally.

Parameters:
peerid - id of a peer, specifying null results in a propagate within the group
adv - The Advertisement to publish.
expiration - Duration in relative milliseconds that this Advertisement will be cached by other peers.

flushAdvertisement

void flushAdvertisement(Advertisement adv)
                        throws IOException
Removes the specified Advertisement from the cache of locally stored Advertisements.

Parameters:
adv - Advertisement to remove.
Throws:
IOException - If there is a problem removing the advertisement.

flushAdvertisements

void flushAdvertisements(String id,
                         int type)
                         throws IOException
Removes the specified Advertisement from the cache of locally stored Advertisements.

Parameters:
id - The Advertisement.getID() value of the Advertisement to be removed.
type - Discovery type PEER, GROUP, ADV.
Throws:
IOException - If there is a problem removing the advertisement.

getAdvExpirationTime

long getAdvExpirationTime(ID id,
                          int type)
Returns the maximum duration in milliseconds for which this document will be cached by peers other than the publisher. This value is either the stored 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 number of milliseconds that other peers will be told to retain this Advertisement in their local caches. -1 is returned if the Advertisement is not known or already expired.

getAdvLifeTime

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 number of milliseconds this Advertisement will remain in the local cache unless refreshed before that time. -1 is returned if the Advertisement is not known or already expired.

getAdvExpirationTime

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

Parameters:
adv - Advertisement
Returns:
The number of milliseconds that other peers will be told to retain this Advertisement in their local caches. -1 is returned if the Advertisement is not known or already expired.

getAdvLifeTime

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 number of milliseconds this Advertisement will remain in the local cache unless refreshed before that time. -1 is returned if the Advertisement is not known or already expired.

addDiscoveryListener

void addDiscoveryListener(DiscoveryListener listener)
Register a Discovery listener. The Discovery listener will be called whenever Advertisement responses are received from remote peers by the Discovery Service.

Parameters:
listener - the DiscoveryListener

removeDiscoveryListener

boolean removeDiscoveryListener(DiscoveryListener listener)
Remove a Discovery listener which was previously registered with getRemoteAdvertisements() or addDiscoveryListener().

Parameters:
listener - The listener to be removed.
Returns:
true if the listener was successfully removed, false otherwise

JXSE