com.caplin.datasource.publisher

Interface DataProvider

public interface DataProvider

Interface that must be implemented in order to provide data updates to DataSource peers. It contains callbacks that handle subscription and discard requests from peers.

The following example shows a skeleton implementation of the DataProvider interface. Typically, a DataProvider implementation requires a reference to its Publisher so it may use that publisher to send messages. The example shows the recommended way to do this, which is to create the Publisher in the constructor of the DataProvider.

Note: if your Publisher is a BroadcastPublisher, you do not need to implement a DataProvider for it. This is because the connected peers (to which the broadcast data updates are sent) do not send the DataSource any subscription or discard requests for the broadcast subjects, so no DataProvider is needed to handle such events.

import java.util.Map;
import java.util.Set;

import com.caplin.datasource.DataSource;
import com.caplin.datasource.messaging.record.RecordType1Message;
import com.caplin.datasource.namespace.Namespace;
import com.caplin.datasource.publisher.DataProvider;
import com.caplin.datasource.publisher.DiscardEvent;
import com.caplin.datasource.publisher.Publisher;
import com.caplin.datasource.publisher.RequestEvent;

public class ExampleDataProvider implements DataProvider
{
        private final Publisher publisher;
        
        public ExampleDataProvider(DataSource datasource, Namespace namespace)
        {
                this.publisher = datasource.createActivePublisher(namespace, this);
        }
        @Override
        public void onRequest(RequestEvent requestEvent)
        {
                // Subscribe to back end system that supplies the data.
                // ...
                
                // Create a message for the DataSource subject.
                RecordType1Message message = publisher.getMessageFactory().createRecordType1Message(requestEvent.getSubject());
                
                // Mark the message as containing an image.
                message.setImage(true);
                
                // Add data to the message.
                message.setField("Bid", "1.23");
                
                // Send the image message to the newly subscribed DataSource peer.
                publisher.publishInitialMessage(message);
        }
        
        @Override
        public void onDiscard(DiscardEvent discardEvent)
        {
                // Unsubscribe from back end system  that supplies the data.
                // ...
        }
        
        // Once this DataProvider has subscribed to the back end system,
        // the back end pushes messages into this DataProvider via this message
        // listener callback. The details of the callback parameters,
        // and the transformation of the data needed to populate the
        // DataSource message, depend on the nature of the back end system.
        public void onDataUpdate(String subject, Map messageData)
        {
                // Create a message for the appropriate DataSource Subject.
                RecordType1Message message = publisher.getMessageFactory().createRecordType1Message(subject);
                
                // Transform the back end update's data into DataSource message fields.
                Set mapKeys = messageData.keySet();
                for(String name : mapKeys)
                {
                        message.setField(name, messageData.get(name));
                }
                
                //Publish the message
                publisher.publishToSubscribedPeers(message);
        }
}

Note: the DataProvider methods are not called on a dedicated worker thread. Therefore, if any of these methods are likely take a relatively long time to execute, they should be coded to run in a separate thread.

Method Summary

Methods

Modifier and Type	Method and Description
void	onDiscard(DiscardEvent discardEvent) Callback that informs the DataProvider that an earlier requested subject has now been discarded.
void	onRequest(RequestEvent requestEvent) Callback that informs the DataProvider that a new request has been received and it should start sending data.

Method Detail

onRequest

void onRequest(RequestEvent requestEvent)

Callback that informs the DataProvider that a new request has been received and it should start sending data.

The action that a DataProvider should take when onRequest is called depends on the type of Publisher that is being used by the DataSource application.

If the Publisher is an ActivePublisher, the DataProvider should perform the following tasks when this method is called:

1. The subject should be retrieved by calling RequestEvent.getSubject().
2. If that DataSource is not already subscribed to the back end system that supplies the data for this subject, the DataSource should make a subscription for the subject.
3. When data is received from the back end system for the subject, the DataProvider should call Publisher.publishInitialMessage(com.caplin.datasource.messaging.Message) to publish the current image of the data to the subscribing peer.
4. If the DataSource is already subscribed to the back end system for this subject and the DataSource has cached the latest values for the subject (this could happen if, for example, another peer has already requested the subject), then the DataProvider can simply call Publisher.publishInitialMessage(com.caplin.datasource.messaging.Message) to publish the current image of the data to the subscribing peer.

If the Publisher is a CompatibilityPublisher the DataProvider should perform the following tasks when this method is called:

1. The subject should be retrieved by calling RequestEvent.getSubject().
2. The Peer making the request should be retrieved by calling RequestEvent.getPeer().
3. The fact that the Peer is subscribed to the subject should be recorded in a data structure.
4. If that DataSource is not already subscribed to the back end system that supplies the data for this subject, the DataSource should make a subscription for the subject.
5. When data is received from the back end system for the subject, the DataProvider should call Publisher.publishInitialMessage(com.caplin.datasource.messaging.Message) to publish the current image of the data to the subscribing peer.
6. If the DataSource is already subscribed to the back end system for this subject and the DataSource has cached the latest values for the subject, then the DataProvider can simply call Publisher.publishInitialMessage(com.caplin.datasource.messaging.Message) to publish the current image of the data to the subscribing peer.
7. The data structure that records which peers are subscribed to which subjects will be used later to determine when the DataSource should unsubscribe from the back end system that supplies the data.

Parameters:

requestEvent - The event that describes the request (which peer and which subject).

onDiscard

void onDiscard(DiscardEvent discardEvent)

Callback that informs the DataProvider that an earlier requested subject has now been discarded.

The action that a DataProvider should take when onDiscard is called depends on the type of Publisher that is being used by the DataSource application.

If the Publisher is an ActivePublisher, the DataProvider should perform the following tasks when this method is called:

1. The subject should be retrieved by calling RequestEvent.getSubject().
2. The DataSource should unsubscribe from the back end system that supplies the data for this subject.
3. The DataSource should stop publishing updates for this subject.

If the Publisher is a CompatibilityPublisher the DataProvider should perform the following tasks when this method is called:

1. The subject should be retrieved by calling RequestEvent.getSubject().
2. The Peer making the request should be retrieved by calling RequestEvent.getPeer().
3. The data structure that records which peers are subscribed to which subjects should be retrieved (see onRequest(RequestEvent).
4. The peer should be removed from the list of peers that are subscribed to this subject.
5. If there are still peers subscribed to the subject, no further action is necessary.
6. If there are now no peers subscribed to the subject then the DataSource should unsubscribe from the back end system that supplies the data for this subject, and stop publishing updates for this subject.

Parameters:

discardEvent - The event that describes the discard (which peer and which subject).