NAME

Crixa::Exchange - A Crixa Exchange

VERSION

version 0.13

DESCRIPTION

This class represents a single exchange. With RabbitMQ, messages are published to an exchange. Queues can then connect to exchanges and receive those messages.

METHODS

This class provides the following methods:

Crixa::Exchange->new

You should not call this method directly under normal circumstances. Instead, you should create an exchange by calling the exchange method on a Crixa::Channel object. However, you need to know what parameters the constructor accepts.

• name => $name

  This is a required string. Note that the empty string is acceptable here, as this is the default exchange name for RabbitMQ.

• exchange_type => $type

  This is an optional string. It can be any type of exchange supported by RabbitMQ, including those provided by plugins.

  This defaults to "direct".

• passive => $bool

  If this is true, then the constructor will throw an error unless the exchange already exists.

  This defaults to false.

• durable => $bool

  If this is true, then the exchange will remain active across server restarts.

  This has nothing to do with whether messages are stored! In order to make sure messages are written to disk, you must declare the queue as durable

  This defaults to false.

• auto_delete => $bool

  If this is true, then the exchange will be deleted when all queues have finished using it.

  This defaults to true.

$exchange->publish(...)

This method sends a message to the exchange. It accepts either a hash or hashref with the following keys:

• routing_key

  This is an optional routing key for the message. If this is not provided then the empty string is used.

• body

  This is the message body. This should be a scalar containing any sort of data.

• mandatory

  If this is true, then if the message cannot be routed to a queue, the server will return an unroutable message. This defaults to false.

  Note that as of this writing Net::AMQP::RabbitMQ does not support return messages from publishing, so this flag is not really useful.

• immediate

  If this is true, then if the message cannot be routed immediately, the server will return an undeliverable message. This defaults to false.

  Note that as of this writing Net::AMQP::RabbitMQ does not support return messages from publishing, so this flag is not really useful.

• props

  This is an optional hashref containing message metadata:

  • content_type => $ct

    This should be a MIME type like "application/json" or "text/plain". This is exactly like an HTTP Content-Type header.

    Note that RabbitMQ doesn't really care about the content of your message. This is for the benefit of whatever code eventually consumes this message.

  • content_encoding => $enc

    The MIME content encoding of the message. This is exactly like an HTTP Content-Encoding header.

    Note that RabbitMQ doesn't really care about the content of your message. This is for the benefit of whatever code eventually consumes this message.

  • message_id => $id

    A unique identifier for the message that you create.

  • correlation_id => $correlation

    This is the ID of the message for which the message you're publishing is a reply to.

  • reply_to => $reply_to

    This is typically used to name the queue to which reply messages should be sent.

  • expiration => $expiration

    This is the message expiration as a number in milliseconds. If the message cannot be delivered within that time frame it will be discarded.

    If both the queue and the message define an expiration time, the lower of the two will be used.

  • type => $type

    The message type (not content type) as a string. This could be something like "order" or "email", etc.

  • user_id => $user_id

    A string identifying the message's sender. If this is provided, then RabbitMQ requires that this be identical to the username used to connect to RabbitMQ.

  • app_id => $app_id

    This is a string identifying the app that sent the message. For example, you might used something like "webcrawler" or "rest-api".

  • delivery_mode => $mode

    This can either be 1 or 2. A 1 is "non-persistent" and a 2 is "persistent". This defines whether or not the message is stored on disk so that it can be recovered across RabbitMQ server restarts.

    Note that even if you set the exchange and queue to be durable, you still must specify the delivery_mode as persistent in order for it to be saved!

  • timestamp => $epoch

    This is an epoch time indicating when the message was sent.

  • priority => $priority

    This can be a number from 0 to 9, but RabbitMQ ignores this.

  • headers => { ... }

    An arbitrary hashref of headers. This is something like "X-*" headers in HTTP. You can put anything you want here. This is used when matching messages to queues via a headers-type exchange.

  You are strongly encouraged to use the well-known properties listed above instead of encoding similar information in the message body or in the headers property.

Note that if you publish a message and there is no queue bound to the exchange which can receive that message, the message will be discarded. This means you must create your exchanges and queues before you publish any messages..

$exchange->queue(...)

This returns a new Crixa::Queue object. This method accepts all of the arguments that can be passed to the Crixa::Queue constructor, either as a hash or hashref. See the Crixa::Queue documentation for more details.

In addition, it also accepts a routing_keys parameter, which should be an arrayref of strings. If these are provided, then the queue is bound to the exchange with each string in the arrayref as a routing key.

This is a convenient way of declaring and binding a queue all at once.

$exchange->delete(...)

This deletes the exchange. It accepts either a hash or hashref with the following keys:

• if_unused => $bool

  If this is true, then the exchange is only deleted if it has no queue bindings. This defaults to true.

• no_wait => $bool

  If this is true, then the method returns immediately without getting confirmation from the server. This defaults to false.

$exchange->name(...)

This returns the exchange name as passed to the constructor.

$exchange->channel

Returns the Crixa::Channel that this exchange uses.

$exchange->exchange_type

This returns the exchange type as passed to the constructor or set by a default.

$exchange->passive

This returns the passive flag as passed to the constructor or set by a default.

$exchange->durable

This returns the durable flag as passed to the constructor or set by a default.

$exchange->auto_delete

This returns the auto-delete flag as passed to the constructor or set by a default.

AUTHORS

• Chris Prather <chris@prather.org>

• Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 - 2015 by Chris Prather.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Crixa

perl -MCPAN -e shell
install Crixa