org.jboss.envers
Interface VersionsReader

public interface VersionsReader

Author:

Adam Warski (adam at warski dot org)

Method Summary

VersionsQueryCreator	createQuery()
<T> T	find(java.lang.Class<T> cls, java.lang.Object primaryKey, java.lang.Number revision) Find an entity by primary key at the given revision.
<T> T	findRevision(java.lang.Class<T> revisionEntityClass, java.lang.Number revision) A helper method; should be used only if a custom revision entity is used.
java.util.Date	getRevisionDate(java.lang.Number revision) Get the date, at which a revision was created.
java.lang.Number	getRevisionNumberForDate(java.util.Date date) Gets the revision number, that corresponds to the given date.
java.util.List<java.lang.Number>	getRevisions(java.lang.Class<?> cls, java.lang.Object primaryKey) Get revisions, at which an entity was modified.

Method Detail

find

<T> T find(java.lang.Class<T> cls,
           java.lang.Object primaryKey,
           java.lang.Number revision)
       throws java.lang.IllegalArgumentException,
              NotVersionedException,
              java.lang.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 versioned) or null, if an entity with that id didn't exist at that revision.

Throws:

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

NotVersionedException - When entities of the given class are not versioned.

java.lang.IllegalStateException - If the associated entity manager is closed.

getRevisions

java.util.List<java.lang.Number> getRevisions(java.lang.Class<?> cls,
                                              java.lang.Object primaryKey)
                                              throws java.lang.IllegalArgumentException,
                                                     NotVersionedException,
                                                     java.lang.IllegalStateException

Get revisions, at which an entity was modified. Warning! Only revisions, at which properties that the entity "owns" changed will be returned. Properties not owned by an entity are:

• @OneToOne(mappedBy="...")
• @OneToMany

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.

Throws:

NotVersionedException - When entities of the given class are not versioned.

java.lang.IllegalArgumentException - If cls, primaryKey is null.

java.lang.IllegalStateException - If the associated entity manager is closed.

getRevisionDate

java.util.Date getRevisionDate(java.lang.Number revision)
                               throws java.lang.IllegalArgumentException,
                                      RevisionDoesNotExistException,
                                      java.lang.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:

java.lang.IllegalArgumentException - If revision is less or equal to 0.

RevisionDoesNotExistException - If the revision does not exist.

java.lang.IllegalStateException - If the associated entity manager is closed.

getRevisionNumberForDate

java.lang.Number getRevisionNumberForDate(java.util.Date date)
                                          throws java.lang.IllegalStateException,
                                                 RevisionDoesNotExistException,
                                                 java.lang.IllegalArgumentException

Gets the revision number, that corresponds to the given date. More precisely, returns the number of the highest revision, which was created 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:

java.lang.IllegalStateException - If the associated entity manager is closed.

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

java.lang.IllegalArgumentException - If date is null.

findRevision

<T> T findRevision(java.lang.Class<T> revisionEntityClass,
                   java.lang.Number revision)
               throws java.lang.IllegalArgumentException,
                      RevisionDoesNotExistException,
                      java.lang.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:

java.lang.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.

java.lang.IllegalStateException - If the associated entity manager is closed.

createQuery

VersionsQueryCreator createQuery()

Returns:

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