Package 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().

Note: After publishing a message, do not reuse the message (e.g. change the content, republish) as this can cause issues.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addElement(String subject)
    Adds an element with the given subject to the container.
    List<ContainerOperation>
    getOperations()
    Gets a list of container operations.
    void
    insertElement(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(String subject)
    Removes an element with the given subject from the container.
    void
    removeElementsWithPrefix(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

    getMessageType, getSubject, isImage, setImage

  • Method Details

    • getOperations

      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.

      Returns:
      The container operations.

    • addElement

      void addElement(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(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(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(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.