Package org.jtrim2.concurrent.query

Contains classes and interfaces for asynchronous data retrieval.

See: Description

Interface Summary

Interface	Description
AsyncDataController	The AsyncDataController used to control the way the data is provided by an AsyncDataLink and the state of providing the data.
AsyncDataLink<DataType>	Defines a link to asynchronously access a specific data.
AsyncDataListener<DataType>	Listens for data provided by an AsyncDataLink.
AsyncDataQuery<QueryArgType,DataType>	Defines an object which can be used to query data based on a specified input.
AsyncDataState	Defines the progress of the providing of a data provided by an AsyncDataLink.
AsyncStateReporter<DataType>	Defines the listener which will be notified periodically by the AsyncDataLink created by the AsyncLinks.createStateReporterLink method.
CachedLinkContainer<CacheRefType>	Defines a container for cached AsyncDataLink instances.
DataConverter<OldDataType,NewDataType>	Defines a conversion from one type to another.
DataInterceptor<DataType>	Defines an interface for intercepting data provided by an AsyncDataLink.
DataTransformer<DataType>	Defines a transformation of objects.

Class Summary

Class	Description
AsyncDataConverter<InputType,ResultType>	Defines a conversion of objects and the TaskExecutorService which should be used to execute the conversion process.
AsyncDataTransformer<DataType>	Defines a transformation of objects to the same type and the TaskExecutorService which should be used to execute the transformation process.
AsyncFormatHelper	Contains static helper methods to create consistent string format for AsyncDataLink and AsyncDataQuery implementations.
AsyncHelper	Contains useful helper methods for asynchronous data transferring using an AsyncDataLink.
AsyncLinks	Contains static factory methods for useful AsyncDataLink implementations.
AsyncQueries	Contains static factory methods for useful AsyncDataQuery implementations.
AsyncReport	Defines how an asynchronous data transfer has completed.
CachedAsyncDataQuery<QueryArgType,DataType>	Defines an AsyncDataQuery which caches AsyncDataLink instances based on the input of the query.
CachedByIDAsyncDataQuery<QueryArgType,DataType>	Defines an AsyncDataQuery which creates AsyncDataLink instances caching their results and caches AsyncDataLink instances based on a unique ID provided to the query with the input argument.
CachedDataRequest<QueryArgType>	Defines a request for a data which should be cached if possible.
CachedLinkRequest<QueryArgType>	Defines a request for a data when the AsyncDataLink providing should be cached.
DataWithUid<DataType>	Defines an object and its ID which uniquely identifies the object within the JVM.
DelegatedAsyncDataController	An AsyncDataController implementation which delegates all of its methods to another AsyncDataController specified at construction time.
InitLaterDataController	Defines an AsyncDataController which forwards every call to a wrapped AsyncDataController but the wrapped AsyncDataController can be specified later, after construction time.
LinkedDataControl	Defines a control object for AsyncDataController instances controlling the data retrieval process of two AsyncDataLink instances.
MultiAsyncDataState	Defines an aggregate state of progress of multiple data retrieval processes.
OrderedData<DataType>	Defines a data with an index which indicates how accurate the data is.
RefCachedData<DataType>	Defines a data and a VolatileReference of the same data.
SimpleDataController	An AsyncDataController implementation which stores a volatile reference to an AsyncDataState but otherwise does nothing.
SimpleDataState	Defines an AsyncDataState with a specific double value as the state of progress and a string describing the current state.

Enum Summary

Enum	Description
DoNothingDataController	Defines an AsyncDataController which does nothing and always returns null as the state of progress.

Exception Summary

Exception	Description
DataTransferException	An exception defining a general failure of transferring a data asynchronously.
SublistenerException	An exception describing unexpected failure in one or more AsyncDataListener.

Package org.jtrim2.concurrent.query Description

Contains classes and interfaces for asynchronous data retrieval. Asynchronous data retrieval is necessary when a particular part of the code cannot block and wait but needs to retrieve a data for its operation. Such is the case with the AWT event dispatch thread, which must not be blocked to avoid frozen GUIs.

Data links

Data links are the fundamental part of the package, they represent a connection to a specific data. Through this connection, the data can be retrieved as many times as required.

The base interface for data links is AsyncDataLink which was designed to be simple to implement and simple to use. To implement it, one must implement its lone method to retrieve the data in a separate thread and notify the specified listener when the data is available. A usually sufficient implementation is to submit a task to a TaskExecutorService and retrieve the data synchronously in that task and when the data is finally available, notify the listener.

Implementations should do only a single task which is as simple as possible and should not do any extra work like caching. Such extra works can and should be implemented in separate implementations and those implementations should then be combined. For common tasks like a data link transforming the result of another data link, caching the result of a data link: the class AsyncLinks contains convenient factory methods.

Data queries

Since data links represent a connection to a single particular data and one does not always want to retrieve the same data over and over, data queries were created.

The base interface for data queries is AsyncDataQuery and usually they are even more easier to implement than data links. Since they are designed to return a data link for a specific input, a usual implementation only needs to create and return a new instance of a data link. That is, in most cases they are just simply a factory of data links.

Just like data links, it is possible to create a complex data query implementation by combining multiple instances. The class AsyncQueries contains convenient factory methods for useful implementations.

Debugging

Debugging concurrent code is always harder than debugging a simple synchronous code. Asynchronous data links are no exceptions. Since usually implementing data links are just submitting a task to an executor and then do the data retrieval process synchronously, it should be relatively easy to test and debug such implementations. If it is desirable to avoid putting break points to the start of such synchronous code, one could use an executor which executes tasks synchronously (assuming executors are used as recommended) in the test code and simply single step the code. Although executing tasks synchronously is different and may not detect synchronization issues, it may help to rule out such issue in specific cases. Also due to the AsyncDataLink interface being simple, synchronization issues are less likely to occur.

See Also:

AsyncDataLink, AsyncDataQuery, AsyncHelper, AsyncLinks, AsyncQueries