# Create a Message Listener for Asynchronous Message Consumption

EMS allows a Message Consumer to consume messages either synchronously or asynchronously. For synchronous consumption, the Message Consumer explicitly calls a receive method on the topic or queue. For asynchronous consumption, you can implement a Message Listener that serves as an asynchronous event handler for messages.

A Message Listener implementation has one method, `onMessage`, that is called by the EMS server when a message arrives on a destination. You implement the `onMessage` method to perform the desired actions when a message arrives. Your implementation should handle all exceptions, and it should not throw any exceptions.

Once you create a Message Listener, you must register it with a specific Message Consumer before calling the connection’s `start` method to begin receiving messages.

A Message Listener is not specific to the type of the destination. The same listener can obtain messages from a queue or a topic, depending upon the destination set for the Message Consumer with which the listener is registered.

Note: The J2EE 1.3 platform introduced message-driven beans (MDBs) that are a special kind of Message Listener. See the J2EE documentation for more information about MDBs.

- Java

  Create an implementation of the `MessageListener` interface, create a `MessageConsumer`, and use the `MessageConsumer` object’s setMessageListener`()` method to register the Message Listener with the Message Consumer:

         public class tibjmsAsyncMsgConsumer implements MessageListener
         {
            /* Create a connection, session and consumer */
         ...
            MessageConsumer QueueReceiver =                             session.createConsumer(queue);
            QueueReceiver.setMessageListener(this);
            connection.start();
         }

  Note: Do not use the Session.setMessageListener() method, which is used by application servers, rather than by applications.

  Implement the `onMessage()` method to perform the desired actions when a message arrives:

         public void onMessage(Message message)
         {
              /* Process message and handle exceptions */
         }

  See the `tibjmsAsyncMsgConsumer.java` sample client for a working example.

- C

  Implement an `onMessage()` function to perform the desired actions when a message arrives:

         void onMessage(tibemsMsgConsumer QueueReceiver,
                   tibemsMsg message, void* closure)
         {
              /* Process message and handle exceptions */
         }

  In another function, that creates a `tibemsMsgConsumer` and uses the `tibemsMsgConsumer_SetMsgListener` function to create a message listener for the Message Consumer, specifying `onMessage()` as the callback function:

      void run()
      {
         tibemsMsgConsumer QueueReceiver = NULL;
         /* Create a connection, session and consumer */
         ...
         status = tibemsSession_CreateConsumer(session,
                       &QueueReceiver, queue, NULL, TIBEMS_FALSE);
         status = tibemsMsgConsumer_SetMsgListener(QueueReceiver,                  onMessage, NULL);
         status = tibemsConnection_Start(connection);
      }

  See the `tibemsAsyncMsgConsumer.c` sample client for a working example.

- C#

  Create an implementation of the `IMessageListener` interface, use `Session.CreateConsumer` to create a `MessageConsumer`, and set the `MessageListener` property on the `MessageConsumer` object to register the Message Listener with the Message Consumer:

         public class csAsyncMsgConsumer : IMessageListener
         {
            /* Create a connection, session and consumer */
         ...
            MessageConsumer QueueReceiver =                   session.CreateConsumer(queue);
            QueueReceiver.MessageListener = this;
            connection.Start();
         }

  Implement the `IMessageListener.OnMessage` method to perform the desired actions when a message arrives:

         public void OnMessage(Message message) {
            try
            {
                 /* Process message and handle exceptions */
            }
         }

  See the `csAsyncMsgConsumer.cs` and `csAsyncMsgConsumerUsingDelegate.cs` sample clients for working examples.

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