com.caplin.datasource.channel

Interface ChannelListener

public interface ChannelListener

Interface that must be implemented in order to perform bi-directional communication with a StreamLink client.

The following example shows a basic implementation of ChannelListener that accepts all channels within a namespace and echoes incoming messages back to the StreamLink client:

import com.caplin.datasource.DataSource;
import com.caplin.datasource.channel.Channel;
import com.caplin.datasource.channel.ChannelListener;
import com.caplin.datasource.messaging.record.RecordMessage;
import com.caplin.datasource.namespace.Namespace;
import com.caplin.datasource.namespace.PrefixNamespace;

public class ChannelExample
{
        public void channelExample(DataSource dataSource)
        {
                // Create a namespace to use for channel subjects.
                Namespace channelNamespace = new PrefixNamespace("/CHANNEL");
                
                // Create a listener to handle channels within the namespace.
                ChannelListener channelListener = new MyChannelListener();
                
                // Register the channel listener with the DataSource.
                dataSource.addChannelListener(channelNamespace, channelListener);
        }
        
        class MyChannelListener implements ChannelListener
        {
                @Override
                public boolean onChannelOpen(Channel channel)
                {
                        // Called to notify you that a peer has opened a channel. Return true
                        // to indicate that you accept the channel.
                        return true;
                }
                
                @Override
                public void onChannelClose(Channel channel)
                {
                        // Called to notify you that a peer has closed a channel.
                }
                
                @Override
                public void onMessageReceived(Channel channel, RecordMessage recordMessage)
                {
                        // Called when a peer sends a message to you on a specified channel. In
                        // this example we will retrieve a field called "Text" from the incoming
                        // message and send a message back to the peer with a response.
                        String channelSubject = channel.getSubject();
                        
                        // Extract the incoming message.
                        String incomingText = recordMessage.getField("Text");
                        
                        // Create a response message.
                        RecordMessage responseMessage = channel.createRecordMessage(channelSubject);
                        responseMessage.setField("Text", "Response to: " + incomingText);
                        
                        // Send the response message back to the peer.
                        channel.sendRecordMessage(responseMessage);
                }
        }
}

Method Summary

Methods

Modifier and Type	Method and Description
void	onChannelClose(Channel channel) Callback that informs the ChannelListener that a StreamLink client wishes to close a channel.
boolean	onChannelOpen(Channel channel) Callback that informs the ChannelListener that a StreamLink client wishes to open a channel.
void	onMessageReceived(Channel channel, RecordMessage recordMessage) Callback that informs the ChannelListener that a StreamLink client has sent a message to the DataSource via a specified channel.

Method Detail

onChannelOpen

boolean onChannelOpen(Channel channel)

Callback that informs the ChannelListener that a StreamLink client wishes to open a channel.

Parameters:

channel - The channel to be opened.

Returns:

A boolean denoting whether the ChannelListener accepts the channel.

If you return true DataSource for Java will send an empty placeholder record back to the StreamLink client for the channel subject. The StreamLink client can then contribute fields to this record in order to send a message to the DataSource.

If you return false DataSource for Java will send a SubjectErrorEvent back to the StreamLink client for the channel subject, with an error of SubjectError.NotFound. This indicates to the StreamLink client that the channel was rejected by the DataSource.

Your ChannelListener should decide whether to accept the channel based on the channel subject, which can be retrieved by calling Channel.getSubject(). This subject should contain all of the information needed for the DataSource to establish a channel. For example, if you are creating a trading application, the channel subject could contain the username of the StreamLink client and an asset class that the user wants to trade, for example:

/CHANNEL/FX/user1

If the channel subject is correctly formed, as in the example above, you should return true. If the subject does not contain all of the required information, or the information is invalid, you should return false.

onChannelClose

void onChannelClose(Channel channel)

Callback that informs the ChannelListener that a StreamLink client wishes to close a channel.

Parameters:

channel - The channel to be closed.

onMessageReceived

void onMessageReceived(Channel channel,
                     RecordMessage recordMessage)

Callback that informs the ChannelListener that a StreamLink client has sent a message to the DataSource via a specified channel.

Parameters:

channel - The channel receiving the message.

recordMessage - A message containing fields that have been sent to the DataSource by the StreamLink client.