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.
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(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	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.
void	subscribe(String source) Subscribes the Messenger to messages originating from the specified source.

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

subscribe

void subscribe(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(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 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:

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.

setTimeout

void setTimeout(long timeInMillis)

getTimeout

long getTimeout()

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.