com.solacesystems.jcsmp

Interface XMLMessageConsumer

All Superinterfaces:

Consumer

@ProviderType
public interface XMLMessageConsumer
extends Consumer

XMLMessageConsumer provides an interface for an application to receive messages from a Solace appliance.

Introduction

An XMLMessageConsumer instance is acquired from JCSMPSession. When acquired successfully, the instance of XMLMessageConsumer has a channel (connection) opened to the appliance. In general, it is an expensive operation to acquire an XMLMessageConsumer instance. Applications must cache this instance, and close it only when it is no longer required.

Note: The methods defined in this interface are not thread-safe, except the start, stop, and close() methods, which can be called at any time by any thread.

Message Reception

To receive messages, an application must call start() to start receiving messages from the underlying connection by using either synchronous receive(...) calls or using asynchronous notification by setting XMLMessageListener. Note: The messages received are read-only. Since sending a message requires the contents to be updated, received messages cannot be sent.

The stop() method is used to disable receiving messages from the underlying connection.

Once the close() method is invoked, the instance of this class loses its channel connection to the appliance. Any further access raises an exception. An application can call JCSMPSession.getMessageConsumer(XMLMessageListener) again to reacquire an "opened" XMLMessageConsumer.

If using client acknowledgement mode (refer to Session for information on setting acknowledgement mode), applications must acknowledge every received message in a timely fashion.

Examples

The following code is the typical way of receiving messages in synchronous mode.

 
        JCSMPSession session = null;
        XMLMessageConsumer consumer = null;
        try {
            JCSMPProperties props = new JCSMPProperties();
            ... // setup properties
            session = JCSMPFactory.onlyInstance().createSession(props);
            consumer = session.getMessageConsumer((XMLMessageListener) null);
            consumer.start();
            XMLMessage received = consumer.receive();
        } catch (...) {
            // exception handling goes here
            ....
        } finally {
            // make sure to release all resources
            if (consumer != null) consumer.close();
            if (session != null) session.closeSession();
        } 
 
 

The following code is the typical way of receiving messages in asynchronous mode.

 
        JCSMPSession session = null;
        XMLMessageConsumer consumer = null;
        try {
            JCSMPProperties props = new JCSMPProperties();
            ... // setup properties
            session = JCSMPFactory.onlyInstance().createSession(props);
            consumer = session.getMessageConsumer(new MyXMLMessageListener());
            consumer.start();
        } catch (...) {
            // exception handling goes here
            ....
        } finally {
            // make sure to release all resources
            if (consumer != null) consumer.close();
            if (session != null) session.closeSession();
        } 
        
        ...
        // implementation of XMLMessageListener
        class MyXMLMessageListener implements XMLMessageListener {
            public void onReceive(BytesXMLMessage message) {
               // handle message received
               ...
            }
            
            public void onException(JCSMPException exception) {
               // handle error
               ...
            }
        }
 
 

Method Summary

Modifier and Type	Method and Description
XMLMessageListener	getMessageListener() Gets the message consumer's message listener.
void	setMessageListener(XMLMessageListener listener) Deprecated. As of release 4.1, please provide an XMLMessageListener when acquiring an XMLMessageConsumer from a session. This method is deprecated and provided for backwards-compatibility; if using it, note that it must be called immediately after acquiring the XMLMessageConsumer, before it is started, and it may only be called once. Failure to respect these conditions will result in an IllegalStateException being thrown.

Methods inherited from interface com.solacesystems.jcsmp.Consumer

close, isClosed, receive, receive, receiveNoWait, start, stop

Method Detail

setMessageListener

void setMessageListener(XMLMessageListener listener)

Deprecated. As of release 4.1, please provide an XMLMessageListener when acquiring an XMLMessageConsumer from a session. This method is deprecated and provided for backwards-compatibility; if using it, note that it must be called immediately after acquiring the XMLMessageConsumer, before it is started, and it may only be called once. Failure to respect these conditions will result in an IllegalStateException being thrown.

Sets the message consumer's message listener. By setting a message listener, the message consumer works in asynchronous mode.

The following calling patterns are not allowed and will result in an exception:

setting the message listener twice to different listeners (or the second time to null). setting the message listener after doing a receive(). doing a receive() after setting the message listener. setting the message listener after the connection is started with JCSMPProperties.MESSAGE_CALLBACK_ON_REACTOR set.

Parameters:

listener - The listener to which the messages are to be delivered.

getMessageListener

XMLMessageListener getMessageListener()

Gets the message consumer's message listener.

Returns:

The message listener if set, null otherwise.