messenger.java

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

     * <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 means that the message was not sent. The exact state of the
     * messenger may be obtained from the {@link #getState()} method. If no exception is thrown, the message is accepted for
     * sending and may or may not be fully processed.</li>
     * <p/>
     * <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) Message#getMessageProperty(Messenger.class)} will return an
     * object of class {@link OutgoingMessageEvent}. Changes in a message's set of properties may be tracked by selecting the
     * message. If an exception was thrown, the message's properties will not be modified
     * <p/>
     * <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 outstanding messages have been processed without this messenger detecting an error.</li>
     * </ul>
     * <p/>
     * <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/>
     * <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 msg          the message
     * @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>
     * <p/>
     * <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 outstanding messages have been processed without this
     * messenger detecting an error.</li>
     * <p/>
     * <li>The invoker may have confirmation of completion (successful 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/>
     * <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/>
     * <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) sendMessage(msg, null, null)}
     * 
     * @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:
     * <p/>
     * <ul>
     * <p/>
     * <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>
     * <p/>
     * <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>
     * <p/>
     * <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 outstanding messages have been processed without this
     * messenger detecting an error.</li>
     * <p/>
     * <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.
     * <p/>
     * </ul>
     * <p/>
     * <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 occasionally
     * 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.
     *
     * @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:
     * <p/>
     * <ul>
     * <p/>
     * <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/>
     * <p/>
     * <ul>
     * <p/>
     * <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>
     * <p/>
     * <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>
     * <p/>
     * <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>
     * <p/>
     * <li>If the message is accepted for sending and later succeeds, then <code>messageSendSucceeded</code> will be
     * invoked.</li>
     * <p/>
     * </ul></li>
     * <p/>
     * <li>If a listener was provided, it is always possible that it is invoked before this method returns.</li>
     * <p/>
     * <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 outstanding messages have been processed without this messenger detecting an error.</li>
     * <p/>
     * <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 abandoned once it is in one of the {@link #TERMINAL} states.</li>
     * <p/>
     * </ul>
     * <p/>
     * As with all <code>sendMessage</code> methods, success is not a guarantee that the message will actually be received.
     * <p/>
     * <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.
     * @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);
}