Skip Headers

# Configuring a History Policy

Previous

Next

If you want to use historical sessions (see "Historical Sessions") to execute historical queries (see "Historical Queries") against a historical schema of your own design, configure your descriptors with a TopLink `HistoryPolicy` that describes your historical schema.

If you are using an Oracle database platform for Oracle9i Database Server (or later), you can query the historical versions of objects automatically maintained by the Oracle database without the need for a history policy. For more information, see "Configuring Historical Sessions Using an Oracle Platform".

Table: Descriptor Support for History Policy Configuration summarizes which descriptors support history policy configuration.

Descriptor Support for History Policy Configuration

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational Descriptors |  |
Object-Relational Descriptors |  |
EIS Descriptors |  |
XML Descriptors |  |

There are many ways to configure a historical database schema. TopLink supports several historical schema configurations that you can describe with a `HistoryPolicy` (see "Historical Session Limitations").

Example Historical Schema

As shown in Table: Example Table for EMPLOYEE and Table: Example History Table EMPLOYEE_HIST, a common approach is to define a special history table to store past versions of an object: one history table for each regular table that requires historical persistence. The history table typically has the same fields as the corresponding regular table plus fields (such as row start and end) used to define an interval that represents the life time of a particular version.

Note: TopLink assumes that the current version of an object corresponds to the historical table row whose row end field is `NULL`.

TopLink will include the history tables described by a `HistoryPolicy` when you execute a historical query.

Table: Example Table for EMPLOYEE shows the schema for an `EMPLOYEE` table. The table currently contains one `EMPLOYEE` instance.

Example Table for EMPLOYEE

EMP_ID | F_NAME | L_NAME | SALARY
--- | --- | --- | ---
1 | Jane | Doe | 55000

Table: Example History Table EMPLOYEE_HIST shows one possible history table `EMPLOYEE_HIST` that stores historical versions of employees. The table contains the current `EMPLOYEE` (the version with a `ROW_END` value of `NULL`) and one historical version.

Example History Table EMPLOYEE_HIST

EMP_ID | F_NAME | L_NAME | SALARY | ROW_START | ROW_END
--- | --- | --- | --- | --- | ---
1 | Jane | Doe | 50000 | 29/08/2004 | 31/08/2004
1 | Jane | Doe | 55000 | 31/08/2004 | NULL

Because every record has a start and end interval, the history table can store multiple versions of the same object (with the same primary key). The unique identifier of a particular version is given by the existing primary key, plus the value of the start field. For example, in Table: Example History Table EMPLOYEE_HIST, the unique identifier of the current version is given by `(EMP_ID, START) = (1, 31/08/2004)`.