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 Summary

Fields

Modifier and Type	Field and Description
protected AsyncDataController	wrappedController The AsyncDataController to which the methods are forwarded.

Constructor Summary

Constructors

Constructor and Description
DelegatedAsyncDataController(AsyncDataController controller) Initializes the wrappedController field with the specified argument.

Method Summary

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.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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 Detail

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 Detail

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