# 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.

Copyright © Cloud Software Group, Inc. All rights reserved.