Module jtrim.query
Package 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:

  • Method Details

    • 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:

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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: