Auditing with OpenJPA

A transactional application often requires to audit the persistent entities. In this brief example, I will present a small code example to outline how an application can audit changes via the life cycle callback methods. The JPA specification prescribes how an entity or a separate, stateless entity listener instance can receive callback notification during various life cycle state transition of an entity. Seven transition events are defined: PrePersist, PostPersist, PreRemove, PostRemove, PreUpdate, PostUpdate and PostLoad. To receive these callbacks either annotate certain methods a) of the entity class itself or b) of a separate entity listener class. The signature of the method in the entity class itself should be

void <METHOD>()

Whereas, callback methods defined on an entity listener class have the following signature

void <METHOD>(Object pc)

In the later case, the managed entity is passed as an argument.

Given this basic framework, how can we implement audit facility such that an application can track any update made on a persistent entity? Of course, to compute this change, the application must be able to access the entity state before and after the update. The central question is:

how can an application access the previous state of an entity inside a callback method?

The answer lies in the fact that OpenJPA can store the state of an entity as it enters the managed lifecycle. This internal copy is used by OpenJPA when a transaction is rolled back. The state of the entities participating in the failed transaction is restored to the original state i.e. as it were before the transaction started. The simple example presented here shows how to access that copy. Of course, a real audit facility has to figure out how to compute the difference between the current and previous state of an entity and where to record those differences.

Let us consider a simple persistent instance, audit.PObject.

   1:  package audit;
   2:  
  3:  import javax.persistence.Entity;
  4:  import javax.persistence.Id;
  5:  import javax.persistence.PostUpdate;
  6:  
  7:  import org.apache.openjpa.enhance.PersistenceCapable;
  8:  import org.apache.openjpa.kernel.SaveFieldManager;
  9:  import org.apache.openjpa.kernel.StateManagerImpl;
 10:  
 11:  @Entity
 12:  public class PObject {
 13:      @Id
 14:      private long id;
 15:     
  16:      private String name;
 17:  
 18:      public long getId() {
 19:          return id;
 20:      }
 21:  
 22:      public void setId(long id) {
 23:          this.id = id;
 24:      }
 25:  
 26:      public String getName() {
 27:          return name;
 28:      }
 29:  
 30:      public void setName(String name) {
 31:          this.name = name;
 32:      }
 33:     
  34:      @PostUpdate
 35:      public void audit() {
 36:          PersistenceCapable currentState = (PersistenceCapable)this;
  37:          StateManagerImpl sm = (StateManagerImpl)currentState.pcGetStateManager();
 38:          SaveFieldManager sfm = sm.getSaveFieldManager();
 39:          PersistenceCapable oldState = sfm.getState();
 40:          PObject old = (PObject)oldState;
 41:         
  42:          System.err.println("old     : " + old);
 43:          System.err.println("current : " + this);
 44:      }
 45:     
  46:      public String toString() {
 47:          return this.getClass().getName()+"@"
 48:               + Integer.toHexString(System.identityHashCode(this))
  49:               + "[" + name +"]";
 50:      }
 51:  }

The meat is in audit() method annotated with @PostUpdate to receive the callback notification. Now, within the method body, following steps are carried out to access the previous state of the instance.

Line 36: Cast this instance to org.apache.openjpa.enhance.PersistenceCapable interface. The cast is safe. Because OpenJPA ensures that every persistent class implements PersistenceCapable. OpenJPA actually modifies original bytecode of audit.PObject class. This bytecode modification process is called enhancement and is described in detail in OpenJPA documentation.

Line 37: Get the StateManager. Every PersistenceCapable instance is managed by a StateManager. It is the StateManager who intercepts every access and mutation of entity state and calls the requisite underlying OpenJPA infrastructure to load or store the state of an entity which in turn may access the database via JDBC.

Line 38: Get the SaveFieldManager. A StateManager may refer to a SaveFieldManager to which StateManager delegates the task of maintaining a copy of managed instance.

Line 39: Get the old state. The old state is maintained by the SaveFieldManager.

Line 40: Cast is back to audit.PObject. This entity refers to the state of PObject as it entered a transaction.

At this point, a real audit application perhaps will do some sort of state comparison to determine what has changed between current and the previous state of this instance. I am just printing their values on the console.

Now let us write a simple "Hellow JPA World" style application to check that the callback is received. I am omitting the scaffolding code to get a JPA EntityManagerFactory etcetera and just listing the transactional method.

   1:      public void testPostPersistCallabck() {
  2:          EntityManager em = emf.createEntityManager();
  3:          em.getTransaction().begin();
  4:          PObject pc = new PObject();
  5:          pc.setId(1001);
  6:          pc.setName("X");
   7:          em.persist(pc);
  8:          em.getTransaction().commit();
   9:          Object pid = pc.getId();
 10:          em.clear();
 11:         
  12:          em = emf.createEntityManager();
 13:          em.getTransaction().begin();
 14:          PObject audit = em.find(PObject.class, pid);
 15:          audit.setName("Y");
 16:          em.getTransaction().commit();
 17:      }

When this code runs on my laptop against a MySQL database, that is what it prints out (hand-edited to show only the generated SQL and System.err.println() output)

203  test  INFO   [main] openjpa.jdbc.JDBC - Using dictionary class "org.apache.openjpa.jdbc.sql.MySQLDictionary".
1078  test  TRACE  [main] openjpa.jdbc.SQL - <t 21933769, conn 11875256> executing prepstmnt 7245716 INSERT INTO PObject (id, name) VALUES (?, ?) [params=(long) 1001, (String) X]
1156  test  TRACE  [main] openjpa.jdbc.SQL - <t 21933769, conn 23978087> executing prepstmnt 1440568 SELECT t0.name FROM PObject t0 WHERE t0.id = ? [params=(long) 1001]
1172  test  TRACE  [main] openjpa.jdbc.SQL - <t 21933769, conn 14837200> executing prepstmnt 30702379 UPDATE PObject SET name = ? WHERE id = ? [params=(String) Y, (long) 1001]

old     : audit.PObject@1581e80[X]
current : audit.PObject@3a9d95[Y]

As the last two lines of log output shows, the audit() callback has been invoked and the method had printed the state of the instance as it were before its name is changed from "X" to "Y".

The two critical points before we close.

• This technique only works with build-time enhancement.
  

• OpenJPA must be configured to record the state of persistent entities participating in a transaction. This is specified by the following property:

            <property name="openjpa.RestoreState" value="all"/>