Release notes from java-dataloader

6.0.0

2025-11-05T23:34:03Z

This is a breaking change release version of the Java DataLoader

The main breaking change is in org.dataloader.CacheMap and specifically the org.dataloader.CacheMap#putIfAbsentAtomically method.

Previous versions of dataloader used synchronised locks to guard the data structures during a dispatch call.

However to provide even higher performance the code has been changed to use a Compare And Swap (CAS) mechanism instead.

This means that there is a new contract on the org.dataloader.CacheMap implementations that they must be atomically thread safe in their writing and reading of cache entries.

The default implementation uses a java.util.concurrent.ConcurrentHashMap to provide this but if you have your own implementations then you need to update them to be atomically thread safe when putting cache entries.

If you don't use your own org.dataloader.CacheMap implementation then this will not be a breaking change version for you since there are no other breaking changes.

What's Changed

Bump com.gradle.develocity from 4.1.1 to 4.2 by @dependabot[bot] in #233
Bump org.jetbrains.kotlin.jvm from 2.2.10 to 2.2.20 by @dependabot[bot] in #230
Bump com.uber.nullaway:nullaway from 0.12.9 to 0.12.10 by @dependabot[bot] in #231
Bump com.github.ben-manes.versions from 0.52.0 to 0.53.0 by @dependabot[bot] in #234
Bump gradle/actions from 4 to 5 by @dependabot[bot] in #236
Bump com.gradle.develocity from 4.2 to 4.2.1 by @dependabot[bot] in #235
Bump com.gradle.develocity from 4.2.1 to 4.2.2 by @dependabot[bot] in #237
Updating the code to use reentrant locks by @bbakerman in #239
remove any Reentrant locks in favor of a CAS linked list by @andimarek in #241
fix master build by @andimarek in #242
Added a loadImpl function to allow delegate overriding better by @bbakerman in #240
Bump org.jetbrains.kotlin.jvm from 2.2.20 to 2.2.21 by @dependabot[bot] in #247
Bump io.github.reyerizo.gradle.jcstress from 0.8.15 to 0.9.0 by @dependabot[bot] in #246
Bump com.google.errorprone:error_prone_core from 2.42.0 to 2.43.0 by @dependabot[bot] in #245
Updated the documentation of the CacheMap and also some refactoring by @bbakerman in #244

Full Changelog: v5.0.3...v6.0.0

5.0.3

2025-09-23T00:36:07Z

This is a small bug fix release to remove Kotlin stdlib as a dependency of java-dataloader

Kotlin as added as a test dependency to help ensure the JSpecify annotations work as expected in Kotlin land.

However even thought we specified testImplementation in gradle, the Kotlin gradle plugin auto added Kotlin stdlib as a pom dependency on publish

#229 fixes this and this release is to publish a new version with the Kotlin stdlib in the pom

What's Changed

Bump com.google.errorprone:error_prone_core from 2.40.0 to 2.41.0 by @dependabot[bot] in #218
update workflows to use 21 and update toolchain plugin by @andimarek in #216
Bump com.uber.nullaway:nullaway from 0.12.7 to 0.12.8 by @dependabot[bot] in #219
Bump org.jetbrains.kotlin.jvm from 2.2.0 to 2.2.10 by @dependabot[bot] in #221
Bump actions/checkout from 4 to 5 by @dependabot[bot] in #220
Bump actions/setup-java from 4 to 5 by @dependabot[bot] in #224
Bump com.uber.nullaway:nullaway from 0.12.8 to 0.12.9 by @dependabot[bot] in #225
Bump com.gradle.develocity from 4.1 to 4.1.1 by @dependabot[bot] in #226
Bump actions/stale from 9 to 10 by @dependabot[bot] in #228
Kotlin stdlib should not be a pom dep by @bbakerman in #229
Bump com.google.errorprone:error_prone_core from 2.41.0 to 2.42.0 by @dependabot[bot] in #232

Full Changelog: v5.0.2...v5.0.3

5.0.2

2025-07-27T08:20:31Z

A small bugfix release that includes a nullability annotation fix for Value Cache

What's Changed

Bump com.google.errorprone:error_prone_core from 2.37.0 to 2.39.0 by @dependabot[bot] in #213
Bump net.ltgt.errorprone from 4.2.0 to 4.3.0 by @dependabot[bot] in #212
Bump com.google.errorprone:error_prone_core from 2.39.0 to 2.40.0 by @dependabot[bot] in #214
Bump com.gradle.develocity from 4.0.2 to 4.1 by @dependabot[bot] in #215
Allow value nullability for ValueCache by @pdambrauskas in #217

New Contributors

@pdambrauskas made their first contribution in #217

Full Changelog: v5.0.1...v5.0.2

5.0.1

2025-07-06T08:53:25Z

This release updates the JSpecify nullable annotations on the BatchLoader method variants so that they work as expected with Kotlin 2 and its stronger enforcement of JSpecify annotations

eg they are now updated like this.

public interface BatchLoader<K, V extends @Nullable Object>

What's Changed

Error Prone / NullAway support for JSpecify by @bbakerman in #196
Move to new Sonatype URLs by @bbakerman in #198
Update Gradle Github action by @dondonz in #199
Add dependabot by @dondonz in #200
Bump com.uber.nullaway:nullaway from 0.12.6 to 0.12.7 by @dependabot in #203
Bump com.gradle.develocity from 3.19 to 4.0.2 by @dependabot in #201
Bump org.jetbrains.kotlin.jvm from 2.1.21 to 2.2.0 by @dependabot in #209
Bump com.github.ben-manes.versions from 0.51.0 to 0.52.0 by @dependabot in #202
More explicit nullable annotations on BatchLoader interfaces by @bbakerman in #207
Bump io.github.gradle-nexus.publish-plugin from 1.0.0 to 2.0.0 by @dependabot in #204
#208 to ensure tests are in place by @bbakerman in #211

New Contributors

@dependabot made their first contribution in #203

Full Changelog: v5.0.0...v5.0.1

5.0.0

2025-05-13T02:00:21Z

Compile time breaking of DataLoaderOptions

Back in version 4.0.0 we introduced immutability into the DataLoaderOptions class, which was a good thing.

However it left the old mutative set methods in place and made them immutable. This was a mistake. This leads to bugs at runtime

for example

DataLoaderOptions options = DataLoaderOptions.newOptions();
if (maxBatchSize != BatchLoader.UNSET_BATCH_SIZE) {
  options.setMaxBatchSize(maxBatchSize);
}
return options.setCacheMap(cache);

The above code would continue compile but the setMaxBatchSize would never take affected with the immutable support.

So to help address #190 version 5.0.0 has removed the set methods and require the Builder methods to be used to ensure that code that relied on the old mutative methods now break at compile time and not at runtime.

DataLoaders now can have names

A DataLoader can now have a name. Its nullable so that old code can still work but its preferred that DataLoaders are named. This will help in debugging and also in instrumentation.

If you register a DataLoader into a DataLoaderRegistry then the names must match otherwise it will be rejected at registration time.

A series of long standing deprecated DataLoaderFactory methods got removed here as well.

What's Changed

Remove jcenter reference after sunset by @dondonz in #184
add jmh testing with one initial performance test by @andimarek in #187
adds explicit jmh dependency for the idea jmh plugin by @andimarek in #192
OSGI - Make org.jspecify.* imports optional by @schulm in #194
Breaking change - adds a name to a DataLoader by @bbakerman in #193
Breaking change: using LongAdder instead of AtomicLong by @dfa1 in #186
Breaking change - renaming old mutable setXX methods by @bbakerman in #191

New Contributors

@schulm made their first contribution in #194

Full Changelog: v4.0.0...v5.0.0

4.0.0

2025-04-07T01:32:54Z

Instrumentation support of DataLoaders

A new org.dataloader.instrumentation.DataLoaderInstrumentation has been added that is a callback to allow you to know when certain DataLoader actions start and when they finish.

        DataLoaderInstrumentation timingInstrumentation = new DataLoaderInstrumentation() {
            @Override
            public DataLoaderInstrumentationContext<DispatchResult<?>> beginDispatch(DataLoader<?, ?> dataLoader) {
                long then = System.currentTimeMillis();
                return DataLoaderInstrumentationHelper.whenCompleted((result, err) -> {
                    long ms = System.currentTimeMillis() - then;
                    System.out.println(format("dispatch time: %d ms", ms));
                });
            }

            @Override
            public DataLoaderInstrumentationContext<List<?>> beginBatchLoader(DataLoader<?, ?> dataLoader, List<?> keys, BatchLoaderEnvironment environment) {
                long then = System.currentTimeMillis();
                return DataLoaderInstrumentationHelper.whenCompleted((result, err) -> {
                    long ms = System.currentTimeMillis() - then;
                    System.out.println(format("batch loader time: %d ms", ms));
                });
            }
        };
        DataLoaderOptions options = DataLoaderOptions.newOptions().setInstrumentation(timingInstrumentation);
        DataLoader<String, User> userDataLoader = DataLoaderFactory.newDataLoader(userBatchLoader, options);

Immutable classes

Some of the key classes like org.dataloader.DataLoaderOptions have been made immutable so as to provide more surety in how they get used and transformed. This is technically a breaking change if you code relied on the old mutability, however on balance we think this is a better code position to be in.

What's Changed

Update version to 3.4.0 by @dondonz in #168
Add stale bot by @dondonz in #169
Removing unused slf4j references by @dondonz in #170
Parameterise more tests across DataLoader implementations by @AlexandreCarlton in #171
Allow ValueCache to work with Publisher DataLoader by @AlexandreCarlton in #172
Transform support for DataLoaders by @bbakerman in #174
Making DataLoaderOptions immutable by @bbakerman in #176
Instrumentation support for dataloader by @bbakerman in #175
add jspecify by @andimarek in #180
Fixed a bug that the Spring team found by @bbakerman in #181
Added a instrumentation of load calls by @bbakerman in #178
Added support for a delegating data loader by @bbakerman in #182
Update documentation for new release by @dondonz in #183

New Contributors

@andimarek made their first contribution in #180

Full Changelog: v3.4.0...v4.0.0

v3.4.0

2024-12-23T02:25:17Z

Thanks to everybody who contributed to this release of Dataloader!

With this release, this library changed from using Java 8 to Java 11.

What's Changed

Remove CacheMap#containsKey before #get by @AlexandreCarlton in #146
Verify a throwing CacheMap#get does not break DataLoader by @AlexandreCarlton in #147
Bump to Java 11 by @AlexandreCarlton in #150
Bump JUnit 4.x to JUnit Jupiter 5 by @AlexandreCarlton in #152
Add a proof-of-concept for "Observer-like" batch loading by @AlexandreCarlton in #148
Parameterise DataLoaderTest on DataLoader by @AlexandreCarlton in #153
Migrate publisher tests by @AlexandreCarlton in #155
Making the Subscribers use a common base class by @bbakerman in #154
Make builds run on other branches by @bbakerman in #157
More tests for Publishers on reactive branch by @bbakerman in #158
Reactive streams branch move reactive classes out of dataloader helper by @bbakerman in #159
Have MappedBatchPublisher take in a Set keys (and add README sections) by @AlexandreCarlton in #160
A PR for reactive streams support by @bbakerman in #151
Tweaked readme by @bbakerman in #161
Update version in readme by @dondonz in #165
Add support for batch loading of a Map of key-value pairs. by @Hc747 in #166
Modernise/update Gradle configuration and misc. polishing. by @Hc747 in #167

New Contributors

@Hc747 made their first contribution in #166

Full Changelog: v3.3.0...v3.4.0

3.3.0

2024-04-14T22:31:43Z

What's Changed

Pre-size resulting lists by @dfa1 in #142
Minor javadoc fixes by @dfa1 in #141
Shuts down executor if its was auto added by our code by @bbakerman in #144
If there is a specific predicate for a dataloader - its is the final say on whether to dispatch by @bbakerman in #145

Full Changelog: v3.2.2...v3.3.0

3.2.2

2023-11-14T04:47:04Z

What's Changed

A series of small fixes to make the code more efficient

Lazily initialize Executor in ScheduledDataLoaderRegistry builder by @kilink in #135
Avoid allocations in DataLoaderHelper.dispatch when there's no work by @kilink in #136

New Contributors

@kilink made their first contribution in #135

Full Changelog: v3.2.1...v3.2.2

3.2.1

2023-10-17T04:44:03Z

New ticker mode

There is a new mode in ScheduledDataLoaderRegistry called ticker mode that will continue to tick away and allow for chained data loader calls. See the readme for more details.

  ScheduledDataLoaderRegistry registry = ScheduledDataLoaderRegistry.newScheduledRegistry()
        .register("a", dataLoaderA)
        .register("b", dataLoaderB)
        .scheduledExecutorService(executorService)
        .schedule(Duration.ofMillis(10))
        .tickerMode(true) // ticker mode is on
        .build();

  CompletableFuture<Object> chainedCalls = dataLoaderA.load("user1")
        .thenCompose(userAsKey -> dataLoaderB.load(userAsKey));

Predicates per dataloader in ScheduledDataLoaderRegistry

ScheduledDataLoaderRegistry now has the capability to have a predicate per data loader specified as well as an overall one. This allows you to have fine control on when dataloaders get dispatched.

What's Changed

Try.getThrowable - fixed incorrect exception message by @rstata in #122
Prepend 0.0.0 to build version by @dondonz in #126
Batch scheduler function support by @bbakerman in #128
Adds a predicate to DataLoaderRegistry and a per dataloader map of pedicates is also possible by @bbakerman in #133
Ticker mode on ScheduledDataLoaderRegistry by @bbakerman in #131

New Contributors

@rstata made their first contribution in #122
@dondonz made their first contribution in #126

Full Changelog: v3.2.0...v3.2.1