Package org.jtrim2.ui.concurrent.query

Interface DataRenderer<DataType>

Type Parameters:
DataType - the type of the data passed to the render method
public interface DataRenderer<DataType>
Defines an arbitrary rendering task. A DataRender is usually passed to an AsyncRenderer and the AsyncRenderer must take care to invoke the appropriate methods of the DataRender.

Instances of a DataRenderer are need to be used in the following ways:

  1. Before actually calling any of the methods of DataRenderer, the startRendering method need to be called. That is, none of the other methods defined by the DataRenderer interface can be called before calling startRendering.
  2. After startRendering has been called, the render method can be called multiple times (zero or more) passing more and more accurate data to it with each invocation. The data is intended to be provided by an AsyncDataLink but this is not strictly necessary (although an AsyncDataLink can model each valid uses).
  3. Once no more data is available the finishRendering method of the DataRenderer. must be called. The finishRendering method is mandatory to be called if startRendering has been called previously.
Note that the startRendering, render and finishRendering methods are all allowed to do some rendering and each invocation to these methods expected to overwrite the previously done rendering by any of these methods. Multiple invocations to render need to overwrite each other's result as well.

Significant rendering: Each method of this interface which is allowed to do some rendering may do a significant or insignificant rendering (or no rendering at all which is handled the same way as insignificant rendering). If a significant rendering was done by a DataRenderer, it means that this DataRenderer might be canceled if there is another DataRenderer which would overwrite its results. This property is required because if DataRenderer would be canceled without regard if it has done a significant rendering or not and new DataRenderer instances were supplied rapidly overwriting its result: It would be possible that no significant rendering is done for a significant amount of time. When painting a component this would manifest as the component does not get repainted until the DataRenderer instances are no longer provided rapidly. Note: Once any of the rendering methods of this interface returns that it has done a significant rendering, subsequent rendering method invocations must also be significant or do no rendering at all (must leave the results of the previous rendering intact).

Thread safety

Implementations of this interface are not required to be safe to be accessed from multiple threads concurrently. In fact, the startRendering, render and finishRendering methods must never be called concurrently because their result must overwrite each other's results and if they were called concurrently it could not be determined which call needs to overwrite the results of which call.

Synchronization transparency

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

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    finishRendering(CancellationToken cancelToken, AsyncReport report)
    This method is called to allow for a final rendering after no more render call will be done.
    boolean
    render(CancellationToken cancelToken, DataType data)
    This method may be called multiple times to do the implementation defined rendering.
    boolean
    startRendering(CancellationToken cancelToken)
    This method is invoked before calling any of the other methods of this interface.
    boolean
    willDoSignificantRender(DataType data)
    This method might be optionally called to determine if a subsequent invocation to the render method will be significant or not.

  • Method Details

    • startRendering

      boolean startRendering(CancellationToken cancelToken)
      This method is invoked before calling any of the other methods of this interface. This method may also do some initial rendering if it can.

      Note: Once this method has been called, it is mandatory to call the finishRendering method of this DataRenderer before it becomes eligible for garbage collection.

      This method should not throw an exception but if it does, the rendering process should be continued as if this method returned false.

      Parameters:
      cancelToken - the CancellationToken signaling cancellation a request when the rendering request has been canceled. Upon cancellation this method may simply return false or throw an OperationCanceledException exception or even continue as if nothing happened. This argument cannot be null.
      Returns:
      true if this method actually did some significant rendering, false otherwise
      Throws:
      OperationCanceledException - implementation may throw this exception if they detect a cancellation request. They are not required to do so, they may even return false or even ignore the cancellation request.

    • willDoSignificantRender

      boolean willDoSignificantRender(DataType data)
      This method might be optionally called to determine if a subsequent invocation to the render method will be significant or not.

      That is, in case this method returns true for a particular data, it promises that a subsequent call to the render method (of the same DataRenderer) will also return true if the same data is passed to the render method. Returning false if simply the refusal of making such commitment. Note: When cancellation is requested, implementations are allowed to break this promise and the render method may return false.

      Notice that returning false is always safe, it does not promises that render method will also return false.

      Unlike other methods of this interface this method must be very quick to return and if this method cannot determine if render method will return true or false, it must simply return false rather than doing some expensive test. For example, this method might check the existence of a property in the passed data but may not analyze the pixels of an image (if the data contains an image).

      This method is provided for performance reasons only, so that callers may be able to more eagerly cancel the rendering process if required. However, it is always safe for this method to simply return false.

      Parameters:
      data - the data object to be checked if passing this data to the render method will cause a significant rendering. This argument can be null if the provider of the data can provide null objects.
      Returns:
      true if a subsequent invocation to the render method with the same data will cause a significant rendering, false otherwise

    • render

      boolean render(CancellationToken cancelToken, DataType data)
      This method may be called multiple times to do the implementation defined rendering. When this method is called multiple times it will be done so with a more and more accurate data and each invocation is expected to overwrite the results of the previous rendering. This method is not called if there is no data available.

      This method should not throw an exception but if it does, the rendering process should be continued as if this method returned false.

      Parameters:
      data - the data object which is the input of the rendering process. This argument can be null if the provider of the data can provide null objects.
      cancelToken - the CancellationToken signaling cancellation a request when the rendering request has been canceled. Upon cancellation this method may simply return false or throw an OperationCanceledException exception or even continue as if nothing happened. This argument cannot be null.
      Returns:
      true if this method actually did some significant rendering, false otherwise
      Throws:
      OperationCanceledException - implementation may throw this exception if they detect a cancellation request. They are not required to do so, they may even return false or even ignore the cancellation request.

    • finishRendering

      void finishRendering(CancellationToken cancelToken, AsyncReport report)
      This method is called to allow for a final rendering after no more render call will be done. This method must be called if startRendering is called on this DataRenderer. Also, this method may not be called more than once.

      Note that in general it is not allowed to restart a DataRenderer, once finishRendering has been called, this DataRenderer object is no longer useful regarding rendering.

      Parameters:
      report - the AsyncReport object defining how the rendering has been completed (the same as with the AsyncDataListener). This argument cannot be null.
      cancelToken - the CancellationToken signaling cancellation a request when the rendering request has been canceled. Upon cancellation this method may simply return or throw an OperationCanceledException exception or even continue as if nothing happened. This argument cannot be null.
      Throws:
      OperationCanceledException - implementation may throw this exception if they detect a cancellation request. They are not required to do so, they may even return normally or simply ignore the cancellation request.