What is this?
What does it offer?
- Supports NHibernate 4.0 or later.
- Allows customizing how many LiquidProjections Transactions it should process in a single database transaction.
- Supports nesting one or more
NHibernateChildProjectors that can be used for maintaining lookup tables and which are part of the same database transaction as the parent projector creates.
- Ensures autonomy by storing the
IProjectionState(e.g. the last transaction checkpoint) in the same transaction as the actual projection data.
- Allows the projector to be configured with an
ExceptionPolicydelegate so that you can handle projection exceptions and get full control on whether or not the projector should retry the entire batch, individual transactions, ignore or abort the exception.
- If the implementation of
IProjectorState has additional custom properties, you can use the
EnrichStatedelegate of the
NHibernateProjectorto update the state object before it is written to the database. This is called as part of the same database transaction that encompasses the projector code.
Why would I use NHibernate for something like a projection
Some have argued that using raw SQL is the fasted method for updating RDBMS-backed projections. And quite often this is true. But depending on the nature of the projection, in particular when it touches the same projection many times in the same batch of events, the unit-of-work (the
ISession) can provide some significant speed improvements.
This package provides a simple caching mechanism in the form of the
IProjectionCache and ships with the
LruProjectionCache based on the FluidCaching project. The
IProjectionCache is meant for the most common scenarios and thus has some limitations:
- If the projector performs database modifications directly on the NHibernate
ISession, that projector must make sure the cache is updated or cleared accordingly.
- The cache doesn't understand relationships where a projection refers to another projection maintained by the same projector. For instance, a projector that maintains a graph of parents and children, where a child is also a (direct or indirect) parent must use a more advanced type of caching.
If you need more advanced caching, please refer to NHibernate's Second Level Caching feature.
About the sample application?
You'll find a sample application under the
Samples folder that tries to demonstrate a couple of aspect of using
LiquidProjections such as event maps, exception handling and lookups in combination with NHibernate. It uses the
JsonFileEventStore example implementation to feed a list of events serialized into the
ExampleEvents.zip into the
This dispatcher gets used by the
CountsProjector to build a Sqlite-backed
DocumentCountProjection (stored in the output directory under
projections.db). Each projection record has a one-to-many relationship to the
ValidityPeriod object to track when a document is valid or not. The projector also maintains a
CountryLookup using a
NHibernateChildProjector to map country codes to country names.
CountsProjector also demonstrates how to employ the
LruProjectionCache to speed up lookups and updates of recently updated projections. And finally, the projector uses a pretty extensive example on how to use the
ExceptionResolution.RetryIndividual to trace down the transaction that is causing the (simulated) non-transient exception and mark that projection as corrupt. In then uses the
Filter property of the
NHibernateProjector to skip any successive attempts to update that corrupted projection.
To expose the data from this projection, the sample program will expose an HTTP API end-point served through the
StatisticsController at route
http://localhost:9000/api/Statistics/CountsPerState. For example, run a GET on this URL to get some counters:
As all my open-source projects are written to be examples of proper coding conventions and Test Driven Development, also consider checking out the unit tests to learn how the many features work together.