endpointservice.java

jxta平台的开发包

     * endpoint protocols may silently drop the message. Each endpoint protocol may interpret the resquest for propagation
     * differenly. The endpointService does not define which destinations the message will actually reach.
     *
     * <p/>The concatenation of the serviceName and serviceParam arguments uniquely designates the listener to which the message
     * must be delivered on arrival.
     *
     * <p/><strong>WARNING</strong>: The message object should not be reused or modified after the call is made. Concurrent
     * modifications will produce unexpected results.
     *
     * @param srcMsg the message to be propagated.
     * @param serviceName a destination service name
     * @param serviceParam a destination queue name within that service
     * @throws IOException if the message could not be propagated
     **/
    public void propagate( Message srcMsg, String serviceName, String serviceParam) throws IOException;
    
    /**
     * Verifies that the given address can be reached.  The verification is performed by the endpoint protocol designated by the
     * given address, as returned by the getProtocolName() method of this address.
     *
     * <p/>The method, and accuracy of the verification depends upon each endpoint protocol.
     *
     * @param addr is the Endpoint Address to ping.
     * @return boolean true if the address can be reached. False otherwise.
     *
     * @deprecated It now always return true. Try and get a messenger instead.
     **/
    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> <li>The service name matches exactly the service name from the * message destination address
     *  and service parameter is null.</li> * </ol>
     *
     *  @param listener the listener
     *  @param serviceName The name of the service destination which will be matched against destination endpoint addresses.
     *  @param serviceParam String containting the value of the service parameter 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 );
    
    /**
     *  Remove the listener for the specified address.
     *
     *  @param serviceName The name of the service destination which will be matched against destination endpoint addresses.
     *  @param serviceParam String containting the value of the service parameter which will be matched against destination
     *  endpoint addresses.  May be null.
     *  @return The listener which was removed.
     *
     **/
    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 an element which matches exactly the
     *  values specified by namespace and name.</li>
     *  <li>The message contains an element who's namespace value matches
     *  exactly the specified namespace value and the specified name is null.</li>
     *  <li>The message contains an element who's names value matches exactly
     *  the specified name value and the specified namespace is null.</li>
     *  <li>The specified name value and the specified namespace are both 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. 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. 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 an element which matches exactly the
     *  values specified by namespace and name.</li>
     *  <li>The message contains an element who's namespace value matches
     *  exactly the specified namespace value and the specified name is null.</li>
     *  <li>The message contains an element who's names value matches exactly
     *  the specified name value and the specified namespace is null.</li>
     *  <li>The specified name value and the specified namespace are both 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. 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. 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 that was registered
     **/
    public MessageFilterListener removeIncomingMessageFilterListener( MessageFilterListener listener, String namespace, String name );
    
    /**
     * Removes the given listener previously registered under the given element name
     *
     * @param listener the listener that was registered
     **/
    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.
     *
     * @param msg The message to be delivered.
     **/
    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 optionaly 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 transpt the MessageTransport to be installed.
     * @return A messenger event listener to invoke when incoming messengers are created.  Null if the MessageTransport was not
     * installed.
     **/
    public MessengerEventListener addMessageTransport( MessageTransport transpt );
    
    /**
     * 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 boolean true if the transport was removed, otherwise 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 getAllMessageTransports();


    /**
     *  Get a MessageTransport by name 
     *
     *  @param name The name of the MessageTransport
     *  @return MessageTransport associated with that name
     **/
    public MessageTransport getMessageTransport( String name );

    /**
     * Builds and returns an Messager that may be used to send messages via this endpoint to the specified destination.
     *
     * @see net.jxta.endpoint.EndpointAddress
     * @deprecated This convenience method adds little value. It is strictly equivalent to {@link #getMessenger(EndpointAddress,
     * Object) <code>getMessenger(addr, null)</code>}
     *
     * @param addr the destination address.
     * @return The messenger. 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.
     *
     * @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.
     *
     * @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 boolean true if the messenger is queued for construction otherwise false.
     **/
    public boolean getMessenger( MessengerEventListener listener, EndpointAddress addr, Object hint );
}