HowTo ChangeLog with JPA

The problem
In almost all projects which have some kind of administrative functionality, there is a need to keep track of changes done to the data.

If we take a car rental store as example, it is good to know who reserved a car and who changed a reservation.

Our entity looks like the following (only the important parts of classes are shown here)

@Entity
public class CarReservation {
@Id, @Version ..
private Car car;
private @Temporal.. Date reservedFrom;
private @Temporal.. Date reservedUntil;
private Customer reservedFor;
.. getters and setters
}


Now let’s consider that the customer calls our shop and likes to move his reservation to a slightly different date. The clerk officer opens the reservation and changes it accordingly. Too bad that he edited the wrong reservation and saved it. Even if he recognises his error quickly, he has no chance to revert the wrong reservation back to the correct values, because they didn’t got stored in the system.

The solution
JPA provides a nice way to receive lifecycle callbacks JPA2 JavaDoc.
We need to somehow get the old values at the time we store the changes in our entity so we can create a ‘diff’. Since there always exists exactly 1 instance of a DB entry per EntityManager, we don’t have a chance to get those old values at save time. There exists a dirty trick with opening a new EntityManager inside the save operation, but that doesn’t perform well. The way I get my hands on the old values is to store them in a Map at load time by utilising @PostLoad via a EntityListener.

The single parts involved in the magic:

• The TrackChangesListener which listens to @PostLoad and @PreUpdate JPA events
• A new @TrackChanges annotation which marks entity fields as being subject to be tracked
• A new @ChangeLog annotation which mark the one String @Lob field to stores the changeLog
• An Editor component which ThreadLocally stores the oldValues and knows which entities are currently being edited (for performance reasons). It also knows the current user so we can also store who edited the entry.

How our Car entity looks after we applied the changelog functionality:

@Entity
@EntityListeners({TrackChangesListener.class})
public class CarReservation {
  @Id, @Version ..

  private @TrackChanges Car car;
  private @TrackChanges @Temporal.. Date reservedFrom;
  private @TrackChanges @Temporal.. Date reservedUntil;
  private @TrackChanges Customer reservedFor;
  private @ChangeLog @Lob String changeLog;
  .. getters and setters
}


And here comes the code:

First the annotations:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface TrackChanges {
}

and

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ChangeLog {
}


And here comes the most important part, the EntityListener:

public class TrackChangesListener
{
    @PostLoad
    public void loadOldData(Object he) {
        if (!Editor.isEdited(he)) {
            return;
        }

        Map oldData = new HashMap();

        collectOldValues(oldData, "", he);

        Editor.setOldData(he, oldData);
    }

    private void collectOldValues(Map oldData, String prefix, Object he)
    {
        List historisedFields = getHistorisedFields(he);

        for (Field field : historisedFields) {
            field.setAccessible(true);
            try
            {
                if (field.getAnnotation(Embedded.class) != null) {
                    Object value = field.get(he);
                    if (value != null) {
                        // recurse into the Embedded field
                        collectOldValues(oldData, prefix + field.getName() + ".", value);
                    }
                }
                else {
                    oldData.put(prefix + field.getName(), field.get(he));
                }
            }
            catch (IllegalAccessException e)
            {
                throw new RuntimeException(e);
            }
        }
    }

    @PreUpdate
    public void updateChangeLog(Object he) {
        if (!Editor.isEdited(he)) {
            return;
        }

        try
        {
            Field changeLogField = getChangeLogField(he);
            Validate.notNull(changeLogField, "could not find @ChangeLog field in Class " + he.getClass().getName());

            StringBuilder changeLog = new StringBuilder();
    
            String changeLogValue = (String) changeLogField.get(he);

            if (changeLogValue != null) {
                changeLog.append(changeLogValue).append("\n\n");
            }

            changeLog.append("changedBy " ).append(Editor.getUser());
            changeLog.append(" on ").append((new Date()).toGMTString()).append('\n');

            boolean changed = false;

            changed = collectChanges(changeLog, Editor.getOldData(he), "", he);

            // update the changeLog field if a trackable change was detected
            if (changed) {
                changeLogField.set(he, changeLog.toString());
            }
        }
        catch (IllegalAccessException e)
        {
            throw new RuntimeException(e);
        }
    }

    private Field getChangeLogField(Object he)
    {
        Field[] fields = he.getClass().getDeclaredFields();

        for (Field field : fields) {
            if (field.getAnnotation(ChangeLog.class) != null) {
                field.setAccessible(true);
                return field;
            }
        }
        return null;
    }

    private boolean collectChanges(StringBuilder changeLog, Map oldData, String prefix, Object he)
    {
        boolean changed = false;
        List historisedFields = getHistorisedFields(he);
        for (Field field : historisedFields) {
            field.setAccessible(true);
            String fieldName = field.getName();
            try
            {
                if (field.getAnnotation(Embedded.class) != null) {
                    Object value = field.get(he);
                    if (value != null) {
                        // recurse into the Embedded field
                        changed |= collectChanges(changeLog, oldData, prefix + field.getName() + ".", value);
                    }
                }
                else {
                    Object newValue = field.get(he);
                    Object oldValue = oldData.get(prefix + fieldName);
                    changed |= addChangeLine(changeLog, prefix + fieldName, oldValue, newValue);
                }
            }
            catch (IllegalAccessException e)
            {
                throw new RuntimeException(e);
            }
        }
        return changed;
    }

    private boolean addChangeLine(StringBuilder changeLog, String fieldName, Object oldValue, Object newValue)
    {
        if (oldValue == null && newValue == null) {
            return false;
        }
        if (oldValue != null && oldValue.equals(newValue)) {
            // no change
            return false;
        }

        String changeLine = fieldName + " old: [" + (oldValue != null ? oldValue : "") + "] new: [" + (newValue != null ? newValue : "") + "]\n";
        changeLog.append(changeLine);
        return true;
    }


    private List getHistorisedFields(Object he)
    {
        Field[] fields = he.getClass().getDeclaredFields();
        List histFields = new ArrayList();

        for (Field field : fields) {
            if (field.getAnnotation(TrackChanges.class) != null) {
                histFields.add(field);
            }
        }

        return histFields;
    }

}