Package com.yahoo.processing.response

Interface DataList<DATATYPE extends Data>

All Superinterfaces:
Data, com.yahoo.component.provider.Freezable, com.yahoo.component.provider.ListenableFreezable
All Known Implementing Classes:
AbstractDataList, ArrayDataList
public interface DataList<DATATYPE extends Data> extends Data
A list of data items created due to a processing request. This list is itself a data item, allowing data items to be organized into a composite tree.

A data list can be frozen even though its child data items are not. When a datalist is frozen the only permissible write operation is to add new items to the end of the list.

Content in a frozen list may be returned to the requesting client immediately by the underlying engine, even if the Response owning the list is not returned yet.

Author:
bratseth

  • Method Summary

    Modifier and Type
    Method
    Description
    DATATYPE
    add(DATATYPE data)
    Adds a child data item to this.
    void
    addDataListener(Runnable runnable)
    Adds a listener which is invoked every time data is added to this list.
    List<DATATYPE>
    asList()
    Returns the content of this as a List.
    default void
    close()
    Notify this list that it will never be accessed again, neither for read nor write.
    CompletableFuture<DataList<DATATYPE>>
    completeFuture()
    Returns a future in which all incoming data in this has become available.
    DATATYPE
    get(int index)
     
    IncomingData<DATATYPE>
    incoming()
    Returns the buffer of incoming/future data to this list.

    Methods inherited from interface com.yahoo.processing.response.Data

    request

    Methods inherited from interface com.yahoo.component.provider.Freezable

    freeze, isFrozen

    Methods inherited from interface com.yahoo.component.provider.ListenableFreezable

    addFreezeListener

  • Method Details

    • add

      DATATYPE add(DATATYPE data)
      Adds a child data item to this.
      Parameters:
      data - the data to add to this
      Returns:
      the input data instance, for chaining

    • get

      DATATYPE get(int index)

    • asList

      List<DATATYPE> asList()
      Returns the content of this as a List. The returned list is either a read-only snapshot or an editable reference to the content of this. If the returned list is editable and this is frozen, the only allowed operation is to add new items to the end of the list.

    • incoming

      IncomingData<DATATYPE> incoming()
      Returns the buffer of incoming/future data to this list. This can be used to provide data to this list from other threads, after its creation, and to consume, wait for, or be notified upon the arrival of such data.

      Some list instances do not support late incoming data, such lists responds to read calls to IncomingData as expected and without incurring any synchronization, and throws an exception on write calls.

    • completeFuture

      CompletableFuture<DataList<DATATYPE>> completeFuture()
      Returns a future in which all incoming data in this has become available. This has two uses:
      • Calling get(int) on this future will block (if necessary) until all incoming data has arrived, transfer that data from the incoming buffer into this list and invoke any listeners on this event on the calling thread.
      • Adding a listener on this future will cause it to be called when completion().get() is called, after the incoming data has been moved to this thread and before the get() call returns.

      Note that if no thread calls completed().get(), this future will never occur.

      Any data list consumer who wishes to make sure it sees the complete data for this list must call dataList.complete().get() before consuming this list. If a guaranteed non-blocking call to this method is desired, register a listener on the future where all data is available for draining (that is, on dataList.incoming().completed()) and resume by calling this method from the listener.

      Making this call on a list which does not support future data always returns immediately and causes no memory synchronization cost.

    • addDataListener

      void addDataListener(Runnable runnable)
      Adds a listener which is invoked every time data is added to this list. The listener is always invoked on the same thread which is adding the data, and hence it can modify this list freely without synchronization.

    • close

      default void close()
      Notify this list that it will never be accessed again, neither for read nor write. Implementations can override this as an optimization to release any data held in the list for garbage collection. This default implementation does nothing.