EclipseLink/Examples/JPA/History

Tracking Changes Using History Policy

EclipseLink provides extended support for tracking all changes made to the database. The EclipseLink HistoryPolicy can be configured on a ClassDescriptor to store a mirror table of the original that will store the state of the object at any point in time. This can be used for auditing purposes, or to allow querying as of past points in time, or to allow restoring old data.

When enabled EclipseLink will insert a row into the history table on every update to the primary table to track the rows state. The history table also defines a start and end timestamp, so that the state of any row at any point in time can be determined.

EclipseLink also supports queries as of a past point in time, either through using EclipseLink Expressions, or through using the "eclipselink.history.as-of" query hint, or an EclipseLink HistoricalSession.

EclipseLink also supports historical queries on database that are enabled with Oracle Flashback.

Example: Enabling history

History support is enabled for the Employee class.

@Entity
@Customizer(org.acme.persistence.HistoryCustomizer.class)
public class Employee{
    @Id
    private long id;
    ...
}

import org.eclipse.persistence.config.DescriptorCustomizer;
import org.eclipse.persistence.descriptors.ClassDescriptor;
import org.eclipse.persistence.history.HistoryPolicy;
 
public class HistoryCustomizer implements DescriptorCustomizer {
 
    public void customize(ClassDescriptor descriptor) {
        HistoryPolicy policy = new HistoryPolicy();
        policy.addHistoryTableName("EMPLOYEE_HIST");
        policy.addStartFieldName("START_DATE");
        policy.addEndFieldName("END_DATE");
        descriptor.setHistoryPolicy(policy);
    }
}

Example history table

The state of the EMPLOYEE_HIST table will mirror the EMPLOYEE, but with multiple rows for each current row, and history for deleted rows.

EMPLOYEE (table)

EMP_ID	FIRSTNAME	LASTNAME	SALARY	ADDRESS_ID
1	Bob	Way	55000	6
2	Sarah	Way	60000	6
4	Jim	Jones	30000	7

EMPLOYEE_HIST (table)

EMP_ID	FIRSTNAME	LASTNAME	SALARY	ADDRESS_ID	START_DATE	END_DATE
1	Bob	Way	55000	6	2010-06-10-12:00:00:0	null
1	Bob	Way	50000	6	2010-05-01-12:00:00:0	2010-06-10-12:00:00:0
2	Sarah	Way	60000	6	2010-06-14-12:00:00:0	null
2	Sarah	Smith	60000	5	2005-01-01-12:00:00:0	2010-06-14-12:00:00:0
2	Sarah	Smith	50000	5	2000-01-01-12:00:00:0	2005-01-01-12:00:00:0
3	John	Smith	40000	5	2000-01-01-12:00:00:0	2010-06-01-12:00:00:0
3	Jim	Jones	30000	7	2006-01-01-12:00:00:0	null