*  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 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);}