rendezvousservice.java

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

     */
    public boolean removeListener(RendezvousListener listener);

    /**
     * Propagates a message to the local network and to as many members of
     * the peer group as possible.
     *
     * <p/>This method sends the message to all peers, rendezvous peers and
     * edge peer. This method of propagation is very expensive and should
     * be used very cautiously. When rendezvous peers are used in order to
     * cache index of data, it is more efficient to use the walk() method.
     *
     * <p/>Only a single HOP at a time is performed. Messages are always
     * delivered to the destination handler on arrival. This handler
     * is responsible for repropagating further, if deemed appropriate.
     *
     * <p/>Loop and TTL control are performed automatically.
     *
     * <p/>Messages can be propagated via this method for the first time or
     * can be re-propagated by re-using a message that came in via propagation.
     * In the later case, the TTL and loop detection parameters CANNOT be
     * re-initialized. If one wants to "re-propagate" a message with a new TTL
     * and blank gateways list one must generate a completely new message.
     * This limits the risk of accidental propagation storms, although they
     * can always be engineered deliberately.
     *
     * @param  msg              is the message to propagate.
     * @param  serviceName      is the name of the service.
     * @param  serviceParam     is the parameter of the service.
     * @param  ttl              The requested TTL for the message.
     * @exception  IOException  if an io error occurs
     */
    public void propagate(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * Propagates a message to the specified peers.
     *
     * @param  destPeerIds      An enumeration of PeerIDs of the peers that are the
     * intended recipients of the propagated message.
     * @param  msg              The message to propagate.
     * @param  serviceName      The name of the service.
     * @param  serviceParam     The parameter of the service.
     * @param  ttl              The requested TTL for the message.
     * @exception  IOException  if an io error occurs
     */
    public void propagate(Enumeration<? extends ID> destPeerIds, Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * Propagates a message to members of the peer group reachable via the
     * local network. Typically this is accomplished by broadcasting or
     * multicasting.
     *
     * <p/>Only a single HOP at a time is performed. Messages are always
     * delivered to the destination handler on arrival. This handler
     * is responsible for repropagating further, if deemed appropriate.
     *
     * <p/>Loop and TTL control are performed automatically.
     *
     * <p/>Messages can be propagated via this method for the first time or
     * can be re-propagated by re-using a message that came in via propagation.
     * In the later case, the TTL and loop detection parameters CANNOT be
     * re-initialized. If one wants to "re-propagate" a message with a new TTL
     * and blank gateways list one must generate a completely new message.
     * This limits the risk of accidental propagation storms, although they
     * can always be engineered deliberately.
     *
     * @param  msg              is the message to propagate.
     * @param  serviceName      is the name of the service.
     * @param  serviceParam     is the parameter of the service.
     * @param  ttl              The requested TTL for the message.
     * @exception  IOException  if an io error occurs
     */
    public void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * Propagates a message to as many members of the peer group as possible.
     *
     * <p/>Only a single HOP at a time is performed. Messages are always
     * delivered to the destination handler on arrival. This handler
     * is responsible for repropagating further, if deemed appropriate.
     *
     * <p/>Loop and TTL control are performed automatically.
     *
     * <p/>Messages can be propagated via this method for the first time or
     * can be re-propagated by re-using a message that came in via propagation.
     * In the later case, the TTL and loop detection parameters CANNOT be
     * re-initialized. If one wants to "re-propagate" a message with a new TTL
     * and blank gateways list one must generate a completely new message.
     * This limits the risk of accidental propagation storms, although they
     * can always be engineered deliberately.
     *
     * @param  msg              is the message to propagate.
     * @param  serviceName      is the name of the service
     * @param  serviceParam     is the parameter of the service
     * @param  ttl              The requested TTL for the message.
     * @exception  IOException  if an io error occurs
     */
    public void propagateInGroup(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * Return {@code true} if connected to a rendezvous.
     *
     * @return {@code true} if connected to a rendezvous otherwise {@code false}.
     */
    public boolean isConnectedToRendezVous();

    /**
     * Returns {@code true} if this peer is acting as a rendezvous peer (per the
     * implementation definition) within the peer group. {@code false} is
     * returned for all other peer roles.
     *
     * @return {@code true} if this peer is acting as a rendezvous peer (per the
     * implementation definition) within the peer group. {@code false} is
     * returned for all other peer roles.
     */
    public boolean isRendezVous();

    /**
     * Returns the current role of this peer within the peergroup.
     *
     * @return The current role of this peer within the peergroup.
     */
    public RendezVousStatus getRendezVousStatus();

    /**
     *  Enable or disable the automatic switching between an Edge Peer
     *  and a Rendezvous Peer.
     *
     * @param auto {@code true} will activate automatic role switching.
     * @return The previous auto start value.
     */
    public boolean setAutoStart(boolean auto);

    /**
     *  Enable or disable the automatic switching between an Edge Peer
     *  and a Rendezvous Peer.
     *
     * @param auto {@code true} will activate automatic role switching.
     * @param period The interval in milliseconds at which the peer should
     * reconsider it's role.
     * @return The previous auto start value.
     */
    public boolean setAutoStart(boolean auto, long period);

    /**
     * Walk a message through the rendezvous peers of the network: only
     * rendezvous peers will receive the message.
     *
     * <p/>Only a single HOP at a time is performed. Messages are always
     * delivered to the destination handler on arrival. This handler
     * is responsible for repropagating further, if deemed appropriate.
     *
     * <p/>Loop and TTL control are performed automatically.
     *
     * <p/>Messages can be propagated via this method for the first time or
     * can be re-propagated by re-using a message that came in via propagation.
     * In the later case, the TTL and loop detection parameters CANNOT be
     * re-initialized. If one wants to "re-propagate" a message with a new TTL
     * and blank gateways list one must generate a completely new message.
     * This limits the risk of accidental propagation storms, although they
     * can always be engineered deliberately.
     *
     * <p/><b>Note</b>: The original msg is not modified and may be reused upon return.
     *
     * @param  msg           is the message to walk.
     * @param  serviceName   is the name of the service
     * @param  serviceParam  is the parameter of the service
     * @param  ttl           is the maximum TTL of the message.
     * @throws  IOException  when walking the message is impossible (network failure)
     */
    public void walk(Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * <p/>Walk a message through the rendezvous peers of the network: only
     * rendezvous peers will receive the message.
     *
     * <p/>Only a single HOP at a time is performed. Messages are always
     * delivered to the destination handler on arrival. This handler
     * is responsible for repropagating further, if deemed appropriate.
     *
     * <p/>Loop and TTL control are performed automatically.
     *
     * <p/>Messages can be propagated via this method for the first time or
     * can be re-propagated by re-using a message that came in via propagation.
     * In the later case, the TTL and loop detection parameters CANNOT be
     * re-initialized. If one wants to "re-propagate" a message with a new TTL
     * and blank gateways list one must generate a completely new message.
     * This limits the risk of accidental propagation storms, although they
     * can always be engineered deliberately.
     *
     * <p/><b>Note</b>: The original msg is not modified and may be reused upon return.
     *
     * @param  destPeerIDs   is a Vector of PeerIDs of the peers which are receiving
     * first the walker. Note that each entry in the Vector will create its own
     * walker.
     * @param  msg           is the message to walk.
     * @param  serviceName   is the name of the service
     * @param  serviceParam  is the parameter of the service
     * @param  ttl           is the maximum TTL of the message.
     * @throws  IOException  when walking the message is impossible (network failure)
     */
    public void walk(Vector<? extends ID> destPeerIDs, Message msg, String serviceName, String serviceParam, int ttl) throws IOException;

    /**
     * Returns a vector of RdvAdvertisement of the local view of rendezvous peers.
     *
     * @deprecated Due to design changes, the list of peers may be empty in
     * configurations which previously returned a non-empty result. Future 
     * JXTA versions are likely to use a different API.
     *
     * @return The local view of RDV peers.
     */
    @Deprecated
    public Vector<RdvAdvertisement> getLocalWalkView();

    /**
     * Set a new deadline for the rendezvous to be proven alive.
     * As a result a lease response must be sought and obtained within the
     * specified delay or the rdv is considered disconnected.
     *
     * <p/>A timeout of 0 or less triggers immediate disconnection.
     *
     * @param  peer     The peer to be challenged
     * @param  timeout  The delay
     */
    public void challengeRendezVous(ID peer, long timeout);
}