discoveryservice.java

JXTA&#8482 is a set of open, generalized peer-to-peer (P2P) protocols that allow any networked devi

     *  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. 
     * 
     *  <p/>Discovery can be performed in two ways : <ul>
     *      <li>With a {@code null} peerid - The discovery query is
     *      propagated on via the Rendezvous Service and via local sub-net
     *      utilizing IP multicast.</li>
     *      <li>With a provided peerid - The discovery query is forwarded to the
     *      specified peer.</li>
     *  </ul>
     *
     *  <p/>The scope of advertisements returned can be narrowed by specifying
     *  an {@code attribute} and {@code value} pair. The {@code attribute} is
     *  a case-sensitive string matching the name of an Advertisement XML tag
     *  who's values will be matched by the {@code value}. Only a limited number
     *  of Advertisement XML fields are indexed. {@link
     *  net.jxta.document.Advertisement#getIndexFields()} will return the 
     *  fields on which you may query for a particular Advertisement type. 
     * 
     *  <p/>The {@code value} is a case-insensitive string who's value is
     *  matched against the values of {@code attribute} fields of Advertisements.
     *  The {@code} value may be of several forms :
     *  <ul>
     *      <li>{@code null} - Don't care. All advertisements with the matching
     *      {@code attribute} will be returned.</li>
     *      <li>exact value - Only advertisements with an {@code attribute}
     *      field who's value exactly matches the string {@code value} will be
     *      returned.</li>
     *      <li>wild card - Only advertisements with an {@code attribute}
     *      field who's value matches the wild card expression {@code value} 
     *      will be returned. eg. The following expressions all match against
     *      "FooBar":
     *      <ul>
     *          <li>{@code fOo*}</li>
     *          <li>{@code *bAr}</li>
     *          <li>{@code *OBa*}</li>
     *      </ul></li>
     *  </ul>
     * 
     * @param peerid If provided the query will be forwarded to the specified
     *      peer. If {@code null} then the query will be propagated through the
     *      network to peers with matching Advertisements.
     *  @param type Discovery type; <tt>PEER</tt>, <tt>GROUP</tt> or <tt>ADV</tt>.
     * @param  attribute  indexed element name (see Advertisement(s) for a
     *       list of indexed fields. A null attribute indicates any advertisement
     *       of specified type
     * @param  value      value of attribute to narrow discovery to. Valid values 
     *      for this parameter or {@code null} (don't care), Exact value, or use
     *      of wild card(s) (e.g. if a Advertisement defines <Name>FooBar</name>,
     *      a value of "*bar", "foo*", or "*ooB*", will return the Advertisement
     * @param  threshold  The maximum number of matching advertisements which
     *      be returned by each responding peer. A {@code threshold} of 0, and 
     *      {@code type} of {@code PEER} has a special behaviour.
     * @param  listener   The listener which will be called when advertisement
     *      which match this query are discovered or {@code null} if no 
     *      callback is desired.
     * @return query ID for this discovery query.
     */
    public int getRemoteAdvertisements(String peerid, int type, String attribute, String value, int threshold, DiscoveryListener listener);

    /**
     *  Retrieve locally stored Advertisements. This is an exhaustive search of
     *  the locally cached results. All valid known matching results will be 
     *  returned.
     *
     *  @param type Discovery type; <tt>PEER</tt>, <tt>GROUP</tt> or <tt>ADV</tt>.
     *  @param  attribute     indexed element name (see Advertisement(s) for a
     *       list of indexed fields. {@code null} indicates any advertisement
     *       of specified type
     *  @param  value         value of attribute to narrow discovery to valid
     *      values for this parameter are {@code null} (don't care), Exact 
     *      value, or use of wild card(s) (e.g. if a Advertisement defines 
     *      <Name>FooBar</name> , a value of "*bar", "foo*", or "*ooB*", will 
     *      return the Advertisement
     *  @return Enumeration of stored advertisements.
     *  @throws  IOException Thrown if an error occurs during retrieval.
     */
    public Enumeration<Advertisement> getLocalAdvertisements(int type, String attribute, String value) throws IOException;

    /**
     * Publish an Advertisement. The Advertisement will expire automatically 
     * on the local peer after <code>DEFAULT_LIFETIME</code> and will expire on
     * other peers after <code>DEFAULT_EXPIRATION</code>.
     *
     * <p/>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.
     *
     * @param adv The Advertisement to publish.
     * @throws IOException When an error occurs during Advertisement publication.
     */
    public void publish(Advertisement adv) 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 <tt>expiration</tt> or <tt>lifetime</tt> milliseconds, 
     * whichever is smaller.
     *
     * <p/>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.
     *
     * @param adv The Advertisement to publish.
     * @param lifetime Duration in relative milliseconds that this advertisement will exist.
     * @param expiration Duration in relative milliseconds that this advertisement will be cached by other peers.
     * @throws IOException When an error occurs during Advertisement publication.
     */
    public void publish(Advertisement adv, long lifetime, long expiration) throws IOException;

    /**
     * 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
     * <tt>DEFAULT_EXPIRATION</tt>.
     *
     *  @param adv Advertisement to publish.
     */
    public 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.
     *
     *  @param adv The Advertisement to publish.
     *  @param expiration  Duration in relative milliseconds that this 
     *      Advertisement will be cached by other peers.
     */
    public void remotePublish(Advertisement adv, long expiration);

    /**
     * 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
     * <tt>DEFAULT_EXPIRATION</tt>.
     *
     *@param peerid The ID of a peer, specifying <tt>null</tt> results in  
     *      propagation within the group.
     *@param adv The Advertisement to publish.
     */
    public 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.
     *
     *  @param  peerid id of a peer, specifying null results in a propagate
     *      within the group
     * @param adv The Advertisement to publish.
     * @param expiration  Duration in relative milliseconds that this 
     *      Advertisement will be cached by other peers.
     */
    public void remotePublish(String peerid, Advertisement adv, long expiration);
    
    /**
     * Removes the specified Advertisement from the cache of locally stored
     * Advertisements.
     *
     * @param adv Advertisement to remove.
     * @throws IOException If there is a problem removing the advertisement.
     */
    public void flushAdvertisement(Advertisement adv)  throws IOException;

    /**
     * Removes the specified Advertisement from the cache of locally stored
     * Advertisements.
     *
     * @param id The {@link Advertisement#getID()} value of the
     *      Advertisement to be removed.
     * @param type Discovery type PEER, GROUP, ADV.
     * @throws IOException If there is a problem removing the advertisement.
     */
    public void flushAdvertisements(String id, int type) throws IOException;

    /**
     *  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.
     *
     *  @param id Document ID, Peer ID, or PeerGroup ID
     *  @param type Discovery type PEER, GROUP, ADV
     *  @return 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.
     */
    public long getAdvExpirationTime(ID id, int type);

    /**
     *  Returns the maximum duration in milliseconds for which this document
     *  should be kept in local cache.
     *
     *  @param id Document ID, Peer ID, or PeerGroup ID
     *  @param type Discovery type PEER, GROUP, ADV
     *  @return 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.
     */
    public long getAdvLifeTime(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.
     *
     *  @param adv Advertisement
     *  @return 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.
     */
    public long getAdvExpirationTime(Advertisement adv);

    /**
     *  Returns the maximum duration in milliseconds for which this document
     *  should be kept in local cache.
     *
     *  @param adv Advertisement
     *  @return 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.
     */
    public long getAdvLifeTime(Advertisement adv);

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

    /**
     *  Remove a Discovery listener which was previously registered with
     *  {@link #getRemoteAdvertisements(String,int,String,String,int,DiscoveryListener) getRemoteAdvertisements()}
     *  or {@link #addDiscoveryListener(DiscoveryListener) addDiscoveryListener()}.
     *
     *  @param listener The listener to be removed.
     *  @return true if the listener was successfully removed, false otherwise
     */
    public boolean removeDiscoveryListener(DiscoveryListener listener);
}