Runs projections: it reads events from EventStores, applies each Projection's handlers, and keeps the results in ProjectionStores that can be queried.
A Projection only describes what should happen. The engine is the part that does it. Each projection gets a primary store, which is one SQLite file per projection on the JVM or an in-memory map in tests.
Lifecycle: start first compares each projection's stored schema hash with the current one, and brings stale stores up to date unless lazyRebuild is on. Then, for each source of each projection, it catches up on the events after the projection's saved position, reading them in batches with readFrom, and only then starts a fiber that follows the new events from the source's hub. start returns once every source has caught up. query first applies any pending lazy rebuild.
Routing: for each event the engine builds a ProjectionContext from the EventEnvelope, runs the matching handler, and applies the resulting ProjectionAction to the store chosen by the projection's ProjectionScope: the primary store for per-entity and global projections, and a shard per routing key for cross-entity ones.
Failures: an event whose handler throws, or that the store rejects, is logged as an error and skipped; an event that no handler matches is skipped too, and logged at debug level. Processing continues with the next event. The saved position is updated after each event that succeeds, so a skipped event is not retried once a later one succeeds.
Persistence: the stores that make, makeWithConfig and makeWithStoresVarargs create are SQLite files, so sqlite-jdbc must be on the runtime classpath and the folders of the files must exist. A store opens its file only when it is first used, so a missing driver or folder shows up as a failure then, not when the engine is created.
Create an engine with the factories on the companion object. make and makeWithConfig give it no event stores, so it has nothing to read; to give it event stores, create it with makeWithStores or makeWithStoresVarargs, or use TestEngine in tests.
Value parameters
- cache
-
shared TransactorCache for SQLite connections
- config
-
the settings the engine was created with
- eventStores
-
per-source event stores keyed by source name
- evolutionSem
-
semaphore guarding rebuilds
- migrationRegistry
-
registered schema migrations
- pendingRebuildRef
-
specs pending lazy rebuild
- primaryStores
-
per-spec primary stores keyed by spec name
- shardsRef
-
sharded stores for cross-entity routing
- specs
-
list of projections this engine manages
Attributes
- Companion
- object
- Source
- ProjectionEngine.scala
- Graph
-
- Supertypes