Package org.jtrim2.concurrent.query

Class DelegatedAsyncDataController

java.lang.Object
org.jtrim2.concurrent.query.DelegatedAsyncDataController
All Implemented Interfaces:
AsyncDataController
public class DelegatedAsyncDataController extends Object implements AsyncDataController
An AsyncDataController implementation which delegates all of its methods to another AsyncDataController specified at construction time.

This implementation does not declare any methods other than the ones AsyncDataController offers but implements all of them by forwarding to another AsyncDataController implementation specified at construction time.

This class was designed for two reasons:

  • To allow a safer way of class inheritance, so there can be no unexpected dependencies on overridden methods. To imitate inheritance subclass DelegatedAsyncDataController: specify the AsyncDataController you want to "subclass" in the constructor and override the required methods or provide new ones.
  • To hide other public methods of an AsyncDataController from external code. This way, the external code can only access methods which the AsyncDataController interface provides.

Thread safety

The thread safety properties of this class entirely depend on the wrapped AsyncDataController instance.

Synchronization transparency

If instances of this class are synchronization transparent or if its synchronization control can be observed by external code entirely depends on the wrapped AsyncDataController instance.

  • Field Details

    • wrappedController

      protected final AsyncDataController wrappedController
      The AsyncDataController to which the methods are forwarded. This field can never be null because the constructor throws NullPointerException if null was specified as the AsyncDataController.

  • Constructor Details

    • DelegatedAsyncDataController

      public DelegatedAsyncDataController(AsyncDataController controller)
      Initializes the wrappedController field with the specified argument.
      Parameters:
      controller - the AsyncDataController to which the methods are forwarded. This argument cannot be null.
      Throws:
      NullPointerException - thrown if the specified AsyncDataController is null

  • Method Details

    • controlData

      public 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.

      Specified by:
      controlData in interface AsyncDataController
      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.

    • getDataState

      public 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.

      Specified by:
      getDataState in interface AsyncDataController
      Returns:
      the current state of progress of the data providing process. This method may return null if the state is not yet available.

    • toString

      public String toString()
      Overrides:
      toString in class Object