org.jtrim2.concurrent.query

Class InitLaterDataController

java.lang.Object

org.jtrim2.concurrent.query.InitLaterDataController

All Implemented Interfaces:

AsyncDataController

public final class InitLaterDataController
extends Object
implements AsyncDataController

Defines an AsyncDataController which forwards every call to a wrapped AsyncDataController but the wrapped AsyncDataController can be specified later, after construction time.

After creating an InitLaterDataController, sooner or later the initController method must be called to set the wrapped AsyncDataController to which calls are forwarded after initController returns. Up until the point before initController was invoked, the InitLaterDataController records the actions requested and will forward all these requests to the wrapped AsyncDataController immediately after it is initialized. More specifically: It will remember every control object sent to it and will forward them to the wrapped AsyncDataController after initialized, in the same order as the control objects were submitted. For the state of progress, the InitLaterDataController will return the state specified at construction time before it is initialized (and after that, it will just return the state returned by wrapped AsyncDataController.

This class is advantageous to use when an AsyncDataController cannot be created right away but is still required (possibly because it need to be returned by a method). Note that even in this case, it is recommended to quickly initialize the InitLaterDataController to avoid excessive accumulation of control objects.

Note that if an InitLaterDataController instance is returned, it is safer to wrap it in a DelegatedAsyncDataController instance (for the return value), so the code accepting the return value may not be able to call the initController method.

Thread safety

Methods of this class are safe to be used by multiple threads concurrently. Note however, that the initController method may only be called at most once.

Synchronization transparency

The methods of this class derive their synchronization transparency property from the wrapped AsyncDataController.

See Also:

DelegatedAsyncDataController

Constructor Summary

Constructors

Constructor and Description
InitLaterDataController() Creates the InitLaterDataController with a null state of progress object to return before actually initialized with an AsyncDataController.
InitLaterDataController(AsyncDataState firstState) Creates the InitLaterDataController with a state of progress object to return before actually initialized with an AsyncDataController.

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.
void	initController(AsyncDataController wrappedController) Initializes this InitLaterDataController with the specified AsyncDataController to which calls are to be forwarded to.
String	toString() Returns the string representation of this InitLaterDataController in no particular format.

Methods inherited from class java.lang.Object

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

Constructor Detail

InitLaterDataController

public InitLaterDataController()

Creates the InitLaterDataController with a null state of progress object to return before actually initialized with an AsyncDataController.

Note that the initController method needs to be called so method calls may be forwarded to the actual AsyncDataController.

InitLaterDataController

public InitLaterDataController(AsyncDataState firstState)

Creates the InitLaterDataController with a state of progress object to return before actually initialized with an AsyncDataController.

Note that the initController method needs to be called so method calls may be forwarded to the actual AsyncDataController.

Parameters:

firstState - the state of progress to be returned by the getDataState method before the newly created InitLaterDataController instance is initialized. This argument can be null, in which case null will be returned prior initialization.

Method Detail

initController

public void initController(AsyncDataController wrappedController)

Initializes this InitLaterDataController with the specified AsyncDataController to which calls are to be forwarded to. This method may invoke the controlData of the specified AsyncDataController.

This method may only be called once.

Parameters:

wrappedController - the AsyncDataController to which calls are forwarded to. This argument cannot be null.

Throws:

IllegalStateException - thrown if this method has already been called

NullPointerException - thrown if the specified AsyncDataController was null

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.

This implementation will forward its call to the wrapped AsyncDataController after being initialized, before that it will collect the specified control object and will forward the control object after initialization.

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.

This implementation will forward its call to the wrapped AsyncDataController after being initialized, before that it will return the state object specified at construction time.

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()

Returns the string representation of this InitLaterDataController in no particular format.

This method is intended to be used for debugging only.

Overrides:

toString in class Object

Returns:

the string representation of this object in no particular format. This method never returns null.