sboesebeck/morphium — documented rules

**WatchingCacheSynchronizer** — opens a MongoDB Change Stream (ChangeStreamMonitor) directly on the watched collections and reacts to whatever it sees change at the database layer, no matter who wrote it.

de.caluga.morphium.data.MorphiumRepository<T, K> — extends CrudRepository<T, K> with Morphium-specific escape hatches that have no equivalent in the Jakarta Data 1.0 specification: distinct(String fieldName) and morphium() (direct access to the underlying Morphium instance for aggregation pipelines, atomic field operations, change streams, and messaging), plus query() as a shortcut for morphium().createQueryFor(entityClass).

de.caluga.morphium.data.MorphiumRepository<T, K> — extends CrudRepository<T, K> with Morphium-specific escape hatches that have no equivalent in the Jakarta Data 1.0 specification: distinct(String fieldName) and morphium() (direct access to the underlying Morphium instance for aggregation pipelines, atomic field operations, change streams, and messaging), plus query() as a shortcut for morphium().createQueryFor(entityClass).

de.caluga.morphium.data.MorphiumRepository<T, K> — extends CrudRepository<T, K> with Morphium-specific escape hatches that have no equivalent in the Jakarta Data 1.0 specification: distinct(String fieldName) and morphium() (direct access to the underlying Morphium instance for aggregation pipelines, atomic field operations, change streams, and messaging), plus query() as a shortcut for morphium().createQueryFor(entityClass).

Repository method names are parsed by MethodNameParser into a QueryDescriptor, which QueryExecutor then translates into a Morphium Query.

Repository method names are parsed by MethodNameParser into a QueryDescriptor, which QueryExecutor then translates into a Morphium Query.

Repository method names are parsed by MethodNameParser into a QueryDescriptor, which QueryExecutor then translates into a Morphium Query.

JdqlParser parses the string into a JdqlQuery;

Aggregate/grouping support (JdqlQuery.java:25-33, JdqlMethodBridge.java:443-620): SELECT COUNT(this), SUM(field), AVG(field), MIN(field), MAX(field) are compiled into a Morphium aggregation pipeline ($match → $group → optional $match for HAVING → optional $sort).

SortMapper.apply(...) (and the equivalent inline logic in FindMethodBridge/JdqlMethodBridge) resolves each Sort.property() to its MongoDB field name and applies ascending/descending order (SortMapper.java:26-36).

Return type T (single entity), Behavior requireSingle throws EmptyResultException on zero results, NonUniqueResultException on more than one, Source QueryResultHelper.java:34-44

Return type Optional<T>, Behavior optionalSingle Optional.empty() on zero results, Optional.of(entity) on exactly one, NonUniqueResultException on more than one, Source QueryResultHelper.java:53-63

The key extension point is AbstractMorphiumRepository<T, K>: it implements all CRUD logic as plain doXxx() methods (doFindById, doFindAll, doSave, doDelete, ...) and exposes a protected void setMorphium(Morphium morphium) setter that your framework subclass or generated proxy must call to wire in a live Morphium instance before any doXxx() method is used.

The key extension point is AbstractMorphiumRepository<T, K>: it implements all CRUD logic as plain doXxx() methods (doFindById, doFindAll, doSave, doDelete, ...) and exposes a protected void setMorphium(Morphium morphium) setter that your framework subclass or generated proxy must call to wire in a live Morphium instance before any doXxx() method is used.

The key extension point is AbstractMorphiumRepository<T, K>: it implements all CRUD logic as plain doXxx() methods (doFindById, doFindAll, doSave, doDelete, ...) and exposes a protected void setMorphium(Morphium morphium) setter that your framework subclass or generated proxy must call to wire in a live Morphium instance before any doXxx() method is used.

The key extension point is AbstractMorphiumRepository<T, K>: it implements all CRUD logic as plain doXxx() methods (doFindById, doFindAll, doSave, doDelete, ...) and exposes a protected void setMorphium(Morphium morphium) setter that your framework subclass or generated proxy must call to wire in a live Morphium instance before any doXxx() method is used.

The key extension point is AbstractMorphiumRepository<T, K>: it implements all CRUD logic as plain doXxx() methods (doFindById, doFindAll, doSave, doDelete, ...) and exposes a protected void setMorphium(Morphium morphium) setter that your framework subclass or generated proxy must call to wire in a live Morphium instance before any doXxx() method is used.

setMessagingWindowSize(int): number of messages processed per batch.

setMessagingMultithreadded(boolean): process multiple messages in parallel using a platform-thread pool;

setUseChangeStream(boolean): use MongoDB Change Streams to get push‑style notifications for new messages;

setMessagingPollPause(int): pause (in ms) between polling requests when not using Change Streams.

Msg.timestamp is used for ordering, not scheduling

Morphium provides MessagingCacheSynchronizer (uses this messaging system) and WatchingCacheSynchronizer (uses Change Streams directly, no messaging needed) — see the [Developer Guide](./developer-guide.md#cache-synchronization) for which one to pick.

PoppyDB is a standalone MongoDB wire protocol-compatible server built on the InMemoryDriver.

MorphiumProcessor.registerMorphiumIdJsonCustomizers(...) (deployment) ist das **exakte Vorbild** für das, was wir bauen wollen:

Quelle MorphiumDriver.getDriverStats() → Map<DriverStatsKey, Double>, Typ Pull (on-demand), Inhalt CONNECTIONS_OPENED/CLOSED/BORROWED/RELEASED/IN_POOL/IN_USE , ERRORS , FAILOVERS , MSG_SENT , REPLY_ , THREADS_CREATED , THREADS_WAITING_FOR_CONNECTION

Quelle Morphium.getStatistics() → Statistics extends HashMap<String,Double>, Typ Pull (on-demand), Inhalt StatisticKeys WRITES , WRITES_CACHED , READS , CHITS , CMISS , NO_CACHED_READS , CHITSPERC , CMISSPERC , CACHE_ENTRIES , REGISTERED_LOGGERS , WRITE_BUFFER_ENTRIES , PULL , PULLSKIP , SKIPPED_MSG_UPDATES , INSTANCE_COUNT

Quelle driver.getNumConnectionsByHost(), Typ Pull, Inhalt Connections pro Host (für Multi-Host-Setups)

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Quelle MorphiumStorageListener<T> (Interface, bereits für MorphiumBlockingCallDetector genutzt), Typ Push (Event), Inhalt preStore / postStore / preRemove / postRemove / postLoad / preUpdate / postUpdate — je Aufruf, mit Objekt/Query/Class-Kontext

Registrierung **ausschließlich** am Ende von MorphiumProducer.buildMorphium(), direkt neben der bestehenden Zeile (aktuell ca. MorphiumBlockingCallDetector.registerOn(instance) fehlt noch im aktuell gelesenen Ausschnitt bis Zeile 500 — muss beim Patch verifiziert werden, aber der Javadoc von MorphiumBlockingCallDetector belegt exakt diesen Aufrufort/diese Reihenfolge).

Configure via AuthSettings.setAuthMechanism("MONGODB-X509") together with the existing SslHelper mTLS setup

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

MethodNameParser/QueryExecutor (query derivation from method names), JdqlParser/ JdqlMethodBridge (the @Query JDQL grammar), FindMethodBridge (@Find/@Delete with @By parameter binding), pagination (AbstractMorphiumRepository's offset and cursor pagination), and sorting.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.

the Morphium bean and MorphiumProperties (morphium.* configuration, MorphiumAutoConfiguration), the @EnableMorphiumRepositories/ MorphiumRepositoryRegistrar/MorphiumRepositoryFactoryBean JDK-proxy mechanism that turns a @Repository interface into a Spring bean, the @MorphiumTransactional AOP aspect, and the actuator health indicator.