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

Available languages: English | 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

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.

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

• Documentation hub – entry point for all guides
• Overview – core concepts, quick start, compatibility
• Migration v5→v6 – step-by-step upgrade guide
• InMemory Driver Guide – capabilities, caveats, testing tips

• 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

• Virtual threads for high-throughput messaging and change streams
• Pattern matching & records across driver and mapping layers
• Sealed class support for cleaner domain models

• 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

• 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

• Complete rewrite of the guide set
• Practical examples and end-to-end use cases
• Dedicated migration playbook from 5.x to 6.x
• Architecture insights and best practices

• Java 21 or newer
• MongoDB 5.0+ for production deployments
• Maven

Maven dependencies:

<dependency>
  <groupId>de.caluga</groupId>
  <artifactId>morphium</artifactId>
  <version>[6.0.0,)</version>
</dependency>
<dependency>
  <groupId>org.mongodb</groupId>
  <artifactId>bson</artifactId>
  <version>4.7.1</version>
</dependency>

Migrating from v5? → docs/howtos/migration-v5-to-v6.md

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

import de.caluga.morphium.Morphium;
import de.caluga.morphium.MorphiumConfig;
import de.caluga.morphium.annotations.*;
import de.caluga.morphium.driver.MorphiumId;
import java.time.LocalDateTime;

// Entity definition
@Entity
public class User {
    @Id
    private MorphiumId id;
    private String name;
    private String email;
    private LocalDateTime createdAt;
    // getters/setters
}

// Configuration
MorphiumConfig cfg = new MorphiumConfig();
cfg.connectionSettings().setDatabase("myapp");
cfg.clusterSettings().addHostToSeed("localhost", 27017);
cfg.driverSettings().setDriverName("PooledDriver");

Morphium morphium = new Morphium(cfg);

// Store entity
User user = new User();
user.setName("John Doe");
user.setEmail("[email protected]");
user.setCreatedAt(LocalDateTime.now());
morphium.store(user);

// Query
List<User> users = morphium.createQueryFor(User.class)
    .f("email").matches(".*@example.com")
    .sort("createdAt")
    .asList();

import de.caluga.morphium.messaging.MorphiumMessaging;
import de.caluga.morphium.messaging.Msg;

// Messaging setup
MorphiumMessaging messaging = morphium.createMessaging();
messaging.setSenderId("my-app");
messaging.start();

// Send a message
Msg message = new Msg("orderQueue", "Process Order", "Order #12345");
message.setPriority(5);
message.setTtl(300000); // 5 minutes
messaging.sendMessage(message);

// Receive messages
messaging.addListenerForTopic("orderQueue", (m, msg) -> {
    log.info("Processing {}", msg.getValue());
    // process order ...
    return null; // no reply
});

# Environment variables
export MONGODB_URI='mongodb://user:pass@localhost:27017/app?replicaSet=rs0'
export MORPHIUM_DRIVER=inmem

# System properties
mvn -Dmorphium.uri='mongodb://localhost/mydb' test

# Properties file (morphium.properties)
morphium.hosts=mongo1.example.com:27017,mongo2.example.com:27017
morphium.database=myapp
morphium.replicaSet=myReplicaSet

# All tests
mvn test

# Full build with checks
mvn clean verify

# Tagged test selection
mvn test -Dgroups="core,messaging"

# Run against a real MongoDB instance
mvn test -Dmorphium.driver=pooled -Dmorphium.uri=mongodb://localhost/testdb

# Default: in-memory driver
./runtests.sh

# Run tagged suites
./runtests.sh --tags core,messaging

# Parallel runs
./runtests.sh --parallel 8 --tags core

# Retry only failed methods
./runtests.sh --rerunfailed
./runtests.sh --rerunfailed --retry 3

# Target a MongoDB cluster
./runtests.sh --driver pooled --uri mongodb://mongo1,mongo2/testdb

# Single test class
./runtests.sh CacheTests

# Statistics
./runtests.sh --stats
./getFailedTests.sh  # list failed methods

New in v6.0

• ✅ Method-level reruns: --rerunfailed only re-executes failing methods
• ✅ No more hangs: known deadlocks resolved
• ✅ Faster iteration: noticeably quicker partial retries
• ✅ Better filtering: class-name filters now reliable

Run ./runtests.sh --help to see every option.

TestConfig consolidates all test settings. Priority order:

1. System properties (-Dmorphium.*)
2. Environment variables (MORPHIUM_*, MONGODB_URI)
3. src/test/resources/morphium-test.properties
4. Defaults (localhost:27017)

The in-memory driver provides a largely MongoDB-compatible data store fully in memory:

Features

• ✅ Full CRUD operations
• ✅ Rich query operator coverage
• ✅ Aggregation stages such as $match, $group, $project
• ✅ Single-instance transactions
• ✅ Basic change streams
• ✅ JavaScript $where support

Performance

• Significantly faster than external MongoDB for tests
• No network latency
• No disk I/O
• Ideal for CI/CD pipelines

Usage

# All tests with the in-memory driver
./runtests.sh --driver inmem

# Specific tests
mvn test -Dmorphium.driver=inmem -Dtest="CacheTests"

See docs/howtos/inmemory-driver.md for feature coverage and limitations.

MorphiumServer runs the Morphium wire-protocol driver in a separate process:

# Start the server
java -jar morphium-6.0.0.jar de.caluga.morphium.server.MorphiumServer

# Connect with mongosh or MongoDB Compass
mongosh mongodb://localhost:27017

Use cases

• Local development without installing MongoDB
• CI environments
• Embedded database for desktop applications
• Smoke-testing MongoDB tooling (mongosh, Compass, mongodump, …)

Current limitations

• No replica set emulation (planned for 6.x)
• No sharding support
• Some advanced aggregation operators and joins still missing

Organizations run Morphium in production for:

• E-commerce: order processing with guaranteed delivery
• Financial services: coordinating transactions across microservices
• Healthcare: patient-data workflows with strict compliance
• IoT platforms: device state synchronization and command distribution
• Content management: document workflows and event notifications

• Slack: Team Morphium
• Blog: https://caluga.de
• GitHub: sboesebeck/morphium
• Issues: Report bugs or request features on GitHub

We appreciate pull requests! Areas where help is especially welcome:

• InMemoryDriver: expanding MongoDB feature coverage
• Documentation: tutorials, examples, translations
• Performance: profiling and benchmarks
• Tests: broader scenarios and regression coverage

How to contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add AmazingFeature')
4. Push the branch (git push origin feature/AmazingFeature)
5. Open a pull request

Tips

• Respect test tags (@Tag("inmemory"), @Tag("external"))
• Run ./runtests.sh --tags core before submitting
• Update documentation when you change APIs

Apache License 2.0 – see LICENSE for details.

Thanks to every contributor who helped ship Morphium 6.0 and to the MongoDB community for continuous feedback.

Questions? Open an issue on GitHub or browse the documentation.

Planning an upgrade? Follow the migration guide.

Enjoy Morphium 6.0! 🚀

Stephan Bösebeck & the Morphium team