Create a Message Consumer

Message consumers are clients that receive messages published to a topic or sent to a queue. When working with topics, a Message Consumer is commonly referred to as a Subscriber.

A Message Consumer can be created with a "message selector" that restricts the consumption of message to those with specific properties. When creating a Message Consumer for topics, you can set a noLocal attribute that prohibits the consumption of messages that are published over the same connection from which they are consumed.

Carefully consider the message selectors that are used with queue consumers. Because messages that do not match a queue consumer’s message selectors remains in the queue until it is retrieved by another consumer, a non-matching message can experience many failed selectors. This is especially so when queue consumers connect, consume a message, and immediately disconnect.

As described in Durable Subscribers for Topics, messages published to topics are only consumed by active subscribers to the topic; otherwise the messages are not consumed and cannot be retrieved later. You can create a durable subscriber that ensures messages published to a topic are received by the subscriber, even if it is not currently running. For queues, messages remain on the queue until they are either consumed by a Message Consumer, the message expiration time has been reached, or the maximum size of the queue is reached.

The following examples create a Message Consumer that consumes messages from the queue and a durable subscriber that consumes messages from a topic. The queue and topic are those that were dynamically created in Dynamically Create Topics and Queues.

Note: The createDurableSubscriber method either creates a new durable subscriber for a topic or attaches the client to a previously created durable subscriber. A user must have durable permission on the topic to create a new durable subscriber for that topic. A user must have at least use_durable permission on the topic to attach to an existing durable subscriber for the topic. See User Permissions for details.
  • Java

    Use the Session object’s createConsumer() method to create a MessageConsumer object: 

       MessageConsumer QueueReceiver = session.createConsumer(queue);

    See the tibjmsMsgConsumer.java sample client for a working example.

    The following Session.createDurableSubscriber() method creates a durable subscriber, named "MyDurable": 

       TopicSubscriber subscriber =
         session.createDurableSubscriber(topic,"myDurable");

    See the tibjmsDurable.java sample client for a working example.

    Shared Subscriptions

    Use the Session object's createSharedConsumer() method to create or add to a shared subscription: 

    MessageConsumer cons1 = session.createSharedConsumer(topic, "mySharedSub");
MessageConsumer cons2 = session.createSharedConsumer(topic, "mySharedSub");

    cons1 and cons2 are two shared consumers on the same subscription called mySharedSub. If a message is published to the topic, then one of those two consumers will receive it. Note that shared consumers on a given subscription do not have to use the same session/connection.

    Use the Session object's createSharedDurableConsumer() method to create or add to a shared durable subscription: 

    MessageConsumer cons1 = session.createSharedDurableConsumer(topic, "myDurableSharedSub");
MessageConsumer cons2 = session.createSharedDurableConsumer(topic, "myDurableSharedSub");

    cons1 and cons2 are two shared durable consumers on the same durable subscription called myDurableSharedSub. If a message is published to the topic, then one of those two consumers will receive it. Note that shared durable consumers on a given subscription do not have to use the same session/connection.

  • C

    Use the tibemsSession_CreateConsumer function to create a message consumer of type tibemsMsgConsumer: 

       tibemsMsgConsumer QueueReceiver = NULL;
   status = tibemsSession_CreateConsumer(session,
                 &QueueReceiver, queue, NULL, TIBEMS_FALSE);

    See the tibemsMsgConsumer.c sample client for a working example.

    The following tibemsSession_CreateDurableSubscriber function creates a durable subscriber, named "myDurable," of type tibemsMsgConsumer: 

       tibemsMsgConsumer  msgConsumer = NULL;
   status = tibemsSession_CreateDurableSubscriber(session,                      &msgConsumer, topic, "myDurable", 
                     NULL, TIBEMS_FALSE);

    See the tibemsDurable.c sample client for a working example.

  • C#

    Use the Session.CreateConsumer method to create a MessageConsumer object: 

       MessageConsumer QueueReceiver = session.createConsumer(queue);

    See the csMsgConsumer.cs sample client for a working example.

    The following Session.CreateDurableSubscriber method creates a durable subscriber, named "MyDurable": 

       TopicSubscriber subscriber =        
         session.CreateDurableSubscriber(topic, "myDurable");

    See the csDurable.cs sample client for a working example.