org.jtrim2.concurrent.query

Class CachedByIDAsyncDataQuery<QueryArgType,DataType>

java.lang.Object

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

Type Parameters:

QueryArgType - the type of the input actually used to query the data. Note however, that this query uses CachedLinkRequest<DataWithUid<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<DataWithUid<QueryArgType>>,DataWithUid<DataType>>, CachedLinkContainer<Object>

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

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. This query will cache at most the specified number of AsyncDataLink instances concurrently.

This query is similar to the one created by the AsyncQueries.cacheLinks(AsyncQueries.cacheResults(wrappedQuery)) method invocation, except that this query 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 AsyncQueries.cacheLinks(AsyncQueries.cacheResults(wrappedQuery)) will actually store the input for the cached AsyncDataLink instances to be able to get data when it disappears from the cache.

Creating instances

It is not possible to directly instantiate this class, to create instances of this class use the AsyncQueries.cacheByID(AsyncDataQuery, ReferenceType, ObjectCache, 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.cacheByID(AsyncDataQuery, ReferenceType, ObjectCache), AsyncQueries.cacheByID(AsyncDataQuery, ReferenceType, ObjectCache, int)

Method Summary

Modifier and Type	Method and Description
Collection<Object>	clearCache() Removes every AsyncDataLink instances from the cache currently cached by this query.
AsyncDataLink<DataWithUid<DataType>>	createDataLink(CachedLinkRequest<DataWithUid<QueryArgType>> arg) Returns an AsyncDataLink which will provide data based on the specified input.
boolean	removeFromCache(Object 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<Object> 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<Object>

Returns:

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

removeFromCache

public boolean removeFromCache(Object 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<Object>

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<DataWithUid<DataType>> createDataLink(CachedLinkRequest<DataWithUid<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<DataWithUid<QueryArgType>>,DataWithUid<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.