Class Messenger
source code
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
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
send(self)
Blocks until the outgoing queue is empty or the operation times out. |
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
|
|
|
|
|
|
Inherited from object :
__delattr__ ,
__format__ ,
__getattribute__ ,
__hash__ ,
__new__ ,
__reduce__ ,
__reduce_ex__ ,
__repr__ ,
__setattr__ ,
__sizeof__ ,
__str__ ,
__subclasshook__
|
|
certificate = property(_get_certificate, _set_certificate, doc...
|
|
private_key = property(_get_private_key, _set_private_key, doc...
|
|
password = property(_get_password, _set_password, doc= ...
|
|
trusted_certificates = property(_get_trusted_certificates, _se...
|
|
timeout = property(_get_timeout, _set_timeout, doc= ...
|
|
incoming_window = property(_get_incoming_window, _set_incoming...
|
|
outgoing_window = property(_get_outgoing_window, _set_outgoing...
|
Inherited from object :
__class__
|
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__
|
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.
|
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.
|
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
|
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
|
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
|
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.
|
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.
|
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
|
Accepts messages retreived from the incoming message queue.
- Parameters:
tracker (tracker) - a tracker as returned by get
|
Rejects messages retreived from the incoming message queue.
- Parameters:
tracker (tracker) - a tracker as returned by get
|
The outgoing queue depth.
- Decorators:
|
The incoming queue depth.
- Decorators:
|
certificate
- Value:
property(_get_certificate, _set_certificate, doc= """
Path to a certificate file for the L{Messenger}. This certificate is
used when the L{Messenger} accepts or establishes SSL/TLS connections.
This property must be specified for the L{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.
""")
|
|
private_key
- Value:
property(_get_private_key, _set_private_key, doc= """
Path to a private key file for the L{Messenger's<Messenger>}
certificate. This property must be specified for the L{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.
""")
|
|
password
- Value:
property(_get_password, _set_password, doc= """
This property contains the password for the L{Messenger.private_key}
file, or None if the file is not encrypted.
""")
|
|
trusted_certificates
- Value:
property(_get_trusted_certificates, _set_trusted_certificates, doc= ""
"
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.
""")
|
|
timeout
- Value:
property(_get_timeout, _set_timeout, doc= """
The timeout property contains the default timeout for blocking
operations performed by the L{Messenger}.
""")
|
|
incoming_window
- Value:
property(_get_incoming_window, _set_incoming_window, doc= """
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.
""")
|
|
outgoing_window
- Value:
property(_get_outgoing_window, _set_outgoing_window, doc= """
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.
""")
|
|