|
JXTA | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface DiscoveryService
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:
discovery.publish(adv);
parent=soccerGroup.getParent(); discovery= parent.getDiscoveryService() discovery.publish(adv);
0
(zero).
Advertisements are often stored in a persistent local cache. This cache
can improve performance and responsiveness by retaining advertisements
between restarts.
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 |
---|
static final int PEER
static final int GROUP
static final int ADV
static final long DEFAULT_LIFETIME
static final long DEFAULT_EXPIRATION
static final long INFINITE_LIFETIME
static final long NO_EXPIRATION
Method Detail |
---|
int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold)
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 :
null
- Don't care. All advertisements with the matching
attribute
will be returned.attribute
field who's value exactly matches the string value
will be
returned.attribute
field who's value matches the wild card expression value
will be returned. eg. The following expressions all match against
"FooBar":
foO*
*Bar
*oBA*
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 typevalue
- 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 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.
int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold, DiscoveryListener listener)
null
peerid - The discovery query is
propagated on via the Rendezvous Service and via local sub-net
utilizing IP multicast.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 :
null
- Don't care. All advertisements with the matching
attribute
will be returned.attribute
field who's value exactly matches the string value
will be
returned.attribute
field who's value matches the wild card expression value
will be returned. eg. The following expressions all match against
"FooBar":
fOo*
*bAr
*OBa*
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 typevalue
- 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 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.
Enumeration<Advertisement> getLocalAdvertisements(int type, String attribute, String value) throws IOException
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 typevalue
- 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
IOException
- Thrown if an error occurs during retrieval.void publish(Advertisement adv) throws IOException
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.
adv
- The Advertisement to publish.
IOException
- When an error occurs during Advertisement publication.void publish(Advertisement adv, long lifetime, long expiration) throws IOException
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.
IOException
- When an error occurs during Advertisement publication.void remotePublish(Advertisement adv)
adv
- Advertisement to publish.void remotePublish(Advertisement adv, long expiration)
adv
- The Advertisement to publish.expiration
- Duration in relative milliseconds that this
Advertisement will be cached by other peers.void remotePublish(String peerid, Advertisement adv)
peerid
- The ID of a peer, specifying null results in
propagation within the group.adv
- The Advertisement to publish.void remotePublish(String peerid, Advertisement adv, long expiration)
peerid
- id of a peer, specifying null results in a propagate
within the groupadv
- The Advertisement to publish.expiration
- Duration in relative milliseconds that this
Advertisement will be cached by other peers.void flushAdvertisement(Advertisement adv) throws IOException
adv
- Advertisement to remove.
IOException
- If there is a problem removing the advertisement.void flushAdvertisements(String id, int type) throws IOException
id
- The Advertisement.getID()
value of the
Advertisement to be removed.type
- Discovery type PEER, GROUP, ADV.
IOException
- If there is a problem removing the advertisement.long getAdvExpirationTime(ID id, int type)
id
- Document ID, Peer ID, or PeerGroup IDtype
- Discovery type PEER, GROUP, ADV
long getAdvLifeTime(ID id, int type)
id
- Document ID, Peer ID, or PeerGroup IDtype
- Discovery type PEER, GROUP, ADV
long getAdvExpirationTime(Advertisement adv)
adv
- Advertisement
long getAdvLifeTime(Advertisement adv)
adv
- Advertisement
void addDiscoveryListener(DiscoveryListener listener)
listener
- the DiscoveryListenerboolean removeDiscoveryListener(DiscoveryListener listener)
getRemoteAdvertisements()
or addDiscoveryListener()
.
listener
- The listener to be removed.
|
JXSE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |