2.2. Declaring Exchanges

An application can declare new exchanges, which may have either built-in or custom exchange types. A declared exchange continues to exist until the broker terminates or it is explicitly removed; if an exchange is declared to be persistent, it continues to exist even after a server restart.
Because there are no predeclared exchanges for custom exchange types, they can only be used if they are explicitly declared. There are predeclared exchanges for all built-in exchange types except for the default exchange, but there are often good reasons for creating new exchanges for these types as well; for instance:
  • Meaningful names: Exchanges can be created to provide names that are meaningful in the application domain. For instance, an exchange name can reflect the kind of messages that are sent to the exchange (e.g. invoices), geographical regions (e.g. carolinas), work queues (e.g. administrator), or other names that are meaningful within a given application domain.
  • Organizing the application: Exchanges can be created to organize the application. For instance, exchanges may be created to reflect priority levels, federation strategies, or other meaningful aspects of application organization.
  • Improving performance for large numbers of bindings: Exchanges with very large numbers of bindings perform more slowly than exchanges with smaller numbers of bindings. Using a larger number of exchanges reduces the number of bindings on each exchange, and can improve performance.
If an attempt is made to create an exchange that exists, no error is raised, provided the exchange is of the right exchange type. When an exchange is created, the following parameters can be provided to configure the exchange:

Exchange Declaration Parameters

  • type (string)
    The type of the exchange. May be a built-in type (e.g. direct, fanout, topic) or custom type (e.g. xml).
  • alternate_exchange (string)
    Exchange name for unroutable messages. If a message can not be routed to a queue, it is sent to the alternate exchange if the message's accept mode was set to none, discard unroutable was set to false, and no queue binding is satisfied by the message.
  • passive (Boolean)
    If set to true, test whether the exchange exists, without creating the exchange.
  • durable (Boolean)
    If set to true, the exchange is durable. Durable exchanges remain active if the server is restarted. If an exchange is not durable, it is purged when the server restarts.
  • auto_delete (Boolean)
    If set to true, the exchange is deleted automatically when the last queue binding for the exchange is deleted. If no bindings have been created for the queue, it is not deleted (if it were, it would not be possible to create such an exchange and bind a queue to it).
  • arguments (FieldTable)
    Implementation-defined options for queue creation. Apache Qpid defines the following options:
    • qpid.msg_sequence (Boolean)
      If set to true, the exchange inserts a sequence number named qpid.msg_sequence into the message headers of each message. The type of this sequence number is int64. The sequence number for the first message sent to the exchange is 0, it is incremented sequentially for each subsequent message, and wraps back to 0 when the capacity of an int64 is exceeded.
    • qpid.ive (Boolean)
      If set to true, the exchange is an initial value exchange, which differs from other exchanges in only one way: the last message sent to the exchange is cached, and if a new queue is bound to the exchange, it attempts to route this message to the queue, if the message matches the binding criteria. This allows a new queue to use the last received message as an initial value.
Section 12.1, “Using qpid-config shows how to create or delete exchanges using qpid-config.
In C++, exchanges are declared using Session_0_10::exchangeDeclare(). AMQP parameters correspond to named function arguments. For instance, the following declaration creates a direct exchange named incoming, specifies that unroutable messages on this exchange should be sent to an exchange named discarded, and specifies that the newly created exchange is durable:
// Declaring exchange parameters in C++

session.exchangeDeclare(arg::exchange="incoming", arg::type="direct", arg::alternateExchange="discarded", arg::durable=true);

In Python, exchanges are declared using Session.exchange_declare(). Here is the same exchange declaration in Python:
# Declaring exchange parameters in Python

session.exchange_declare(exchange="incoming", type="direct", alternate_exchange="discarded", durable=true)

Qpid exchange parameters are specified by placing them in a FieldTable, and passing it as the arguments parameter.
// Declaring Qpid exchange parameters in C++

FieldTable args;
args.setInt("qpid.msg_sequence",1);

session.exchangeDeclare(arg::exchange="incoming", arg::type="direct", arg::arguments=args);

Here is the same exchange declaration in Python:
args = {}
args["qpid.msg_sequence"] = 1

session.exchange_declare(exchange="incoming", type="direct", arguments=args)