org.jtrim2.concurrent.query

Interface AsyncDataController

All Known Implementing Classes:

DelegatedAsyncDataController, DoNothingDataController, InitLaterDataController, SimpleDataController

public interface AsyncDataController

The AsyncDataController used to control the way the data is provided by an AsyncDataLink and the state of providing the data.

Controlling the data providing process

Although AsyncDataLink instances are assumed to be linked to a particular data, they may provide that data in multiple steps by providing more and more accurate version of the data. This can be controlled by the controlData method.

Checking the state of the data providing process

Sometimes it is good to know what actually is the AsyncDataLink providing the data is doing. This knowledge can be used for various purposes like visually displaying the progress to the user or tracking the cause of bugs when a data is never loaded (e.g.: due to a deadlock). For this purpose implementations must provide this state through the getDataState method. This state as a bare minimum must provide a double value between 0.0 and 1.0 of the state of the current progress.

Thread safety

Implementations of this interface are required to be safe to use by multiple threads concurrently.

Synchronization transparency

Implementations of this interface are not required to be synchronization transparent except for the getDataState method which must be implemented so that its synchronization is invisible to users of this interface in terms of correctness.

See Also:

AsyncDataLink, AsyncDataLink.getData(org.jtrim2.cancel.CancellationToken, AsyncDataListener), InitLaterDataController

Method Summary

Modifier and Type	Method and Description
void	controlData(Object controlArg) Notifies the AsyncDataLink providing the data, that the data should be provided in a specific way.
AsyncDataState	getDataState() Returns the current progress of the data providing process.

Method Detail

controlData

void controlData(Object controlArg)

Notifies the AsyncDataLink providing the data, that the data should be provided in a specific way. This may affect the intermediate incomplete datas only and regardless how and when this method was called it may not affect the final and complete data provided by the AsyncDataLink.

How exactly the data providing can be affected is entirely implementation dependent. For example an implementation may allow requests like "I don't need intermediate data, only the final one" or set up some priorities, that some part of the data should be provided as soon as possible and others are less important. Also implementations may choose to completely ignore this method call.

In general the order of the control arguments of multiple controlData method call is considered to be important.

Note however, that this method only hints the AsyncDataLink and usually implementations cannot make any hard guarantees that they will honor the request.

Parameters:

controlArg - the control arguments defining the way how the data should be provided. Implementations may make various restrictions on what this argument is allowed to be (e.g.: its class). Note that the control argument in general is expected to be safely sharable across multiple threads concurrently and to be a relatively lightweight object. That is, it is highly recommended that control arguments be simple immutable objects only containing a minimal number of hints.

Throws:

IllegalArgumentException - implementations may choose to throw this exception if they find that the passed argument is inappropriate

NullPointerException - implementations may choose to throw this exception if they do not support null as a control object

ClassCastException - implementations may choose to throw this exception if the passed control object is not an instance of a required class

getDataState

AsyncDataState getDataState()

Returns the current progress of the data providing process. The progress as a minimum must contain a double value between 0.0 and 1.0 which defines the rough progress where 0.0 means "just started" and 1.0 means (almost) completed.

This method must be implemented to return as quickly as possible. That is, this method should do little more than accessing a volatile field or similar actions.

In case actual providing of the data has not yet been started and the implementation knows little or nothing about what kind of data will be provided, it should return a null AsyncDataState rather than a state with an arbitrary chosen class.

Returns:

the current state of progress of the data providing process. This method may return null if the state is not yet available.