messenger.java

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

    public static final int TERMINAL = (UNRESOLVABLE | CLOSED | BROKEN);

    /**
     * Composite state.
     * <p/>
     * Any message that may have been submitted in the past has been either sent or failed already.
     * If a messenger is in a state <code>IDLE & RESOLVED & USABLE</code>, then the expected delay in sending a message
     * is minimal.
     */
    public static final int IDLE = (UNRESOLVED | RESOLVING | CONNECTED | DISCONNECTED | UNRESOLVABLE | CLOSED | BROKEN);

    /**
     * Composite state.
     * <p/>
     * This messenger cannot take new messages for now. All available buffering space is occupied.
     * Note that only the usable states can be saturated. Once a messenger is in the process of terminating
     * and thus takes no new messages anyway, it no-longer shows as saturated.
     */
    public static final int SATURATED = (RESOLSATURATED | SENDINGSATURATED | RECONSATURATED);

    /**
     * Returns the current state.
     *
     * @return one of the legal discrete state values.
     */
    public int getState();

    /**
     * Blocks unless and until the current state is or has become one of the desired values.  The observable states are guaranteed
     * to be represented by a single bit. Multiple desired values may be specified by passing them <code>OR</code>ed together.
     * <p/>
     * This class defines the list of constants that may be used and how these may be combined.
     * <p/>
     * Note that the state can change as soon as this method returns, so any observation is only an indication of the
     * past. Synchronizing on the object itself has no other effect than interfering with other threads doing the same. Obviously,
     * certain transitions cannot happen unless a new message is submitted. So unless another thread is using a messenger, it is
     * safe to assume that a non-saturated messenger will not become saturated spontaneously. Note that messengers returned by
     * different endpoint service interface objects (what {@link net.jxta.peergroup.PeerGroup#getEndpointService()} returns) are
     * different. However a given endpoint interface object will return an existing messenger to the same exact destination if
     * there is a {@link Messenger#USABLE} one.
     * <p/>
     * With an unshared messenger, one can wait for any change with {@code waitState(~getState(), 0);}.
     * <p/>
     * Note that it is advisable to always include {@link #TERMINAL} as part
     * of the desired states with unless being blocked past the messenger
     * termination is an acceptable behaviour.
     * <p/>
     * Examples:<p/>
     * <p/>
     * Ensure that the messenger can take more messages (or is {@code UNUSABLE}): {@code waitState(~SATURATED)}<p/>
     * <p/>
     * Ensure that all submitted messages have been sent: {@code waitState(TERMINAL | IDLE)}
     * <p/>
     * Ensure that the messenger is already resolved and can take more messages: {@code waitState(TERMINAL | (RESOLVED & ~SATURATED))}
     *
     * @param wantedStates The binary OR of the desired states.
     * @param timeout      The maximum number of milliseconds to wait. A timeout of 0 means no time limit.
     * @return The desired state that was reached or the current state when time ran out.
     * @throws InterruptedException If the invoking thread was interrupted before the condition was realized.
     */
    int waitState(int wantedStates, long timeout) throws InterruptedException;

    /**
     * Returns {@code true} if this messenger is closed and no longer
     * accepting messages to be sent. This is a shortcut for 
     * {@code (getState() & USABLE == 0)}. Once closed, a messenger should be 
     * discarded. 
     *
     * @return {@code true} if this messenger is closed, otherwise {@code false}.
     */
    boolean isClosed();

    /**
     * Returns an indication of whether this messenger may be worth closing.
     *
     * @return {@code true} if the messenger is idle otherwise {@code false}.
     * @deprecated no longer relevant and always false. This notably is <bold>not</bold> equivalent to the {@link #IDLE} state.
     */
    @Deprecated
    boolean isIdle();

    /**
     * Returns {@code true} if the <code>sendMessage</code> methods of
     * this messenger are fully synchronous.
     *
     * @deprecated all messengers are asynchronous, and the {@link #sendMessageB} method is always blocking.
     *
     * @return true if synchronous
     */
    @Deprecated
    boolean isSynchronous();

    /**
     * Returns the destination of this messenger.
     *
     * @return The destination address of this messenger
     * @see Messenger#getLogicalDestinationAddress()
     */
    EndpointAddress getDestinationAddress();

    /**
     * Returns the internal EndpointAddress object of the destination of the user. 
     * This method is intended to be used for applications that require a weak
     * or soft reference to an EndpointMessenger: the returned Endpoint Address 
     * object will be unreferenced when this messenger will finalize.
     *
     * @deprecated EndpointAddress is now immutable which means that this result
     * is the same as {@link #getDestinationAddress()}. This method will be
     * eventually removed.
     *
     * @return EndpointAddress the destination address of this messenger
     * @see #getDestinationAddress()
     */
    @Deprecated
    EndpointAddress getDestinationAddressObject();

    /**
     * Returns the logical destination of this messenger. This may be a
     * different address than is returned by
     * {@link #getDestinationAddress() getDestinationAddress} and refers to
     * the entity which is located at the destination address.
     * <p/>
     * By analogy, a telephone number would be the destination address, and
     * the owner of that telephone number would be the logical destination.
     * Each logical destination may be known by one or more destination
     * addresses.
     *
     * @return EndpointAddress the logical destination address of this messenger.
     * @see #getDestinationAddress()
     */
    EndpointAddress getLogicalDestinationAddress();

    /**
     * Returns the maximum message size that this messenger can be used to send.
     * The limit refers to the cumulative size of application level elements.
     * The various {@code sendMessage()} variants will refuse to send messages
     * that exceed this limit.
     *
     * @return the limit.
     */
    long getMTU();

    /**
     * If applicable, returns another messenger that will send messages to the same destination address than this one, but with
     * the specified default service and serviceParam, possibly rewriting addresses to ensure delivery through the specified
     * redirection. This is not generally useful to applications and most messengers will return null. This method is needed
     * by the EndpointService when interacting with Messengers provided by Transport modules. If you are not implementing a
     * Transport module, then you can ignore this method.
     * <p/>
     * <b>Important:</b> The channel so obtained is not configured to support the {@link #sendMessage(Message,String,String,
     *OutgoingMessageEventListener)} legacy method. If use of this method is desired, {@link ChannelMessenger#setMessageWatcher}
     * must be used first.
     *
     * @param redirection  The requested redirection. The resulting channel messenger will use this to force
     *                     delivery of the message only in the specified group (or possibly descendents, but not parents). If null the local
     *                     group is assumed. This redirection is applied only to messages that are sent to a service name and service param that
     *                     do not imply a group redirection.
     * @param service      The service to which the resulting channel will send messages, when they are not sent to a
     *                     specified service.
     * @param serviceParam The service parameter that the resulting channel will use to send messages, when no parameter is
     *                     specified.
     * @return a channelMessenger as specified.
     * @see MessageSender#getMessenger(EndpointAddress,Object)
     */
    Messenger getChannelMessenger(PeerGroupID redirection, String service, String serviceParam);

    /**
     * Close this messenger after processing any pending messages. This method 
     * is not blocking. Upon return, the messenger will be in one of the non 
     * {@link #USABLE} states, which means that no message may be sent through 
     * it. Any other effect of this method, such as an underlying connection 
     * being closed, or all pending messages being processed, may be deferred
     * indefinitely.  When the messenger has completely processed the closure 
     * request, it will be in one of the {@link #TERMINAL} states (which are 
     * also {@link #IDLE} states). Therefore, if one is interested in the 
     * outcome of the closure, one may wait for the messenger to be in a 
     * {@link #TERMINAL} or {@link #IDLE} state, and check which it is. 
     * {@link #CLOSED} denotes success (all outstanding messages have been 
     * sent), as opposed to {@link #UNRESOLVABLE} or {@link #BROKEN}.
     */
    void close();

    /**
     * Makes sure that all outstanding messages have been processed; 
     * successfully or not. This method waits unless and until the state of the 
     * messenger is an {@link #IDLE} state. If the reached state is neither 
     * {@link #CLOSED} or any {@link #USABLE} state, then it throws an 
     * IOException. Else it returns silently.<p/>
     * 
     * <p/><b>If another thread keeps sending messages, this method may never 
     * return.</b>
     * 
     * <p/>This method is deliberately simple. If a timeout needs to be 
     * provided, or if more detailed conditions are required, the 
     * {@link #waitState(int,long)} and {@link #getState()} methods should be 
     * used. For example : 
     * 
     * <p/><code><pre>
     * int myFlush(long notTooLong) {
     *   messenger.waitState(IDLE, notTooLong);
     *   if ((messenger.getState() & IDLE) == 0) return TOOLONG;
     *   if ((messenger.getState() & USABLE) != 0) return FLUSHED;
     *   if (messenger.getState() == CLOSED) return CLOSEDANDFLUSHED;
     *   return BROKEN;
     * }
     * </pre></code>
     * 
     * <p/>Note: {@link #close()} being asynchronous, it is valid to invoke 
     * <code>flush()</code> after <code>close()</code> as a form of synchronous 
     * variant of <code>close()</code>. If this messenger is not shared with any 
     * other thread, then invoking <code>flush()</code> before 
     * <code>close</code> is a more familiar means of achieving the same effect.
     *
     * @throws IOException This messenger failed before processing all 
     * outstanding messages successfully.
     */
    void flush() throws IOException;

    /**
     * Force the messenger to start resolving if it is not resolved yet. Any 
     * attempt at sending a message has the same effect, but the message may 
     * fail as a result, depending upon the method used.
     */
    void resolve();

    /**
     * Simple sending: blocks until the message was accepted for sending or the messenger is not {@link #USABLE}; whichever occurs
     * first.  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/>
     * <p/>
     * Error Handling:
     * <p/>
     * <ul>