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 and 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.
com.google.common.util.concurrent.ListenableFuture<DataList<DATATYPE>>	complete() 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.ListenableFreezable

addFreezeListener

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

freeze, isFrozen

Method Detail

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.

complete

com.google.common.util.concurrent.ListenableFuture<DataList<DATATYPE>> complete()

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.