public abstract class

AbstractDataSource

extends Object
implements DataSource<T>
java.lang.Object
   ↳ com.facebook.datasource.AbstractDataSource<T>
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

An abstract implementation of DataSource interface.

It is highly recommended that other data sources extend this class as it takes care of the state, as well as of notifying listeners when the state changes.

Subclasses should override closeResult(T) if results need clean up

Summary

Nested Classes
interface AbstractDataSource.DataSourceInstrumenter Allows to capture unit of works for instrumentation purposes. 
Protected Constructors
AbstractDataSource()
Public Methods
boolean close()
Cancels the ongoing request and releases all associated resources.
static AbstractDataSource.DataSourceInstrumenter getDataSourceInstrumenter()
Map<String, Object> getExtras()
synchronized Throwable getFailureCause()
synchronized float getProgress()
synchronized T getResult()
The most recent result of the asynchronous computation.
synchronized boolean hasFailed()
boolean hasMultipleResults()
synchronized boolean hasResult()
synchronized boolean isClosed()
synchronized boolean isFinished()
static void provideInstrumenter(AbstractDataSource.DataSourceInstrumenter dataSourceInstrumenter)
boolean setResult(T value, boolean isLast)
void subscribe(DataSubscriber<T> dataSubscriber, Executor executor)
Subscribe for notifications whenever the state of the DataSource changes.
Protected Methods
void closeResult(T result)
Subclasses should override this method to close the result that is not needed anymore.
void notifyDataSubscriber(DataSubscriber<T> dataSubscriber, Executor executor, boolean isFailure, boolean isCancellation)
void notifyProgressUpdate()
void setExtras(Map<String, Object> extras)
boolean setFailure(Throwable throwable)
Subclasses should invoke this method to set the failure.
boolean setFailure(Throwable throwable, Map<String, Object> extras)
boolean setProgress(float progress)
Subclasses should invoke this method to set the progress.
boolean setResult(T value, boolean isLast, Map<String, Object> extras)
Subclasses should invoke this method to set the result to value.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.facebook.datasource.DataSource

Protected Constructors

protected AbstractDataSource ()

Public Methods

public boolean close ()

Cancels the ongoing request and releases all associated resources.

Subsequent calls to getResult() will return null.

Returns
  • true if the data source is closed for the first time

public static AbstractDataSource.DataSourceInstrumenter getDataSourceInstrumenter ()

public Map<String, Object> getExtras ()

public synchronized Throwable getFailureCause ()

public synchronized float getProgress ()

public synchronized T getResult ()

The most recent result of the asynchronous computation.

The caller gains ownership of the object and is responsible for releasing it. Note that subsequent calls to getResult might give different results. Later results should be considered to be of higher quality.

This method will return null in the following cases:

  • when the DataSource does not have a result (hasResult returns false).
  • when the last result produced was null.

Returns
  • current best result

public synchronized boolean hasFailed ()

public boolean hasMultipleResults ()

public synchronized boolean hasResult ()

public synchronized boolean isClosed ()

public synchronized boolean isFinished ()

public static void provideInstrumenter (AbstractDataSource.DataSourceInstrumenter dataSourceInstrumenter)

public boolean setResult (T value, boolean isLast)

public void subscribe (DataSubscriber<T> dataSubscriber, Executor executor)

Subscribe for notifications whenever the state of the DataSource changes.

All changes will be observed on the provided executor.

Protected Methods

protected void closeResult (T result)

Subclasses should override this method to close the result that is not needed anymore.

This method is called in two cases: 1. to clear the result when data source gets closed 2. to clear the previous result when a new result is set

protected void notifyDataSubscriber (DataSubscriber<T> dataSubscriber, Executor executor, boolean isFailure, boolean isCancellation)

protected void notifyProgressUpdate ()

protected void setExtras (Map<String, Object> extras)

protected boolean setFailure (Throwable throwable)

Subclasses should invoke this method to set the failure.

This method will return true if the failure was successfully set, or false if the data source has already been set, failed or closed.

If the failure was successfully set, state of the data source will be set to AbstractDataSource.DataSourceStatus#FAILURE.

This will also notify the subscribers if the failure was successfully set.

Do NOT call this method from a synchronized block as it invokes external code of the subscribers.

Parameters
throwable the failure cause to be set.
Returns
  • true if the failure was successfully set.

protected boolean setFailure (Throwable throwable, Map<String, Object> extras)

protected boolean setProgress (float progress)

Subclasses should invoke this method to set the progress.

This method will return true if the progress was successfully set, or false if the data source has already been set, failed or closed.

This will also notify the subscribers if the progress was successfully set.

Do NOT call this method from a synchronized block as it invokes external code of the subscribers.

Parameters
progress the progress in range [0, 1] to be set.
Returns
  • true if the progress was successfully set.

protected boolean setResult (T value, boolean isLast, Map<String, Object> extras)

Subclasses should invoke this method to set the result to value.

This method will return true if the value was successfully set, or false if the data source has already been set, failed or closed.

If the value was successfully set and isLast is true, state of the data source will be set to AbstractDataSource.DataSourceStatus#SUCCESS.

closeResult(T) will be called for the previous result if the new value was successfully set, OR for the new result otherwise.

This will also notify the subscribers if the value was successfully set.

Do NOT call this method from a synchronized block as it invokes external code of the subscribers.

Parameters
value the value that was the result of the task.
isLast whether or not the value is last.
extras an object with extra data for this datasource
Returns
  • true if the value was successfully set.