org.apache.qpid.proton.messenger
Interface Messenger


public interface Messenger

Messenger defines a high level interface for sending and receiving messages. Every Messenger contains a single logical queue of incoming messages and a single logical queue of outgoing messages. These messages in these queues may be destined for, or originate from, a variety of addresses.

Address Syntax

An address has the following form: [ amqp[s]:// ] [user[:password]@] domain [/[name]] Where domain can be one of: host | host:port | ip | ip:port | name The following are valid examples of addresses: - example.org - example.org:1234 - amqp://example.org - amqps://example.org - example.org/incoming - amqps://example.org/outgoing - amqps://fred:trustno1@example.org - 127.0.0.1:1234 - amqps://127.0.0.1:1234

Sending & Receiving Messages

The Messenger interface works in conjuction with the Message class. The Message class is a mutable holder of message content. The put method will encode the content in a given Message object into the outgoing message queue leaving that Message object free to be modified or discarded without having any impact on the content in the outgoing queue. Similarly, the get method will decode the content in the incoming message queue into the supplied Message object.


Field Summary
static int CUMULATIVE
          Flag for use with reject(), accept() and settle() methods.
 
Method Summary
 void accept(Tracker tracker, int flags)
          Accepts messages retrieved from the incoming message queue.
 Message get()
          Returns the message from the head of the incoming message queue.
 int getIncomingWindow()
           
 int getOutgoingWindow()
           
 Status getStatus(Tracker tracker)
          Gets the last known remote state of the delivery associated with the given tracker.
 long getTimeout()
           
 int incoming()
          Returns a count of the messages available on the incoming queue.
 Tracker incomingTracker()
          Returns a token which can be used to accept or reject the message returned in the previous get() call.
 void interrupt()
           
 boolean isBlocking()
           
 int outgoing()
          Returns a count of the messages currently on the outgoing queue (i.e.
 Tracker outgoingTracker()
          Returns a token which can be used to track the status of the message of the previous put() call.
 void put(Message message)
          Places the content contained in the message onto the outgoing queue of the Messenger.
 void recv()
          Receives an arbitrary number of messages into the incoming queue of the Messenger.
 void recv(int count)
          Receives up to the specified number of messages into the incoming queue of the Messenger.
 void reject(Tracker tracker, int flags)
          Rejects messages retrieved from the incoming message queue.
 void send()
          Blocks until the outgoing queue is empty and, in the event that an outgoing window has been set, until the messages in that window have been received by the target to which they were sent, or the operation times out.
 void send(int n)
           
 void setBlocking(boolean b)
           
 void setIncomingWindow(int window)
           
 void setOutgoingWindow(int window)
           
 void setTimeout(long timeInMillis)
           
 void settle(Tracker tracker, int flags)
           
 void start()
          Transitions the Messenger to an active state.
 void stop()
          Transitions the Messenger to an inactive state.
 boolean stopped()
           
 void subscribe(java.lang.String source)
          Subscribes the Messenger to messages originating from the specified source.
 boolean work(long timeout)
           
 

Field Detail

CUMULATIVE

static final int CUMULATIVE
Flag for use with reject(), accept() and settle() methods.

See Also:
Constant Field Values
Method Detail

put

void put(Message message)
         throws MessengerException
Places the content contained in the message onto the outgoing queue of the Messenger. This method will never block. The send call may be used to block until the messages are sent. Either a send() or a recv() call is neceesary at present to cause the messages to actually be sent out.

Throws:
MessengerException

send

void send()
          throws TimeoutException
Blocks until the outgoing queue is empty and, in the event that an outgoing window has been set, until the messages in that window have been received by the target to which they were sent, or the operation times out. The timeout property controls how long a Messenger will block before timing out.

Throws:
TimeoutException

send

void send(int n)
          throws TimeoutException
Throws:
TimeoutException

subscribe

void subscribe(java.lang.String source)
               throws MessengerException
Subscribes the Messenger to messages originating from the specified source. The source is an address as specified in the Messenger introduction with the following addition. If the domain portion of the address begins with the '~' character, the Messenger will interpret the domain as host/port, bind to it, and listen for incoming messages. For example "~0.0.0.0", "amqp://~0.0.0.0" will bind to any local interface and listen for incoming messages.

Throws:
MessengerException

recv

void recv()
          throws TimeoutException
Receives an arbitrary number of messages into the incoming queue of the Messenger. This method will block until at least one message is available or the operation times out.

Throws:
TimeoutException

recv

void recv(int count)
          throws TimeoutException
Receives up to the specified number of messages into the incoming queue of the Messenger. This method will block until at least one message is available or the operation times out.

Throws:
TimeoutException

get

Message get()
Returns the message from the head of the incoming message queue.


start

void start()
           throws java.io.IOException
Transitions the Messenger to an active state. A Messenger is initially created in an inactive state. When inactive, a Messenger will not send or receive messages from its internal queues. A Messenger must be started before calling send() or recv().

Throws:
java.io.IOException

stop

void stop()
Transitions the Messenger to an inactive state. An inactive Messenger will not send or receive messages from its internal queues. A Messenger should be stopped before being discarded to ensure a clean shutdown handshake occurs on any internally managed connections.


stopped

boolean stopped()

work

boolean work(long timeout)

interrupt

void interrupt()

setTimeout

void setTimeout(long timeInMillis)

getTimeout

long getTimeout()

isBlocking

boolean isBlocking()

setBlocking

void setBlocking(boolean b)

outgoing

int outgoing()
Returns a count of the messages currently on the outgoing queue (i.e. those that have been put() but not yet actually sent out).


incoming

int incoming()
Returns a count of the messages available on the incoming queue.


getIncomingWindow

int getIncomingWindow()

setIncomingWindow

void setIncomingWindow(int window)

getOutgoingWindow

int getOutgoingWindow()

setOutgoingWindow

void setOutgoingWindow(int window)

incomingTracker

Tracker incomingTracker()
Returns a token which can be used to accept or reject the message returned in the previous get() call.


outgoingTracker

Tracker outgoingTracker()
Returns a token which can be used to track the status of the message of the previous put() call.


reject

void reject(Tracker tracker,
            int flags)
Rejects messages retrieved from the incoming message queue. The tracker object for a message is obtained through a call to incomingTracker() following a get(). If the flags argument contains CUMULATIVE, then all message up to the one identified by the tracker will be rejected.


accept

void accept(Tracker tracker,
            int flags)
Accepts messages retrieved from the incoming message queue. The tracker object for a message is obtained through a call to incomingTracker() following a get(). If the flags argument contains CUMULATIVE, then all message up to the one identified by the tracker will be accepted.


settle

void settle(Tracker tracker,
            int flags)

getStatus

Status getStatus(Tracker tracker)
Gets the last known remote state of the delivery associated with the given tracker.