(Quick Reference)

3 Configuration - Reference Documentation

Authors: Bud Byrd

Version: 3.1.3

3.1Server Connection

3.2Defining Queues

3.3Defining Exchanges

3.4Binding Queues and Exchanges

3 Configuration

Configuration of the connection to the RabbitMQ server is done in your project's grails-app/conf/Config.groovy file.

Below is the list of general configuration properties.

Configuration Property	Required	Description	Type	Default
`autoStart`		If true, will start any consumers during the bootstrap phase of the application startup.	`Boolean`	`true`
`enabled`		If false, will register the plugin's beans, but prevent the plugin connecting to the RabbitMQ broker(s) and consuming messages.	`String`	`true`

If autoStart is set to false, all of the connections to the broker will be initiated, but the message consumers will not automatically start consuming messages. To start consuming, use the rabbitContext bean and call rabbitContext.startConsumers().

3.1 Server Connection

The plugin expects the connection configuration to the RabbitMQ server to be defined. A bare minimum configuration example looks like:

rabbitmq {
    connection = {
        connection host: "example.com", username: "foo", password: "bar"
    }
}

Connections to many different RabbitMQ servers can be configured. A multi-server configuration looks like:

rabbitmq {
    connection = {
        connection host: "rabbit1.example.com", username: "foo", password: "bar"
        connection host: "rabbit2.example.com", username: "foo", password: "bar"
    }
}

The following table enumerates all the configuration options available to the connection configuration:

Configuration Property	Description	Type	Default
`host`	Hostname or IP address of the RabbitMQ server to connect to.	`String`	none
`username`	Username to log into the RabbitMQ server with.	`String`	none
`password`	Password to log into the RabbitMQ server with.	`String`	none
`name`	Name of the connection. This is used while sending messages to a specific RabbitMQ server when using multiple servers.	`String`	none
`isDefault`	A connection with this set to true will be the server messages are sent to if no specific connection is specified when sending the message.	`booleang`	`false`
`port`	Port to connect to the RabbitMQ server with.	`Integer`	5672
`virtualHost`	Name of the virtual host to connect to the RabbitMQ server with.	`String`	none
`ssl`	Whether to use SSL when connecting to a RabbitMQ server.	`boolean`	`false`
`threads`	Threadpool size, if greater than 0, determines how many concurrent messages can be processed at any given time. If set to 0, consumers can consume as many messages as it's configured to.	`String`	`0`
`automaticReconnect`	If true, will cause the application to automatically reconnect to a server when its connection is dropped.	`boolean`	`true`
`requestedHeartbeat`	Heartbeat interval, in seconds. A value of `0` disables heartbeats.	`Integer`	`0`

3.2 Defining Queues

The plugin allows authors to define the exchanges and queues programatically inside the configuration. This allows the application to configure its own queues without someone having to manually create the exchanges and queues prior to running the application.

Queue configuration is also done in the Config.groovy file under the rabbitmq block, much as the server connection is configured. Usage is best illustrated with an example:

rabbitmq {
    queues = {
        queue name: "example.queue", durable: true, exchange: "example.exchange"
    }
}

The above code will define a queue named example.queue, and its durable flag will be set.

Be sure to note that the queues property is a closure. You must ensure that the = is present for this feature to function properly.

If using the multi-server feature of the plugin, it is important to consider what server the queue should be defined in. The connection property specifies which server to create the queue in, illustrated below:

rabbitmq {
    queues = {
        // Assume there is a connection with the name "server1"…
        queue name: "example.queue", connection: "server1", durable: true
    }
}

If there are many queues to be defined for a specific server connection, the connection method provides a convenient way to bunch queue creation.

rabbitmq {
    queues = {
        // Assume there is a connection with the name "server1"…
        connection name: "server1", {
            queue name: "example.queue", durable: true
            queue name: "example2.queue", durable: true
        }
    }
}

Below is a table of all of the options available when defining queues:

Property	Description	Type	Default
`arguments`	Extra arguments used to create the queue. See the RabbitMQ documentation for more information.	`Map`	none
`autoDelete`	Whether to automatically delete the queue once there are no more consumers listening to it.	`boolean`	`false`
`binding`	Used in conjunction with exchanges. See the section below for more information.	Mixed	none
`durable`	Whether messages should be persisted to the disk on the RabbitMQ server to survive server restarts.	`boolean`	`false`
`exchange`	Binds a queue to an exchange in conjunction with the `binding` property. Ignored if used inside an exchange declaration.	`String`	none
`match`	Required when binding to a headers exchange. Either "any" or "all".	`String`	none
`name`	Name of the queue.	`String`	none
`connection`	Name of the connection to create the queue with. Uses the default connection if omitted.	`String`	none

3.3 Defining Exchanges

Defining exchanges is very similar to defining queues. The following code illustrates how to define an exchange:

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "topic"
    }
}

The above example will create an exchange with the name example.exchange and of the type topic. Below is a list of all the options availble when creating exchanges:

Property	Description	Type	Default
`arguments`	Extra arguments used to create the exchange. See the RabbitMQ documentation for more information.	`Map`	none
`autoDelete`	Whether to automatically delete the exchange once there are no longer any queues bound to it.	`boolean`	`false`
`durable`	Whether messages should be persisted to the disk on the RabbitMQ server to survive server restarts.	`boolean`	`false`
`name`	Name of the exchange.	`String`	none
`type`	One of "fanout", "topic", "direct", or "headers".	`String`	none
`connection`	Name of the connection to create the exchange with. Uses the default connection if omitted.	`String`	none

The same connection considerations exist for exchanges as with queues. The same connection method works for exchanges as well.

3.4 Binding Queues and Exchanges

Queues can be bound to an exchange by setting the exchange property when declaring the queue to the name of the exchange to bind to. This is the preferred method if the application being configured is not responsible for defining and configuring the exchange being bound to.

Queues can also be bound to an exchange by declaring the queues inside of a closure passed as the last parameter of an exchange definition. This is a convenient method to do queue binding when your application is responsible for defining and configuring the exchange.

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "topic", {
            queue name: "example.queue", binding: "sample.binding.#"
        }
    }
}

This example will create a topic exchange named example.exchange, as well as create a queue named example.queue. The queue will be bound to the exchange with the topic or routing key of "sample.binding.#".

Queues need to have their binding defined specifically for the type of exchange they are bound to.

Fanout Exchanges

Fanout exchanges are the easiest to configure bindings for, since they require none. Fanout exchanges simply send every message it received to every queue bound to it.

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "fanout", {
            queue name: "example.queue"
        }
    }
}

Topic Exchanges

Topic exchanges require queues to define a topic. Topics can be an exact match, but their strength is in their partial matching ability. See the RabbitMQ documentation for details about this kind of exchange.

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "topic", {
            queue name: "example.queue", binding: "exmaple.binding.#"
        }
    }
}

Direct Exchanges

Direct exchanges are similar to topic exchanges, except that their "topics" only function with direct name matching. The appropriate name for the binding in this case is "routing key". Queues must define a routing key when binding to this type of exchange.

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "direct", {
            queue name: "example.queue", binding: "exmapleRoutingKey"
        }
    }
}

Header Exchanges

Header exchanges are like topic exchanges, but with the ability to define multiple match keywords. The binding for queues allows the queue to match on all or one of multiple header values. The queue must also set the match property for this exchange type, and the value must be one of "any" or "all".

rabbitmq {
    queues = {
        exchange name: "example.exchange", type: "headers", {
            queue name: "example.queue", match: "any", binding: [
                "header1": "header-value-1",
                "header2": "header-value-2"
            ]
        }
    }
}

<< 2Quick Start

4Consuming Messages >>

3 Configuration - Reference Documentation

Table of Contents

3 Configuration

3.1 Server Connection

3.2 Defining Queues

3.3 Defining Exchanges

3.4 Binding Queues and Exchanges

Fanout Exchanges

Topic Exchanges

Direct Exchanges

Header Exchanges

Command Line

Connection Configuration

Consumer Configuration

Rabbit Message Publisher