com.solacesystems.jcsmp

Interface DestinationConsumer

All Superinterfaces:

Consumer

All Known Implementing Classes:

TopicConsumerImpl

public interface DestinationConsumer
extends Consumer

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

Introduction

A DestinationConsumer instance is acquired from JCSMPDestinationSession. When acquired successfully, the instance of DestinationConsumer has a channel (connection) opened to the appliance. Applications must cache this instance reference, and close it only when it is no longer required.

Note: The methods defined in this interface are non-thread-safe, except the close() method, 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 synchronous receive(...) calls, or by using asynchronous notification by setting DestinationListener. Note: The received messages are read-only.

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 re-acquire an "opened" DestinationConsumer by calling JCSMPDestinationSession.getMessageConsumer(DestinationListener) again.

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.

        JCSMPDestinationSession session = null;
        DestinationConsumer consumer = null;
        try {
            JCSMPProperties props = new JCSMPProperties();
            //... setup properties
            session = JCSMPFactory.onlyInstance().createDestinationSession(props);
            consumer = session.getMessageConsumer(null);
            consumer.start();
            BytesXMLMessage 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.

        JCSMPDestinationSession session = null;
        DestinationConsumer consumer = null;
        try {
            JCSMPProperties props = new JCSMPProperties();
            // setup properties
            session = JCSMPFactory.onlyInstance().createDestinationSession(props);
            consumer = session.getMessageConsumer(new MyDestinationListener());
            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 DestinationListener
        class MyDestinationListener implements DestinationListener {
            public void onReceive(BytesXMLMessage message) {
               // handle message received
               //...
            }
            
            public void onException(JCSMPException exception) {
               // handle error
               //...
            }
        }
 

Method Summary

Modifier and Type	Method and Description
DestinationListener	getMessageDestinationListener() Gets the message consumer's message listener.

Methods inherited from interface com.solacesystems.jcsmp.Consumer

close, closeSync, closeSync, receive, receive, receiveNoWait, start, startSync, stop, stopSync, stopSyncStart, stopSyncWait

Method Detail

getMessageDestinationListener

DestinationListener getMessageDestinationListener()

Gets the message consumer's message listener.

Returns:

The message listener if set, null otherwise.