To start working with Envers, all configuration that you must do is add the
event listeners to persistence.xml, as described in the
quick start.
However, as Envers generates some tables, it is possible to set the prefix and suffix that is added to the entity name to create a versions table for an entity, as well as set the names of the fields that are generated.
In more detail, here are the properites that you can set:
| Property name | Default value | Description |
| org.jboss.envers.versionsTablePrefix | String that will be prepended to the name of a versioned entity to create the name of the entity, that will hold version information. | |
| org.jboss.envers.versionsTableSuffix | _versions | String that will be appended to the name of a versioned entity
to create the name of the entity, that will hold version information. If you version
an entity with a table name Person, in the default setting Envers will
generate a Person_versions table to store historical data.
|
| org.jboss.envers.revisionFieldName | _revision | Name of a field in the versions entity that will hold the revision number. |
| org.jboss.envers.revisionTypeFieldName | _revision_type | Name of a field in the versions entity that will hold the type of the revision (currently, this can be: add, mod, del). |
| org.jboss.envers.revisionOnCollectionChange | true | Should a revision be generated when a not-owned relation field changes (this can be either a collection in a one-to-many relation, or the field using "mappedBy" attribute in a one-to-one relation). |
| org.jboss.envers.warnOnUnsupportedTypes | false | When true, a warning in the log will be issued when a property is versioned with an unsupported type, instead of an exception. This way, the configuration process isn't interrupted, but the version schema isn't complete (it lacks the unsupported properties, which won't be versioned). |
| org.jboss.envers.unversionedOptimisticLockingField | false | When true, properties to be used for optimistic locking, annotated with @Version, will be automatically unversioned (their history won't be stored; it normally doesn't make sense to store it). |
To change the name of the revision table and its fields (the table, in which the numbers of
revisions and their timestamps are stored), you can use
the @RevisionEntity annotation. For more information, see
here (near the end of the page).
To set the value of any of the properties described above, simply add an entry
to your persistence.xml. For example:
<persistence-unit ...>
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<class>...</class>
<properties>
<property name="hibernate.dialect" ... />
<!-- other hibernate properties -->
<property name="hibernate.ejb.event.post-insert"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="hibernate.ejb.event.post-update"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="hibernate.ejb.event.post-delete"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="hibernate.ejb.event.pre-collection-update"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="hibernate.ejb.event.pre-collection-remove"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="hibernate.ejb.event.post-collection-recreate"
value="org.jboss.envers.event.VersionsEventListener" />
<property name="org.jboss.envers.versionsTableSuffix" value="_V" />
<property name="org.jboss.envers.revisionFieldName" value="ver_rev" />
<!-- other envers properties -->
</properties>
</persistence-unit>
You can also set the name of the versions table on a per-entity basis, using
the @VersionsTable annotation (javadoc).
It may be tedious to add this annotation to every versioned entity, so if possible,
it's better to use a prefix/suffix.
If you have a mapping with secondary tables, version tables for them will be generated
in the same way (by adding the prefix and suffix). If you wish to overwrite this
behaviour, you can use the @SecondaryVersionsTable and
@SecondaryVersionsTables annotations.
If you want to version a relation mapped with @OneToMany+@JoinColumn,
please see here for a description of the additional
@VersionsJoinTable annotation that you'll probably want to use.