Teneo/Hibernate/Auditing

Teneo supports auditing (from November 2012), a summary of the functionality:

• auditing can be enabled for specific types
• earlier versions of objects can be retrieved
• possible to navigate/iterate over the history of an object
• query for version history using attribute and ereference values

Enable auditing

Auditing can be enabled by calling setAuditing(true) on the datastore or setting the enable auditing option to true (see next section). To prevent auditing of specific types you can use the @NoAuditing annotation. Set this annotation in the EMF EAnnotation of the EClass using source 'teneo.jpa' and key 'value'.

Audit Entries

When auditing is enabled then each database action on an entity are persisted in a separate table. Teneo will generate a separate additional type for each audited type, these audit types/eclasses are generated and mapped at runtime.

Each audit EClass models the audit entries for a domain EClass, its audit entries are stored in a separate table. Teneo will store three types of events: ADD, UPDATE and DELETE.

Teneo provides an api to retrieve the audit entries, this is described in more detail below.

Auditing Options

Teneo has many configuration options, three options are specific for auditing:

• ENABLE_AUDITING (teneo.mapping.auditing.enable): default is false, enables auditing if set to "true"
• AUDITING_ENTITY_PREFIX (teneo.naming.auditing.entity.prefix): defines the prefix which is set before the EClass name, this is used to compute the entity name and the table name used to store auditing entries.
• AUDITING_ENTITY_POSTFIX (teneo.naming.auditing.entity.postfix): (default is 'Auditing') defines the prefix which is set before the EClass name, this is used to compute the entity name and the table name used to store auditing entries.

Retrieving Audit Entries

Audit entries can be retrieved using the AuditVersionProvider. The AuditVersionProvider can be retrieved from the data store using the getAuditVersionProvider method.

By Object

The AuditVersionProvider provides several methods to retrieve the history of an object. You can retrieve the latest audit entries or all audit entries for an object. See the getAllAuditEntries, getLatestAuditEntry methods.

From an audit entry you can find the next or previous entries using the getNextEntry and getPreviousEntry methods of the AuditVersionProvider.

Query

Each audit type/EClass is mapped to hibernate as a standard type. This means that you can query for audit entries using HQL.

Some things to note when querying:

• Selecting on primitive types can be done in the same way as for the standard type.
• the EClass name of the audit entry is controlled by the options discussed above, as a default the term Auditing is appended to the original EClass name, so if the domain EClass is Book, then the auditing EClass will be BookAuditing.
• Teneo stores all references as strings, so association joining is not directly possible. Also when filtering on an EReference association you should use the id string representation of an entity. To get the id string representation call the getIdString method on the AuditVersionProvider.

This code snipper illustrates how to query for audit entries:

final AuditVersionProvider vp = testStore.getEmfDataStore().getAuditVersionProvider();
// select on pages and the author
final Query qry = testStore.getSession().createQuery("select e from BookAuditing e where pages=1 and author=:author");
// set the author parameter, create the id string using the getIdString method.
qry.setParameter("author", vp.getIdString(writer));
final List<?> list = qry.list();

Test cases

The following test cases give examples on how to iterate over audit entries or query for audit entries:

• SimpleLibraryAuditingAction.java
• EMapAuditingTrueEMapAction.java

Revisions

An audit entry represents the state at a certain point in time. Teneo also provides an api to get the actual instance with the values/references at a certain timestamp. The special feature is that also referenced objects are in the same state.

For example, a Book references a Writer. When retrieving a Book in the state it has on the 1st of September 2011, then the referenced Writer will also be in the state for the 1st of September 2011.

To get actual instances you can use the getRevision methods of the AuditVersionProvider class.

Note that the AuditVersionProvider internally uses a Resource to resolve proxies against the audit entries in the database. This means that revisions retrieved through the getRevision method are part of a resource.

If a referenced entity is not audited (so there are no audit entries in the database) then the referenced entity is read from the database directly.

Limitations

Auditing does not work in combination with specific functionality:

• EmbeddedId is not supported, this is neither supported with Hibernate envers.
• EAV mapping can not be combined with auditing. This can be solved, but requires some additional work, please ask on the newsgroup if relevant for your case.
• Embeddable/Embedded works fine in combination with auditing, but only if annotated in the model, so not using a separate xml/hbm mapping file. This can be solved, but needs some additional work, please ask on the newsgroup if relevant for your case.
• the delete audit entry does not contain any collection values