Added class loader option to the project by ThomasWega · Pull Request #4159 · MorphiaOrg/morphia

ThomasWega · 2026-02-12T14:49:07Z

Found this issue out when creating a Paper (Minecraft) plugin. Minecraft plugins each have their own ClassLoader. This makes it impossible for me to map classes as the class loader morphia is using is just a different one.

There was a workaround in earlier version as I was able to find here
https://stackoverflow.com/a/63698526
Even a suggested feature here: #1394

If I'm not mistaken, that's no longer the case. This pretty recent issue on github was a similar thing, but it suggested to use Thread.currentThread().getContextClassLoader() which 2.5.2 does I think, however that just does not solve my issue as you can see from this screenshot.

The classloader is just different.

I've tried adding the option to input custom classloader in the project. Take this more as a draft than a finished thing. I'm looking for feedback and will make any change you request. There is also still one place that uses the old classloader which I've marked with FIXME. I'm quite honestly not sure if all places require to use the custom class loader.

I have tested this version on my server with my project and it seems to work completely fine. It fixed the previous issues where no classes could be mapped and when they were mapped manually they would not resolve when being taken from the database.

I also would've done this change for 3.0.0 but I just wasn't able to get it to work with my maven. It's using the maven 4 which is in preview and seems like my PC is having issues loading it even though I've upgraded.

I'm also available on the discord server as ThomasWega if you want to discuss anything there

evanchooly

Thanks for the PR and the detailed write-up — the motivation is solid. Environments like Minecraft Paper plugins (and OSGi, etc.) where the context classloader doesn't match the application classloader are a real pain point, and Morphia should support custom classloaders.

That said, I found several issues with the current implementation that would need to be addressed before this can be merged.

Critical Issues

1. `MorphiaConfigHelper` reflection bug — will crash at runtime

The change in MorphiaConfigHelper.getEntry():

.getDeclaredConstructor(morphiaConfig.getClass())
.newInstance(morphiaConfig);

morphiaConfig.getClass() returns the runtime class (e.g., ManualMorphiaConfig), but all the converters declare their constructor parameter as MorphiaConfig (the interface). So getDeclaredConstructor(ManualMorphiaConfig.class) will throw NoSuchMethodException. This should be getDeclaredConstructor(MorphiaConfig.class).

2. SmallRye config loading is broken

The converters (ClassNameConverter, DiscriminatorFunctionConverter, NamingStrategyConverter, etc.) are referenced via @WithConverter annotations and instantiated by SmallRye Config using no-arg constructors. This PR removes all no-arg constructors by adding a required MorphiaConfig parameter. SmallRye won't be able to instantiate them, which would break MorphiaConfig.load() entirely.

3. Circular dependency in config loading

MorphiaConfig.load(path, classLoader) needs to create a config, but the converters used during loading now require a MorphiaConfig instance that doesn't exist yet — chicken-and-egg problem.

4. `classLoader()` on the `MorphiaConfig` interface is incompatible with SmallRye

MorphiaConfig is a @ConfigMapping interface. Adding ClassLoader classLoader() without @WithDefault means SmallRye would try to map it from the config file, but ClassLoader isn't a serializable config value. This needs to be excluded from SmallRye mapping or handled differently.

Design Issues

5. `getClassLoader()` on public `Datastore` interface

This is added without @MorphiaInternal, making it part of the public API contract. This is an implementation detail that shouldn't be exposed publicly — users shouldn't need to call datastore.getClassLoader().

6. `DiscriminatorLookup` holds a full `Mapper` reference

This introduces a bidirectional dependency: Mapper → DiscriminatorLookup → Mapper. It would be cleaner to pass just the ClassLoader or a Supplier<ClassLoader> rather than the entire Mapper.

7. Incomplete implementation (the FIXME)

As you noted, Conversions.java still uses the old classloader:

// FIXME still old classloader!
return Thread.currentThread().getContextClassLoader().loadClass(className);

8. `ManualMorphiaConfig.classLoader()` default is evaluated lazily each call

return orDefault(classLoader, Thread.currentThread().getContextClassLoader());

Each call could return a different classloader depending on which thread calls it. The default should be captured once at construction time.

Suggested Approach

Rather than threading MorphiaConfig through SmallRye converters (which breaks config loading), consider setting the classloader on the config after loading and using it only at runtime — not during config parsing. The converters don't need a custom classloader during config load since Morphia's own classes are being resolved at that point. The custom classloader is primarily needed at runtime for discriminator lookup, entity scanning, reference resolution, and proxy creation.

ThomasWega · 2026-02-14T17:34:12Z

Hey. Thank you for the feedback, it's deeply appreciated. Before I start digging into it, is it okay that I'm doing this on the 2.5 branch, or will I need to do these changes on the master branch for it to get merged? As I was saying, I'm not able to get the master branch working properly on any of my PCs.

This reverts commit d0e18df.

ThomasWega · 2026-02-14T18:52:16Z

I have reverted the previous commit and went with a new approach. I think it's now much better and you'll like it more. Should not disrupt the other parts of the code that much. I will be looking into the Conversions class now. That one will probably need quite a lot of changes for it's usages, so that's why I want to do it in a separate commit

evanchooly · 2026-02-14T20:01:38Z

sounds good. those comments were claude's (i'm not that verbose) but i was working on my own response as well. i'll wait for the follow up changes, though. :)

ThomasWega · 2026-02-14T20:45:16Z

I suppose ready for review now. I've tried to keep it as clean and simple. Everything that's not super internal should be backwards compatible. Just added new methods with new parameters and kept the old ones.

All usages of Thread.currentThread().getContextClassLoader() have now been replaced, except if you are using the default (current) approach in which case it defaults to that.
Also converters use the contextClassLoader as it was said above those don't need custom class loader.

Let me know if there's anything more you need me to do :)

evanchooly

Overall, I like the direction. There have been a few "using the wrong classloader" bugs "recently." They're hard to suss out because they require operating in contexts I don't have access to (glassfish/wildfly apps, minecraft plugins, etc.) and this change would help close some of those gaps I think we've gotten lucky so far to have not run in to. There are some simplifications in the comments that I think might serve to shrink this PR down even further. if I get time before you get to them, i'll see about pushing a patch to this PR showing what i'm thinking. But if you beat me to it, I won't complain either. Thanks for all the work you've put in so far. This revision is definitely cleaner than the first one.

evanchooly · 2026-02-16T03:46:24Z

core/src/main/java/dev/morphia/aggregation/AggregationImpl.java

    }

-    private static class MappingCursor<R> implements MongoCursor<R> {
+    private class MappingCursor<R> implements MongoCursor<R> {


Turns out this class isn't even used. I'll delete it on the 2.5 branch, though, so don't worry about it just now.

evanchooly · 2026-02-16T03:51:26Z

core/src/main/java/dev/morphia/config/MorphiaConfig.java

+     * @param classLoader the classloader to use when loading resources from the classpath
+     * @return the loaded config
+     */
+    static MorphiaConfig load(ClassLoader classLoader) {


Adding new methods to an API in a patch release is verboten by semver. I'm trying to decide how much semver matters to me with the 2.5. On the one hand, semver is important. On the other hand, 3.0 is much slower in coming than I'd hoped (though I'm actually closer than I thought to what might be considered a beta or RC if I downscope a little and push things to a 3.1...) and adhering to such a rule seems a little counterproductive in that light. Maybe make a 2.6 out of all this and satisfy both? That gets close to too many active branches, though, so maybe mark 2.4 and 2.5 as "done" and any future fixes go in to 2.6 alone? Or maybe just 2.4 and 2.6 since I think 2.5 is mildly breaking because of the driver upgrade and some internal incompatibilities... Thoughts?

evanchooly · 2026-02-16T03:54:27Z

core/src/main/java/dev/morphia/config/MorphiaConfig.java

+     * @since 3.0
+     */
+    static MorphiaConfig load(String path, ClassLoader classLoader) {
+        List<ConfigSource> configSources = classPathSources(path, classLoader);


Same comment on semver here but one additional. I would add a classLoader(ClassLoader) method to MorphiaConfig (if we're ditching semver 👎🏻 or bumping to 2.6 👍🏻 ) and then pass this class loader to the config once it's constructed.) Something similar used to exist for MapperOptions but was there primarily for the play framework which effectively doesn't exist anymore (for most of us anyway...).

evanchooly · 2026-02-16T03:55:48Z

core/src/main/java/dev/morphia/mapping/codec/pojo/EntityModel.java

    private final PropertyModel idProperty;
    private final PropertyModel versionProperty;
    private final List<EntityListener<?>> listeners = new ArrayList<>();
+    private final ClassLoader classLoader;


Not sure that is strictly necessary. Or that I like it. EntityModels should be pretty agnostic about such state. When I can finally implement multi tenancy this gets much more important.

evanchooly · 2026-02-16T03:56:19Z

core/src/main/java/dev/morphia/mapping/codec/pojo/EntityModelBuilder.java

        return type;
    }

+    public Mapper mapper() {


a builder shouldn't need this reference. when the builder still exists, that context should have access to the mapper.

evanchooly · 2026-02-16T03:57:58Z

core/src/main/java/dev/morphia/mapping/codec/pojo/MorphiaCodec.java

            if (idProperty != null) {
                if (ObjectId.class.equals(idProperty.getType()) || String.class.equals(idProperty.getType())) {
-                    idProperty.setValue(entity, convert(new ObjectId(), idProperty.getType()));
+                    idProperty.setValue(entity, convert(new ObjectId(), idProperty.getType(), datastore.getClassLoader()));


same as above. Pretty sure I've removed getClassLoader() from Datastore once already. :)

evanchooly · 2026-02-16T04:09:37Z

core/src/main/java/dev/morphia/mapping/codec/ArrayFieldAccessor.java

            return newArray;
        }
-        return Conversions.convert(o, type);
+        return Conversions.convert(o, type, classLoader);


Maybe a clean approach would be to make Conversions.convert() not static and create an instance of it from the classloader configured on MorphiaConfig. then the convert method signature doesn't really change and the interesting parts of the API that are nominally available for non-Morphia usage stays smaller (a partial focus of 3.0 is paring down the API surface area. so many overloads....) Then we just pass in the Conversions instance (stored on the Datastore?) when we create these kinds of classes. It reduce the amount of classloader parameters being passed from class to class, i think.

evanchooly · 2026-02-16T04:12:59Z

core/src/main/java/dev/morphia/Datastore.java

    Mapper getMapper();

+    @MorphiaInternal
+    default ClassLoader getClassLoader() {


evanchooly · 2026-02-16T04:14:15Z

core/src/main/java/dev/morphia/DatastoreImpl.java

                .next();

-        refreshCodec.decode(new DocumentReader(id), DecoderContext.builder().checkedDiscriminator(true).build());
+        refreshCodec.decode(new DocumentReader(id, getClassLoader()), DecoderContext.builder().checkedDiscriminator(true).build());


this argument would be the Conversions instance field we'd add to the DatastoreImpl, e.g.

evanchooly · 2026-02-16T04:15:02Z

core/src/main/java/dev/morphia/Morphia.java

+     * @return a Datastore that you can use to interact with MongoDB
+     * @since 3.0.0
+     */
+    public static Datastore createDatastore(MongoClient mongoClient, MorphiaConfig config, ClassLoader classLoader) {


This wouldn't be necessary. We'd just use config.classLoader() inside DatastoreImpl to get what we need.

Added class loader option to the project

d0e18df

ThomasWega marked this pull request as draft February 12, 2026 14:54

evanchooly requested changes Feb 14, 2026

View reviewed changes

ThomasWega added 2 commits February 14, 2026 19:42

Revert "Added class loader option to the project"

388af9b

This reverts commit d0e18df.

Reworked class loader approach

75527d0

Conversions now use classloader as well and all it's usages.

93832c6

ThomasWega force-pushed the 2.5_classloader branch from c1adc84 to 93832c6 Compare February 14, 2026 20:39

removed unnecessary code created by me

7ebee8e

ThomasWega marked this pull request as ready for review February 14, 2026 20:45

evanchooly requested changes Feb 16, 2026

View reviewed changes

Conversation

ThomasWega commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evanchooly left a comment

Choose a reason for hiding this comment

Critical Issues

1. MorphiaConfigHelper reflection bug — will crash at runtime

2. SmallRye config loading is broken

3. Circular dependency in config loading

4. classLoader() on the MorphiaConfig interface is incompatible with SmallRye

Design Issues

5. getClassLoader() on public Datastore interface

6. DiscriminatorLookup holds a full Mapper reference

7. Incomplete implementation (the FIXME)

8. ManualMorphiaConfig.classLoader() default is evaluated lazily each call

Suggested Approach

Uh oh!

ThomasWega commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ThomasWega commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evanchooly commented Feb 14, 2026

Uh oh!

ThomasWega commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evanchooly left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ThomasWega commented Feb 12, 2026 •

edited

Loading

1. `MorphiaConfigHelper` reflection bug — will crash at runtime

4. `classLoader()` on the `MorphiaConfig` interface is incompatible with SmallRye

5. `getClassLoader()` on public `Datastore` interface

6. `DiscriminatorLookup` holds a full `Mapper` reference

8. `ManualMorphiaConfig.classLoader()` default is evaluated lazily each call

ThomasWega commented Feb 14, 2026 •

edited

Loading

ThomasWega commented Feb 14, 2026 •

edited

Loading

ThomasWega commented Feb 14, 2026 •

edited

Loading