A MessageProducer sends a message an Exchange. It is the Exchange (within the Broker) that routes the message to zero or more queue(s). Routing is performed according to rules expressed as bindings between the exchange and queues and a routing key included with each message.
To understand how this mechanism is used to deliver messages to queues and topics, see Exchanges within the Apache Qpid Broker-J book.
It is important to understand that when synchronous publish is not exlicitly enabled, MessageProducer#send() is asynchronous in nature. When #send() returns to the application, the application cannot be certain if the Broker has received the message. The Client may not have yet started to send the message, the message could residing in a TCP/IP buffer, or the messages could be in some intermediate buffer within the Broker. If the application requires certainty the message has been received by the Broker, a transactional session must be used, or synchronous publishing must be enabled using either the system property or the connection URL option.
Qpid JMS MessageProducers have a number of features above that required by JMS. These are described in the sub-sections that follow.
With this feature, publishing a message with a routing key for which no binding exists on the exchange will result in the message being returned to the publisher's connection.
The Message is returned to the application in an asynchronous fashion via the Connection's ExceptionListener. When a message is returned, it will be invoked with a JMSException whose linked exception is an AMQNoRouteException. The returned message is available to the application by calling AMQNoRouteException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly once for each returned message.
If synchronous publishing has been enabled, and a mandatory message is returned, the MessageProducer#send() method will throw a JMSException.
The mandatory message feature is turned on by default for Queue
destinations and off for Topic destinations. This can be overridden
using system properties qpid.default_mandatory and qpid.default_mandatory_topic for Queues and Topics
respectively.
Note
If this the mandatory flag is not set, the Broker will treat the messages as unroutable.
With this feature, if a mandatory message is published with a routing key for which no binding exists on the exchange the Broker will close the connection. This client feature requires support for the corresponding feature by the Broker.
To enable or disable from the client, use the Connection URL option closeWhenNoRoute.
See Closing client connections on unroutable mandatory messages within the Apache Qpid Broker-J book for full details of the functioning of this feature.
This feature is defined in AMQP specifications.
When this feature is enabled, when publishing a message the Broker ensures that a Consumer is attached to queue. If there is no Consumer attached to the queue, the message is returned to the publisher's connection. The Message is returned to the application in an asynchronous fashion using the Connection's ExceptionListener.
The ExceptionListener will be invoked with a JMSException whose linked exception is an AMQNoConsumersException. The returned message is available to the application by calling AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly once for each returned message.
If synchronous publishing has been enabled, and an immediate message is returned, the MessageProducer#send() method will throw a JMSException.
The immediate message feature is turned off by default. It can be
enabled with system property qpid.default_immediate.
With this feature, if a message is sent to a queue that is overflow, the producer's session is blocked until the queue becomes underfull, or a timeout expires. This client feature requires support for the corresponding feature by the Broker.
To control the timeout use System property qpid.flow_control_wait_failure. To control the frequency with
which warnings are logged whilst a Session is blocked, use System property qpid.flow_control_wait_notify_period
See Producer Flow Control within the Apache Qpid Broker-Java book for full details of the functioning of this feature.
Apache Qpid, Messaging built on AMQP; Copyright © 2015 The Apache Software Foundation; Licensed under the Apache License, Version 2.0; Apache Qpid, Qpid, Qpid Proton, Proton, Apache, the Apache feather logo, and the Apache Qpid project logo are trademarks of The Apache Software Foundation; All other marks mentioned may be trademarks or registered trademarks of their respective owners