Annotation Interface Temporal

@Documented @Target({PACKAGE,TYPE,FIELD,METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Incubating public @interface Temporal
Specifies that the annotated entity class is a temporal entity or temporal collection. A temporal entity or collection keeps a historical record of changes over time. Each row of the mapped table or tables represents a single revision of a single instance of the entity, or an element of the collection whose existence is bounded in time, with:
  • a rowStart() timestamp representing the instant at which the revision became effective, and
  • a rowEnd() timestamp representing the instant at which the revision was superseded by a newer revision.
The revision which is currently effective has a null value for its rowEnd() timestamp.

Given the identifier of an instance of a temporal entity, along with an instant, which may be represented by an instance of Instant, the effective revision of the temporal entity with the given identifier at the given instant is the revision with:

  • rowStart() timestamp less than or equal to the given instant, and
  • rowEnd() timestamp null or greater than the given instant.

There are three strategies for mapping a temporal entity or collection to a table or tables.

  • In the single table strategy, current and historical data is stored together in the same table. Foreign keys referencing this table have no constraints, and so the database cannot enforce referential integrity. The table may be partitioned into current and historical partitions.
  • In the separate history table strategy, current data is stored in one table, and historical data is stored in a second table. Referential integrity may be enforced for current data, but not for historical data. The rowStart and rowEnd columns belong to the history table.
  • In the native strategy, temporal data is stored in a temporal table when temporal tables are supported natively by the database. The rowStart and rowEnd columns are managed by the database itself. Depending on the capabilities of the database, referential integrity might be enforced.

The configuration property "hibernate.temporal.table_strategy" controls the temporal table mapping strategy.

By default, a session or stateless session reads revisions of temporal data which are currently effective. To read historical revisions effective at a given instant, set the temporal data instant when creating the session or stateless session.

The following recommendations do not apply to the native mapping strategy:

  • It is recommended that every temporal entity declare a version attribute. The primary key of a table mapped by a temporal entity includes the columns mapped by the identifier of the entity, along with the version column, if there is one, or the rowStart() column if there is no version.
  • When working with temporal entities, it is important to ensure that referential integrity is maintained by the application and validated by triggers or offline processes.

By default, timestamps for the rowStart and rowEnd columns are generated in Java, unless native temporal tables are used. If timestamps should be generated on the database server, enable the configuration property "hibernate.temporal.use_server_transaction_timestamps".

An alternative approach, which is not compatible with the native mapping strategy, is to provide a custom Supplier of changeset ids by specifying the configuration property "hibernate.temporal.changeset_id_supplier". Changeset ids must be unique and comparable and must increase monotonically. Typically, such an id is obtained by persisting an instance of an application-defined entity class with a generated id which represents the current changeset. This entity associates the changeset id with other information about the work being performed, such as the current timestamp, current application user, and so on.

See Also:
API Note:
Secondary tables and joined inheritance mappings are not supported for temporal entities.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Temporal.Excluded
    Excludes the annotated attribute from temporal versioning.
    static @interface 
    Temporal.HistoryPartitioning
    Enables partitioning for a temporal table mapped by a temporal entity or collection in the single table temporal mapping strategy.
    static @interface 
    Temporal.HistoryTable
    Specifies the name of the separate history table for a temporal entity or collection when the history table strategy is used.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    rowEnd
    The name of the column holding the ending timestamp or changeset id of a revision; the timestamp or id representing the moment the revision was superseded; that is, the "effective to" timestamp.
    String
    rowStart
    The name of the column holding the starting timestamp or changeset id of a revision; the timestamp or id representing the moment the revision became effective; that is, the "effective from" timestamp.
    int
    secondPrecision
    The fractional seconds precision for both temporal columns.

  • Element Details

    • rowStart

      String rowStart
      The name of the column holding the starting timestamp or changeset id of a revision; the timestamp or id representing the moment the revision became effective; that is, the "effective from" timestamp.
      Default:
      "effective"

    • rowEnd

      String rowEnd
      The name of the column holding the ending timestamp or changeset id of a revision; the timestamp or id representing the moment the revision was superseded; that is, the "effective to" timestamp.
      Default:
      "superseded"

    • secondPrecision

      int secondPrecision
      The fractional seconds precision for both temporal columns.
      See Also:
      Default:
      -1