From 86244f08d8c4450791c6c9ed1e4df7dff691efc0 Mon Sep 17 00:00:00 2001 From: evanchooly Date: Mon, 5 Oct 2026 10:16:01 -0400 Subject: [PATCH] Document critter runtime generation's class loader/module requirement Runtime generation can't access entities outside Morphia's module or class loader; recommend critter-maven for app-server, shared-lib and JPMS layouts. Refs MorphiaOrg/morphia#4357 --- content/morphia/3.0/configuration.md | 1 + content/morphia/3.0/maven-plugin.md | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/content/morphia/3.0/configuration.md b/content/morphia/3.0/configuration.md index 33522eb..d4b75c9 100644 --- a/content/morphia/3.0/configuration.md +++ b/content/morphia/3.0/configuration.md @@ -91,6 +91,7 @@ morphia.mapper=critter Or pass `-Dmorphia.mapper=critter` on the Maven command line when running tests. For production deployments, consider using the [critter-maven plugin](../maven-plugin/) to generate models at build time and eliminate the startup cost entirely. +Runtime generation requires your entities to be loaded by the same class loader (or be in the same module) as Morphia; if they aren't, as in some application server or JPMS layouts, use the plugin. See [Class loaders and modules](../maven-plugin/#class-loaders-and-modules). ## User-defined Codecs diff --git a/content/morphia/3.0/maven-plugin.md b/content/morphia/3.0/maven-plugin.md index b15bf08..2c8f732 100644 --- a/content/morphia/3.0/maven-plugin.md +++ b/content/morphia/3.0/maven-plugin.md @@ -6,7 +6,7 @@ weight: 60 The `critter-maven` plugin generates Morphia entity models and property accessors at build time (AOT — ahead of time), so they are ready on the classpath before your application starts. Without the plugin, Morphia generates the same models at each JVM startup. -The plugin is entirely optional; the runtime fallback produces identical results. It is recommended to use the plugin, however. +The plugin is optional; where runtime generation works, it produces identical results. It is recommended to use the plugin, however, and it is required to get critter models when your entities live outside Morphia's class loader or module (see [Class loaders and modules](#class-loaders-and-modules)). ## Why use it? @@ -19,6 +19,24 @@ The plugin is entirely optional; the runtime fallback produces identical results Both paths generate the bytecode necessary to manage your entities. The plugin simply moves the generation work from JVM startup to build time. +## Class loaders and modules + +Runtime generation defines its property accessors as hidden nestmates of each entity class. +The JVM only allows that with full privilege access to the entity, which Morphia has only when the entity is in the same module as Morphia. +On the classpath, that means the entity must be loaded by the same class loader as Morphia. + +That isn't the case in layouts like these: + +* Morphia in an application server's shared library directory, with the entities in a web application or other deployment that has its own class loader +* Plugin or isolated class loader setups where the entities are loaded separately from Morphia +* Entities in a separate JPMS module from Morphia + +There, runtime generation fails for every entity. +Morphia logs a warning once per entity saying it can't access the entity and falls back to the reflection-based model, so your application keeps working, but without the critter models. + +Pre-generated models from the `critter-maven` plugin aren't affected: they are compiled alongside your entities and loaded from the entities' own class loader. +If your application uses one of these layouts, use the plugin to get critter models. + ## Setup Add the plugin to your `pom.xml` and set `morphia.mapper=critter` in your config: