org.hibernate.envers
Interface AuditReader

All Known Subinterfaces:

AuditReaderImplementor

All Known Implementing Classes:

AuditReaderImpl

public interface AuditReader

Method Summary

AuditQueryCreator	createQuery()
<T> T	find(Class<T> cls, Object primaryKey, Number revision) Find an entity by primary key at the given revision.
<T> T	find(Class<T> cls, String entityName, Object primaryKey, Number revision) Find an entity by primary key at the given revision with the specified entityName.
<T> T	findRevision(Class<T> revisionEntityClass, Number revision) A helper method; should be used only if a custom revision entity is used.
<T> Map<Number,T>	findRevisions(Class<T> revisionEntityClass, Set<Number> revisions) Find a map of revisions using the revision numbers specified.
CrossTypeRevisionChangesReader	getCrossTypeRevisionChangesReader()
<T> T	getCurrentRevision(Class<T> revisionEntityClass, boolean persist) Gets an instance of the current revision entity, to which any entries in the audit tables will be bound.
String	getEntityName(Object primaryKey, Number revision, Object entity)
Date	getRevisionDate(Number revision) Get the date, at which a revision was created.
Number	getRevisionNumberForDate(Date date) Gets the revision number, that corresponds to the given date.
List<Number>	getRevisions(Class<?> cls, Object primaryKey) Get a list of revision numbers, at which an entity was modified.
List<Number>	getRevisions(Class<?> cls, String entityName, Object primaryKey) Get a list of revision numbers, at which an entity was modified, looking by entityName.
boolean	isEntityClassAudited(Class<?> entityClass) Checks if the entityClass was configured to be audited.
boolean	isEntityNameAudited(String entityName) Checks if the entityName was configured to be audited.

Method Detail

find

<T> T find(Class<T> cls,
           Object primaryKey,
           Number revision)
       throws IllegalArgumentException,
              NotAuditedException,
              IllegalStateException

Find an entity by primary key at the given revision.

Parameters:

cls - Class of the entity.

primaryKey - Primary key of the entity.

revision - Revision in which to get the entity.

Returns:

The found entity instance at the given revision (its properties may be partially filled if not all properties are audited) or null, if an entity with that id didn't exist at that revision.

Throws:

IllegalArgumentException - If cls or primaryKey is null or revision is less or equal to 0.

NotAuditedException - When entities of the given class are not audited.

IllegalStateException - If the associated entity manager is closed.

find

<T> T find(Class<T> cls,
           String entityName,
           Object primaryKey,
           Number revision)
       throws IllegalArgumentException,
              NotAuditedException,
              IllegalStateException

Find an entity by primary key at the given revision with the specified entityName.

Parameters:

cls - Class of the entity.

entityName - Name of the entity (if can't be guessed basing on the cls).

primaryKey - Primary key of the entity.

revision - Revision in which to get the entity.

Returns:

The found entity instance at the given revision (its properties may be partially filled if not all properties are audited) or null, if an entity with that id didn't exist at that revision.

Throws:

IllegalArgumentException - If cls or primaryKey is null or revision is less or equal to 0.

NotAuditedException - When entities of the given class are not audited.

IllegalStateException - If the associated entity manager is closed.

getRevisions

List<Number> getRevisions(Class<?> cls,
                          Object primaryKey)
                          throws IllegalArgumentException,
                                 NotAuditedException,
                                 IllegalStateException

Get a list of revision numbers, at which an entity was modified.

Parameters:

cls - Class of the entity.

primaryKey - Primary key of the entity.

Returns:

A list of revision numbers, at which the entity was modified, sorted in ascending order (so older revisions come first).

Throws:

NotAuditedException - When entities of the given class are not audited.

IllegalArgumentException - If cls or primaryKey is null.

IllegalStateException - If the associated entity manager is closed.

getRevisions

List<Number> getRevisions(Class<?> cls,
                          String entityName,
                          Object primaryKey)
                          throws IllegalArgumentException,
                                 NotAuditedException,
                                 IllegalStateException

Get a list of revision numbers, at which an entity was modified, looking by entityName.

Parameters:

cls - Class of the entity.

entityName - Name of the entity (if can't be guessed basing on the cls).

primaryKey - Primary key of the entity.

Returns:

A list of revision numbers, at which the entity was modified, sorted in ascending order (so older revisions come first).

Throws:

NotAuditedException - When entities of the given class are not audited.

IllegalArgumentException - If cls or primaryKey is null.

IllegalStateException - If the associated entity manager is closed.

getRevisionDate

Date getRevisionDate(Number revision)
                     throws IllegalArgumentException,
                            RevisionDoesNotExistException,
                            IllegalStateException

Get the date, at which a revision was created.

Parameters:

revision - Number of the revision for which to get the date.

Returns:

Date of commiting the given revision.

Throws:

IllegalArgumentException - If revision is less or equal to 0.

RevisionDoesNotExistException - If the revision does not exist.

IllegalStateException - If the associated entity manager is closed.

getRevisionNumberForDate

Number getRevisionNumberForDate(Date date)
                                throws IllegalStateException,
                                       RevisionDoesNotExistException,
                                       IllegalArgumentException

Gets the revision number, that corresponds to the given date. More precisely, returns the number of the highest revision, which was created on or before the given date. So: getRevisionDate(getRevisionNumberForDate(date)) <= date and getRevisionDate(getRevisionNumberForDate(date)+1) > date.

Parameters:

date - Date for which to get the revision.

Returns:

Revision number corresponding to the given date.

Throws:

IllegalStateException - If the associated entity manager is closed.

RevisionDoesNotExistException - If the given date is before the first revision.

IllegalArgumentException - If date is null.

findRevision

<T> T findRevision(Class<T> revisionEntityClass,
                   Number revision)
               throws IllegalArgumentException,
                      RevisionDoesNotExistException,
                      IllegalStateException

A helper method; should be used only if a custom revision entity is used. See also RevisionEntity.

Parameters:

revisionEntityClass - Class of the revision entity. Should be annotated with RevisionEntity.

revision - Number of the revision for which to get the data.

Returns:

Entity containing data for the given revision.

Throws:

IllegalArgumentException - If revision is less or equal to 0 or if the class of the revision entity is invalid.

RevisionDoesNotExistException - If the revision does not exist.

IllegalStateException - If the associated entity manager is closed.

findRevisions

<T> Map<Number,T> findRevisions(Class<T> revisionEntityClass,
                                Set<Number> revisions)
                            throws IllegalArgumentException,
                                   IllegalStateException

Find a map of revisions using the revision numbers specified.

Parameters:

revisionEntityClass - Class of the revision entity. Should be annotated with RevisionEntity.

revisions - Revision numbers of the revision for which to get the data.

Returns:

A map of revision number and the given revision entity.

Throws:

IllegalArgumentException - If a revision number is less or equal to 0 or if the class of the revision entity is invalid.

IllegalStateException - If the associated entity manager is closed.

getCurrentRevision

<T> T getCurrentRevision(Class<T> revisionEntityClass,
                         boolean persist)

Gets an instance of the current revision entity, to which any entries in the audit tables will be bound. Please note the if persist is false, and no audited entities are modified in this session, then the obtained revision entity instance won't be persisted. If persist is true, the revision entity instance will always be persisted, regardless of whether audited entities are changed or not.

Parameters:

revisionEntityClass - Class of the revision entity. Should be annotated with RevisionEntity.

persist - If the revision entity is not yet persisted, should it become persisted. This way, the primary identifier (id) will be filled (if it's assigned by the DB) and available, but the revision entity will be persisted even if there are no changes to audited entities. Otherwise, the revision number (id) can be null.

Returns:

The current revision entity, to which any entries in the audit tables will be bound.

createQuery

AuditQueryCreator createQuery()

Returns:

A query creator, associated with this AuditReader instance, with which queries can be created and later executed. Shouldn't be used after the associated Session or EntityManager is closed.

isEntityClassAudited

boolean isEntityClassAudited(Class<?> entityClass)

Checks if the entityClass was configured to be audited. Calling isEntityNameAudited() with the string of the class name will return the same value.

Parameters:

entityClass - Class of the entity asking for audit support

Returns:

true if the entityClass is audited.

isEntityNameAudited

boolean isEntityNameAudited(String entityName)

Checks if the entityName was configured to be audited.

Parameters:

entityName - EntityName of the entity asking for audit support.

Returns:

true if the entityName is audited.

getEntityName

String getEntityName(Object primaryKey,
                     Number revision,
                     Object entity)
                     throws HibernateException

Parameters:

entity - that was obtained previously from the same AuditReader.

Returns:

the entityName for the given entity, null in case the entity is not associated with this AuditReader instance.

Throws:

HibernateException

getCrossTypeRevisionChangesReader

CrossTypeRevisionChangesReader getCrossTypeRevisionChangesReader()
                                                                 throws AuditException

Returns:

Basic implementation of CrossTypeRevisionChangesReader interface. Raises an exception if the default mechanism of tracking entity names modified during revisions has not been enabled.

Throws:

AuditException - If none of the following conditions is satisfied:

• org.hibernate.envers.track_entities_changed_in_revision parameter is set to true.
• Custom revision entity (annotated with RevisionEntity) extends DefaultTrackingModifiedEntitiesRevisionEntity base class.
• Custom revision entity (annotated with RevisionEntity) encapsulates a field marked with ModifiedEntityNames interface.