Module proton :: Class Messenger
[frames] | no frames]

Class Messenger

source code


The Messenger class 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:

Sending & Receiving Messages

The Messenger class 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.

>>> message = Message()
>>> for i in range(3):
...   message.address = "amqp://host/queue"
...   message.subject = "Hello World %i" % i
...   messenger.put(message)
>>> messenger.send()

Similarly, the get method will decode the content in the incoming message queue into the supplied Message object.

>>> message = Message()
>>> messenger.recv(10):
>>> while messenger.incoming > 0:
...   messenger.get(message)
...   print message.subject
Hello World 0
Hello World 1
Hello World 2
Instance Methods
 
__init__(self, name=None)
Construct a new Messenger with the given name.
source code
 
__del__(self) source code
 
start(self)
Transitions the Messenger to an active state.
source code
 
stop(self)
Transitions the Messenger to an inactive state.
source code
 
subscribe(self, source)
Subscribes the Messenger to messages originating from the specified source.
source code
 
put(self, message)
Places the content contained in the message onto the outgoing queue of the Messenger.
source code
 
status(self, tracker)
Gets the last known remote state of the delivery associated with the given tracker.
source code
 
settle(self, tracker=None) source code
 
send(self, n=-1)
Blocks until the outgoing queue is empty or the operation times out.
source code
 
recv(self, n=None)
Receives up to n messages into the incoming queue of the Messenger.
source code
 
work(self, timeout=None) source code
 
interrupt(self) source code
 
get(self, message=None)
Moves the message from the head of the incoming message queue into the supplied message object.
source code
 
accept(self, tracker=None)
Accepts messages retreived from the incoming message queue.
source code
 
reject(self, tracker=None)
Rejects messages retreived from the incoming message queue.
source code
 
route(self, pattern, address) source code
 
rewrite(self, pattern, address) source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties
  name
The name of the Messenger.
  certificate
Path to a certificate file for the Messenger.
  private_key
Path to a private key file for the Messenger's certificate.
  password
This property contains the password for the Messenger.private_key file, or None if the file is not encrypted.
  trusted_certificates
A path do a database of trusted certificates for use in verifying the peer on an SSL/TLS connection.
  timeout
The timeout property contains the default timeout for blocking operations performed by the Messenger.
  blocking
  incoming_window
The incoming tracking window for the messenger.
  outgoing_window
The outgoing tracking window for the messenger.
  stopped
  outgoing
The outgoing queue depth.
  incoming
The incoming queue depth.

Inherited from object: __class__

Method Details

__init__(self, name=None)
(Constructor)

source code 

Construct a new Messenger with the given name. The name has global scope. If a NULL name is supplied, a uuid.UUID based name will be chosen.

Parameters:
  • name (string) - the name of the messenger or None
Overrides: object.__init__

start(self)

source code 

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.

stop(self)

source code 

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.

subscribe(self, source)

source code 

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", and "amqps://~0.0.0.0" will all bind to any local interface and listen for incoming messages with the last variant only permitting incoming SSL connections.

Parameters:
  • source (string) - the source of messages to subscribe to

put(self, message)

source code 

Places the content contained in the message onto the outgoing queue of the Messenger. This method will never block, however it will send any unblocked Messages in the outgoing queue immediately and leave any blocked Messages remaining in the outgoing queue. The send call may be used to block until the outgoing queue is empty. The outgoing property may be used to check the depth of the outgoing queue.

Parameters:
  • message (Message) - the message to place in the outgoing queue
Returns:
a tracker

status(self, tracker)

source code 

Gets the last known remote state of the delivery associated with the given tracker.

Parameters:
  • tracker (tracker) - the tracker whose status is to be retrieved
Returns:
one of None, PENDING, REJECTED, or ACCEPTED

send(self, n=-1)

source code 

Blocks until the outgoing queue is empty or the operation times out. The timeout property controls how long a Messenger will block before timing out.

recv(self, n=None)

source code 

Receives up to n messages into the incoming queue of the Messenger. If n is not specified, Messenger will receive as many messages as it can buffer internally. This method will block until at least one message is available or the operation times out.

get(self, message=None)

source code 

Moves the message from the head of the incoming message queue into the supplied message object. Any content in the message will be overwritten.

Parameters:
  • message (Message) - the destination message object
Returns:
a tracker

accept(self, tracker=None)

source code 

Accepts messages retreived from the incoming message queue.

Parameters:
  • tracker (tracker) - a tracker as returned by get

reject(self, tracker=None)

source code 

Rejects messages retreived from the incoming message queue.

Parameters:
  • tracker (tracker) - a tracker as returned by get

Property Details

name

The name of the Messenger.

Get Method:
unreachable.name(self) - The name of the Messenger.

certificate

Path to a certificate file for the Messenger. This certificate is used when the Messenger accepts or establishes SSL/TLS connections. This property must be specified for the Messenger to accept incoming SSL/TLS connections and to establish client authenticated outgoing SSL/TLS connection. Non client authenticated outgoing SSL/TLS connections do not require this property.

Get Method:
_get_certificate(self)
Set Method:
_set_certificate(self, value)

private_key

Path to a private key file for the Messenger's certificate. This property must be specified for the Messenger to accept incoming SSL/TLS connections and to establish client authenticated outgoing SSL/TLS connection. Non client authenticated SSL/TLS connections do not require this property.

Get Method:
_get_private_key(self)
Set Method:
_set_private_key(self, value)

password

This property contains the password for the Messenger.private_key file, or None if the file is not encrypted.

Get Method:
_get_password(self)
Set Method:
_set_password(self, value)

trusted_certificates

A path do a database of trusted certificates for use in verifying the peer on an SSL/TLS connection. If this property is None, then the peer will not be verified.

Get Method:
_get_trusted_certificates(self)
Set Method:
_set_trusted_certificates(self, value)

timeout

The timeout property contains the default timeout for blocking operations performed by the Messenger.

Get Method:
_get_timeout(self)
Set Method:
_set_timeout(self, value)

blocking

Get Method:
_is_blocking(self)
Set Method:
_set_blocking(self, b)

incoming_window

The incoming tracking window for the messenger. The messenger will track the remote status of this many incoming deliveries after they have been accepted or rejected. Defaults to zero.

Get Method:
_get_incoming_window(self)
Set Method:
_set_incoming_window(self, window)

outgoing_window

The outgoing tracking window for the messenger. The messenger will track the remote status of this many outgoing deliveries after calling send. Defaults to zero.

Get Method:
_get_outgoing_window(self)
Set Method:
_set_outgoing_window(self, window)

stopped

Get Method:
unreachable.stopped(self)

outgoing

The outgoing queue depth.

Get Method:
unreachable.outgoing(self) - The outgoing queue depth.

incoming

The incoming queue depth.

Get Method:
unreachable.incoming(self) - The incoming queue depth.