Additional JPA annotations - SCD

The JBStrap framework supports SCD (Slowly Changing Dimension) implementations. This means that a table can store the active states of the records and their associated historical data. That is, the data and its history are stored in the same table. Using database logs, any state of the record can be retrieved at any time.

To implement the SCD, you need to use multiple annotations on the given entity to tell the framework which field of the entity to store. By combining annotations, SCD Type 2 and SCD Type 6 can be implemented.

Click here for a detailed description of the SCD .

Below is an example of implementing SCD Type 6.

Initial state of a record:

id	entity_id	supplier_code	supplier_name	state	valid_from	valid_to	active_flag
1	123	ABC	Example supply co.	CA	1900-01-01 00:00	null	Y

The table above shows the initial state of the record. Now modify the value of the state field from CA to IL and see what happens. Because the table contains its own history, a new record is added to the table and the state of the previous record will change. After making modification, if you save the record to the table, the data table in the database will look like this:

id	entity_id	supplier_code	supplier_name	state	valid_from	valid_to	active_flag
1	123	ABC	Example supply co.	CA	1900-01-01 00:00	2020-03-06 12:34	N
2	123	ABC	Example supply co.	IL	2020-03-06 12:34	null	Y

You can see that the modified record was added to the data table as a new record and that the record has remained in its previous state. Each record receives a unique identifier, which is stored in the id field. The unique identifier for the record, the entity_id field, was added as a data field, as the record may appear multiple times in the table. Therefore, the unique identifier of the record cannot be used as the identifier of the table.

Other fields were added to the table to indicate the state of the record. Such a field is active_flag, which represents the current state of the record. In the current state of the record, the value of the active_flag field is always Y , while in all preceding states it is set to N . You can also see that the field named valid_from always shows when the record is valid. This corresponds to the record creation time. The value of the valid_to column is not always filled. When the record is in a valid state, the value of the valid_to field will be null. If the record is modified, the modification date is stored in the valid_to column which indicates that the record is not valid anymore from then on and another state is used instead. In case the record is deleted, the valid_to field is also filled with the time of the deletion, and the value of the active_flag field is also changed to N . This will not add a new record to the table, so the record will not have a valid status.

  The following entity class must be implemented for the above example:  
         
@SCD
@Entity
public class SCDTable implements Serializable {
    private static final long serialVersionUID = 1;

    @Id
    public Long id;

    @EntityId
    @Column(name="entity_id")
    public Long entityId;

    @Column(name="supplier_code")
    public String supplierCode;

    @Column(name="supplier_name")
    public String supplierName;

    @Column(name="state")
    public String state;

    @ValidFrom
    @Column(name="valid_from")
    @Temporal(TemporalType.TIMESTAMP)
    public Date validFrom;

    @ValidTo
    @Column(name="valid_to")
    @Temporal(TemporalType.TIMESTAMP)
    public Date validTo;

    @ActiveFlag
    @Column(name="active_flag")
    public String activeFlag;

    /*
    ... getters and setters
    */
}

SCD

This annotation must be placed on the entity where the data is to be stored according to the SCD standard. The annotation has no parameters, it only indicates that we want to store data in the entity based on SCD.

  In the example above, the annotation of the SCD appears as follows:  
        
@SCD
@Entity
public class SCDTable implements Serializable {
...
}

EntityId

This annotation should be placed in the field containing the unique identifier for the record. Because the table contains all record states as separate records, this identifier must be different from the table's unique identifier.

  In the example above, the unique identifier for the record is the entity_id field. The example also shows that the value of the field is the same (123) for all records. The annotation in the example is as follows:  
        
@EntityId
@Column(name="entity_id")
private Long entityId;

ValidFrom

This annotation must be placed in the field where you want to store the start of the record's validity. The field where the annotation is placed must be Date , otherwise the save process will return an error. The annotated field will always get a value. The value of the field will be the date record's creation date, and in case of a modification the date of the modification.

  In the above example the annotation is used in the following way:  
        
@ValidFrom
@Column(name="valid_from")
@Temporal(TemporalType.TIMESTAMP)
public Date validFrom;

ValidTo

This annotation must be placed in the field where you want to store the end of the record's validity. The field where the annotation is placed must be Date , otherwise the save process will return an error. The annotated field does not always receive a value. If the record is valid, the value of the field will be null. If the record is invalid, the date of modification or deletion of the record will be the value of the field.

  In the above example the annotation is used in the following way:  
        
@ValidTo
@Column(name="valid_to")
@Temporal(TemporalType.TIMESTAMP)
public Date validTo;

ActiveFlag

This annotation should be placed in the field where you want to store the flag indicating the active state of the record. The annotation must always be placed on a String type field, otherwise the record save process will give an error. The annotated field will always receive a value. When the record is active, the value of the field is Y , and when the record is inactive, the value of the field is N .

  In the above example the annotation is used in the following way:  
        
@ActiveFlag
@Column(name="active_flag")
public String activeFlag;