Morphium 6.2.0

Feature-rich MongoDB ODM and messaging framework for Java 21+

Available languages: English and Deutsch

🗄️ High-performance object mapping with annotation-driven configuration
📨 Integrated message queue backed by MongoDB (no extra infrastructure)
⚡ Multi-level caching with cluster-wide invalidation
🔌 Custom MongoDB wire-protocol driver tuned for Morphium
🧪 In-memory driver for fast tests (no MongoDB required)
🎯 JMS API (experimental) for standards-based messaging
🚀 Java 21 with virtual threads for optimal concurrency

🎯 Why Morphium?

Morphium is the only Java ODM that ships a message queue living inside MongoDB. If you already run MongoDB, you can power persistence, messaging, caching, and change streams with a single component.

| Feature | Morphium | Spring Data + RabbitMQ | Kafka | |---------|----------|------------------------|-------| | Infrastructure | MongoDB only | MongoDB + RabbitMQ | MongoDB + Kafka | | Setup complexity | ⭐ Very low | ⭐⭐⭐ Medium | ⭐⭐⭐⭐⭐ High | | Message persistence | Built in | Optional | Built in | | Message priority | ✅ Yes | ✅ Yes | ❌ No | | Distributed locks | ✅ Yes | ❌ No | ❌ No | | Throughput (internal tests) | ~8K msg/s | 10K–50K msg/s | 100K+ msg/s | | Operations | ⭐ Very easy | ⭐⭐ Medium | ⭐⭐⭐⭐ Complex |

* Numbers are indicative and depend heavily on hardware and workload.

📚 Documentation

Quick access

Documentation hub – entry point for all guides
Overview – core concepts, quick start, compatibility
Upgrade v6.1→v6.2 – migration checklist for 6.2.0
Migration v5→v6 – step-by-step upgrade guide
InMemory Driver Guide – capabilities, caveats, testing tips
Optimistic Locking (@Version) – prevent lost updates with @Version
SSL/TLS & MONGODB-X509 – encrypted connections and certificate-based authentication

More resources

Aggregation examples: docs/howtos/aggregation-examples.md
Messaging implementations: docs/howtos/messaging-implementations.md
Performance guide: docs/performance-scalability-guide.md
Production deployment: docs/production-deployment-guide.md
Monitoring & troubleshooting: docs/monitoring-metrics-guide.md

🚀 What’s New in v6.2

Multi-Module Maven Build

Morphium is now a multi-module project: morphium-parent (BOM), morphium (core library), and poppydb (server). The core library de.caluga:morphium no longer drags in server dependencies (Netty, etc.) — 90% leaner for users who just need the ODM.

PoppyDB – Standalone MongoDB-Compatible Server

The former MorphiumServer is now an independent module de.caluga:poppydb. It implements the MongoDB Wire Protocol as an in-memory server with Replica Set emulation, Change Streams, Aggregation Pipeline, and snapshot-based persistence.

PoppyDB and Morphium Messaging are optimized for each other — both sides recognize the counterpart and adapt their behavior, resulting in lower latency and less overhead than with a real MongoDB as messaging backend.

<dependency>
    <groupId>de.caluga</groupId>
    <artifactId>poppydb</artifactId>
    <version>6.2.0</version>
    <scope>test</scope> <!-- or remove scope for production use -->
</dependency>

✅ Full Wire Protocol: Any MongoDB client can connect (mongosh, Compass, PyMongo, ...)
✅ Messaging Backend: Run Morphium messaging without MongoDB — optimized for low-latency
✅ CLI Tooling: poppydb-6.2.0-cli.jar for standalone deployment
✅ Replica Set Emulation: Test cluster behavior without real MongoDB
✅ Snapshot Persistence: --dump-dir / --dump-interval to preserve data across restarts

MorphiumDriverException is now unchecked

MorphiumDriverException extends RuntimeException — consistent with the MongoDB Java driver. Eliminates 40+ boilerplate catch-wrap-rethrow blocks.

@Reference Cascade Delete/Store

@Reference now supports cascadeDelete and cascadeStore for automatic lifecycle management of referenced entities.

@AutoSequence

Annotation-driven auto-increment sequences — no manual counter management needed.

@CreationTime Improvements

Works correctly with store() and storeList(), supports @CreationTime on Date, long, and String fields.

CosmosDB Auto-Detection

Morphium detects Azure CosmosDB connections and automatically adjusts behavior for compatibility.

See CHANGELOG for full details.

Upgrading from 6.1.x to 6.2.0

Breaking: MorphiumDriverException is now unchecked

MorphiumDriverException extends RuntimeException instead of Exception. This eliminates boilerplate catch-wrap-rethrow blocks but requires attention in existing code:

// Multi-catch — simplify (MorphiumDriverException IS a RuntimeException now)
// Before:
catch (RuntimeException | MorphiumDriverException e) { ... }
// After:
catch (RuntimeException e) { ... }

// throws declarations — can be removed (but still compile if left in)
// Before:
public void doStuff() throws MorphiumDriverException { ... }
// After:
public void doStuff() { ... }

// Standalone catch — works unchanged
catch (MorphiumDriverException e) { ... }  // still compiles

Breaking: MorphiumServer → PoppyDB

The embedded MongoDB-compatible server was extracted to its own module and renamed:

| | 6.1.x | 6.2.0 | |---|---|---| | Maven artifact | included in morphium | separate: de.caluga:poppydb:6.2.0 | | Package | de.caluga.morphium.server | de.caluga.poppydb | | Main class | MorphiumServer | PoppyDB | | CLI JAR | morphium-*-server-cli.jar | poppydb-*-cli.jar | | Test tag | @Tag("morphiumserver") | @Tag("poppydb") |

If you use PoppyDB in tests, add the dependency:

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

Wire-protocol compatibility is preserved — PoppyDB responds to both poppyDB and morphiumServer in the hello handshake.

Deprecated: Direct config setters → sub-objects

MorphiumConfig now organizes settings into typed sub-objects. The old setters still work but are @Deprecated:

// 6.1.x style (deprecated but functional)
cfg.setDatabase("mydb");
cfg.addHostToSeed("localhost", 27017);

// 6.2.0 style (preferred)
cfg.connectionSettings().setDatabase("mydb");
cfg.clusterSettings().addHostToSeed("localhost", 27017);
cfg.driverSettings().setDriverName("PooledDriver");

Available sub-objects: connectionSettings(), clusterSettings(), driverSettings(), messagingSettings(), cacheSettings(), authSettings(), threadPoolSettings(), objectMappingSettings(), writerSettings().

New: Multi-Module Maven Structure

The morphium core artifact no longer bundles server dependencies (Netty, etc.). If you only use Morphium as ODM, your dependency tree is ~90% leaner — no changes to your pom needed.

Migration checklist

Search for catch (RuntimeException | MorphiumDriverException — simplify to catch (RuntimeException
Search for import de.caluga.morphium.server — replace with import de.caluga.poppydb
Search for MorphiumServer — rename to PoppyDB
Search for @Tag("morphiumserver") — rename to @Tag("poppydb")
Add poppydb dependency if you use the embedded server in tests
Optional: migrate direct config setters to sub-object style
Optional: adopt new features (@Reference(cascadeDelete), @AutoSequence, @Version)

🚀 What’s New in v6.1.x

MONGODB-X509 Client-Certificate Authentication

Connect to MongoDB instances that require mutual TLS / x.509 client certificates
Configure via AuthSettings.setAuthMechanism("MONGODB-X509") together with the existing SslHelper mTLS setup

`@Version` – Optimistic Locking

Prevents lost updates in concurrent environments without requiring pessimistic database locks. See docs/howtos/optimistic-locking.md for the full guide.

🚀 What’s New in v6.0

Java 21 & Modern Language Features

Virtual threads for high-throughput messaging and change streams
Pattern matching across driver and mapping layers
Records: Not yet supported as @Entity or @Embedded types (see #116)
Sealed class support for cleaner domain models

Driver & Connectivity

SSL/TLS Support: Secure connections to MongoDB instances (added in v6.0)
Virtual threads in the driver for optimal concurrency

Messaging Improvements

Fewer duplicates thanks to refined message processing
Virtual-thread integration for smoother concurrency
Higher throughput confirmed in internal benchmarking
Distributed locking for coordinated multi-instance deployments

In-Memory Driver Enhancements

No MongoDB required for unit tests or CI pipelines
Significantly faster test cycles in pure in-memory mode
~93% MongoDB feature coverage including advanced operations
Full aggregation pipeline with $lookup, $graphLookup, $bucket, $mergeObjects
MapReduce support with JavaScript engine integration
Array operators including $pop, $push, $pull, $addToSet
Change streams & transactions available for integration testing
Drop-in replacement for most development and testing scenarios

Documentation Overhaul

Complete rewrite of the guide set
Practical examples and end-to-end use

Morphium

Install / Use

README

Morphium 6.2.0

🎯 Why Morphium?

📚 Documentation

Quick access

More resources

🚀 What’s New in v6.2

Multi-Module Maven Build

PoppyDB – Standalone MongoDB-Compatible Server

MorphiumDriverException is now unchecked

@Reference Cascade Delete/Store

@AutoSequence

@CreationTime Improvements

CosmosDB Auto-Detection

Upgrading from 6.1.x to 6.2.0

Breaking: MorphiumDriverException is now unchecked

Breaking: MorphiumServer → PoppyDB

Deprecated: Direct config setters → sub-objects

New: Multi-Module Maven Structure

Migration checklist

🚀 What’s New in v6.1.x

MONGODB-X509 Client-Certificate Authentication

`@Version` – Optimistic Locking

🚀 What’s New in v6.0

Java 21 & Modern Language Features

Driver & Connectivity

Messaging Improvements

In-Memory Driver Enhancements

Documentation Overhaul

Morphium

Install / Use

README

Morphium 6.2.0

🎯 Why Morphium?

📚 Documentation

Quick access

More resources

🚀 What’s New in v6.2

Multi-Module Maven Build

PoppyDB – Standalone MongoDB-Compatible Server

MorphiumDriverException is now unchecked

@Reference Cascade Delete/Store

@AutoSequence

@CreationTime Improvements

CosmosDB Auto-Detection

Upgrading from 6.1.x to 6.2.0

Breaking: MorphiumDriverException is now unchecked

Breaking: MorphiumServer → PoppyDB

Deprecated: Direct config setters → sub-objects

New: Multi-Module Maven Structure

Migration checklist

🚀 What’s New in v6.1.x

MONGODB-X509 Client-Certificate Authentication

@Version – Optimistic Locking

🚀 What’s New in v6.0

Java 21 & Modern Language Features

Driver & Connectivity

Messaging Improvements

In-Memory Driver Enhancements

Documentation Overhaul

`@Version` – Optimistic Locking