TL;DR
Langohr is a RabbitMQ Clojure client that embraces AMQP 0.9.1 model.
While Langohr is not yet quite ready for 1.0, it is past all major breaking changes and the doc site are in good enough shape to announce them.
A Brief History Lesson
Langohr is a RabbitMQ Clojure client that embraces AMQP 0.9.1 model. ClojureWerkz started with Langohr and it has served us well over the last 16 months or so. Before starting Langohr, ClojureWerkz core team members already had years of experience working with (and on) 3 other RabbitMQ clients:
- amqp gem
- the official Java client
- Hot Bunnies
However, up until now it’s lacked the key feature ClojureWerkz projects share: documentation guides. Fortunately, not any more.
Langohr Documentation Guides Are Here!
There is a good thing about starting Langohr documentation work later: Langohr benefits from amqp gem documentation guides that we’ve gotten good feedback on. In the end we decided to adapt amqp gem guides for Langohr, revisit and edit them and contribute any improvement that come to mind back to the Ruby client documentation.
Today we are happy to report that most of the work is already done and available at clojurerabbitmq.info:
Getting started
This is your typical Getting Started guide, covering things like RabbitMQ installation, adding Langohr as a dependency to your project, basic concepts and a few examples to demonstrate key features:
- The “Hello, world” of messaging
- Blabbr, a Twitter-like one-to-many topology example
- Weathr, an n-to-m topology example
AMQP Concepts
This article covers AMQP 0.9.1 model, concepts and protocol structure. It is not client-specific and now lives on rabbitmq.com so we simply link to it.
Conneciting To The Broker
This guide covers:
- How to connect to RabbitMQ with Langohr
- How to use connection URI to connect to RabbitMQ (also: on Heroku)
- How to open a channel
- How to close a channel
- How to disconnect
Queues and Consumers
This is the key article for applications that primarily consume messages.
For example:
- How to declare AMQP queues with Langohr
- Queue properties
- How to declare server-named queues
- How to declare temporary exclusive queues
- How to consume messages (“push API”)
- How to fetch messages (“pull API”)
- Message and delivery properties
- Message acknowledgements
- How to purge queues
- How to delete queues
- Other topics related to queues
Exchanges and Publishing
This is another long article that covers multiple topics relavant for apps that mostly produce messages.
It covers:
- Exchange types
- How to declare AMQP exchanges with Langohr
- How to publish messages
- Exchange propreties
- Fanout exchanges
- Direct exchanges
- Topic exchanges
- Default exchange
- Message and delivery properties
- Message routing
- Bindings
- How to delete exchanges
- Other topics related to exchanges and publishing
Together with the Queues guide, this is the bulk of Langohr documentation.
There are also several smaller guides most of which are not yet ready. They will be added as the time permits.
The Road To 1.0
Langohr 1.0
is still a few months away. The API is largely locked down but we take a conservative stance and try to be careful about
calling things “done”. There is still a number of features we’d like to add before the big 1.0
release and a number of small documentation
guides still remain to be written.
Thank You Contributors
We would like to thank people who have helped make Langohr documentation better by reviewing our drafts, suggesting improvements, correcting the grammar and simply encouraging us to take this project through to completion:
- Theo Hultberg
- Álvaro Videla
- Chris Duncan (for editing the original amqp gem guides)
If you’d like to contribute, all the docs are open source and available on GitHub. Fork away and submit us a pull request when you are done.
News and Updates
If you’d like to follow Langohr progress, new releases and updates are announced on Twitter. Langohr also has a mailing list, feel free to ask questions and report issues there.
Langohr is a ClojureWerkz Project
Langohr is part of the group of libraries known as ClojureWerkz, together with
- Elastisch, a minimalistic well documented Clojure client for ElasticSearch
- Welle, a Riak client with batteries included
- Monger, a Clojure MongoDB client for a more civilized age
- Neocons, a client for the Neo4J REST API
- Quartzite, a powerful scheduling library
and several others. If you like Langohr, you may also like our other projects.
Let us know what you think on Twitter or on the Clojure mailing list.
The ClojureWerkz Team