Package org.jtrim2.ui.concurrent.query

Interface AsyncRenderer

public interface AsyncRenderer
Defines an object which is capable to render a component asynchronously.

To render the component associated with the AsyncRenderer call its render method with the arguments used to do the rendering. Multiple calls to the render method may overwrite each other. That is, only the last render method call is guaranteed to have any effect previous calls might be discarded at the discretion of the implementation. Therefore a single instance of AsyncRenderer should not be used to render multiple components.

A rendering request is defined by an AsyncDataLink and a DataRenderer where the data link provides the data for the DataRenderer. In what context the AsyncRenderer calls the rendering methods is completely implementation dependent but usually it should execute it in a context of a TaskExecutor. Note however that implementations are also allowed to execute rendering synchronously (despite the name of this class). For example, executing synchronously might be useful for debugging.

Note on cancellation: Rendering requests can be canceled but note that canceling a request might also implicitly cause the cancellation of every previous rendering requests. This is because the canceled request might have caused the cancellation of previous requests (since rendering requests may overwrite each other).

Thread safety

Implementations of this interface are required to be safe to be accessed from multiple threads concurrently.

Synchronization transparency

Implementations of this listener are not required to be synchronization transparent.
See Also:

  • Method Details

    • render

      <DataType> RenderingState render(CancellationToken cancelToken, AsyncDataLink<DataType> dataLink, DataRenderer<? super DataType> renderer)
      Submits a rendering requests to be done asynchronously.

      First the startRendering method of the renderer will be called, then the data is requested from the passed AsyncDataLink and the provided data is passed to the render method of the renderer. Once each data has been retrieved by the data link or this rendering request has been canceled (either by explicit cancellation or by another request overwriting it) finishRendering will be called. The finishRendering method is always called if the startRendering method has been called.

      Note that if another render method call overwrites this request, this request might be completely ignored.

      Type Parameters:
      DataType - the type of the data retrieved by the passed data link
      Parameters:
      cancelToken - the CancellationToken which can be used to cancel this rendering request. This argument cannot be null.
      dataLink - the AsyncDataLink providing the data for the render method of the passed renderer. This argument can be null, in which case a data link is assumed which does not return any data but completes successfully immediately.
      renderer - the DataRenderer which is used to do the rendering. How and where this renderer renders depends completely on the passed DataRenderer. This argument cannot be null.
      Returns:
      an object through which the caller might check the progress of this rendering request. This method never returns null.
      Throws:
      NullPointerException - thrown if the specified CancellationToken or the DataRenderer is null