org.jtrim2.concurrent.query

Interface AsyncDataQuery<QueryArgType,DataType>

Type Parameters:

QueryArgType - the type of the input of the query. It is recommended that this type be immutable or effectively immutable.

DataType - the type of the data to be retrieved. As with AsyncDataLink, this type is strongly recommended to be immutable or effectively immutable.

All Known Implementing Classes:

CachedAsyncDataQuery, CachedByIDAsyncDataQuery

public interface AsyncDataQuery<QueryArgType,DataType>

Defines an object which can be used to query data based on a specified input.

Instances of this class must be able to create a AsyncDataLink based on the provided input. The AsyncDataLink then can be used to actually retrieve the input. So to simply retrieve the data based on the provided input, the following code should be used:

createDataLink(input).getData(listener)

In most cases AsyncDataQuery implementations are expected to be relatively simple. They should only create a new instance of an AsyncDataLink with the specified input.

There are some cases however when more sophisticated implementations of AsyncDataQuery is needed. A notable example of such case is when caching is needed. Such caching mechanism are available in the AsyncQueries utility class:

• AsyncQueries.cacheResults(AsyncDataQuery)
• AsyncQueries.cacheLinks(AsyncDataQuery, int)
• AsyncQueries.cacheByID(AsyncDataQuery, ReferenceType, ObjectCache, int)

The intended use of this interface is that implementations should do as little work as possible. That is, an implementation which allow files to be loaded based on the path to the file should not actually also try to prefetch or cache (etc.) it. Such implementation should only return an AsyncDataLink which actually will load the file when requested. Various other processing should be implemented in a different (preferably generic) implementation and then those implementations should be combined with each other. The AsyncQueries utility class also provides many methods to link queries and links after each other.

String representation of data links and queries

Since AsyncDataLink and AsyncDataQuery instances can be attached in a convoluted way, it can be very helpful if the toString() method returns a human readable string describing what the AsyncDataLink will do. The string representation is not intended to be parsed or even be parsable it is only intended to contain helpful information when debugging an application. To be consistent with the string representation provided by implementations in JTrim, the following guidelines should be used:

• The representation should be multi-lined each line describing a single action.
• The representation should be readable from top to bottom describing the consecutive actions.
• When an AsyncDataLink or AsyncDataQuery wraps another query, the string representation of the subquery or sublink should be indented. The indentations should be done using the appendIndented methods of the AsyncFormatHelper class.
• When working with arrays or collections it is recommended to add the content as an indented multi-line string with each element in a separate line. The AsyncFormatHelper contains methods to format them so.
• The efficiency is not an issue because the string representation is intended to be used for debugging only.
• The methods in AsyncFormatHelper should be used whenever possible for better consistency.

Thread safety

Implementations of this interface are required to be safe to use by multiple threads concurrently.

Synchronization transparency

Implementations of this interface are not required to be synchronization transparent. Note however that the createDataLink method must return reasonably fast, must never do expensive tasks synchronously and especially not depend on some external resources.

See Also:

AsyncDataController, AsyncDataLink, AsyncDataListener, AsyncQueries

Method Summary

Modifier and Type	Method and Description
AsyncDataLink<DataType>	createDataLink(QueryArgType arg) Creates a AsyncDataLink which will provide data based on the specified input.

Method Detail

createDataLink

AsyncDataLink<DataType> createDataLink(QueryArgType arg)

Creates a AsyncDataLink which will provide data based on the specified input.

This method must return immediately without blocking and should not actually start retrieving the requested data (not in way detectable by the user but for example: prefetching is allowed).

Parameters:

arg - the input argument which is to be used to retrieve the data. It is implementation dependent if null is allowed as an argument.

Returns:

the AsyncDataLink which will provide data based on the specified input. This method never returns null.

Throws:

NullPointerException - thrown if the implementation does not allow null as an input but null was passed