Messenger (proton-j 0.8.redhat-001 API)

All Known Implementing Classes:

MessengerImpl
```
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.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class Messenger.Factory

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Messenger.Factory`

Field Summary

Fields
Modifier and Type Field and Description

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

Fields
Modifier and Type	Field and Description
`static int`	`CUMULATIVE` Flag for use with reject(), accept() and settle() methods.

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`java.lang.String`	`getCertificate()` Get the path to the certificate file.
`int`	`getIncomingWindow()`
`int`	`getOutgoingWindow()`
`java.lang.String`	`getPassword()` Get the password for the priate key file.
`java.lang.String`	`getPrivateKey()` Get the path to the private key file.
`Status`	`getStatus(Tracker tracker)` Gets the last known remote state of the delivery associated with the given tracker.
`long`	`getTimeout()`
`java.lang.String`	`getTrustedCertificates()` Get the path to the trusted certificate database.
`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.
`int`	`receiving()` Returns the capacity of the incoming message queue of 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`	`rewrite(java.lang.String pattern, java.lang.String address)`
`void`	`route(java.lang.String pattern, java.lang.String address)`
`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`	`setCertificate(java.lang.String certificate)` Set the path to the certificate file.
`void`	`setIncomingWindow(int window)`
`void`	`setOutgoingWindow(int window)`
`void`	`setPassword(java.lang.String password)` Set the password for private key file.
`void`	`setPrivateKey(java.lang.String privateKey)` Set the path to private key file.
`void`	`setTimeout(long timeInMillis)`
`void`	`settle(Tracker tracker, int flags)`
`void`	`setTrustedCertificates(java.lang.String trusted)` Set the path to the trusted certificate database.
`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)` Sends or receives any outstanding messages queued for a messenger.

- 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
  - receiving
```
int receiving()
```
    Returns the capacity of the incoming message queue of messenger. Note this count does not include those messages already available on the incoming queue (see incoming()). Rather it returns the number of incoming queue entries available for receiving messages
  - 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)
             throws TimeoutException
```
    Sends or receives any outstanding messages queued for a messenger. If timeout is zero, no blocking is done. A timeout of -1 blocks forever, otherwise timeout is the maximum time (in millisecs) to block. Returns True if work was performed.
    
    Throws:
    
    TimeoutException
  - 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.
  - route
```
void route(java.lang.String pattern,
         java.lang.String address)
```
  - rewrite
```
void rewrite(java.lang.String pattern,
           java.lang.String address)
```
  - setCertificate
```
void setCertificate(java.lang.String certificate)
```
    Set the path to the certificate file.
  - getCertificate
```
java.lang.String getCertificate()
```
    Get the path to the certificate file.
  - setPrivateKey
```
void setPrivateKey(java.lang.String privateKey)
```
    Set the path to private key file.
  - getPrivateKey
```
java.lang.String getPrivateKey()
```
    Get the path to the private key file.
  - setPassword
```
void setPassword(java.lang.String password)
```
    Set the password for private key file.
  - getPassword
```
java.lang.String getPassword()
```
    Get the password for the priate key file.
  - setTrustedCertificates
```
void setTrustedCertificates(java.lang.String trusted)
```
    Set the path to the trusted certificate database.
  - getTrustedCertificates
```
java.lang.String getTrustedCertificates()
```
    Get the path to the trusted certificate database.

Interface Messenger

Address Syntax

Sending & Receiving Messages

Nested Class Summary

Field Summary

Method Summary

Field Detail

CUMULATIVE

Method Detail

put

send

send

subscribe

recv

recv

receiving

get

start

stop

stopped

work

interrupt

setTimeout

getTimeout

isBlocking

setBlocking

outgoing

incoming

getIncomingWindow

setIncomingWindow

getOutgoingWindow

setOutgoingWindow

incomingTracker

outgoingTracker

reject

accept

settle

getStatus

route

rewrite

setCertificate

getCertificate

setPrivateKey

getPrivateKey

setPassword

getPassword

setTrustedCertificates

getTrustedCertificates