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 the 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.

DiscoveryService also provides a mechanism for publishing advertisements, so that they may be discovered. The rules to follow when publishing are

use the current discovery service to publish advertisements private to the group.

        discovery.publish(adv,discovery.ADV);
 

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

        parent=soccerGroup.getParent();
        discovery= parent.getDiscoveryService()
        discovery.publish(adv,discovery.ADV);
 

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" ?>
       <DiscoveryQuery>
        <Type>int</Type>
        <Threshold>int</Threshold>
        <PeerAdv>peeradv</PeerPdv>
        <Attr>attribute</Attr>
        <Value>value</Value>
       </DiscoveryQuery>
 

A discovery Response

      <?xml version="1.0"?>
       <DiscoveryResponse>
        <Count>int<Count>
        <Type>int</Type>
        <PeerAdv> adv </PeerAdv>
        <Attr> attribute </Attr>
        <Value> value </Aalue>
        <Response Expiration="expiration" >adv</Response>
        ......
        <Response Expiration="expiration" >adv</Response>
      </DiscoveryResponse>
 

Since:

JXTA 1.0

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 Infintite lifetime for advertisements.
static long	NO_EXPIRATION Specifies that the advertisment will have no expiration and will be kept indefinitly.
static int	PEER DiscoveryService type Peer

Method Summary

void	addDiscoveryListener(DiscoveryListener listener) register a discovery listener, to notified on discovery events
void	flushAdvertisements(java.lang.String id, int type) flushs stored Advertisement(s),
long	getAdvExpirationTime(java.lang.String id, int type) Returns the maximum duration in milliseconds for which this document should cached by those other than the publisher.
long	getAdvLifeTime(java.lang.String id, int type) get Advertisement's life time
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 other jxta Advertisements.
int	getRemoteAdvertisements(java.lang.String peerid, int type, java.lang.String attribute, java.lang.String value, int threshold, DiscoveryListener listener) This method discovers PeerAdvertisements, GroupAdvertisements and jxta Advertisements.
void	publish(Advertisement advertisement, int type) Publish an advertisement with a default lifetime of DEFAULT_LIFETIME and default expiration time for "others" of DEFAULT_EXPIRATION
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 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, 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(java.lang.String peerid, Advertisement adv, int type) 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(java.lang.String peerid, Advertisement adv, int type, 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

GROUP

public static final int GROUP

DiscoveryService type Group

ADV

public static final int ADV

DiscoveryService type Advertisement

DEFAULT_LIFETIME

public static final long DEFAULT_LIFETIME

Default lifetime time for advertisements. This is the maxiumum 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.

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.

INFINITE_LIFETIME

public static final long INFINITE_LIFETIME

Infintite lifetime for advertisements. The advertisement is valid forever. (well maybe it will expire when the sun burns out, but not before then).

NO_EXPIRATION

public static final long NO_EXPIRATION

Specifies that the advertisment will have no expiration and will be kept indefinitly.

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 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 disocvery 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 disocvery 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 od PEER has a special behaviour peers respond with own adv only.

Returns:

query ID for this discovery query

Since:

JXTA 1.0

getRemoteAdvertisements

public int getRemoteAdvertisements(java.lang.String peerid,
                                   int type,
                                   java.lang.String attribute,
                                   java.lang.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 disocvery 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 disocvery 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 od 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

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 - Discovery type PEER, GROUP, ADV

attribute - attribute name to narrow disocvery 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 disocvery 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:

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 with a default lifetime of DEFAULT_LIFETIME and default expiration time for "others" of DEFAULT_EXPIRATION

Parameters:

advertisement - publish an adverisement within this group

type - Discovery 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, or lifetime whichever is smaller

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:

java.io.IOException - - If an I/O error occurs

remotePublish

public void remotePublish(Advertisement adv,
                          int type)

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

Since:

JXTA 1.0

remotePublish

public void remotePublish(Advertisement adv,
                          int type,
                          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:

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

Since:

JXTA 1.0

remotePublish

public void remotePublish(java.lang.String peerid,
                          Advertisement adv,
                          int type)

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

Since:

JXTA 1.0

remotePublish

public void remotePublish(java.lang.String peerid,
                          Advertisement adv,
                          int type,
                          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

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

Since:

JXTA 1.0

flushAdvertisements

public void flushAdvertisements(java.lang.String id,
                                int type)
                         throws java.io.IOException

flushs stored Advertisement(s),

Parameters:

id - Document ID, Peer ID, or PeerGroup ID, a null value flushs all content of type "type"

type - Discovery type PEER, GROUP, ADV

Throws:

java.io.IOException - - If an I/O error occurs

Since:

JXTA 1.0

getAdvExpirationTime

public long getAdvExpirationTime(java.lang.String id,
                                 int type)

Returns the maximum duration in milliseconds for which this document should 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

Since:

JXTA 1.0

getAdvLifeTime

public long getAdvLifeTime(java.lang.String id,
                           int type)

get Advertisement's life time

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

Since:

JXTA 1.0

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