Preparing for 3.0

Minimum Java Version

Morphia 2.x made the jump to Java 11 and 3.0 will make the jump to Java 17. While this may not work for everyone, we’re hopeful that it won’t be a significant migration issue since by the time 3.0 releases, major frameworks such as Spring Boot and Quarkus will have long-since completed their moves to 17 as well. This move will enable Morphia to continue to evolve to meet modern demands over the next few years.

Build time vs runtime

Traditionally Morphia, like most object mappers, has leaned heavily on reflection at runtime to discover any mapped entities and to handle the read/write operations with the database. Modern JVMs take an increasingly dimmer view of such efforts and is closing off some avenues to support such features. Taking some lessons learned from Quarkus’s model, much of this work will be moving to build time processing such that when you deploy your application, all the mapping information will not only be known but processed and ready for usage. This will necessitate the introduction of a basic maven/gradle plugin to collect and process this information. Moving to this model opens the door to some interesting optimizations and potential new features that are impractical if not impossible in the current approach.


For the last several years, critter has been available as an optional add on to Morphia that offers some nice features over and above what Morphia does in core. In addition to compile time checked constants for property names, etc., the latest critter can also generate the codecs necessary to manage entities with minimal or no reflection needed. In 3.0, critter will be brought in to Morphia proper and will live under the same lifecycle and release cycles as Morphia itself. Indeed, it will likely be the core of how Morphia works in the future. Much testing and performance evaluation needs to happen before that final decision is reached but that will be part of the 3.0 dev cycle as well.

Configuration file

Morphia 2.4 introduces a new configuration file based method of configuring Morphia’s behavior for your needs. As of 3.0, this will be the only way to configure Morphia and the programmatic API will be removed from the public API. For more details, please see the configuration section.

After some feedback about some unexpected use cases, this transition has been postponed and the requisite MapperOptions based methods undeprecated. Programmatic configuration is a much more popular, and in some cases vital, option than previously known. So for now, those methods will stay while the future of configuration and mapping gets a rethink. Apologies for the noise and dust.


With 2.0, much of the focus was on pivoting to the (then) new POJO Codecs and simplifying the API. Over the course of the 2.x cycle, many overloaded methods have been consolidated in to Options based variants. These Options classes make the task of adding, and removing, various options much simpler while also keeping the core API slim enough to easily process. That said, these older methods still exist and continue to clutter the API. Morphia 3.0 will see the removal of all deprecated items.

One thing to note on a handful of deprecations is that the method isn’t going away as such as the usage of it will change in a breaking manner. e.g., Query#update(UpdateOperator first, UpdateOperator…​ updates). This method will, in 3.0, return an UpdateResult like the execute() method you have to call today does. Migrating to this new form when 3.0 arrives should be as simple as removing that last method call in the chain.

This use of deprecation is not optimal but seemed the best way to educate users about the upcoming change.

Field vs Property Mapping

In the current scheme of mapping, this distinction has meant more than it will in future versions. As such, this distinction will go away and Morphia will simply evaluate and process both fields and accessor methods for mapping metadata. The config value for this setting will silently vanish from the config file schema and the only thing you should notice is a warning about an unknown config property which can be removed at your leisure.