Menu Search

5.5. MessageProducer

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 Java Broker book.

It is important to understand that when not used on a transactional session, 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 Qpid JMS 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.

Qpid JMS MessageProducers have a number of features above that required by JMS. These are described in the sub-sections that follow.

5.5.1. Mandatory Messages

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.

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

Please note, according to AMQP specifications the mandatory flag on a message tells the server how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a Return method. If this flag is zero, the server silently drops the message. Please, refer AMQP specifications for more details.

5.5.2. Close When No Route

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 Java Broker book for full details of the functioning of this feature.

5.5.3. Immediate Messages

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.

The immediate message feature is turned off by default. It can be enabled with system property qpid.default_immediate.

5.5.4. Flow Control

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 Java Broker book for full details of the functioning of this feature.