Advanced

Advanced Topics

This page covers more advanced concepts in MongoHelper: codec registries, metadata, and index creation.

Codec Registries and Custom Types

MongoHelper builds a CodecRegistry for each database using:

• Enum codecs from EnumMetaCodecProvider
• Type/model codecs from TypeMetaCodecProvider
• The default MongoDB codec registry from MongoClientSettings.getDefaultCodecRegistry()

The registries are combined using CodecRegistries.fromRegistries(...).

Before the registries are combined, MongoHelper calls:

List<CodecRegistry> OrmSchematic.handleCodecRegistry(List<CodecRegistry> registries)

This allows each schematic to:

• Add custom codec registries
• Remove or replace registries
• Apply any custom logic to how codecs are configured

Example: Adding a Custom Codec Registry

@Override
public List<CodecRegistry> handleCodecRegistry(List<CodecRegistry> registries) {
    CodecRegistry customRegistry = ...; // build your custom registry

    registries.add(0, customRegistry); // give it higher priority
    return registries;
}

Metadata and Index Creation

When a schematic is registered, MongoHelper:

1. Walks each model class using a ModelWalker and builds a ModelMeta.
2. Registers the model metadata in ModelMetaRegistry.
3. Uses ModelMeta to determine index definitions.
4. Builds IndexModel instances from IndexMeta.
5. Calls collection.createIndexes(indexModels) for each collection that has defined indexes.

This means index creation is automated and driven entirely by your model metadata. You do not need to manually create indexes in your application startup logic, as long as your model metadata is correct.

Filter Validation for Unique Indexes

BaseOperations<M> includes a helper to validate that a filter uses unique keys when required:

protected void validateFilterUniques(@NotNull Bson filter) {
    // checks if the filter contains at least one unique index field
}

If there is no unique key present in the filter, an IllegalStateException with the message "No unique keys found" is thrown.

This protects operations that must target a unique document (for example, certain upsert or update operations) from accidentally matching multiple documents.

Error Handling Summary

Some important error conditions in MongoHelper:

• Duplicate schematic instance: registering the same OrmSchematic instance more than once throws an IllegalStateException.
• Missing operations group: calling mongoHelper.get(SomeClass.class) when no OperationsGroup exists for that class throws an exception.
• Missing unique keys in filter (where required): BaseOperations.validateFilterUniques(...) throws IllegalStateException("No unique keys found").

When to Drop Down to the Raw Driver

MongoHelper is designed to cover common CRUD and metadata-driven use cases. You can always drop down to the raw driver by calling:

OperationsGroup<MyModel> group = mongoHelper.get(MyModel.class);
MongoCollection<MyModel> collection = group.getCollection();

// Now use the MongoDB driver API directly
collection.aggregate(...);
collection.bulkWrite(...);

This lets you:

• Use advanced MongoDB features not yet wrapped by MongoHelper
• Combine MongoHelper's metadata and grouping with low-level operations