info

date: 2026-03-11 20:09:00

tags:

creator Stephan Bösebeck

logged in

ADMIN

Morphium 6.2.0 — What's New?

After months of work, Morphium 6.2.0 is ready. This release brings some fundamental changes — most notably the extraction of PoppyDB as a standalone module. But let's go through it step by step.

Multi-Module Maven Build

Morphium used to be a single Maven project. That worked fine, but it meant everyone who only needed the MongoDB client was pulling in Netty and the entire server code. Starting with 6.2.0, Morphium is a multi-module project:

morphium-parent — Parent POM
morphium (artifactId unchanged!) — the core client
poppydb — the server, now standalone

For existing projects, nothing changes in the Maven coordinates:

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>morphium</artifactId>
    <version>6.2.0</version>
</dependency>

PoppyDB: The Server Grows Up

The in-memory MongoDB-compatible server previously known as "MorphiumServer" has been given its own name: PoppyDB (Poppy — the flower that morphine comes from). More details in a dedicated blog post.

@Reference Cascade & Cycle Detection

References in Morphium can now cascade:

@Entity
public class Order {
    @Id private MorphiumId id;

    @Reference(cascadeDelete = true)
    private Customer customer;

    @Reference(orphanRemoval = true)
    private List<OrderItem> items;
}

cascadeDelete = true — Deletes referenced objects when the parent is deleted
orphanRemoval = true — Removes references that are no longer in the collection after an update

Circular references (A→B→A) are detected and handled cleanly — during both serialization and deserialization.

@AutoSequence — Sequence Numbers Without Boilerplate

Previously, you had to use the SequenceGenerator manually. Now a single annotation is enough:

@Entity
public class ImportRecord {
    @Id private MorphiumId id;

    @AutoSequence(name = "import_number", startValue = 1000, inc = 1)
    private Long importNumber;
}

Explicitly set values are never overwritten — only null (or 0 for primitives) triggers assignment. When using storeList(), all sequence numbers are fetched in a single round-trip.

@Version — Optimistic Locking

Finally built in: optimistic locking via @Version. On insert, the version is set to 1; on each update, it's atomically incremented. If someone tries to save a stale version, a VersionMismatchException is thrown:

@Entity
public class Account {
    @Id private MorphiumId id;
    @Version private Long version;
    private double balance;
}

CosmosDB Auto-Detection

Morphium now automatically detects whether it's talking to MongoDB, CosmosDB, or PoppyDB. Detection happens via the hello handshake response, allowing Morphium to account for backend-specific behavior:

if (morphium.isCosmosDB()) {
// CosmosDB-specific logic
}

Azure sovereign cloud domains are supported as well.

MorphiumDriverException Is Now Unchecked

MorphiumDriverException now extends RuntimeException instead of Exception. This follows the conventions of MongoDB Java Driver (MongoException), JPA, jOOQ, and Spring Data.

Migration: Existing catch blocks continue to work. Only catch (RuntimeException | MorphiumDriverException e) needs to be simplified to catch (RuntimeException e).

@CreationTime / @LastChange Improvements

LocalDateTime support as a fourth field type
Field annotation only — the class-level annotation is no longer required
Preset values preserved — explicitly set @CreationTime values are no longer overwritten on insert

More Highlights

MONGODB-X509 client certificate authentication
mongodb+srv:// connection strings for MongoDB Atlas
Configurable LocalDateTimeMapper — store as Date or ISO-8601 string
SequenceGenerator.getNextBatch(int) for bulk sequence allocation
resetThreadLocalOverrides() — clean up all per-thread overrides in a single call

Bug Fixes

Enum deserialization in Maps and Collections now works correctly
Custom TypeMappers are consulted in queries
BufferedWriter concurrent double-write fixed
Quarkus/OSGi ClassLoader — all Class.forName() calls now use the context ClassLoader
WriteConcern on standalone MongoDB — graceful downgrade from w>1 to w:1

Upgrade

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>morphium</artifactId>
    <version>6.2.0</version>
</dependency>

If you're using PoppyDB for testing:

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>poppydb</artifactId>
    <version>6.2.0</version>
    <scope>test</scope>
</dependency>

Full release notes are available in the CHANGELOG on GitHub.