WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 Operating Systems: AIX, Linux, Solaris, Windows

Message and exception listeners in C++

A C++ application uses a message listener to receive messages asynchronously, and it uses an exception listener to be notified asynchronously of a problem with a connection.

Related concepts
Error conditions that can be handled at run time

Message listeners in C++

To receive messages asynchronously, a C++ application must define a message listener class that is based on the abstract class MessageListener. The message listener class must provide an implementation of the onMessage() method. The application can then instantiate the class to create a message listener and register the message listener with one or more message consumers by calling the setMessageListener() method for each message consumer. Subsequently, when a message arrives for a message consumer, XMS calls the onMessage() method to deliver the message. XMS does not make a copy of the message listener, and the application must ensure that the message listener is still available when XMS calls the onMessage() method.

If more than one message consumer in a session has a registered message listener, only one onMessage() method can run at a time. For more information about this situation, and what to do if your application requires concurrent delivery of messages, see Asynchronous message delivery.

To stop the asynchronous delivery of messages to a message consumer, the application can call the setMessageListener() method again, by passing a null pointer as the parameter instead of a pointer to a message listener. Unless the registration of a message listener is cancelled in this way, the message listener must exist for as long as the message consumer exists.

A new message listener can be registered with a message consumer without cancelling the registration of an existing message listener. If the onMessage() method of an existing message listener is running when a new message listener is registered, the active method completes normally, and any subsequent messages are processed by calls to the onMessage() method of the new message listener. If a transaction is in progress when a message listener is changed, the transaction is completed by calls to the onMessage() method of the new message listener.

The following code fragment provides an example of a message listener class implementation with an onMessage() method:
#include <xms.hpp>

using namespace std;

class MyMsgListener : public xms::MessageListener
{
public:

  xmsVOID onMessage(const xms::Message * pMsg);
};

  -------–--------------------------------------------

xmsVOID MyMsgListener::onMessage(const xms::Message * pMsg)
{
  if (pMsg != NULL)
  {
    cout << pMsg->getJMSCorrelationID() << endl;
    cout << pMsg->getJMSMessageID() << endl;

    if (pMsg->getType() == XMS_MESSAGE_TYPE_BYTES)
    {
      xms::BytesMessage * pBytes = (xms::BytesMessage *) pMsg;

      cout << pBytes->readUTF() << endl;
    }

    delete pMsg;
  }
}
Because XMS delivers a pointer to a message when it calls the onMessage() method, the application must release the message using the delete operator.
The following code fragment now shows how an application can use this message listener class to implement the asynchronous delivery of messages to a message consumer:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])
{
  int                    nRC = 0;
  xms::ConnectionFactory cf;
  xms::Connection        conn;
  xms::Session           sess;
  xms::Destination       dest;
  xms::MessageConsumer   msgConn;
  MyMsgListener          msgLst;

  try
  {
    cf.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
    cf.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
    cf.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
    cf.setIntProperty(XMSC_RTT_PORT, 1506);

    conn    = cf.createConnection();
    sess    = conn.createSession();
    dest    = xms::Destination(XMS_DESTINATION_TYPE_TOPIC, "test");
    msgConn = sess.createConsumer(dest);

    msgConn.setMessageListener(&msgLst);

    conn.start();

    while(xmsTRUE)
    {
      Sleep(1000);
      cout << "Waiting..." << endl;
    }
  }
  catch(exception & ex)
  {
    nRC = -1;
  }

  return(nRC);
}

Exception listeners in C++

Using an exception listener is similar in principle to using a message listener.

A C++ application must define an exception listener class that is based on the abstract class ExceptionListener. The exception listener class must provide an implementation of the onException() method. The application can then instantiate the class to create an exception listener, and register the exception listener with a connection by calling the setExceptionListener() method. Subsequently, if XMS detects a problem with the connection, XMS calls the onException() method to pass an exception to the application. XMS does not make a copy of the exception listener, and so the application must ensure that the exception listener is still available when XMS calls the onException() method.

To stop the asynchronous reporting of problems with a connection, the application can call the setExceptionListener() method again, by passing a null pointer as the parameter instead of a pointer to an exception listener. Unless the registration of an exception listener is cancelled in this way, the exception listener must exist for as long as the connection exists.

Because XMS passes a pointer to an exception when it calls the onException() method, the application must release the exception by using the C++ delete operator.


Concept topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.