Class DataLoader<K,V>
- Type Parameters:
K
- type parameter indicating the type of the data load keysV
- type parameter indicating the type of the data that is returned
CompletableFuture
is returned, that completes as the batch function completes.
With batching enabled the execution will start after calling dispatch()
, causing the queue of
loaded keys to be sent to the batch function, clears the queue, and returns a promise to the values.
As BatchLoader
batch functions are executed the resulting futures are cached using a cache
implementation of choice, so they will only execute once. Individual cache keys can be cleared, so they will
be re-fetched when referred to again.
It is also possible to clear the cache entirely, and prime it with values before they are used.
Both caching and batching can be disabled. Configuration of the data loader is done by providing a
DataLoaderOptions
instance on creation.
A call to the batch loader might result in individual exception failures for item with the returned list. if
you want to capture these specific item failures then use Try
as a return value and
create the data loader with newDataLoaderWithTry(BatchLoader)
form. The Try values will be interpreted
as either success values or cause the load(Object)
promise to complete exceptionally.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final DataLoaderHelper
<K, V> private final StatisticsCollector
private final ValueCache
<K, V> -
Constructor Summary
ConstructorsConstructorDescriptionDataLoader
(Object batchLoadFunction, DataLoaderOptions options) DataLoader
(Object batchLoadFunction, DataLoaderOptions options, Clock clock) DataLoader
(BatchLoader<K, V> batchLoadFunction) Deprecated.DataLoader
(BatchLoader<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
instead -
Method Summary
Modifier and TypeMethodDescriptionDataLoader
<K, V> Clears the future with the specified key from the cache, if caching is enabled, so it will be re-fetched on the next load request.DataLoader
<K, V> clear
(K key, BiConsumer<Void, Throwable> handler) Clears the future with the specified key from the cache remote value store, if caching is enabled and a remote store is set, so it will be re-fetched and stored on the next load request.DataLoader
<K, V> clearAll()
Clears the entire cache map of the loader.DataLoader
<K, V> clearAll
(BiConsumer<Void, Throwable> handler) Clears the entire cache map of the loader, and of the cached value store.determineFutureCache
(DataLoaderOptions loaderOptions) private ValueCache
<K, V> determineValueCache
(DataLoaderOptions loaderOptions) dispatch()
Dispatches the queued load requests to the batch execution function and returns a promise of the result.Normallydispatch()
is an asynchronous operation but this version will 'join' on the results if dispatch and wait for them to complete.int
Dispatches the queued load requests to the batch execution function and returns both the promise of the result and the number of entries that were dispatched.getCacheKey
(K key) Gets the object that is used in the internal cache map as key, by applying the cache key function to the provided key.Gets the cacheMap associated with this data loader passed in viaDataLoaderOptions.cacheMap()
getIfCompleted
(K key) This will return an optional promise to a value previously loaded via aload(Object)
call that has in fact been completed or empty if no call has been made for that key or the promise has not completed yet.getIfPresent
(K key) This will return an optional promise to a value previously loaded via aload(Object)
call or empty if not call has been made for that key.This returns the last instant the data loader was dispatched.Gets the statistics associated with this data loader.This returns theDuration
since the data loader was dispatched.ValueCache
<K, V> Gets the valueCache associated with this data loader passed in viaDataLoaderOptions.valueCache()
Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.Requests to load the list of data provided by the specified keys asynchronously, and returns a composite future of the resulting values.Requests to load the list of data provided by the specified keys asynchronously, and returns a composite future of the resulting values.static <K,
V> DataLoader <K, V> newDataLoader
(BatchLoader<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoader
(BatchLoader<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoader
(BatchLoaderWithContext<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoader
(BatchLoaderWithContext<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoaderWithTry
(BatchLoader<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoaderWithTry
(BatchLoader<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoaderWithTry
(BatchLoaderWithContext<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newDataLoaderWithTry
(BatchLoaderWithContext<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoader
(MappedBatchLoader<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoader
(MappedBatchLoader<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoader
(MappedBatchLoaderWithContext<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoader
(MappedBatchLoaderWithContext<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoaderWithTry
(MappedBatchLoader<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoaderWithTry
(MappedBatchLoader<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoaderWithTry
(MappedBatchLoaderWithContext<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadstatic <K,
V> DataLoader <K, V> newMappedDataLoaderWithTry
(MappedBatchLoaderWithContext<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadDataLoader
<K, V> Primes the cache with the given key and error.DataLoader
<K, V> prime
(K key, CompletableFuture<V> value) Primes the cache with the given key and value.DataLoader
<K, V> Primes the cache with the given key and value.
-
Field Details
-
helper
-
stats
-
futureCache
-
valueCache
-
-
Constructor Details
-
DataLoader
Deprecated.useDataLoaderFactory
insteadCreates a new data loader with the provided batch load function, and default options.- Parameters:
batchLoadFunction
- the batch load function to use
-
DataLoader
Deprecated.useDataLoaderFactory
insteadCreates a new data loader with the provided batch load function and options.- Parameters:
batchLoadFunction
- the batch load function to useoptions
- the batch load options
-
DataLoader
DataLoader(Object batchLoadFunction, DataLoaderOptions options) -
DataLoader
DataLoader(Object batchLoadFunction, DataLoaderOptions options, Clock clock)
-
-
Method Details
-
newDataLoader
Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size).- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use- Returns:
- a new DataLoader
-
newDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newDataLoader(BatchLoader<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function with the provided options- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to useoptions
- the options to use- Returns:
- a new DataLoader
-
newDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoader<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size) where the batch loader function returns a list ofTry
objects.If its important you to know the exact status of each item in a batch call and whether it threw exceptions then you can use this form to create the data loader.
Using Try objects allows you to capture a value returned or an exception that might have occurred trying to get a value. .
- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objects- Returns:
- a new DataLoader
-
newDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoader<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and with the provided options where the batch loader function returns a list ofTry
objects.- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objectsoptions
- the options to use- Returns:
- a new DataLoader
- See Also:
-
newDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newDataLoader(BatchLoaderWithContext<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size).- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use- Returns:
- a new DataLoader
-
newDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newDataLoader(BatchLoaderWithContext<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function with the provided options- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to useoptions
- the options to use- Returns:
- a new DataLoader
-
newDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoaderWithContext<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size) where the batch loader function returns a list ofTry
objects.If its important you to know the exact status of each item in a batch call and whether it threw exceptions then you can use this form to create the data loader.
Using Try objects allows you to capture a value returned or an exception that might have occurred trying to get a value. .
- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objects- Returns:
- a new DataLoader
-
newDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoaderWithContext<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and with the provided options where the batch loader function returns a list ofTry
objects.- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objectsoptions
- the options to use- Returns:
- a new DataLoader
- See Also:
-
newMappedDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoader<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size).- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use- Returns:
- a new DataLoader
-
newMappedDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoader<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function with the provided options- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to useoptions
- the options to use- Returns:
- a new DataLoader
-
newMappedDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoader<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size) where the batch loader function returns a list ofTry
objects.If its important you to know the exact status of each item in a batch call and whether it threw exceptions then you can use this form to create the data loader.
Using Try objects allows you to capture a value returned or an exception that might have occurred trying to get a value. .
- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objects- Returns:
- a new DataLoader
-
newMappedDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoader<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and with the provided options where the batch loader function returns a list ofTry
objects.- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objectsoptions
- the options to use- Returns:
- a new DataLoader
- See Also:
-
newMappedDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoaderWithContext<K, V> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified mapped batch loader function and default options (batching, caching and unlimited batch size).- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use- Returns:
- a new DataLoader
-
newMappedDataLoader
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoaderWithContext<K, V> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function with the provided options- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to useoptions
- the options to use- Returns:
- a new DataLoader
-
newMappedDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K, Try<V>> batchLoadFunction) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and default options (batching, caching and unlimited batch size) where the batch loader function returns a list ofTry
objects.If its important you to know the exact status of each item in a batch call and whether it threw exceptions then you can use this form to create the data loader.
Using Try objects allows you to capture a value returned or an exception that might have occurred trying to get a value. .
- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objects- Returns:
- a new DataLoader
-
newMappedDataLoaderWithTry
@Deprecated public static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K, Try<V>> batchLoadFunction, DataLoaderOptions options) Deprecated.useDataLoaderFactory
insteadCreates new DataLoader with the specified batch loader function and with the provided options where the batch loader function returns a list ofTry
objects.- Type Parameters:
K
- the key typeV
- the value type- Parameters:
batchLoadFunction
- the batch load function to use that usesTry
objectsoptions
- the options to use- Returns:
- a new DataLoader
- See Also:
-
determineFutureCache
-
determineValueCache
-
getLastDispatchTime
This returns the last instant the data loader was dispatched. When the data loader is created this value is set to now.- Returns:
- the instant since the last dispatch
-
getTimeSinceDispatch
This returns theDuration
since the data loader was dispatched. When the data loader is created this is zero.- Returns:
- the time duration since the last dispatch
-
load
Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.If batching is enabled (the default), you'll have to call
dispatch()
at a later stage to start batch execution. If you forget this call the future will never be completed (unless already completed, and returned from cache).- Parameters:
key
- the key to load- Returns:
- the future of the value
-
getIfPresent
This will return an optional promise to a value previously loaded via aload(Object)
call or empty if not call has been made for that key.If you do get a present CompletableFuture it does not mean it has been dispatched and completed yet. It just means its at least pending and in cache.
If caching is disabled there will never be a present Optional returned.
NOTE : This will NOT cause a data load to happen. You must called
load(Object)
for that to happen.- Parameters:
key
- the key to check- Returns:
- an Optional to the future of the value
-
getIfCompleted
This will return an optional promise to a value previously loaded via aload(Object)
call that has in fact been completed or empty if no call has been made for that key or the promise has not completed yet.If you do get a present CompletableFuture it means it has been dispatched and completed. Completed is defined as
CompletableFuture.isDone()
returning true.If caching is disabled there will never be a present Optional returned.
NOTE : This will NOT cause a data load to happen. You must called
load(Object)
for that to happen.- Parameters:
key
- the key to check- Returns:
- an Optional to the future of the value
-
load
Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.If batching is enabled (the default), you'll have to call
dispatch()
at a later stage to start batch execution. If you forget this call the future will never be completed (unless already completed, and returned from cache).The key context object may be useful in the batch loader interfaces such as
BatchLoaderWithContext
orMappedBatchLoaderWithContext
to help retrieve data.- Parameters:
key
- the key to loadkeyContext
- a context object that is specific to this key- Returns:
- the future of the value
-
loadMany
Requests to load the list of data provided by the specified keys asynchronously, and returns a composite future of the resulting values.If batching is enabled (the default), you'll have to call
dispatch()
at a later stage to start batch execution. If you forget this call the future will never be completed (unless already completed, and returned from cache).- Parameters:
keys
- the list of keys to load- Returns:
- the composite future of the list of values
-
loadMany
Requests to load the list of data provided by the specified keys asynchronously, and returns a composite future of the resulting values.If batching is enabled (the default), you'll have to call
dispatch()
at a later stage to start batch execution. If you forget this call the future will never be completed (unless already completed, and returned from cache).The key context object may be useful in the batch loader interfaces such as
BatchLoaderWithContext
orMappedBatchLoaderWithContext
to help retrieve data.- Parameters:
keys
- the list of keys to loadkeyContexts
- the list of key calling context objects- Returns:
- the composite future of the list of values
-
dispatch
Dispatches the queued load requests to the batch execution function and returns a promise of the result.If batching is disabled, or there are no queued requests, then a succeeded promise is returned.
- Returns:
- the promise of the queued load requests
-
dispatchWithCounts
Dispatches the queued load requests to the batch execution function and returns both the promise of the result and the number of entries that were dispatched.If batching is disabled, or there are no queued requests, then a succeeded promise with no entries dispatched is returned.
- Returns:
- the promise of the queued load requests and the number of keys dispatched.
-
dispatchAndJoin
Normallydispatch()
is an asynchronous operation but this version will 'join' on the results if dispatch and wait for them to complete. If theCompletableFuture
callbacks make more calls to this data loader then thedispatchDepth()
will be > 0 and this method will loop around and wait for any other extra batch loads to occur.- Returns:
- the list of all results when the
dispatchDepth()
reached 0
-
dispatchDepth
public int dispatchDepth()- Returns:
- the depth of the batched key loads that need to be dispatched
-
clear
Clears the future with the specified key from the cache, if caching is enabled, so it will be re-fetched on the next load request.- Parameters:
key
- the key to remove- Returns:
- the data loader for fluent coding
-
clear
Clears the future with the specified key from the cache remote value store, if caching is enabled and a remote store is set, so it will be re-fetched and stored on the next load request.- Parameters:
key
- the key to removehandler
- a handler that will be called after the async remote clear completes- Returns:
- the data loader for fluent coding
-
clearAll
Clears the entire cache map of the loader.- Returns:
- the data loader for fluent coding
-
clearAll
Clears the entire cache map of the loader, and of the cached value store.- Parameters:
handler
- a handler that will be called after the async remote clear all completes- Returns:
- the data loader for fluent coding
-
prime
Primes the cache with the given key and value. Note this will only prime the future cache and not the value store. UseValueCache.set(Object, Object)
if you want to prime it with values before use- Parameters:
key
- the keyvalue
- the value- Returns:
- the data loader for fluent coding
-
prime
Primes the cache with the given key and error.- Parameters:
key
- the keyerror
- the exception to prime instead of a value- Returns:
- the data loader for fluent coding
-
prime
Primes the cache with the given key and value. Note this will only prime the future cache and not the value store. UseValueCache.set(Object, Object)
if you want to prime it with values before use- Parameters:
key
- the keyvalue
- the value- Returns:
- the data loader for fluent coding
-
getCacheKey
Gets the object that is used in the internal cache map as key, by applying the cache key function to the provided key.If no cache key function is present in
DataLoaderOptions
, then the returned value equals the input key.- Parameters:
key
- the input key- Returns:
- the cache key after the input is transformed with the cache key function
-
getStatistics
Gets the statistics associated with this data loader. These will have been gather via theStatisticsCollector
passed in viaDataLoaderOptions.getStatisticsCollector()
- Returns:
- statistics for this data loader
-
getCacheMap
Gets the cacheMap associated with this data loader passed in viaDataLoaderOptions.cacheMap()
- Returns:
- the cacheMap of this data loader
-
getValueCache
Gets the valueCache associated with this data loader passed in viaDataLoaderOptions.valueCache()
- Returns:
- the valueCache of this data loader
-
DataLoaderFactory
instead