Package com.caplin.datasource.interfaces

Interface DSContainer

All Superinterfaces:
DSData, DSPacket, DSSerializable, Iterable<DSField>
public interface DSContainer extends DSData

Extends DSData to provide helper methods for sending Container objects. The Container object maintains a list of links to other objects (e.g. a Record) . These linked objects can be added to the end of the Container or inserted at a specific position as required. Objects can also be removed from the container either individually by name or by specifying a prefix that matches multiple objects.

DSContainer does not represent a container as such, rather it is a message containing information about changes to be made to a container. Thus an instance of DSContainer can be used to create new containers or to add, remove and insert objects into an existing container maintained in the cache of another Caplin DataSource such as a Liberator or Transformer.

If the DSContainer message is sent with the DSData.F_IMAGE flag set, the cached container in the receiving DataSource will be cleared and any objects added and inserted in this container update will replace them. If multiple DataSources are contributing updates to the same container then it may be preferable to use the cleardownObjectsWithPrefix(String) method instead of sending an image. Assuming the DataSources are providing objects with different namespaces this will allow the DataSource to clear its own objects from the container without affecting objects provided by other DataSources.

If the DSData.F_IMAGE flag is not set, the adds, removes and inserts specified in the DSContainer will adjust the contents of the existing cached container accordingly.

  • Field Details

    • ADD_OBJECT_FIELDNUM

      static final int ADD_OBJECT_FIELDNUM
      Field used to identify that the object (identified by the field value) should be added to this container.
      See Also:

    • ADD_OBJECT_AND_REQUEST_FIELDNUM

      static final int ADD_OBJECT_AND_REQUEST_FIELDNUM
      Field used to identify that the object (identified by the field value) should be added to this container and a request should be made by the receiving DataSource for the object.
      See Also:

    • REMOVE_OBJECT_FIELDNUM

      static final int REMOVE_OBJECT_FIELDNUM
      Field used to identify that the object (identified by the field value) should be removed from this container.
      See Also:

    • CLEARDOWN_WITH_PREFIX_FIELDNUM

      static final int CLEARDOWN_WITH_PREFIX_FIELDNUM
      Field used to identify that any objects that match the prefix provided as a field value should be removed from the container.
      See Also:

  • Method Details

    • addObject

      void addObject(String objectName)

      Adds an instruction to append an object to this container.

      Parameters:
      objectName - the name of the object to be appended to this container (e.g. /OBJ1).

    • addObject

      void addObject(String objectName, boolean makeRequest)
      Deprecated.
      Use addObject(String) instead.

      Adds an instruction to append an object to this container.

      Parameters:
      objectName - the name of the object to be appended to this container (e.g. /OBJ1).
      makeRequest - true if the receiving DataSource should make a request for this object, false if this DataSource will automatically send the object without it needing to be requested.

    • removeObject

      void removeObject(String objectName)

      Adds an instruction to remove an object from this container.

      Parameters:
      objectName - the name of the object to be removed from this container (e.g. /OBJ1).

    • insertObject

      void insertObject(String objectName, int position) throws IndexOutOfBoundsException

      Adds an instruction to insert an object into this container, pushing any object currently at that position, and all objects at successive positions, up one place (to the next higher index position).

      If insertObject is called more than once on the same DSContainer, the subsequent inserts are relative to the earlier ones. For example, assume a container has object X at position 9 and object Y at position 10. Now insert object A at position 5, followed by object B at position 10. The insertion of object A moves X to position 10 and Y to position 11. When B is subsequently inserted at position 10, it goes immediately before X, not before Y; X moves to position 11 and Y moves to position 12.

      Parameters:
      objectName - the name of the object to be inserted into this container (e.g. /OBJ1).
      position - the position in the container where the object is to be inserted, where position 0 (zero) represents the position of the first object.
      Throws:
      IndexOutOfBoundsException - if position is negative.

    • cleardownObjectsWithPrefix

      void cleardownObjectsWithPrefix(String prefix)

      Adds an instruction to remove all objects from the container that have an object name that matches the provided prefix.

      Instructions are processed in the order that they are added to the container and affect earlier instructions. For example, if in the same message you add object /A/1, clear down based on the prefix /A and add object /A/2 then the processed container will only contain object /A/2 because object /A/1 will be cleared.

      Parameters:
      prefix - The prefix to match object names against and remove from the container.