messenger.java

jxta_src_2.41b jxta 2.41b 最新版源码 from www.jxta.org

     *
     *   <li>There is no guarantee that the process of sending the message will not fail after that method returned. If this messenger
     *   subsequently reaches an {@link #IDLE} state that is either {@link #CLOSED} or a {@link #USABLE} state, then it may be inferred
     *   that all outsdanding messages have been processed without this messenger detecting an error.</li>
     * </ul>
     *
     * <p/><b>WARNING:</b> The Message object should not be reused or modified until completely processed. Concurrent modification
     * of a message while a messenger is sending the message will produce incorrect and unpredictable results.  If completion is
     * not monitored, the message should <b>never</b> be reused. If necessary, a clone of the message may be provided to
     * {@link #sendMessageB}:
     *
     * <p/><code><pre>
     *     messenger.sendMessageB( (Message) myMessage.clone(), theService, theParam );
     * </pre></code>
     *
     * <p/>There is no guarantee that a message successfully sent will actually be received.<p/>
     *
     * @param service  Optionally replaces the service in the destination
     * address. If {@code null} then the destination address's default
     * service will be used.  If the empty string ("") is used then
     * no service is included in the destination address.
     * @param serviceParam  Optionally replaces the service param in the
     * destination address. If {@code null} then the destination address's
     * default service parameter will be used. If the empty string ("") is used
     * then no service param is included in the destination address.
     * @throws IOException Thrown if the message cannot be sent.
     **/
    void sendMessageB( Message msg, String service, String serviceParam ) throws IOException;

    /**
     * Sends a message to the destination specified at construction. If a service name and service param are specified, they will
     * replace those specified at construction for the purpose of sending this message only.
     *
     * <p/>This method is identical to {@link #sendMessage(Message, String, String)}, except that it does not throw an exception. The invoker
     * has to retrieve a detailed status from the message if needed.
     *
     * <p/>Error Handling:  <ul>
     *   <li>A return result of {@code false} indicates that the message was not accepted to be sent. This may be due to
     *   local resource limits being reached or to the messenger being in a state that is not {@link #USABLE} or to the message
     *   being invalid. The exact cause of the failure can be retrieved from the message by using
     *   {@link Message#getMessageProperty(Object) <code>Message.getMessageProperty(Messenger.class)</code>}.  If appropriate,
     *   another attempt at sending the message, may be made after waiting for the congestion to clear (for example by using
     *   {@link #waitState(int, long)}).</li>
     *
     *   <li>A return result of {@code true} indicates that the message was accepted for sending. <b>It does not imply that
     *   the message will be sent or that the destination will receive the message.</b> There will be no indication by this method
     *   of any errors in sending the message. If this messenger subsequently reaches an {@link #IDLE} state that is either {@link
     *   #CLOSED} or a {@link #USABLE} state, then it may be inferred that all outsdanding messages have been processed without this
     *   messenger detecting an error.</li>
     *
     *   <li>The invoker may have confirmation of completion (succesfull or not) by observing the message's properties. When the
     *   message has been fully processed, {@link Message#getMessageProperty(Object) <code>Message.getMessageProperty(Messenger.class)</code>}
     *   will return an object of class {@link OutgoingMessageEvent}. Changes in a message's set of properties may be tracked by
     *   selecting the message.</li>
     * </ul>
     *
     * <p/><b>WARNING:</b> The Message object should not be reused or modified until completely processed. Concurrent modification
     * of a message while a messenger is sending the message will produce incorrect and unpredictable results.  If completion is
     * not monitored, the message should <b>never</b> be reused. If necessary, a clone of the message may be provided to
     * {@link #sendMessageN}:
     *
     * <p/><code><pre>
     *     messenger.sendMessageN( (Message) myMessage.clone(), theService, theParam );
     * </pre></code>
     *
     * <p/>There is no guarantee that a message successfully sent will actually be received.<p/>
     *
     * @param msg The message to send.
     * @param service  Optionally replaces the service in the destination
     * address. If {@code null} then the destination address's default
     * service will be used.  If the empty string ("") is used then
     * no service is included in the destination address.
     * @param serviceParam  Optionally replaces the service param in the
     * destination address. If {@code null} then the destination address's
     * default service parameter will be used. If the empty string ("") is used
     * then no service param is included in the destination address.
     * @return boolean {@code true} if the message has been accepted for sending, otherwise {@code false}.
     **/
    boolean sendMessageN( Message msg, String service, String serviceParam );

    /**
     * Sends a message to the destination specified at construction as if by invoking {@link #sendMessage(Message,String,String)
     * <code>sendMessage(msg, null, null)</code>}
     *
     * <p/>This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a {@link ListenerAdaptor} object explicitly to have a listener called.
     *
     * @param msg The message to send.
     * @return boolean {@code true} if the message has been accepted for sending, otherwise {@code false}.
     * @throws IOException Thrown if the message cannot be sent.
     **/
    boolean sendMessage( Message msg ) throws IOException;

    /**
     * Sends a message to the destination specified at construction. If a service name and service param are specified, they will
     * replace those specified at construction for the purpose of sending this message only.
     *
     * <p/>Error Handling:
     *
     * <ul>
     *
     *   <li>An {@link java.io.IOException} means that this message is invalid or that this messenger is now in one of the
     * non {@link #USABLE} states and may no longer send new messages, and that the message was not sent. The exact state of
     * the messenger may be obtained from the {@link #getState()} method.</li>
     *
     *   <li>A return result of {@code false} indicates that the message was not accepted to be sent. Usually this is due to
     *   local resource limits being reached. If needed, another attempt at sending the message, may be made after waiting for the
     *   congestion to clear (for example by using {@link #waitState(int, long)}).</li>
     *
     *   <li>A return result of {@code true} indicates that the message was accepted for sending. <b>It does not imply that
     *   the message will be sent or that the destination will receive the message.</b> There will be no immediate indication of any
     *   errors in sending the message. If this messenger subsequently reaches an {@link #IDLE} state that is either {@link #CLOSED}
     *   or a {@link #USABLE} state, then it may be inferred that all outsdanding messages have been processed without this
     *   messenger detecting an error.</li>
     *
     *   <li>The invoker may have confirmation of completion by observing the message's properties. When the message has been fully
     *   processed, {@link Message#getMessageProperty(Object) <code>Message.getMessageProperty(Messenger.class)</code>} will return
     *   an object of class {@link OutgoingMessageEvent}. Changes in a message's set of properties may be tracked by selecting
     *   the message.
     *
     * </ul>
     *
     * <p/><b>WARNING:</b> The Message object should not be reused or modified until completely processed. Concurrent modification
     * of a message while a messenger is sending the message will produce incorrect and unpredictable results.  If completion is
     * not monitored, the message should <b>never</b> be reused. If necessary, a clone of the message may be provided to
     * <code>sendMessage</code>:
     *
     * <p/><code><pre>
     *     messenger.sendMessage( (Message) myMessage.clone(), theService, theParam );
     * </pre></code>
     *
     * <p/>There is no guarantee that a message successfully sent will actually be received.<p/>
     *
     * <p/><b>Limitation:</b> using this method along with {@link net.jxta.util.SimpleSelector#select} on the same message may occasionaly
     * cause some errors to not be thrown. Prefer {@link #sendMessageN} when using {@link net.jxta.util.SimpleSelector#select}.
     *
     * <p/>This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a {@link ListenerAdaptor} object explicitly to have a listener called.
     *
     *
     * @param msg The message to send.
     * @param service  Optionally replaces the service in the destination
     * address. If {@code null} then the destination address's default
     * service will be used.  If the empty string ("") is used then
     * no service is included in the destination address.
     * @param serviceParam  Optionally replaces the service param in the
     * destination address. If {@code null} then the destination address's
     * default service parameter will be used. If the empty string ("") is used
     * then no service param is included in the destination address.
     * @return boolean {@code true} if the message has been accepted for sending, otherwise {@code false}.
     * @throws IOException Thrown if the message cannot be sent.
     **/
    boolean sendMessage( Message msg, String service, String serviceParam ) throws IOException;

    /**
     * Sends a message to the destination specified at construction. If a service name and service param are specified, they will
     * replace those specified at construction for the purpose of sending this message only.
     *
     * <p/><b>WARNING:</b> The Message object should not be reused or modified until the message has been fully processed.
     * Concurrent modification of a message while a messenger is sending the message will produce incorrect and unpredictable
     * results. If a listener is provided it is invoked after the message is considered fully processed. However it is recommended
     * not to reuse or otherwise modify a messages after sending it. If necessary, a clone of the message may be provided to
     * <code>sendMessage</code>:
     *
     * <p/><code><pre>
     *     messenger.sendMessage( (Message) myMessage.clone() );
     * </pre></code>
     *
     * <p/>Error Handling:
     *
     * <ul>
     *
     *   <li>If a listener was provided, it will always be invoked. Depending upon the outcome either the
     *   {@link OutgoingMessageEventListener#messageSendFailed(OutgoingMessageEvent)} or the {@link
     *   OutgoingMessageEventListener#messageSendSucceeded(OutgoingMessageEvent)} method will be invoked:<p/>
     *
     *   <ul>
     *
     *     <li>If the message could not be accepted for sending due to temporary resource saturation,
     *     <code>messageSendFailed</code> will be invoked. The {@link Throwable} object returned by the {@link
     *     OutgoingMessageEvent#getFailure()} method of the passed event object will be null.</li>
     *
     *     <li>If the message could not be accepted for sending due to the messenger not being {@link #USABLE},
     *     <code>messageSendFailed</code> will be invoked. The {@link Throwable} object returned by the {@link
     *     OutgoingMessageEvent#getFailure()} method of the passed event object will reflect the messenger's condition.</li>
     *
     *     <li>If the message is accepted for sending but later fails, then <code>messageSendFailed</code> will be invoked.  The
     *     {@link Throwable} object returned by the {@link OutgoingMessageEvent#getFailure()} method of the passed event object
     *     will reflect the origin of the failure.</li>
     *
     *     <li>If the message is accepted for sending and later succeeds, then <code>messageSendSucceeded</code> will be
     *     invoked.</li>
     *   
     *   </ul></li>
     *
     *   <li>If a listener was provided, it is always possible that it is invoked before this method returns.</li>
     *
     *   <li>If no listener was provided, </b> There will be no notification of any errors nor success in sending the message. If
     *   this messenger subsequently reaches an {@link #IDLE} state that is either {@link #CLOSED} or a {@link #USABLE} state, then it
     *   may be inferred that all outsdanding messages have been processed without this messenger detecting an error.</li>
     *
     *   <li>This method does not throw exceptions. As a result, when used with a {@code null} listener, it provides very
     *   little feedback to the invoker. A messenger should be abandonned once it is in one of the {@link #TERMINAL} states.</li>
     *
     * </ul>
     * <p/>
     * As with all <code>sendMessage</code> methods, success is not a guarantee that the message will actually be received.
     *
     * <p/>This is a legacy method. Modern code should prefer the other methods and select messages. If a listener API is preferred, it is possible to use a {@link ListenerAdaptor} object explicitly to have a listener called.
     *
     *
     * @param msg The message to send.
     * @param service  Optionally replaces the service in the destination
     * address. If {@code null} then the destination address's default
     * service will be used.  If the empty string ("") is used then
     * no service is included in the destination address.
     *
     * @deprecated This legacy method is being phased out. Prefer {@link #sendMessageN} to send messages in a non blocking fashion.
     *
     * @param serviceParam  Optionally replaces the service param in the
     * destination address. If {@code null} then the destination address's
     * default service parameter will be used. If the empty string ("") is used
     * then no service param is included in the destination address.
     * @param listener  listener for events about this message or null if
     * no notification is desired.
     * @throws UnsupportedOperationException If this messenger is not a channel or was not given a {@link ListenerAdaptor}.
     * (all messengers obtained through {@link EndpointService#getMessenger} are configured properly.
     **/
    void sendMessage( Message msg, String service, String serviceParam, OutgoingMessageEventListener listener );
}