org.jtrim2.concurrent.query

Class CachedAsyncDataQuery<QueryArgType,DataType>

java.lang.Object

org.jtrim2.concurrent.query.CachedAsyncDataQuery<QueryArgType,DataType>

Type Parameters:

QueryArgType - the type of the input actually used to query the data. Note however, that this query uses CachedLinkRequest<QueryArgType> as input.

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

All Implemented Interfaces:

AsyncDataQuery<CachedLinkRequest<QueryArgType>,DataType>, CachedLinkContainer<QueryArgType>

public final class CachedAsyncDataQuery<QueryArgType,DataType>
extends Object
implements AsyncDataQuery<CachedLinkRequest<QueryArgType>,DataType>, CachedLinkContainer<QueryArgType>

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

This query caches only at most a 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 it is possible to manually remove cached items from the returned AsyncDataQuery using its clearCache and removeFromCache methods.

Creating instances

It is not possible to directly instantiate this class, to create instances of this class use the AsyncQueries.cacheLinks(AsyncDataQuery, int) method.

Thread safety

This class is safe to be used by multiple threads concurrently.

Synchronization transparency

This class is not synchronization transparent but methods of this class return reasonably fast. That is, they can be executed by methods need to be responsive (e.g.: listeners, methods called on the AWT event dispatch thread).

See Also:

AsyncQueries.cacheLinks(AsyncDataQuery), AsyncQueries.cacheLinks(AsyncDataQuery, int)

Method Summary

Modifier and Type	Method and Description
Collection<QueryArgType>	clearCache() Removes every AsyncDataLink instances from the cache currently cached by this query.
AsyncDataLink<DataType>	createDataLink(CachedLinkRequest<QueryArgType> arg) Returns an AsyncDataLink which will provide data based on the specified input.
boolean	removeFromCache(QueryArgType arg) Removes a cached AsyncDataLink which was cached by the specified input.
String	toString() Returns the string representation of this AsyncDataQuery in no particular format.

Methods inherited from class java.lang.Object

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

Method Detail

clearCache

public Collection<QueryArgType> clearCache()

Removes every AsyncDataLink instances from the cache currently cached by this query. A subsequent retrieval request from the cache will fail to find any required AsyncDataLink, therefore causing the implementation to fallback to recreate the required AsyncDataLink instance.

Note that this method takes linear time in the number of cached AsyncDataLink instances.

Specified by:

clearCache in interface CachedLinkContainer<QueryArgType>

Returns:

the collection of inputs whose AsyncDataLink instances were cached before calling this method. This method never returns null.

removeFromCache

public boolean removeFromCache(QueryArgType arg)

Removes a cached AsyncDataLink which was cached by the specified input. A subsequent retrieval request from the cache requiring the AsyncDataLink associated with the specified input will fail, therefore causing the implementation to fallback to recreate the required AsyncDataLink instance.

Specified by:

removeFromCache in interface CachedLinkContainer<QueryArgType>

Parameters:

arg - the input for which the associated AsyncDataLink is to be removed from the cache. This argument can be null.

Returns:

true if an AsyncDataLink instance was cached for the specified input, false otherwise. If this method returns false, it did nothing because there was no AsyncDataLink associated with the given input in the cache.

createDataLink

public AsyncDataLink<DataType> createDataLink(CachedLinkRequest<QueryArgType> arg)

Returns an AsyncDataLink which will provide data based on the specified input. The returned AsyncDataLink may be retrieved from the cache rather than actually requesting it from the underlying AsyncDataLink.

Regardless if the requested AsyncDataLink was cached or not, this method returns immediately without blocking.

Specified by:

createDataLink in interface AsyncDataQuery<CachedLinkRequest<QueryArgType>,DataType>

Parameters:

arg - the input argument which is to be used to retrieve the data. This argument contains information about how the returned AsyncDataLink may be cached and the actual input which determines what data is to be retrieved by the returned AsyncDataLink. This argument cannot be null.

Returns:

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

Throws:

NullPointerException - thrown if the specified argument is null

toString

public String toString()

Returns the string representation of this AsyncDataQuery 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.