rendezvousserviceprovider.java

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

            if (rendezvousServiceMonitor != null) {
                this.rendezvousMeter = rendezvousServiceMonitor.getRendezvousMeter();
            }
        }
    }

    /**
     * Resets the local idea of the lease to the specified value.
     * As a result a lease response must be sought and obtained within the
     * new specified delay or the rdv is considered disconnected.
     *
     * @param peer  The peer to be challenged
     * @param delay The delay
     */
    public abstract void challengeRendezVous(ID peer, long delay);

    /**
     * Attempt to connect to the specified rendezvous peer.
     *
     * @param addr The endpoint address of the rendezvous peer.
     * @param hint An optional hint which may be {@code null}.
     * @throws IOException If no connection could be made to the specified peer.
     */
    public abstract void connectToRendezVous(EndpointAddress addr, Object hint) throws IOException;

    /**
     * Remove a RendezVousService point.
     *
     * @param peerID the PeerId of the RendezVous to disconnect from.
     */
    public abstract void disconnectFromRendezVous(ID peerID);

    /**
     * Returns the peers that are currently connected to this peer.
     *
     * @return The peers that are currently connected to this peer.
     */
    public abstract Vector<ID> getConnectedPeerIDs();

    /**
     * Propagates a message onto as many peers on the local network
     * as possible. Typically the message will go to all the peers to
     * which at least one endpoint transport can address without using
     * the router.
     * <p/>
     * This method sends the message to all peers, rendezvous peers and
     * edge peer. This method of propagation is very expensive and should
     * not be frequently used. 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.
     * <p/>
     * Note: The original msg is not modified and may be reused upon return.
     *
     * @param msg          is the message to propagate.
     * @param serviceName  is the name of the service
     * @param serviceParam is the parameter of the service
     * @param initialTTL   is the maximum TTL of the message (note that the Rendezvous
     *                     Service implementation is free to decrease that value.
     * @throws java.io.IOException if an io error occurs
     */
    public abstract void propagate(Message msg, String serviceName, String serviceParam, int initialTTL) throws IOException;

    /**
     * Propagates a message onto as many peers on the local network
     * as possible. Typically the message will go to all the peers to
     * which at least one endpoint transport can address without using
     * the router.
     * <p/>
     * This method sends the message to all peers, rendezvous peers and
     * edge peer. This method of propagation is very expensive and should
     * not be frequently used. 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.
     * <p/>
     * Note: The original msg is not modified and may be reused upon return.
     *
     * @param destPeerIds  An enumeration of the peers that are recipients of the
     *                     propagated message.
     * @param msg          is the message to propagate.
     * @param serviceName  is the name of the service
     * @param serviceParam is the parameter of the service
     * @param initialTTL   is the maximum TTL of the message (note that the Rendezvous
     *                     Service implementation is free to decrease that value.
     * @throws java.io.IOException if an io error occurs
     */
    public abstract void propagate(Enumeration<? extends ID> destPeerIds, Message msg, String serviceName, String serviceParam, int initialTTL) throws IOException;

    /**
     * Propagates a message onto as many peers on the local network
     * as possible. Typically the message will go to all the peers to
     * which at least one endpoint transport can address without using
     * the router.
     * <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/>
     * Note: The original msg is not modified and may be reused upon return.
     *
     * @param msg          is the message to propagate.
     * @param serviceName  is the name of the service
     * @param serviceParam is the parameter of the service
     * @param initialTTL   is the maximum TTL of the message (note that the Rendezvous
     *                     Service implementation is free to decrease that value.
     * @throws java.io.IOException if an io error occurs
     */
    public abstract void propagateToNeighbors(Message msg, String serviceName, String serviceParam, int initialTTL) throws IOException;

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

    /**
     ** The following API is related to the new Rendezvous Peer walk mechanism.
     **
     **/

    /**
     * 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/>
     * Note: 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 initialTTL   is the maximum TTL of the message (note that the Rendezvous
     *                     Service implementation is free to decrease that value.
     * @throws IOException when walking the message is impossible (network failure)
     */
    public abstract void walk(Message msg, String serviceName, String serviceParam, int initialTTL) throws IOException;

    /**
     * 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/>
     * Note: The original msg is not modified and may be reused upon return.
     *
     * @param destPeerIDs  is a Vector of PeerID 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 initialTTL   is the maximum TTL of the message (note that the Rendezvous
     *                     Service implementation is free to decrease that value.
     * @throws IOException when walking the message is impossible (network failure)
     */
    public abstract void walk(Vector<? extends ID> destPeerIDs, Message msg, String serviceName, String serviceParam, int initialTTL) throws IOException;

    /**
     * Process a propagated message.
     *
     * @param message the message received
     * @param propHdr the message header
     * @param srcAddr the source address
     * @param dstAddr the message destination addreess
     */
    protected void processReceivedMessage(Message message, RendezVousPropagateMessage propHdr, EndpointAddress srcAddr, EndpointAddress dstAddr) {

        EndpointListener listener = rdvService.endpoint.getIncomingMessageListener(dstAddr.getServiceName(),
                dstAddr.getServiceParameter());

        if (listener != null) {
            // We have a local listener for this message. Deliver it.

            if (Logging.SHOW_FINE && LOG.isLoggable(Level.FINE)) {
                LOG.fine("Calling local listener " + listener.getClass().getName() + " for [" + dstAddr.getServiceName() + "/"
                        + dstAddr.getServiceParameter() + "] with " + message + " (" + propHdr.getMsgId() + ")");
            }

            rdvService.endpoint.processIncomingMessage(message, srcAddr, dstAddr);
            if (RendezvousMeterBuildSettings.RENDEZVOUS_METERING && (rendezvousMeter != null)) {
                rendezvousMeter.receivedMessageProcessedLocally();
            }

            // NOTE: this this is only beneficial in ad-hoc mode with no rendezvous infrastructure
            // with one node bridging two networks (2 interfaces).
            // This should not be a base feature but rather an ad-hoc mode only feature, as
            // it creates additional unnecessary traffic leading to message loss and latency.
            // hamada disabling this feature as a general base functionality.
            // This should addressed differently in Ad-hoc mode, where a multi-homed node would
            // repropagate when more than one interface is enabled

            // Pass the message on.
            // repropagate(message, propHdr, dstAddr.getServiceName(), dstAddr.getServiceParameter());
        } else {
            if (Logging.SHOW_FINE && LOG.isLoggable(Level.FINE)) {
                LOG.fine("No message listener found for ServiceName :" + dstAddr.getServiceName() + " ServiceParam :"
                        + dstAddr.getServiceParameter());
            }
        }
    }

    /**
     * Responsible for forwarding received messages to the rest of the network