*     *   <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 );}