Introduction
============

This package define basic components of a Messaging Gateway [#MessagingGateway]_ integrated inside Zope using AMQP.

Zope Component Architecture (ZCA) is about loosely coupled design in an Application.
AMQP is about loosely coupled communication between Applications. This package tries to join the two.

  * Documentation: http://docs.affinitic.be/affinitic.zamqp
  * Code Repository: http://bitbucket.org/jfroche/affinitic.zamqp
  * Buildbot: http://buildbot.affinitic.be/builders/affinitic.zamqp%20linux_debian/
  * Test Coverage: http://coverage.affinitic.be/affinitic.zamqp/affinitic.zamqp.html

AMQP
----

The Advanced Message Queuing Protocol [#amqp]_ is a very performant protocol that is implemented
in many platforms, many languages and thus can exchange information reliably between many framework/applications.
It enables good Enterprise Application Integration (EAI) [#EAI]_ and real loosely coupled systems
communication.

The most known AMQP open source servers (aka Message Broker) are: `RabbitMQ <http://www.rabbitmq.com>`_ and `Qpid <http://qpid.apache.org/>`_

Such message broker are scalable (using clustering) and performant enough to handle several thousand of messages a second. Most
of them handle hundred thousands queues without any problem.

Existing Python AMQP libraries
------------------------------

Python itself has different libraries available that implement the protocol. Here are the two most known libraries:

    * `amqplib <http://pypi.python.org/pypi/amqplib>`_
    * `txAMQP <http://pypi.python.org/pypi/txAMQP>`_

As you might not want to deal with a "low level" API, there is a higher level API available via
`carrot <http://pypi.python.org/pypi/carrot>`_.

Why this package ?
------------------

AFAIK Zope unfortunately doesn't have any AMQP integration.

The іdea behind this project is to provide a messaging solution together with the observer pattern
in Zope [#events]_. An image might help to understand what we try to implement here:

.. image:: zamqp.png

As you might also see, AMQP also permit asynchronous events in Zope.

What do we mean by Zope integration ?
-------------------------------------

  * Using ZCA to declare publisher, consumer and connection to broker. In other word, create a clean Messaging Gateway [#MessagingGateway]_ to be use with zope applications.
  * Messaging with transaction support. Meaning a transactional delivery support together with Zope transaction [#transaction]_ (and ZODB)
  * Using ZCA to implement the Message Translator pattern [#MessageTranslator]_
  * Using ZCA to implement a Publish-Subscribe (aka Observer pattern) inside Zope with message coming from a Queue

Dependencies
------------

We use `carrot <http://pypi.python.org/pypi/carrot>`_ to send/receive messages and enable consumers in separate threads within Zope. We use as much as possible the API defined by `carrot <http://pypi.python.org/pypi/carrot>`_. So you might want also to read the `carrot documentation <http://github.com/ask/carrot>`_.

We use `grok <http://grok.zope.org>`_ to define our zope components. This avoids us to write too much
zcml.

Tested with
-----------

We tested this package with:

    * Python 2.4 and Python 2.6
    * Zope 2.10 and 2.12
    * `five.dbevent <http://pypi.python.org/pypi/five.dbevent>`_ to add our event subscribers just after Zope database initialization
    * `RabbitMQ <http://www.rabbitmq.com>`_

.. rubric:: Footnotes

.. [#amqp] If needed here are some nice links that might help you to understand what AMQP is about:

    * http://blogs.digitar.com/jjww/2009/01/rabbits-and-warrens/
    * http://amqp.org

.. [#EAI] See:

    * http://en.wikipedia.org/wiki/Enterprise_application_integration
    * http://www.eaipatterns.com
    * A must read: Martin Fowler, *Patterns of Enterprise Application Architecture*, Addison-Wesley, 2003, ISBN: `0321127420 <http://www.amazon.com/exec/obidos/ASIN/0321127420/enterpriseint-20>`_

.. [#events] http://wiki.zope.org/zope3/events.html

.. [#transaction] http://pypi.python.org/pypi/transaction

.. [#MessageTranslator] http://www.eaipatterns.com/MessageTranslator.html

.. [#MessagingGateway] http://www.eaipatterns.com/MessagingGateway.html
