com.caplin.datasource.messaging.container

Interface ContainerMessage

All Superinterfaces:

Message

public interface ContainerMessage
extends Message

An instance of ContainerMessage represents an update to a container.

You do not have to implement this interface yourself. An instance can be constructed using the MessageFactory.createContainerMessage(String) method of the MessageFactory that is available on the Publisher interface.

If you make a subscription to a namespace and receive a ContainerMessage via the SubscriptionListener.containerUpdated(com.caplin.datasource.subscription.Subscription, com.caplin.datasource.Peer, ContainerMessage) callback method on your implementation of SubscriptionListener then there are two ways to process the incoming message, a basic approach and a model-based approach. For details, see getOperations().

Method Summary

Methods

Modifier and Type	Method and Description
void	addElement(java.lang.String subject) Adds an element with the given subject to the container.
java.util.List<ContainerOperation>	getOperations() Gets a list of container operations.
void	insertElement(java.lang.String subject, int position) Inserts an element with the given subject at the given position within the container.
boolean	isDoNotAuthenticate() Gets a boolean value indicating whether subscriptions to this ContainerMessage's constituents should be authenticated by an authentication module when the container is subscribed to.
void	removeElement(java.lang.String subject) Removes an element with the given subject from the container.
void	removeElementsWithPrefix(java.lang.String prefix) Adds an operation to remove all elements from the container that have a subject that match the specified prefix.
void	setDoNotAuthenticate(boolean doNotAuthenticate) Sets a boolean value indicating whether this ContainerMessage's constituents should be authenticated by an authentication module when the container is subscribed to.

Methods inherited from interface com.caplin.datasource.messaging.Message

getSubject, isImage, setImage

Method Detail

getOperations

java.util.List<ContainerOperation> getOperations()

Gets a list of container operations. The order of the operations is significant.

Use this method to examine the contents of a container message when you receive it via the callback method SubscriptionListener.containerUpdated(com.caplin.datasource.subscription.Subscription, com.caplin.datasource.Peer, ContainerMessage) on your implementation of SubscriptionListener.

There are two ways to process the container operations on an incoming ContainerMessage. The first is a basic approach in which you simply check the type of each operation and apply it to your container object, as shown in the following example:

In the second approach, you implement a model of the container and apply each operation to the model in sequence; for details, see ContainerModel.

Example of basic approach to container processing:

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.ContainerOperation;
import com.caplin.datasource.subscription.BaseSubscriptionListener;
import com.caplin.datasource.subscription.Subscription;

/**
* This class represent a container and uses the containerUpdated() callback to keep the elements
* up to date. It assumes that there is one instance of this class per container.
*/
public class BasicContainerProcessing extends BaseSubscriptionListener
{
        private final List elements = new ArrayList();
        
        public BasicContainerProcessing(Logger logger)
        {
                super(logger);
        }
        
        @Override
        public void containerUpdated(Subscription subscription, Peer peer, ContainerMessage containerMessage)
        {
                for(ContainerOperation operation : containerMessage.getOperations())
                {
                        switch(operation.getType())
                        {
                                case ADD:
                                elements.add(operation.getElementSubject());
                                break;
                                
                                case REMOVE:
                                elements.remove(operation.getElementSubject());
                                break;
                                
                                case INSERT:
                                elements.add(operation.getElementPosition(), operation.getElementSubject());
                                break;
                                
                                case REMOVE_WITH_PREFIX:
                                List elementsCopy = new ArrayList(elements);
                                for(String subject : elementsCopy)
                                {
                                        if(subject.startsWith(operation.getElementSubject()))
                                        {
                                                elements.remove(subject);
                                        }
                                }
                                break;
                        }
                }
        }
}

Returns:

The container operations.

addElement

void addElement(java.lang.String subject)

Adds an element with the given subject to the container.

The element is 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.

Use this method when building a container message to send via a Publisher.

Parameters:

subject - The subject of the element to add.

removeElement

void removeElement(java.lang.String subject)

Removes an element with the given subject from the container.

Use this method when building a container message to send using a Publisher.

Parameters:

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

insertElement

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

Inserts an element with the given subject at the given position within the container.

Use this method when building a container message to send using a Publisher.

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)

Adds an operation to remove all elements from the container that have a subject that match the specified prefix.

Instructions are processed in the order in which they are added to the container and this affects earlier instructions. For example, assume that in the same message you:

1. call addElement(String) to add a container element with subject /A/1,
2. call removeElementsWithPrefix(String) with prefix /A,
3. call addElement(String) to add a container element with subject /A/2.

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

Use this method when building a container message to send using a Publisher.

Parameters:

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

isDoNotAuthenticate

boolean isDoNotAuthenticate()

Gets a boolean value indicating whether subscriptions to this ContainerMessage's constituents should be authenticated by an authentication module when the container is subscribed to.

To change a ContainerMessage to be a 'doNotAthenticate', call setDoNotAuthenticate(boolean) passing in the value true.

Returns:

true if this ContainerMessage is a 'doNotAuthenticate' ContainerMessage false if it is not.

setDoNotAuthenticate

void setDoNotAuthenticate(boolean doNotAuthenticate)

Sets a boolean value indicating whether this ContainerMessage's constituents should be authenticated by an authentication module when the container is subscribed to.

By default, a newly created ContainerMessage is set to not be a 'doNotAuthenticate' ContainerMessage.

Parameters:

doNotAuthenticate - When set to true, the resulting subscriptions to the ContainerMessage's constituents will not be authenticated, when false, they will be.