com.caplin.datasource.messaging.container

Interface ContainerModel

public interface ContainerModel

This interface defines a model that represents a container. Implement it to simplify the processing of incoming ContainerMessages.

Note: You do not have to use this interface to process ContainerMessages. You can instead use the basic approach, as explained in ContainerMessage.getOperations().

To use the ContainerModel interface:

• Create a class that implements ContainerModel and represents (models) a container.
• Ensure the class also implements SubscriptionListener.
• In the callback method SubscriptionListener.containerUpdated(com.caplin.datasource.subscription.Subscription, com.caplin.datasource.Peer, ContainerMessage) , iterate through the ContainerOperations and call ContainerOperation.updateContainer(ContainerModel) on each in turn.
• Each call to ContainerOperation.updateContainer(ContainerModel) invokes the appropriate callback method on your implementation of ContainerModel: addElement(String), removeElement(String), insertElement(String, int) or removeElementsWithPrefix(String).
• Implement the above callback methods to apply the correct transformations to the list of container elements in your ContainerModel.

Here is an example implementation of ContainerModel:

import java.util.ArrayList;
import java.util.List;
import java.util.logging.Logger;

import com.caplin.datasource.Peer;
import com.caplin.datasource.messaging.container.ContainerMessage;
import com.caplin.datasource.messaging.container.ContainerModel;
import com.caplin.datasource.messaging.container.ContainerOperation;
import com.caplin.datasource.subscription.BaseSubscriptionListener;
import com.caplin.datasource.subscription.Subscription;

/**
* This class represents (models) a container. It uses the containerUpdated() callback of the SubscriptionListener
* interface to keep the container elements up to date. There must be one instance of this class for each container
* that is to be modelled.
*/
public class ModelBasedContainerProcessing extends BaseSubscriptionListener implements ContainerModel
{
        //
        // Note that BaseSubscriptionListener is an implementation of the SubscriptionListener interface
        //
        
        private final List elements = new ArrayList(); // The container elements.
        
        public ModelBasedContainerProcessing(Logger logger)
        {
                super(logger);
        }
        
        @Override
        public void containerUpdated(Subscription subscription, Peer peer, ContainerMessage containerMessage) // Called when a container update is received.
        {
                for(ContainerOperation operation : containerMessage.getOperations())
                {
                        // Invokes the relevant method from the following set, to process
                        // the container operation.
                        operation.updateContainer(this);
                }
        }
        
        @Override
        public void addElement(String subject)
        {
                // Add (append) an element with the given subject to the container model.
                elements.add(subject);
        }
        
        @Override
        public void removeElement(String subject)
        {
                // Remove the element with the given subject from the container model.
                elements.remove(subject);
        }
        
        @Override
        public void insertElement(String subject, int position)
        {
                // Insert an element with the given subject into the container model.
                elements.add(position, subject);
        }
        
        @Override
        public void removeElementsWithPrefix(String prefix)
        {
                // Remove all elements from the container model that have a subject
                // matching the specified prefix.
                List elementsCopy = new ArrayList(elements);
                for(String subject : elementsCopy)
                {
                        if(subject.startsWith(prefix))
                        {
                                elements.remove(subject);
                        }
                }
        }
}

Method Summary

Methods

Modifier and Type	Method and Description
void	addElement(java.lang.String subject) Called to indicate that you should add (append) an element with the given subject to the container.
void	insertElement(java.lang.String subject, int position) Called to indicate that you should insert an element with the given subject at the given position within the container.
void	removeElement(java.lang.String subject) Called to indicate that you should remove the element with the given subject from the container.
void	removeElementsWithPrefix(java.lang.String prefix) Called to indicate that you should remove all elements from the container that have a subject that matches the specified prefix.

Method Detail

addElement

void addElement(java.lang.String subject)

Called to indicate that you should add (append) an element with the given subject to the container.

The element must be added to the end of the container. For example, if there are three elements already in the container at positions 0, 1, and 2 respectively, adding a fourth element places it at position 3.

Parameters:

subject - The subject of the element to add.

removeElement

void removeElement(java.lang.String subject)

Called to indicate that you should remove the element with the given subject from the container.

Parameters:

subject - The subject of the element to be to removed.

insertElement

void insertElement(java.lang.String subject,
                 int position)

Called to indicate that you should insert an element with the given subject at the given position within the container.

Parameters:

subject - The subject of the element to be inserted.

position - The position at which to insert the element. The first element in a container is at position 0.

removeElementsWithPrefix

void removeElementsWithPrefix(java.lang.String prefix)

Called to indicate that you should remove all elements from the container that have a subject that matches the specified prefix.

Instructions should be processed in the order in which they are retrieved from the ContainerMessage and this affects earlier instructions. For example, assume that in the same message you received these operations:

1. Add a container element with subject /A/1,
2. Remove all container elements with prefix /A,
3. Add a container element with subject /A/2.

When this sequence has been processed, the container should only contain the element /A/2, because /A/1 was removed at step 2.

Parameters:

prefix - The prefix to match subjects for which elements are to be removed from the container.