Menu Search

5.6. MessageConsumer

A MessageConsumer receives messages from a Queue or Topic.

MessageConsumer objects are created from the Session.

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

5.6.1. Consumers have Exchange/Queue Declaration and Binding Side Effect

By default, calling Session#createConsumer() will cause:

  1. If the exchange does not exist on the Broker, it will be created. The exchange is specified by the Binding URL associated with the Destination.

  2. If the queue does not exist on the Broker, it will be created. The queue is specified by the Binding URL associated with the Destination.

  3. If there is no binding between the exchange and queue, a binding will be created using the routingkey as a bindingkey. The exchange, queue and routing key are specified by the Binding URL associated with the Destination.

The exchange declare, queue declare and bind side effects can be suppressed using system properties qpid.declare_exchanges, qpid.declare_queues and qpid.bind_queues.

5.6.2. Topic Subscriptions

The Client implements each subscription to a Topic as separate queue on the Broker. From the perspective of the JMS application this implementational detail is irrelevant: the application never needs to directly address these queues. However, these details are important when considering Management and Operational concerns.

Durable topic subscriptions use a durable and exclusive queue named as follows:

        clientid: + subscriptionId
      

where subscriptionId is that passed to the Session#createDurableSubscriber(javax.jms.Topic,java.lang.String)

Calling Session#unsubscribe(java.lang.String) deletes the underlying queue.

Non-durable topic subscriptions use a non-durable, exclusive and auto-delete queue named as follows:

        tmp + _ + ip + _ + port + _ + sequence
      

where ip is the ip address of the client with dots replaced by underscores, port is the ephemeral port number assigned to the client's connection, and sequence is a sequence number.

Closing the consumer (or closing the connection) will delete the underlying queue.

5.6.3. Maximum Delivery Count

With this feature, the Broker keeps track of a number of times a message has been delivered to a consumer. If the count ever exceeds a threshold value, the Broker moves the message to a dead letter queue (DLQ). This is used to prevent poison messages preventing a system's operation. This client feature requires support for the corresponding feature by the Broker.

When using this feature, the application must either set system property qpid.reject.behaviour or the Binding URL option rejectbehaviour to the value server.

See Handling Undeliverable Messages within the Apache Qpid Broker-J book for full details of the functioning of this feature.

Note

The optional JMS message header JMSXDeliveryCount is not supported.