org.jtrim2.concurrent.query

Class CachedDataRequest<QueryArgType>

java.lang.Object

org.jtrim2.concurrent.query.CachedDataRequest<QueryArgType>

Type Parameters:

QueryArgType - the type of the actual input of the query for the data retrieval process. Note that this type is recommended to be immutable or effectively immutable.

public final class CachedDataRequest<QueryArgType>
extends Object

Defines a request for a data which should be cached if possible. The request is intended to passed to an AsyncDataQuery as an input.

Apart from the input of the query, the request contains the cache to be used to cache the requested data and a timeout value. The timeout value determines how much time must elapse until an abandoned data retrieval request (i.e.: when every data retrieval request was canceled) should actually stop the data retrieval process. It can be advantageous not to stop the data retrieval process immediately when every request was canceled if there is a chance, that the data can be requested soon.

Note: Two instances of CachedDataRequest are considered equal if, and only if their query arguments are equal. Other properties are ignored by the equals and the hashCode methods. The reason of this to allow the AsyncQueries.cacheLinks(AsyncQueries.cacheResults(wrappedQuery)) invocations to work as expected.

Thread safety

The methods of this class are safe to be accessed by multiple threads concurrently. Instances of this class are immutable except that its properties might be mutable objects (i.e.: the ObjectCache and possibly the QueryArg).

Synchronization transparency

The methods of this class are synchronization transparent.

See Also:

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

Constructor Summary

Constructors

Constructor and Description
CachedDataRequest(QueryArgType queryArg) Creates and initializes the CachedDataRequest with the given properties.
CachedDataRequest(QueryArgType queryArg, ReferenceType refType) Creates and initializes the CachedDataRequest with the given properties.
CachedDataRequest(QueryArgType queryArg, ReferenceType refType, ObjectCache objectCache) Creates and initializes the CachedDataRequest with the given properties.
CachedDataRequest(QueryArgType queryArg, ReferenceType refType, ObjectCache objectCache, long dataCancelTimeout, TimeUnit timeunit) Creates and initializes the CachedDataRequest with the given properties.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj) Checks if the specified object is a CachedDataRequest and has a query argument which equals to the query argument of this CachedDataRequest.
long	getDataCancelTimeout(TimeUnit timeunit) Returns the timeout value to wait before actually canceling abandoned data retrieval processes in the given time unit.
ObjectCache	getObjectCache() Returns the ObjectCache used to cache the data to be retrieved.
QueryArgType	getQueryArg() Returns the object used as the input of the query of the data.
ReferenceType	getRefType() Returns the ReferenceType to be used to reference the cached data using the ObjectCache property.
int	hashCode() Returns a hash code value compatible with the equals method, usable in hash tables.
String	toString() Returns the string representation of this CachedDataRequest in no particular format.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CachedDataRequest

public CachedDataRequest(QueryArgType queryArg)

Creates and initializes the CachedDataRequest with the given properties.

The ObjectCache used to cache data is ObjectCache.javaRefCache() and the reference type is ReferenceType.WeakRefType using this constructor.

The time in the given unit to wait before actually canceling abandoned requests is 5 seconds using this constructor.

Parameters:

queryArg - the object used as the input of the AsyncDataQuery to retrieve the requested data. This argument can be null if the query accepts null values as its input.

Throws:

NullPointerException - thrown if refType is null

CachedDataRequest

public CachedDataRequest(QueryArgType queryArg,
                         ReferenceType refType)

Creates and initializes the CachedDataRequest with the given properties.

The ObjectCache used to cache data is ObjectCache.javaRefCache() using this constructor.

The time in the given unit to wait before actually canceling abandoned requests is 5 seconds using this constructor.

Parameters:

queryArg - the object used as the input of the AsyncDataQuery to retrieve the requested data. This argument can be null if the query accepts null values as its input.

refType - the ReferenceType to be used to reference the cached data using the JavaRefObjectCache.INSTANCE cache. This argument cannot be null.

Throws:

NullPointerException - thrown if refType is null

CachedDataRequest

public CachedDataRequest(QueryArgType queryArg,
                         ReferenceType refType,
                         ObjectCache objectCache)

Creates and initializes the CachedDataRequest with the given properties.

The time in the given unit to wait before actually canceling abandoned requests is 5 seconds using this constructor.

Parameters:

queryArg - the object used as the input of the AsyncDataQuery to retrieve the requested data. This argument can be null if the query accepts null values as its input.

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

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

Throws:

NullPointerException - thrown if refType is null

CachedDataRequest

public CachedDataRequest(QueryArgType queryArg,
                         ReferenceType refType,
                         ObjectCache objectCache,
                         long dataCancelTimeout,
                         TimeUnit timeunit)

Creates and initializes the CachedDataRequest with the given properties.

Parameters:

queryArg - the object used as the input of the AsyncDataQuery to retrieve the requested data. This argument can be null if the query accepts null values as its input.

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

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

dataCancelTimeout - the time in the given unit to wait before actually canceling abandoned requests. Before this time elapses, it is possible to start requesting the data and continuing where the request was left off. This argument must be greater than or equal to zero. In case this argument is zero, the data requesting will be canceled as soon as the data is detected to be not required.

timeunit - the time unit of the dataCancelTimeout argument. This argument cannot be null.

Throws:

IllegalArgumentException - thrown if dataCancelTimeout < 0

NullPointerException - thrown if refType or timeunit is null

Method Detail

getDataCancelTimeout

public long getDataCancelTimeout(TimeUnit timeunit)

Returns the timeout value to wait before actually canceling abandoned data retrieval processes in the given time unit.

Before this time elapses, it is possible to start requesting the data and continuing where the request was left off. This is advantageous when there is a chance of an abandoned data may be requested again soon.

Parameters:

timeunit - the time unit in which the timeout value is to be returned. This argument cannot be null.

Returns:

the timeout value to wait before actually canceling abandoned data retrieval processes in the given time unit. This method always returns a value greater than or equal to zero.

Throws:

NullPointerException - thrown if the specified time unit is null

getObjectCache

public ObjectCache getObjectCache()

Returns the ObjectCache used to cache the data to be retrieved.

Returns:

the ObjectCache used to cache the data to be retrieved. This method never returns null.

getQueryArg

public QueryArgType getQueryArg()

Returns the object used as the input of the query of the data. That is, this is the only property which determines what data is to be retrieved. Other properties only define the behaviour of the cache.

Returns:

the object used as the input of the query of the data. This method may return null if null was passed in the constructor.

getRefType

public ReferenceType getRefType()

Returns the ReferenceType to be used to reference the cached data using the ObjectCache property. That is, this value is intended to be passed to the getReference method of the ObjectCache.

Returns:

the ReferenceType to be used to reference the cached data using the ObjectCache property. This method never returns null.

toString

public String toString()

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

hashCode

public int hashCode()

Returns a hash code value compatible with the equals method, usable in hash tables.

Overrides:

hashCode in class Object

Returns:

the hash code value of this object

equals

public boolean equals(Object obj)

Checks if the specified object is a CachedDataRequest and has a query argument which equals to the query argument of this CachedDataRequest. Other properties of CachedDataRequest are ignored for the comparison.

Overrides:

equals in class Object

Parameters:

obj - the object to which this CachedDataRequest is to be compared to. This argument can be null, in which case the return value is false.

Returns:

true if the specified object is a CachedDataRequest and has a query argument which equals to the query argument of this CachedDataRequest, false otherwise