Data Stream

FirstSpirit Developer API Interface: de.espirit.firstspirit.client.plugin.dataaccess.DataStream
Developer API documentation: DataStream<D>

The data stream is responsible for supplying a listing of data objects of a type matching the data access plug-in's parameterization.

The stream object is utilized whenever sets of data objects are required, i.e. to populate a list of data objects to add to an FS_INDEX input component or to display data objects in a report.

After initialization, FirstSpirit polls the data stream object on an as-needed basis, collecting a specific number of data objects for display in the data access plug-in's result list. As result lists shown in the clients' user interface support continuous scrolling, the number of requested data objects in each poll may vary; generally, the FirstSpirit clients attempt to request enough data objects to fill clear, vertical space in the result list. If the data stream object indicates it cannot provide any more data objects (i.e., all available results have been provided as data objects), FirstSpirit will stop polling the stream.

Due to the batch-oriented nature of this algorithm, stream classes must be designed to avoid returning the same data object multiple times over repeated polls.

Code Example

This class implementing the interface DataStream<D> is designed both to provide the initial batch of data items (displayed as a result list for this plug-in is displayed or filter settings are changed) and to supply additional data items incrementally as the user requests them (caused by scrolling to the bottom of the result list). This class has no direct representation in the clients' user interface.

public class MyDataStream implements DataStream<MyDataObject> {

    private final List<MyDataObject> _sourceData;
    private Iterator<MyDataObject> _iterator;
    private int _total;

    public MyDataStream(@NotNull final MyDataStreamBuilder.MyFilterableAspect filterable) {
        // Place pre-made objects of type MyDataObject into an array list.
        // We use this array in lieu of an external data source.
        _sourceData = new ArrayList<MyDataObject>();
        _sourceData.add(new MyDataObject("Example Data #1", "I am some sample text."));
        _sourceData.add(new MyDataObject("Example Data #2", "I am more sample text."));
        _sourceData.add(new MyDataObject("Example Data #3", null));

        // Keep the source data list's iterator in a field for use in other methods.
        _iterator = _sourceData.iterator();

        // Update the total count of data objects available.
        _total = _sourceData.size();
    }

    public List<MyDataObject> getNext(final int count) {
        // Create an array list and add up to "count" data objects.
        final List<MyDataObject> dataObjects = new ArrayList<MyDataObject>();
        while (dataObjects.size() < count && _iterator.hasNext()) {
            dataObjects.add(_iterator.next());
        }
        return dataObjects;
    }

    // Indicate if any data objects are available that haven't been returned by #getNext(...) yet.
    public boolean hasNext() {
        return _iterator.hasNext();
    }

    // Indicate the total number of data objects that may be returned.
    public int getTotal() {
        return _total;
    }

    // Perform clean-up.
    public void close() {
        _total = 0;
    }
}

hasNext()

getNext()

This method returns the next increment of data objects, starting from an offset stored privately in the data stream object and including at most a given number of data objects corresponding to the parameter count included in the method call. The value of the parameter count may vary between calls: during initial list generation, it may be higher than in subsequent requests for additional data increments.

Bear in mind that getNext() is concerned with retrieving and providing the next x data objects, where x corresponds to the method's parameter count. Unless count evaluates to 1, this method is not designed to be a simple iterator, supplying one data object per call.

Please note that a data stream's getNext() method may be called immediately after the data stream object is instantiated. If collecting results with a default (potentially empty) filter configuration is associated with high costs (e.g. polling a web service that does not provide an easy way of limiting an initial set of data), you should ensure that getNext() only begins assembling results when specific conditions - e.g. a three-character minimum for a text search pattern or a non-default option being selected in a drop-down box pattern - are met.

getTotal()

getTotal() returns an integer corresponding to the total number of results retrieved so far since the most recent call of start(). This number is shown near the report list in the format "x Results".

close()

close() is called before a data stream object is discarded. This method is responsible for stopping any data retrieval processes still occurring and destroying any temporary data that cannot be treated properly by Java's garbage collection.