org.jtrim2.concurrent.query

Class AsyncQueries

java.lang.Object

org.jtrim2.concurrent.query.AsyncQueries

public final class AsyncQueries
extends Object

Contains static factory methods for useful AsyncDataQuery implementations.

This class cannot be inherited or instantiated.

Thread safety

Unless otherwise noted, methods of this class are safe to use by multiple threads concurrently.

Synchronization transparency

Methods of this class are synchronization transparent.

See Also:

AsyncDataQuery, AsyncLinks, AsyncHelper

Method Summary

Modifier and Type	Method and Description
static <QueryArgType,DataType> CachedByIDAsyncDataQuery<QueryArgType,DataType>	cacheByID(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery, ReferenceType refType, ObjectCache refCreator) Creates and returns 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.
static <QueryArgType,DataType> CachedByIDAsyncDataQuery<QueryArgType,DataType>	cacheByID(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery, ReferenceType refType, ObjectCache refCreator, int maxCacheSize) Creates and returns 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.
static <QueryArgType,DataType> CachedAsyncDataQuery<QueryArgType,DataType>	cacheLinks(AsyncDataQuery<? super QueryArgType,DataType> wrappedQuery) Creates and returns an AsyncDataQuery which caches AsyncDataLink instances based on the input of the query.
static <QueryArgType,DataType> CachedAsyncDataQuery<QueryArgType,DataType>	cacheLinks(AsyncDataQuery<? super QueryArgType,DataType> wrappedQuery, int maxCacheSize) Creates and returns an AsyncDataQuery which caches AsyncDataLink instances based on the input of the query.
static <QueryArgType,DataType> AsyncDataQuery<CachedDataRequest<QueryArgType>,DataType>	cacheResults(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery) Creates and returns an AsyncDataQuery which creates AsyncDataLink instances caching their results.
static <QueryArgType,OldDataType,NewDataType> AsyncDataQuery<QueryArgType,NewDataType>	convertResultsAsync(AsyncDataQuery<? super QueryArgType,? extends OldDataType> wrappedQuery, AsyncDataQuery<? super OldDataType,? extends NewDataType> converter) Creates an AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but applies a conversion on the provided data defined by an AsyncDataQuery.
static <QueryArgType,OldDataType,NewDataType> AsyncDataQuery<QueryArgType,NewDataType>	convertResultsSync(AsyncDataQuery<? super QueryArgType,? extends OldDataType> wrappedQuery, DataConverter<? super OldDataType,? extends NewDataType> converter) Creates a new AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but will apply the user defined conversion on the data.
static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataType>	extractCachedResults(AsyncDataQuery<? super QueryArgType,RefCachedData<DataType>> query) Creates an AsyncDataQuery which will provide the data part of the specified query without the VolatileReference to it.
static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataWithUid<DataType>>	markResultsWithUid(AsyncDataQuery<? super QueryArgType,? extends DataType> query) Returns an AsyncDataQuery which returns the same results as the specified AsyncDataLink but creates a DataWithUid object with a new unique ID from the provided data of the specified AsyncDataQuery.
static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataType>	removeUidFromResults(AsyncDataQuery<? super QueryArgType,DataWithUid<DataType>> query) Creates an AsyncDataQuery which will provide the data part of the specified query without the UID.

Methods inherited from class java.lang.Object

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

Method Detail

cacheResults

public static <QueryArgType,DataType> AsyncDataQuery<CachedDataRequest<QueryArgType>,DataType> cacheResults(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery)

Creates and returns an AsyncDataQuery which creates AsyncDataLink instances caching their results. The returned AsyncDataQuery is based on a user specified one.

Note that the AsyncDataLink instances themselves will not be cached. That is, requesting an AsyncDataLink from the returned AsyncDataQuery will return a new, independent AsyncDataLink instance. Only these AsyncDataLink instances will cache their results. The caching mechanism done by these AsyncDataLink instances is the same as those created by the AsyncLinks.cacheResult(AsyncDataLink, ReferenceType,ObjectCache) method.

The ObjectCache and other parameters defining the exact caching mechanism must be specified when querying new AsyncDataLink from the returned AsyncDataQuery.

As an example: Assume that the specified AsyncDataQuery loads a file by its filename as a byte array. The returned AsyncDataQuery will then load the files as a byte array as well, however individual AsyncDataLink instances will cache their results and will not reread the file. However whenever a new AsyncDataLink is returned by the returned AsyncDataQuery it will still need to reread the file at the first attempt of loading regardless that a file with the same name has been requested from the returned AsyncDataQuery.

Type Parameters:

QueryArgType - the type of the input of the specified AsyncDataQuery

DataType - the type of the data returned by the specified (and the returned) AsyncDataQuery

Parameters:

wrappedQuery - the AsyncDataQuery whose AsyncDataLink instances are to cache their results. This argument cannot be null.

Returns:

the AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but AsyncDataLink instances created by it will cache their results. Notice that this returned query requires additional inputs to specify how data is to be cached. This method never returns null.

Throws:

NullPointerException - thrown if the specified AsyncDataQuery is null

See Also:

cacheByID(AsyncDataQuery, ReferenceType, ObjectCache, int), cacheLinks(AsyncDataQuery, int), AsyncLinks.cacheResult(AsyncDataLink, ReferenceType, ObjectCache)

cacheLinks

public static <QueryArgType,DataType> CachedAsyncDataQuery<QueryArgType,DataType> cacheLinks(AsyncDataQuery<? super QueryArgType,DataType> wrappedQuery)

Creates and returns an AsyncDataQuery which caches AsyncDataLink instances based on the input of the query. That is, the returned AsyncDataQuery may return the same AsyncDataLink for the same input (based on equals). The data provided by the AsyncDataLink instances are not cached by the returned query. Those can be cached by using the cacheResults method.

The AsyncDataQuery created by this method caches only at most 128 AsyncDataLink instances and when this limit is exceeded, the one used least recently is discarded from the cache. Also a lease time can be specified when requesting an AsyncDataLink when it must be removed from the cache and the AsyncDataLink needs to be recreated if requested again.

Note that most often you want to cache both the AsyncDataLink and the data provided by them. Assume that there is a query which loads the content of a file as a byte array by file name:

 AsyncDataQuery<Path, byte[]> baseQuery = ...;
 AsyncDataQuery<CachedLinkRequest<CachedDataRequest<Path>>, byte[]> cachedQuery;
 cachedQuery = AsyncQueries.cacheLinks(AsyncQueries.cacheResults(baseQuery));
 

In the above example code cachedQuery will cache both the AsyncDataLink instances and the data provided by them. Note that order of cacheLinks and cacheResults method calls is important and applying the cacheLinks method first would not result in a desirable behaviour because the returned links would not share the cached data of the AsyncDataLink instances.

Note that it is possible to manually remove cached items from the returned AsyncDataQuery using its clearCache and removeFromCache methods.

Type Parameters:

QueryArgType - the type of the input argument of the specified AsyncDataQuery

DataType - the type of the data provided by the specified (and returned) AsyncDataQuery

Parameters:

wrappedQuery - the AsyncDataQuery which actually provides the data. The returned AsyncDataQuery will fall back to use this AsyncDataQuery for uncached AsyncDataLink instances. This argument cannot be null.

Returns:

the AsyncDataQuery which caches AsyncDataLink instances based on the input of the query. This method never returns null.

Throws:

NullPointerException - thrown if the specified AsyncDataQuery is {!code null}

See Also:

cacheLinks(AsyncDataQuery, int), cacheResults(AsyncDataQuery), cacheByID(AsyncDataQuery,ReferenceType, ObjectCache, int)

cacheLinks

public static <QueryArgType,DataType> CachedAsyncDataQuery<QueryArgType,DataType> cacheLinks(AsyncDataQuery<? super QueryArgType,DataType> wrappedQuery,
                                                                                             int maxCacheSize)

Creates and returns an AsyncDataQuery which caches AsyncDataLink instances based on the input of the query. That is, the returned AsyncDataQuery may return the same AsyncDataLink for the same input (based on equals). The data provided by the AsyncDataLink instances are not cached by the returned query. Those can be cached by using the cacheResults method.

The AsyncDataQuery created by this method caches only at most the specified number of AsyncDataLink instances and when this limit is exceeded, the one used least recently is discarded from the cache. Also a lease time can be specified when requesting an AsyncDataLink when it must be removed from the cache and the AsyncDataLink needs to be recreated if requested again.

Note that most often you want to cache both the AsyncDataLink and the data provided by them. Assume that there is a query which loads the content of a file as a byte array by file name:

 AsyncDataQuery<Path, byte[]> baseQuery = ...;
 AsyncDataQuery<CachedLinkRequest<CachedDataRequest<Path>>, byte[]> cachedQuery;
 cachedQuery = AsyncQueries.cacheLinks(AsyncQueries.cacheResults(baseQuery));
 

In the above example code cachedQuery will cache both the AsyncDataLink instances and the data provided by them. Note that order of cacheLinks and cacheResults method calls is important and applying the cacheLinks method first would not result in a desirable behaviour because the returned links would not share the cached data of the AsyncDataLink instances.

Note that it is possible to manually remove cached items from the returned AsyncDataQuery using its clearCache and removeFromCache methods.

Type Parameters:

QueryArgType - the type of the input argument of the specified AsyncDataQuery

DataType - the type of the data provided by the specified (and returned) AsyncDataQuery

Parameters:

wrappedQuery - the AsyncDataQuery which actually provides the data. The returned AsyncDataQuery will fall back to use this AsyncDataQuery for uncached AsyncDataLink instances. This argument cannot be null.

maxCacheSize - the maximum number of AsyncDataLink to store in the cache. When this argument is 0, the returned AsyncDataQuery will not actually cache AsyncDataLink instances. This argument must greater than or equal to zero.

Returns:

the AsyncDataQuery which caches AsyncDataLink instances based on the input of the query. This method never returns null.

Throws:

IllegalArgumentException - thrown if the maxCacheSize is lesser than zero

NullPointerException - thrown if the specified AsyncDataQuery is {!code null}

See Also:

cacheLinks(AsyncDataQuery), cacheResults(AsyncDataQuery), cacheByID(AsyncDataQuery,ReferenceType, ObjectCache, int)

cacheByID

public static <QueryArgType,DataType> CachedByIDAsyncDataQuery<QueryArgType,DataType> cacheByID(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery,
                                                                                                ReferenceType refType,
                                                                                                ObjectCache refCreator)

Creates and returns 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. The returned query will cache at most 128 AsyncDataLink instances concurrently.

This method call is similar to calling cacheLinks(cacheResults(wrappedQuery)), except that the query returned by this method caches AsyncDataLink instances using a supplied ID instead of the input itself. Caching by ID is preferable when the input is large (i.e. retains considerable memory) because cacheLinks(cacheResults(wrappedQuery)) will actually store the input for the cached AsyncDataLink instances to be able to get data when it disappears from the cache.

Type Parameters:

QueryArgType - the type of the input of the query

DataType - the type of the data provided by the query

Parameters:

wrappedQuery - the query which actually provides the data based on an input. This argument cannot be null.

refType - the ReferenceType to be used to reference the cached data using the specified ObjectCache. This argument cannot be null.

refCreator - the ObjectCache to use to cache the data. This argument can be null in which case ObjectCache.javaRefCache() is used as the ObjectCache.

Returns:

the 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. This method never returns null.

Throws:

NullPointerException - thrown if wrappedQuery or refType is null

See Also:

cacheLinks(AsyncDataQuery, int), cacheResults(AsyncDataQuery), cacheByID(AsyncDataQuery,ReferenceType, ObjectCache, int)

cacheByID

public static <QueryArgType,DataType> CachedByIDAsyncDataQuery<QueryArgType,DataType> cacheByID(AsyncDataQuery<? super QueryArgType,? extends DataType> wrappedQuery,
                                                                                                ReferenceType refType,
                                                                                                ObjectCache refCreator,
                                                                                                int maxCacheSize)

Creates and returns 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. The returned query will cache at most the specified number of AsyncDataLink instances concurrently.

This method call is similar to calling cacheLinks(cacheResults(wrappedQuery)), except that the query returned by this method caches AsyncDataLink instances using a supplied ID instead of the input itself. Caching by ID is preferable when the input is large (i.e. retains considerable memory) because cacheLinks(cacheResults(wrappedQuery)) will actually store the input for the cached AsyncDataLink instances to be able to get data when it disappears from the cache.

Type Parameters:

QueryArgType - the type of the input of the query

DataType - the type of the data provided by the query

Parameters:

wrappedQuery - the query which actually provides the data based on an input. This argument cannot be null.

refType - the ReferenceType to be used to reference the cached data using the specified ObjectCache. This argument cannot be null.

refCreator - the ObjectCache to use to cache the data. This argument can be null in which case ObjectCache.javaRefCache() is used as the ObjectCache.

maxCacheSize - the maximum number of AsyncDataLink instances to be cached concurrently by the returned query. This argument must be greater than or equal to zero.

Returns:

the 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. This method never returns null.

Throws:

IllegalArgumentException - thrown if maxCacheSize < 0

NullPointerException - thrown if wrappedQuery or refType is null

See Also:

cacheLinks(AsyncDataQuery, int), cacheResults(AsyncDataQuery), cacheByID(AsyncDataQuery,ReferenceType, ObjectCache)

convertResultsSync

public static <QueryArgType,OldDataType,NewDataType> AsyncDataQuery<QueryArgType,NewDataType> convertResultsSync(AsyncDataQuery<? super QueryArgType,? extends OldDataType> wrappedQuery,
                                                                                                                 DataConverter<? super OldDataType,? extends NewDataType> converter)

Creates a new AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but will apply the user defined conversion on the data. That is, the returned query will transform the AsyncDataLink instances created by the specified query as done by the AsyncLinks.convertResultSync(AsyncDataLink, DataConverter) method.

Note that the conversion is applied in an AsyncDataListener and therefore needs to be a fast, non-blocking conversion.

Type Parameters:

QueryArgType - the type of the input of both the specified and the returned query

OldDataType - the type of the data provided by the specified query which is to be converted

NewDataType - the type of the data provided by the returned query

Parameters:

wrappedQuery - the query whose provided data is to be converted. This argument cannot be null.

converter - the DataConverter defining the conversion of the data. The DataConverter#convertData(OldDataType) method will be applied to every data provided by the specified query and the result will actually be provided by the resulting query. This argument cannot be null.

Returns:

the AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but will apply the user defined conversion on the data. This method never returns null.

Throws:

NullPointerException - thrown if any of the arguments is null

See Also:

AsyncLinks.convertResultSync(AsyncDataLink, DataConverter), convertResultsAsync(AsyncDataQuery, AsyncDataQuery)

convertResultsAsync

public static <QueryArgType,OldDataType,NewDataType> AsyncDataQuery<QueryArgType,NewDataType> convertResultsAsync(AsyncDataQuery<? super QueryArgType,? extends OldDataType> wrappedQuery,
                                                                                                                  AsyncDataQuery<? super OldDataType,? extends NewDataType> converter)

Creates an AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but applies a conversion on the provided data defined by an AsyncDataQuery. That is, every data provided by the specified query (wrappedQuery) will be used as an input for the converter query (converter) and the data provided by this converter query will be provided by the returned query.

This method is best used when the conversion need to applied on the data cannot be executed in the AsyncDataListener.onDataArrive method (probably because the conversion takes too much time to complete).

The returned query works by converting every AsyncDataLink created by the specified query using the AsyncLinks.convertResultAsync(AsyncDataLink, AsyncDataQuery) method. For further details how exactly the conversion is done refer to the documentation of the convertResult method.

Type Parameters:

QueryArgType - the type of the input of both the specified and the returned query

OldDataType - the type of the data provided by the specified query which is to be converted

NewDataType - the type of the data provided by the returned query

Parameters:

wrappedQuery - the query whose provided data is to be converted. This argument cannot be null.

converter - the AsyncDataQuery defining the conversion of the data. The DataConverter#convertData(OldDataType) method will be applied to every data provided by the specified query and the result will actually be provided by the resulting query. This argument cannot be null.

Returns:

the AsyncDataQuery which will provide the same data as the specified AsyncDataQuery but applies a conversion on the provided data defined by an AsyncDataQuery. This method never returns null.

See Also:

AsyncLinks.convertResultAsync(AsyncDataLink, AsyncDataQuery), convertResultsSync(AsyncDataQuery, DataConverter), LinkedDataControl

extractCachedResults

public static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataType> extractCachedResults(AsyncDataQuery<? super QueryArgType,RefCachedData<DataType>> query)

Creates an AsyncDataQuery which will provide the data part of the specified query without the VolatileReference to it.

This method was designed to remove no longer necessary VolatileReference from the data provided by AsyncDataLink created by the AsyncLinks.refCacheResult(AsyncDataLink, ReferenceType, ObjectCache, long, TimeUnit) method.

Type Parameters:

QueryArgType - the type of the input of both the specified and the returned query

DataType - the type of the data provided by the returned query

Parameters:

query - the AsyncDataQuery whose data part is to be extracted and provided by the returned query. This argument cannot be null.

Returns:

the AsyncDataQuery which will provide the data part of the specified query. This method never returns null.

Throws:

NullPointerException - thrown if the specified query is null

See Also:

AsyncLinks.refCacheResult(AsyncDataLink, ReferenceType, ObjectCache, long, TimeUnit)

removeUidFromResults

public static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataType> removeUidFromResults(AsyncDataQuery<? super QueryArgType,DataWithUid<DataType>> query)

Creates an AsyncDataQuery which will provide the data part of the specified query without the UID.

This method was designed to remove no longer necessary UID from the data provided by AsyncDataLink created by the markResultsWithUid(AsyncDataQuery) method.

Type Parameters:

QueryArgType - the type of the input of both the specified and the returned query

DataType - the type of the data provided by the returned query

Parameters:

query - the AsyncDataQuery whose data part is to be extracted and provided by the returned query. This argument cannot be null.

Returns:

the AsyncDataQuery which will provide the data part of the specified query. This method never returns null.

Throws:

NullPointerException - thrown if the specified query is null

See Also:

markResultsWithUid(AsyncDataQuery)

markResultsWithUid

public static <QueryArgType,DataType> AsyncDataQuery<QueryArgType,DataWithUid<DataType>> markResultsWithUid(AsyncDataQuery<? super QueryArgType,? extends DataType> query)

Returns an AsyncDataQuery which returns the same results as the specified AsyncDataLink but creates a DataWithUid object with a new unique ID from the provided data of the specified AsyncDataQuery.

The returned AsyncDataQuery works by applying the AsyncLinks.markResultWithUid(AsyncDataLink) method on every AsyncDataLink created by the specified query.

The ID of the provided datas will be unique, so that no other object equals to them. That is, the ID will be different even for same data if requested multiple times.

Type Parameters:

QueryArgType - the type of the input of both the specified and the returned query

DataType - the type of the data provided by the specified AsyncDataQuery

Parameters:

query - the AsyncDataQuery from which the data part is to be derived for the results of the returned AsyncDataQuery. This argument cannot be null.

Returns:

the AsyncDataQuery providing the DataWithUid objects with the data parts provided by the specified AsyncDataQuery. This method never returns null.

Throws:

NullPointerException - thrown if the specified AsyncDataQuery is null

See Also:

AsyncLinks.markResultWithUid(AsyncDataLink), removeUidFromResults(AsyncDataQuery)