endpointservice.java

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

    /**
     * Verifies that the given address can be reached. The method, and accuracy
     * of the verification depends upon each Message Transport. In some cases
     * the address may be contacted to determine connectivity but this is not
     * guaranteed.
     *
     * @param addr is the Endpoint Address to ping.
     * @return {@code true} if the address can be reached otherwise {@code false}.
     * @deprecated The cost of performing this operation is generally the same
     * as getting a Messenger for the destination. Using {@code getMessenger()}
     * is a better approach because the resulting Messenger is generally needed
     * soon after ping.
     */
    @Deprecated
    public boolean ping(EndpointAddress addr);

    /**
     * Add a listener for the specified address.
     * <p/>
     * A single registered listener will be called for incoming messages
     * when (in order of preference) : <ol>
     * <li>The service name and service parameter match exactly to the
     * service name and service parameter specified in the destination
     * address of the message.</li>
     * <p/>
     * <li>The service name matches exactly the service name from the
     * message destination address and service parameter is {@code null}.
     * </li>
     * </ol>
     *
     * @param listener The listener which will be called when messages are
     * received for the registered destination.
     * @param serviceName The name of the service destination which will be
     * matched against incoming message destination endpoint addresses.
     * @param serviceParam An optional service parameter value which will be 
     * matched against destination endpoint addresses. May be null.
     * @return true if the listener was registered, otherwise false.
     */
    public boolean addIncomingMessageListener(EndpointListener listener, String serviceName, String serviceParam);

    /**
     * Get the listener for the specified address.
     *
     * @param serviceName  The service name to which the listener is registered.
     * @param serviceParam The service parameter to which the listener is
     *                     registered. May be {@code null}.
     * @return The currently registered listener or {@code null} if there is no
     *         listener for the specified name and parameter.
     */
    public EndpointListener getIncomingMessageListener(String serviceName, String serviceParam);

    /**
     * Remove the listener for the specified address.
     *
     * @param serviceName  The service name to which the listener is registered.
     * @param serviceParam The service parameter to which the listener is
     *                     registered. May be {@code null}.
     * @return The listener which was removed or {@code null} if there was
     *         no listener for the specified name and parameter.
     */
    public EndpointListener removeIncomingMessageListener(String serviceName, String serviceParam);

    /**
     * Registers a message filter listener. Each message will be tested against
     * the list of filters as part of its sending or receiving.
     * <p/>
     * The listener is invoked for a message when:
     * <ul>
     *   <li>The message contains a message element which matches exactly the
     *   values specified by namespace and name.</li>
     *  
     *   <li>The message contains a message element who's namespace value 
     *   matches exactly the specified namespace value and the specified name is
     *   {@code null}.</li>
     *  
     *   <li>The message contains a message element who's names value matches
     *   exactly the specified name value and the specified namespace is
     *   {@code null}.</li>
     * 
     *   <li>The specified name value and the specified namespace are both
     *   {@code null}.</li>
     * </ul>
     *
     * @param listener  The filter which will be called.
     * @param namespace Only messages containing elements of this namespace
     *                  which also match the 'name' parameter will be processed. {@code null}
     *                  may be use to specify all namespaces.
     * @param name      only messages containing elements of this name which also
     *                  match the 'namespace' parameter will be processed. {@code null} may be
     *                  use to specify all names.
     */
    public void addIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name);

    /**
     * Registers a message filter listener. Each message will be tested against
     * the list of filters as part of its sending or receiving.
     * <p/>
     * The listener is invoked for a message when:
     * <ul>
     *   <li>The message contains a message element which matches exactly the
     *   values specified by namespace and name.</li>
     *  
     *   <li>The message contains a message element who's namespace value 
     *   matches exactly the specified namespace value and the specified name is
     *   {@code null}.</li>
     *  
     *   <li>The message contains a message element who's names value matches
     *   exactly the specified name value and the specified namespace is
     *   {@code null}.</li>
     * 
     *   <li>The specified name value and the specified namespace are both
     *   {@code null}.</li>
     * </ul>
     *
     * @param listener  The filter which will be called.
     * @param namespace Only messages containing elements of this namespace
     *                  which also match the 'name' parameter will be processed. {@code null}
     *                  may be used to specify all namespaces.
     * @param name      only messages containing elements of this name which also
     *                  match the 'namespace' parameter will be processed. {@code null} may be
     *                  use to specify all names.
     */
    public void addOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name);

    /**
     * Removes the given listener previously registered under the given element 
     * name
     *
     * @param listener  the listener to remove
     * @param namespace the name space
     * @param name      the name
     * @return the removed listener
     */
    public MessageFilterListener removeIncomingMessageFilterListener(MessageFilterListener listener, String namespace, String name);

    /**
     * Removes the given listener previously registered under the given element
     * name.
     *
     * @param listener  the listener to remove
     * @param namespace the name space
     * @param name      the name
     * @return the removed listener
     */
    public MessageFilterListener removeOutgoingMessageFilterListener(MessageFilterListener listener, String namespace, String name);

    /**
     * Delivers the provided message to the correct listener as specified by
     * the message's destination address.
     * <p/>
     * Two additional common message elements are optionally used by Message
     * Transports in conjunction with the Endpoint Service. Message Transports
     * may typically provide received messages to the Endpoint Service
     * containing these elements and the Endpoint service will dispatch the
     * messages based upon their content. Message Transports may use alternate
     * mechanisms for determining message source and destination addresses and
     * need not use these elements.
     * <p/>
     * The {@code jxta:EndpointSourceAddress} Message Element contains an 
     * Endpoint Address for the source of this message. The source address has a
     * variety of meanings based upon the usage of the underlying Message 
     * Transport. For low level transports such as TCP or HTTP the source 
     * address is the return address of the peer from which the message was 
     * received, ie. the hop address. For higher level Message Transports such 
     * as the Endpoint Router Transport or the TLS transport the source address 
     * is the virtual Endpoint Address of the peer which originated the message 
     * regardless of any intervening hops the message may have made.
     * <p/>
     * The {@code jxta:EndpointDestinationAddress} Message Element contains an 
     * Endpoint Address which will be used by the Endpoint Service to dispatch a
     * received message to the recipient specified by the service name and 
     * service parameter. The protocol address is also provided to the recipient 
     * service and can be used in some protocols for determining how the message 
     * was received. For example a service may wish to handle messages which
     * were sent directly differently than messages which were sent via 
     * propagation.
     *
     * @param msg The message to be delivered.
     * @deprecated Please convert your code to use the
     * {@link EndpointListener#processIncomingMessage(Message,EndpointAddress,EndpointAddress)}
     * method instead. The addressing method used by demux() was never part of
     * the formal JXTA protocol specification but was a defacto part because
     * demux() depended upon it.
     */
    @Deprecated
    public void demux(Message msg);

    /**
     * Adds the specified MessageTransport to this endpoint. A MessageTransport
     * may only be added if there are no other equivalent MessageTransports
     * available (as determined by {@link Object#equals(Object) equals()}).
     * <p/>
     * The MessageTransport becomes usable by the endpoint service to send
     * unicast messages and optionally propagation and ping messages if it is a
     * {@link net.jxta.endpoint.MessageSender}. The endpoint service becomes
     * usable by this MessageTransport to handle incoming messages if it is a
     * {@link MessageReceiver}.
     *
     * @param transport the MessageTransport to be installed.
     * @return A messenger event listener to invoke when incoming messengers are
     *         created or {@code null} if the MessageTransport was not installed.
     */
    public MessengerEventListener addMessageTransport(MessageTransport transport);

    /**
     * Removes the given MessageTransport protocol from this endpoint service.
     * <p/>
     * Transports remove themselves from the list when stopped. This method
     * is normally only called from the stoppApp method of the transport. To
     * cleanly remove a transport, call the transport's
     * {@link net.jxta.platform.Module#stopApp() stopApp()}and allow it to call
     * this method.
     *
     * @param transpt the MessageTransport to be removed.
     * @return {@code true} if the Message Transport was removed, otherwise
     * {@code false}.
     */
    public boolean removeMessageTransport(MessageTransport transpt);

    /**
     * Get an iterator of the MessageTransports available to this
     * EndpointService.
     *
     * @return the iterator of all message transports.
     */
    public Iterator<MessageTransport> getAllMessageTransports();

    /**
     * Get a Message Transport by protocol name.
     *
     * @param name The protocol name of the MessageTransport.
     * @return The Message Transport for the specified protocol name or
     * {@code null} if there is no matching Message Transport
     */
    public MessageTransport getMessageTransport(String name);

    /**
     * Returns a Messenger that may be used to send messages via  this endpoint
     * to the specified destination.
     *
     * @param addr the destination address.
     * @return The messenger or {@code null} is returned if the destination
     * address is not reachable.
     */
    public Messenger getMessenger(EndpointAddress addr);

    /**
     * Asynchronously acquire a messenger for the specified address. The
     * listener will be called when the messenger has been constructed.
     *
     * @param listener the listener to call when the messenger is ready.
     * @param addr     the destination for the messenger.
     * @param hint     the messenger hint, if any, otherwise null.
     * @return {@code true} if the messenger is queued for construction
     * otherwise {@code false}.
     * @deprecated This method is being phased out. Prefer one of the other
     * non-blocking variants. If a listener style paradigm is required, use
     * {@link ListenerAdaptor} which emulates this functionality.
     */
    @Deprecated
    public boolean getMessenger(MessengerEventListener listener, EndpointAddress addr, Object hint);

    /**
     * Returns a Direct Messenger that may be used to send messages via  this endpoint to the specified destination.
     * </p>
     * Direct messengers are non self destructive, they must be explicilty closed.
     *
     * @param addr the destination address.
     * @param hint the messenger hint, if any, otherwise null.
     * @param exclusive if true avoids caching the messenger
     * @return The messenger or {@code null} is returned if the destination address is not reachable.
     * @throws IllegalArgumentException if hint is not of RouteAdvertisement, or PeerAdvertisement type.
     */
    public Messenger getDirectMessenger(EndpointAddress addr, Object hint, boolean exclusive);
}