Interface AuditLog

All Superinterfaces:
AutoCloseable
public interface AuditLog extends AutoCloseable
A service for querying the audit log. Provides access to revision history and modification types for audited entities, complementing the transparent point-in-time reads available via atChangeset() sessions.

Obtain an instance via AuditLogFactory.create(SessionFactory). The instance manages an internal session for audit queries; close it when done to release the session and its JDBC connection.

Since:
7.4
See Also:

  • Field Details

    • ALL_CHANGESETS

      static final Object ALL_CHANGESETS
      A special changeset identifier that selects all historical revisions from an audit log table without filtering. Pass this magic value to atChangeset() to obtain a session that reads all audit rows, including deletions.

      Usage: 

      try (var s = sf.withOptions()
        .atChangeset(AuditLog.ALL_CHANGESETS).open()) {
    var history = s.createSelectionQuery(
            "from MyEntity where id = :id",
            MyEntity.class)
        .setParameter("id", entityId)
        .getResultList();
}
      See Also:

  • Method Details

    • close

      void close()
      Close this audit log and release its internal session.
      Specified by:
      close in interface AutoCloseable

    • getChangesets

      List<Object> getChangesets(Class<?> entityClass, Object id)
      List all changeset identifiers where the given entity was modified, ordered chronologically.
      Parameters:
      entityClass - the audited entity class
      id - the entity identifier
      Returns:
      the list of changeset identifiers

    • getModificationType

      ModificationType getModificationType(Class<?> entityClass, Object id, Object changesetId)
      Get the modification type (ADD/MOD/DEL) for an entity at a specific changeset.
      Parameters:
      entityClass - the audited entity class
      id - "at the entity identifier
      changesetId - the changeset identifier
      Returns:
      the modification type, or null if the entity was not modified in that changeset

    • isAudited

      boolean isAudited(Class<?> entityClass)
      Check if an entity type is audited.
      Parameters:
      entityClass - the entity class
      Returns:
      true if the entity is audited

    • find

      <T> T find(Class<T> entityClass, Object id, Object changesetId)
      Find an entity snapshot as of a specific changeset, that is, immediately after the changeset was applied. Returns the state at the most recent revision at or before the given changeset.
      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      id - the entity identifier
      changesetId - the changeset identifier
      Returns:
      the entity state in that changeset, or null if the entity did not exist (e.g. before creation or after deletion)

    • find

      <T> T find(Class<T> entityClass, Object id, Object changesetId, boolean includeDeletions)
      Find an entity snapshot as of a specific changeset, that is, immediately after the changeset was applied, optionally including deleted entities.

      When includeDeletions is false, this behaves identically to find(Class, Object, Object), returning null for DEL revisions. When true, the entity state at deletion is returned instead of null.

      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      id - the entity identifier
      changesetId - the changeset identifier
      includeDeletions - whether to include deleted entities
      Returns:
      the entity state in that changeset

    • find

      <T> T find(Class<T> entityClass, Object id, Instant instant)
      Find an entity snapshot as of the given instant. Returns the state at the highest revision on or before the instant.
      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      id - the entity identifier
      instant - the point in time
      Returns:
      the entity state, or null

    • findEntitiesModifiedAt

      <T> List<T> findEntitiesModifiedAt(Class<T> entityClass, Object changesetId)
      Find all entity snapshots of the given type that were modified in a specific changeset.
      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      changesetId - the changeset identifier
      Returns:
      the entity snapshots modified in that changeset

    • findEntitiesModifiedAt

      <T> List<T> findEntitiesModifiedAt(Class<T> entityClass, Object changesetId, ModificationType modificationType)
      Find all entity snapshots of the given type that were modified in a specific changeset with the specified modification type.
      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      changesetId - the changeset identifier
      modificationType - the modification type filter
      Returns:
      the matching entity snapshots

    • findEntitiesGroupedByModificationType

      <T> Map<ModificationType, List<T>> findEntitiesGroupedByModificationType(Class<T> entityClass, Object changesetId)
      Find all entity snapshots of the given type that were modified in a specific changeset, grouped by modification type (ADD, MOD, DEL).
      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      changesetId - the changeset identifier
      Returns:
      entity snapshots grouped by modification type

    • getHistory

      <T> List<AuditEntry<T>> getHistory(Class<T> entityClass, Object id)
      Get the full audit history for an entity, ordered chronologically by changeset identifier.

      Each entry contains the entity snapshot, the changeset identifier (or changelog entity), and the modification type (ADD/MOD/DEL).

      For DEL entries, the entity snapshot reflects the state at the moment of deletion.

      Type Parameters:
      T - the entity type
      Parameters:
      entityClass - the audited entity class
      id - the entity identifier
      Returns:
      the audit history as a list of AuditEntry

    • getEntityTypesModifiedAt

      Set<Class<?>> getEntityTypesModifiedAt(Object changesetId)
      Get the set of entity types that were modified in the given changeset.

      Requires a @Changelog with a @ModifiedEntities property (e.g. DefaultTrackingModifiedEntitiesChangelog).

      Parameters:
      changesetId - the changeset identifier
      Returns:
      the set of entity classes modified in that changeset
      Throws:
      AuditException - if entity change tracking is not enabled

    • findAllEntitiesModifiedAt

      List<Object> findAllEntitiesModifiedAt(Object changesetId)
      Find all entity snapshots across all audited types that were modified in the given changeset.

      Requires a @Changelog with a @ModifiedEntities property (e.g. DefaultTrackingModifiedEntitiesChangelog).

      Parameters:
      changesetId - the changeset identifier
      Returns:
      all entity snapshots modified in that changeset
      Throws:
      AuditException - if entity change tracking is not enabled

    • findAllEntitiesModifiedAt

      List<Object> findAllEntitiesModifiedAt(Object changesetId, ModificationType modificationType)
      Find all entity snapshots across all audited types that were modified in the given changeset with the specified modification type.

      Requires a @Changelog with a @ModifiedEntities property (e.g. DefaultTrackingModifiedEntitiesChangelog).

      Parameters:
      changesetId - the changeset identifier
      modificationType - the modification type filter
      Returns:
      the matching entity snapshots
      Throws:
      AuditException - if entity change tracking is not enabled

    • findAllEntitiesGroupedByModificationType

      Map<ModificationType, List<Object>> findAllEntitiesGroupedByModificationType(Object changesetId)
      Find all entity snapshots modified in the given changeset, grouped by modification type (ADD, MOD, DEL).

      Requires a @Changelog with a @ModifiedEntities property (e.g. DefaultTrackingModifiedEntitiesChangelog).

      Parameters:
      changesetId - the changeset identifier
      Returns:
      entity snapshots grouped by modification type
      Throws:
      AuditException - if entity change tracking is not enabled

    • getChangesetTimestamp

      Instant getChangesetTimestamp(Object changesetId)
      Get the timestamp of a specific changeset. Requires a @Changelog with a @Timestamp field.
      Parameters:
      changesetId - the changeset identifier
      Returns:
      the changeset timestamp
      Throws:
      AuditException - if no changelog entity is configured or the changeset does not exist

    • getChangesetId

      Object getChangesetId(Instant instant)
      Get the changeset identifier that was current at or before the given instant. Requires a @Changelog with a @Timestamp field.
      Parameters:
      instant - the point in time
      Returns:
      the most recent changeset identifier at or before the given instant
      Throws:
      AuditException - if no changeset exists at or before the given instant

    • findChangeset

      <T> T findChangeset(Class<T> changelogClass, Object changesetId)
      Load the changelog entity for the given changeset identifier. Requires a @Changelog.
      Type Parameters:
      T - the changelog entity type
      Parameters:
      changelogClass - the changelog entity class
      changesetId - the changeset identifier
      Returns:
      the changelog entity
      Throws:
      AuditException - if no changelog entity is configured or the changeset does not exist

    • findChangesets

      <T> Map<Object,T> findChangesets(Class<T> changelogClass, Set<?> changesetIds)
      Load changeset entities for multiple changeset identifiers. Requires a @Changelog.
      Type Parameters:
      T - the changelog entity type
      Parameters:
      changelogClass - the changelog entity class
      changesetIds - the changeset identifiers
      Returns:
      a map from changeset identifier to changelog entity