Module proton :: Class Messenger

Class Messenger

object --+
         |
        Messenger

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:

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 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

send(self)
Blocks until the outgoing queue is empty or the operation times out.

source code

recv(self, n)
Receives up to n messages into the incoming queue of the Messenger.

source code

get(self, message)
Moves the message from the head of the incoming message queue into the supplied message object.

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

send(self)

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)

source code

Receives up to n messages into the incoming queue of the Messenger. This method will block until at least one message is available or the operation times out.

get(self, message)

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

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)

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.

Class Messenger

Address Syntax

Sending & Receiving Messages

__init__(self, name=None) (Constructor)

start(self)

stop(self)

subscribe(self, source)

put(self, message)

send(self)

recv(self, n)

get(self, message)

name

certificate

private_key

password

trusted_certificates

timeout

outgoing

incoming

init(self, name=None)
(Constructor)