public interface AsyncDataController
AsyncDataController used to control the way the data is provided
by an AsyncDataLink and the state of providing the data.
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.
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.
getDataState method which must be implemented so that
its synchronization is invisible to users of this interface in terms of
correctness.| 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.
|
void controlData(Object controlArg)
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.
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.IllegalArgumentException - implementations may choose to throw
this exception if they find that the passed argument is inappropriateNullPointerException - implementations may choose to throw this
exception if they do not support null as a control objectClassCastException - implementations may choose to throw this
exception if the passed control object is not an instance of a required
classAsyncDataState getDataState()
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.
null if the state is not yet available.