messenger.java

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

     *
     * <p/>Messenger has terminated its useful life. State will never change any more.
     **/
    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 descreet 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/>
     * 
     * Ensure that the messenger can take more messages (or is {@code UNUSABLE}): {@code waitState(~SATURATED)}<p/>
     * 
     * Ensure that all submitted messages have been sent: {@code waitState( TERMINAL | IDLE )}
     * 
     * 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. The messenger should be discarded.
     *
     *  @return {@code true} if this messenger is closed, otherwise 
     *  {@code false}.
     *
     *  @deprecated Use {@code (getState() & USABLE == 0)} instead.
     **/
    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.
     */
    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.
     **/
    boolean isSynchronous();

    /**
     *  Returns the destination of this messenger. The returned EndpointAddress is a clone and can be freely used by the caller.
     *
     *  @see Messenger#getLogicalDestinationAddress()
     *
     *  @return EndpointAddress the destination address of this messenger
     **/
    EndpointAddress getDestinationAddress();
    
    /**
     *  Returns the internal EndpointAddress object of the destination of the user. Changing the content of the object may have
     *  unpredictable consequence on the behavior of the EndpointMessenger. This method is intended to be used for applications
     *  that requires to have weak or soft reference to an EndpointMessenger: the returned Endpoint Address object will be
     *  unreferenced when this messenger will finalize.
     *
     *  @see #getDestinationAddress()
     *
     *  @return EndpointAddress the destination address of this messenger
     **/
    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.
     *
     *  @see #getDestinationAddress()
     *
     *  @return EndpointAddress the logical destination address of this messenger.
     **/
    EndpointAddress getLogicalDestinationAddress();

    /**
     *  Returns the maximum message size that this messenger can be used to send. 
     *  The limit refers to the cummulative size of application level elements. 
     *  The various {@code sendMessage()} varients 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 generaly usefull 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.
     *
     * @see MessageSender#getMessenger(EndpointAddress, Object)
     *
     * @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 decendants, 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.
     **/
     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 interrested 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/>
     *
     * <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.<p/>
     *
     * @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:
     *
     * <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 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>
     *
     *   <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