NHibernate Auditing v3 – Poor Man’s Envers

Jason Dentler — Tue, 06 Jul 2010 05:25:00 GMT

First, let me explain the title of this post. The Hibernate folks – you know, that NHibernate knock off written in the Java (pronounced “ex em el”) programming language – have a project called Envers. Among other things, It audits changes to entities, then allows you to easily retrieve the entity as it was at any previous point in time.

Well, Simon Duduica is porting this over to .NET and NHibernate, and he’s making some AMAZING progress. On June 28th, he shared this news with us on the NH Contrib development group:

Hi everybody,

I have news regarding Envers.NET. I've commited a version that works in basic tests for CUD operations, with entities that have relationships between them, also with entities that are not audited. To make things work I had to make two small modifications of NHibernate, both modifications were tested running all NHibernate unit tests and they all passed. I already sent the first modification to Fabio and the second I will send this evening. I would like to thank Tuna for helping me out with good advices when I was stuck :)

So, on to the topic of this post. For NHibernate 3.0 Cookbook, I’ve included a section that explains how to use NHibernate to generate audit triggers. Originally, I had planned to use the code from my previous blog post on the topic, but I didn’t like its structure. I also didn’t want to include all that plumbing code in the printed book. Instead, I’ve rewritten and contributed the “framework” code to uNHAddIns. The “how-to use it” is explained in the book, so I won’t explain it here.

Today, I was writing an integration test for this contribution, and thought the idea was worth sharing. I have a simple Cat class:

When I do anything to this cat, in addition to the normal INSERT, UPDATE, or DELETE, a database trigger records that action in a table called CatAudit:

I wanted an easy way to investigate the contents of this table to prove that my audit triggers worked. Here’s what I came up with, along with help from Jose Romaniello (@jfroma). First, I created a class to match this table:

Next, I mapped it, made it readonly and excluded it from hbm2ddl with this mapping:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
				   assembly="uNhAddIns.Test"
				   namespace="uNhAddIns.Test.Audit.TriggerGenerator">
  <typedef class="NHibernate.Type.EnumStringType`1[[uNhAddIns.Audit.TriggerGenerator.TriggerActions, uNhAddIns]], NHibernate"
           name="triggerActions" />
  <class name="CatAudit" 
         mutable="false"
         schema-action="none">
    <composite-id>
      <key-property name="Id" />
      <key-property name="AuditUser" />
      <key-property name="AuditTimestamp" />
    </composite-id>
    <property name="Color"/>
    <property name="AuditOperation" type="triggerActions" />
  </class>
	
</hibernate-mapping>

I made it readonly by setting mutable="false" and excluded it from hbm2ddl with schema-action="none". That’s it!

By the way, the <typedef> along with type="triggerActions" just tells NHibernate I've stored my TriggerActions enum values as strings, not numbers.

How Test your mappings: the Ghostbuster

Fabio Maulo — Mon, 20 Oct 2008 13:48:00 GMT

In NHibernate, when you have the FlushMode configured to AutoFlush, session.Flush() is called when NH detects a dirty entity instance and when a query with an intersected QuerySpace is performed. (The QuerySpace is represented by all tables affected in a query.)

Example:

  <class name="Animal">
     <id name="Id">
         <generator class="hilo"/>
     </id>
     <property name="Description"/>

     <joined-subclass name="Reptile">
         <key column="animalId"/>
         <property name="BodyTemperature"/>
     </joined-subclass>

 </class>

In the above domain, a query on the Reptile class in a opened session with a dirty instance of Animal would cause session.Flush() will be called.

After a session.Get<Animal>(animalId) we can be pretty sure that there is no dirty entities in the session, sure ?

Don’t be so sure! The real answer is: It depends.

For example try this domain:

public enum Sex
{
 Unspecified,
 Male,
 Female
}
public class Person
{
 public virtual int Id { get; set; }
 public virtual Sex Sex { get; set; }
}

with this mapping:

  <class name="Person">
     <id name="Id">
         <generator class="hilo"/>
     </id>
     <property name="Sex" type="int"/>
 </class>

In the mapping I define the property Sex of type int but in the class the type is Sex; even if you don’t receive an exception, because an int is convertible to Sex and viceversa, your persistence will have a unexpected behavior. NH will detect a modification, of your entity, “immediately” after session.Get because it having an int in the entity snap-shot (retrieved from DB) and a Sex in the actual state. The example are showing a very simple case of “ghosts” in your application. In a big environment, with a complex domain, find “ghosts” it is not so easy.

The Ghostbusters

[TestFixtureSetUp]
public void TestFixtureSetUp()
{
 XmlConfigurator.Configure();
 cfg = new Configuration();
 cfg.Configure();
 new SchemaExport(cfg).Create(false, true);
 sessions = (ISessionFactoryImplementor) cfg.BuildSessionFactory();
 PopulateDb();
}

Few words about the TestFixtureSetUp:

if you are testing your domain persistence you can run the “ghostbuster” in each test.
if you are testing yours DAOs and you have an implementation of ObjectMother or TestDataBuilder you can use it in the implementation of PopulateDb() method.
If you don’t have tests you can leave the PopulateDb() method empty and configure NH to an existing copy of your DB.

[Test, Explicit]
public void UnexpectedUpdateDeleteOnFetch()
{
 PersistingMappings(null);
}

[Test, Explicit]
public void UnexpectedUpdateDeleteOnFetchSpecific()
{
 var entitiesFilter = new[]
                          {
                              "Person"
                          };
 PersistingMappings(entitiesFilter);
}

In my experience the above two tests are needed. The first sound like “close your eyes and pray” the second allow you to analyze some specific entities.

To avoid breaking the test, on each unexpected DB-hit, I’ll use the power of log4net in the whole fixture.

To intercept unexpected Flush a possible, easy and quickly, way is an implementation of IInterceptor.

private class NoUpdateInterceptor : EmptyInterceptor
{
 private readonly IList<string> invalidUpdates;

 public NoUpdateInterceptor(IList<string> invalidUpdates)
 {
     this.invalidUpdates = invalidUpdates;
 }

 public override bool OnFlushDirty(object entity, object id, object[] currentState, object[] previousState, string[] propertyNames, IType[] types)
 {
     string msg = " FlushDirty :" + entity.GetType().FullName;
     log.Debug(msg);
     invalidUpdates.Add(msg);
     return false;
 }

 public override bool OnSave(object entity, object id, object[] state, string[] propertyNames, IType[] types)
 {
     string msg = " Save       :" + entity.GetType().FullName;
     log.Debug(msg);
     invalidUpdates.Add(msg);
     return false;
 }

 public override void OnDelete(object entity, object id, object[] state, string[] propertyNames, IType[] types)
 {
     string msg = " Delete     :" + entity.GetType().FullName;
     log.Debug(msg);
     invalidUpdates.Add(msg);
 }
}

As you can see I’m interested in : unexpected Flush of dirty instance, unexpected Saves and unexpected Deletes.

The PersistingMappings is my “driver” to test each entity. The responsibility of the method is iterate each persistent class known by the SessionFactory (or the selected in UnexpectedUpdateDeleteOnFetchSpecific methods), run the test of each entity and reports all issues found.

private void PersistingMappings(ICollection<string> entitiesFilter)
{
 var invalidUpdates = new List<string>();
 var nop = new NoUpdateInterceptor(invalidUpdates);

 IEnumerable<string> entitiesToCheck;
 if (entitiesFilter == null)
 {
     entitiesToCheck = cfg.ClassMappings.Select(x => x.EntityName);
 }
 else
 {
     entitiesToCheck = from persistentClass in cfg.ClassMappings
                       where entitiesFilter.Contains(persistentClass.EntityName)
                       select persistentClass.EntityName;
 }

 foreach (var entityName in entitiesToCheck)
 {
     EntityPersistenceTest(invalidUpdates, entityName, nop);
 }

 if (invalidUpdates.Count > 0)
 {
     if (logError.IsDebugEnabled)
     {
         logError.Debug("  ");
         logError.Debug("------ INVALID UPDATES -------");
         invalidUpdates.ForEach(x => logError.Debug(x));
         logError.Debug("------------------------------");
     }
 }
 Assert.AreEqual(0, invalidUpdates.Count, "Has unexpected updates.");
}

To check each persistent entity I’m using the Configuration.ClassMappings collection and extracting the EntityName from the PersistentClass. The use of EntityName don’t mean that I’m using the tag entity-name (as you can see in the mapping above).

The real “ghostbuster” is:

private void EntityPersistenceTest(ICollection<string> invalidUpdates,
 string entityName, IInterceptor nop)
{
 const string queryTemplate = "select e.{0} from {1} e";
 string msg = "s--------" + entityName;
 log.Debug(msg);

 using (var s = sessions.OpenSession(nop))
 using (var tx = s.BeginTransaction())
 {
     IList entityIds = null;
     try
     {
         string queryString = string.Format(queryTemplate, DefaultIdName, entityName);
         entityIds = s.CreateQuery(queryString).SetMaxResults(1).List();
     }
     catch (Exception e)
     {
         log.Debug("Possible METEORITE:" + e.Message);
     }

     if (entityIds != null)
     {
         if (entityIds.Count == 0 || entityIds[0] == null)
         {
             log.Debug("No instances");
         }
         else
         {
             if (entityIds.Count > 1)
             {
                 msg = ">Has " + entityIds.Count + " subclasses";
                 log.Debug(msg);
             }
             object entityId = entityIds[0];
             try
             {
                 s.Get(entityName, entityId);
                 try
                 {
                     s.Flush();
                 }
                 catch (Exception ex)
                 {
                     string emsg = string.Format("EXCEPTION - Flushing entity [#{0}]: {1}", entityId, ex.Message);
                     log.Debug(emsg);
                     invalidUpdates.Add(emsg);
                 }
             }
             catch (Exception ex)
             {
                 string emsg = string.Format("EXCEPTION - Getting [#{0}]: {1}", entityId, ex.Message);
                 invalidUpdates.Add(emsg);
                 log.Debug(emsg);
             }
         }
         tx.Rollback();
     }
 }
 msg = "e--------" + entityName;
 log.Debug(msg);
}

The core of the test is:

s.Get(entityName, entityId);
s.Flush();

If I Get an entity, from a clear fresh session, without touch the state what I’m expect is that the follow Flush don’t make absolutely nothing but… you know… perhaps there is an ugly “ghost”. Each try-catch are checking some special situation.

And now lets go to run the “ghostbuster” in your application. Code available here.

NHibernate blog : mapping, NHibernate

NHibernate Auditing v3 – Poor Man’s Envers

How Test your mappings: the Ghostbuster

The Ghostbusters