Container Object

SL4B provides connection failover functionality, allowing a client application that has lost its connection to a Liberator to failover and connect to another Liberator instead. It also provides client side load balancing, where each client randomly selects which primary Liberator it will initially attempt to connect to.

Contents

What Are Container Objects

Containers are a way of grouping objects in the Liberator so that they can be subscribed to as a unit rather than individually.
What is a container?
Containers are created in the datasource providing the data.

Back to contents

Using Container Objects In SL4B

To subscribe to a container the client must use the SL4B_AbstractRttpProvider.getContainer() method. An example is provided below. 

    ExampleSubscriber.prototype = new SL4B_AbstractSubscriber;
    function ExampleSubscriber()
    {
        this.initialise();
    }          
    
    var exampleSubscriber = new ExampleSubscriber();
    SL4B_Accessor.getRttpProvider().getContainer(exampleSubscriber, "/CONTAINERNAME", "Field1,Field2");

Notification Of Changes In Container Structure

To be notified of changes to the container structure (additions/deletions/re-ordering) the client must implement the SL4B_AbstractSubscriber.structureMultiChange() callback on the registered subscriber. 

    ExampleSubscriber.prototype.structureMultiChange = ExampleSubscriber_StructureMultiChange;
    function ExampleSubscriber_StructureMultiChange (containerName, containerStructureChanges, elementOrderChanges, totalContainerSize)
    {
        // process changes in container structure
    }

Notification Of Changes To Container Constituents

To be notified of changes for all the constituent objects the client must implement the recordMultiUpdated() callback on the registered subscriber. 

    ExampleSubscriber.prototype.recordMultiUpdated = ExampleSubscriber_RecordMultiUpdated;
    function ExampleSubscriber_RecordMultiUpdated(objectName, fieldData)
    {
        // process changes for container constituent fields
    }

Container Events

An illustration of a sequence of changes to the container and the corresponding structureMultiChange() callbacks are illustrated below.

Event 1: A container has been newly subscribed to, it contains 3 items.
Illustration of Event 1
The structureMultiChange() callback would consist of:

Event 2: A new symbol /ITEM_Y has been added to the container at position 1 (between /ITEM_A and /ITEM_B, position is zero based)
Illustration of Event 2
The structureMultiChange() callback would consist of:

Event 3: Symbol /ITEM_Y is subsequently deleted.
Illustration of Event 3
The structureMultiChange() callback would consist of:

Event 4: Symbol /ITEM_X is added at the end of the container and /ITEMC is deleted.
Illustration of Event 4
The structureMultiChange() callback would consist of:

Container Paging

Paging is the ability to request a subset of a container's contents. For example a container may have 1800 objects within it, however the client may only want to display the first 20.
What is container paging?
By setting paging using the optional windowStart and windowEnd arguments on the SL4B_AbstractRttpProvider.getContainer() method, updates and structural changes for items outside the window are not received. 

    ExampleSubscriber.prototype = new SL4B_AbstractSubscriber;
    function ExampleSubscriber()
    {
        this.initialise();
    }

    var exampleSubscriber = new ExampleSubscriber();
    var windowStartPos = 0;
    var windowEndPos = 9;
    var containerKey = SL4B_Accessor.getRttpProvider().getContainer(exampleSubscriber, "/CONTAINERNAME", "Field1,Field2", windowStartPos, windowEndPos);

To control paging after the initial request, use the SL4B_AbstractRttpProvider.setContainerWindow() method. 

    SL4B_Accessor.getRttpProvider().setContainerWindow(exampleSubscriber.containerKey, 10, 19);

To clear the window and receive updates for the whole container, use SL4B_AbstractRttpProvider.clearContainerWindow(). 

    SL4B_Accessor.getRttpProvider().clearContainerWindow(exampleSubscriber.containerKey);

As changes are made to the container window, structure updates (via the structureMultiChange() callback) are notified to the client so that it can keep its view up to date. An illustration is provided below.

Event 1: The first 5 items (0-4) are requested from a container with 10 items inside it.
Illustration of Event 1
The structureMultiChange() callback would consist of:

Event 2: The last item in the container, /ITEM_J is removed.
Illustration of Event 2
The structureMultiChange() callback would consist of:

Event 3: A new item /ITEM_Z is inserted at position 0.
Illustration of Event 3
The structureMultiChange() callback would consist of:

Example Container Code

The container example (found in .../examples/sl4b/container-demo.html within the kit) shows an example of how to request and page through a container.

Back to contents