Package org.jtrim2.ui.concurrent.query

Class BackgroundDataProvider<IDType,RightType>

java.lang.Object
org.jtrim2.ui.concurrent.query.BackgroundDataProvider<IDType,RightType>
Type Parameters:
IDType - the type of the request ID of the underlying access manager
RightType - the type of the rights handled by the underlying access manager
public final class BackgroundDataProvider<IDType,RightType> extends Object
Defines a class that allows to create AsyncDataQuery and AsyncDataLink instances which only provides data until a requested AccessToken is available.

Every BackgroundDataProvider has an associated AccessManager and data requested from a data query or data link created by the BackgroundDataProvider will be provided in the context of an access token of the associated access manager. That is, the onDataArrive(DataType) method of the listeners will be called in the context of the access token. Both the onDataArrive and the onDoneReceive method is called from the UI Thread.

Thread safety

Methods of this class are safe to be accessed from multiple threads concurrently.

Synchronization transparency

Methods of this class are synchronization transparent but they are non-blocking quick methods allowed to be called from the UI thread.

  • Constructor Details

    • BackgroundDataProvider

      public BackgroundDataProvider(AccessManager<IDType,RightType> accessManager, UiExecutorProvider uiExecutorProvider)
      Creates a new BackgroundDataProvider with the given AccessManager.
      Parameters:
      accessManager - the AccessManager from which access tokens are requested to transfer data in their context. This argument cannot be null.
      uiExecutorProvider - a factory to create executors running tasks on the UI thread of the associated UI framework. This argument cannot be null.
      Throws:
      NullPointerException - thrown if the specified access manager is null

  • Method Details

    • createQuery

      public <QueryArgType, DataType> AsyncDataQuery<QueryArgType,DataType> createQuery(AccessRequest<? extends IDType,? extends RightType> request, AsyncDataQuery<QueryArgType,DataType> wrappedQuery)
      Creates an AsyncDataQuery which forwards every requested to the specified AsyncDataQuery but delivers the retrieved data in the context of an access token of the access manager of this BackgroundDataProvider.

      The returned data query will simply wrap the data links of the specified data query using the createLink method. So everything what holds for the links created by the createLink holds for the data links of the returned data query.

      Type Parameters:
      QueryArgType - the type of the input of the query
      DataType - the type of the data to be retrieved
      Parameters:
      request - the AccessRequest used to acquire the required access token in which context the data will be provided. This argument cannot be null.
      wrappedQuery - the AsyncDataQuery actually used to retrieve the data requested by the returned AsyncDataQuery. This argument cannot be null.
      Returns:
      the AsyncDataQuery which forwards every requested to the specified AsyncDataQuery but delivers the retrieved data in the context of an access token of the access manager of this BackgroundDataProvider. This method never returns null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      See Also:

    • createLink

      public <DataType> AsyncDataLink<DataType> createLink(AccessRequest<? extends IDType,? extends RightType> request, AsyncDataLink<DataType> wrappedLink)
      Creates an AsyncDataLink which forwards every requested to the specified AsyncDataLink but delivers the retrieved data in the context of an access token of the access manager of this BackgroundDataProvider and also on the UI thread.

      The required access token is attempted to be retrieved every time the data is requested (i.e.: getData is invoked). In case the access token cannot be acquired, the data transferring is automatically canceled. If the access token can be acquired but the token is released while retrieving the data, the data retrieval process is canceled and no more data will be transfered to the listener. Note however that the wrapped data link may not respond to this cancellation request and may actually continue retrieving data but this retrieved data will not be forwarded to the listener of the data retrieval.

      The listener is used the following way:

      The onDataArrive method is always called in the context of the acquired access token (and therefore the access token will remain acquired at least until the onDataArrive method returns.

      The onDoneReceive method is attempted to be called in the context of the access token. If the access token has been released, the onDoneReceive method is called regardless but not from the context of the access token. In this later case, the AsyncReport will signal that the data retrieval process has been canceled. Therefore if the isCanceled() method of the AsyncReport returns true, the onDoneReceive method has been called in the context of the access token (the opposite may not be true).

      Both of the above mentioned methods are always called from the UI thread.

      Type Parameters:
      DataType - the type of the data to be retrieved
      Parameters:
      request - the AccessRequest used to acquire the required access token in which context the data will be provided. This argument cannot be null.
      wrappedLink - the AsyncDataLink actually used to retrieve the data requested by the returned AsyncDataLink. This argument cannot be null.
      Returns:
      the AsyncDataLink which forwards every requested to the specified AsyncDataLink but delivers the retrieved data in the context of an access token of the access manager of this BackgroundDataProvider. This method never returns null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      See Also: