K - type parameter indicating the type of the data load keysV - type parameter indicating the type of the data that is returnedpublic class DataLoader<K,V>
extends java.lang.Object
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.
| Constructor and Description |
|---|
DataLoader(BatchLoader<K,V> batchLoadFunction)
Creates a new data loader with the provided batch load function, and default options.
|
DataLoader(BatchLoader<K,V> batchLoadFunction,
DataLoaderOptions options)
Creates a new data loader with the provided batch load function and options.
|
| Modifier and Type | Method and Description |
|---|---|
DataLoader<K,V> |
clear(K key)
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> |
clearAll()
Clears the entire cache map of the loader.
|
java.util.concurrent.CompletableFuture<java.util.List<V>> |
dispatch()
Dispatches the queued load requests to the batch execution function and returns a promise of the result.
|
java.util.List<V> |
dispatchAndJoin()
Normally
dispatch() is an asynchronous operation but this version will 'join' on the
results if dispatch and wait for them to complete. |
int |
dispatchDepth() |
java.lang.Object |
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.
|
Statistics |
getStatistics()
Gets the statistics associated with this data loader.
|
java.util.concurrent.CompletableFuture<V> |
load(K key)
Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.
|
java.util.concurrent.CompletableFuture<V> |
load(K key,
java.lang.Object keyContext)
Requests to load the data with the specified key asynchronously, and returns a future of the resulting value.
|
java.util.concurrent.CompletableFuture<java.util.List<V>> |
loadMany(java.util.List<K> keys)
Requests to load the list of data provided by the specified keys asynchronously, and returns a composite future
of the resulting values.
|
java.util.concurrent.CompletableFuture<java.util.List<V>> |
loadMany(java.util.List<K> keys,
java.util.List<java.lang.Object> keyContexts)
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)
Creates new DataLoader with the specified batch loader function and default options
(batching, caching and unlimited batch size).
|
static <K,V> DataLoader<K,V> |
newDataLoader(BatchLoader<K,V> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function with the provided options
|
static <K,V> DataLoader<K,V> |
newDataLoader(BatchLoaderWithContext<K,V> batchLoadFunction)
Creates new DataLoader with the specified batch loader function and default options
(batching, caching and unlimited batch size).
|
static <K,V> DataLoader<K,V> |
newDataLoader(BatchLoaderWithContext<K,V> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function with the provided options
|
static <K,V> DataLoader<K,V> |
newDataLoaderWithTry(BatchLoader<K,Try<V>> batchLoadFunction)
Creates 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 of
Try objects. |
static <K,V> DataLoader<K,V> |
newDataLoaderWithTry(BatchLoader<K,Try<V>> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function and with the provided options
where the batch loader function returns a list of
Try objects. |
static <K,V> DataLoader<K,V> |
newDataLoaderWithTry(BatchLoaderWithContext<K,Try<V>> batchLoadFunction)
Creates 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 of
Try objects. |
static <K,V> DataLoader<K,V> |
newDataLoaderWithTry(BatchLoaderWithContext<K,Try<V>> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function and with the provided options
where the batch loader function returns a list of
Try objects. |
static <K,V> DataLoader<K,V> |
newMappedDataLoader(MappedBatchLoader<K,V> batchLoadFunction)
Creates new DataLoader with the specified batch loader function and default options
(batching, caching and unlimited batch size).
|
static <K,V> DataLoader<K,V> |
newMappedDataLoader(MappedBatchLoader<K,V> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function with the provided options
|
static <K,V> DataLoader<K,V> |
newMappedDataLoader(MappedBatchLoaderWithContext<K,V> batchLoadFunction)
Creates new DataLoader with the specified mapped batch loader function and default options
(batching, caching and unlimited batch size).
|
static <K,V> DataLoader<K,V> |
newMappedDataLoader(MappedBatchLoaderWithContext<K,V> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function with the provided options
|
static <K,V> DataLoader<K,V> |
newMappedDataLoaderWithTry(MappedBatchLoader<K,Try<V>> batchLoadFunction)
Creates 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 of
Try objects. |
static <K,V> DataLoader<K,V> |
newMappedDataLoaderWithTry(MappedBatchLoader<K,Try<V>> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function and with the provided options
where the batch loader function returns a list of
Try objects. |
static <K,V> DataLoader<K,V> |
newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K,Try<V>> batchLoadFunction)
Creates 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 of
Try objects. |
static <K,V> DataLoader<K,V> |
newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K,Try<V>> batchLoadFunction,
DataLoaderOptions options)
Creates new DataLoader with the specified batch loader function and with the provided options
where the batch loader function returns a list of
Try objects. |
DataLoader<K,V> |
prime(K key,
java.lang.Exception error)
Primes the cache with the given key and error.
|
DataLoader<K,V> |
prime(K key,
V value)
Primes the cache with the given key and value.
|
public DataLoader(BatchLoader<K,V> batchLoadFunction)
batchLoadFunction - the batch load function to usepublic DataLoader(BatchLoader<K,V> batchLoadFunction, DataLoaderOptions options)
batchLoadFunction - the batch load function to useoptions - the batch load optionspublic static <K,V> DataLoader<K,V> newDataLoader(BatchLoader<K,V> batchLoadFunction)
K - the key typeV - the value typebatchLoadFunction - the batch load function to usepublic static <K,V> DataLoader<K,V> newDataLoader(BatchLoader<K,V> batchLoadFunction, DataLoaderOptions options)
K - the key typeV - the value typebatchLoadFunction - the batch load function to useoptions - the options to usepublic static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoader<K,Try<V>> batchLoadFunction)
Try 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. .
K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectspublic static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoader<K,Try<V>> batchLoadFunction, DataLoaderOptions options)
Try objects.K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectsoptions - the options to usenewDataLoaderWithTry(BatchLoader)public static <K,V> DataLoader<K,V> newDataLoader(BatchLoaderWithContext<K,V> batchLoadFunction)
K - the key typeV - the value typebatchLoadFunction - the batch load function to usepublic static <K,V> DataLoader<K,V> newDataLoader(BatchLoaderWithContext<K,V> batchLoadFunction, DataLoaderOptions options)
K - the key typeV - the value typebatchLoadFunction - the batch load function to useoptions - the options to usepublic static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoaderWithContext<K,Try<V>> batchLoadFunction)
Try 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. .
K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectspublic static <K,V> DataLoader<K,V> newDataLoaderWithTry(BatchLoaderWithContext<K,Try<V>> batchLoadFunction, DataLoaderOptions options)
Try objects.K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectsoptions - the options to usenewDataLoaderWithTry(BatchLoader)public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoader<K,V> batchLoadFunction)
K - the key typeV - the value typebatchLoadFunction - the batch load function to usepublic static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoader<K,V> batchLoadFunction, DataLoaderOptions options)
K - the key typeV - the value typebatchLoadFunction - the batch load function to useoptions - the options to usepublic static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoader<K,Try<V>> batchLoadFunction)
Try 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. .
K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectspublic static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoader<K,Try<V>> batchLoadFunction, DataLoaderOptions options)
Try objects.K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectsoptions - the options to usenewDataLoaderWithTry(BatchLoader)public static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoaderWithContext<K,V> batchLoadFunction)
K - the key typeV - the value typebatchLoadFunction - the batch load function to usepublic static <K,V> DataLoader<K,V> newMappedDataLoader(MappedBatchLoaderWithContext<K,V> batchLoadFunction, DataLoaderOptions options)
K - the key typeV - the value typebatchLoadFunction - the batch load function to useoptions - the options to usepublic static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K,Try<V>> batchLoadFunction)
Try 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. .
K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectspublic static <K,V> DataLoader<K,V> newMappedDataLoaderWithTry(MappedBatchLoaderWithContext<K,Try<V>> batchLoadFunction, DataLoaderOptions options)
Try objects.K - the key typeV - the value typebatchLoadFunction - the batch load function to use that uses Try objectsoptions - the options to usenewDataLoaderWithTry(BatchLoader)public java.util.concurrent.CompletableFuture<V> load(K key)
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).
key - the key to loadpublic java.util.concurrent.CompletableFuture<V> load(K key, java.lang.Object keyContext)
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 or
MappedBatchLoaderWithContext to help retrieve data.
key - the key to loadkeyContext - a context object that is specific to this keypublic java.util.concurrent.CompletableFuture<java.util.List<V>> loadMany(java.util.List<K> keys)
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).
keys - the list of keys to loadpublic java.util.concurrent.CompletableFuture<java.util.List<V>> loadMany(java.util.List<K> keys, java.util.List<java.lang.Object> keyContexts)
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 or
MappedBatchLoaderWithContext to help retrieve data.
keys - the list of keys to loadkeyContexts - the list of key calling context objectspublic java.util.concurrent.CompletableFuture<java.util.List<V>> dispatch()
If batching is disabled, or there are no queued requests, then a succeeded promise is returned.
public java.util.List<V> dispatchAndJoin()
dispatch() is an asynchronous operation but this version will 'join' on the
results if dispatch and wait for them to complete. If the CompletableFuture callbacks make more
calls to this data loader then the dispatchDepth() will be > 0 and this method will loop
around and wait for any other extra batch loads to occur.dispatchDepth() reached 0public int dispatchDepth()
public DataLoader<K,V> clear(K key)
key - the key to removepublic DataLoader<K,V> clearAll()
public DataLoader<K,V> prime(K key, V value)
key - the keyvalue - the valuepublic DataLoader<K,V> prime(K key, java.lang.Exception error)
key - the keyerror - the exception to prime instead of a valuepublic java.lang.Object getCacheKey(K key)
If no cache key function is present in DataLoaderOptions, then the returned value equals the input key.
key - the input keypublic Statistics getStatistics()
StatisticsCollector passed in via DataLoaderOptions.getStatisticsCollector()