3.8.7.2. Surrogate Version Mapping
OpenJPA supports version fields as defined by the JPA specification, but allows you to use a surrogate version column in place of a version field if you like.
You map the surrogate version column with the
org.apache.openjpa.persistence.jdbc.VersionColumn annotation.
You can also use the
org.apache.openjpa.persistence.jdbc.VersionColumns
annotation to declare an array of VersionColumn values.
Each VersionColumn has the following properties:
-
String name: Defaults toVERSN. -
String table -
int length -
int precision -
int scale -
String columnDefinition -
boolean nullable -
boolean insertable -
boolean updatable
All properties correspond exactly to the same-named properties on the standard Column annotation, described in Column.
By default, OpenJPA assumes that surrogate versioning uses a version number strategy.
You can choose a different strategy with the VersionStrategy annotation described in Version Strategy.
If multiple columns are used for surrogate versioning, then each column, by default, uses a version number.
But column definition for each version column can be set independently to other numeric types.
The version values are compared to detect optimistic concurrent modification.
Such comparison must determine whether a version value v1 represents an earlier, later or same with respect to another version value v2.
While result of such comparison is obvious for a single numeric column that monotonically increases on each update, the same is not true when version value is an array of numbers.
By default, OpenJPA compares a version v1 as later than another version v2, if any array element of v1 is later than the corresponding element of v2. v1 is equal to v2 if every array element is equal and v1 is earlier to v1 if some elements of v1 are earlier and rest are equal to corresponding element of v2.
Multiple surrogate version columns can be spread across primary and secondary tables.
For example, following example shows 3 version columns v01, v11, v12, v21 defined across the primary and secondary tables of a persistent entity
@Entity
@Table(name="PRIMARY")
@SecondaryTables({
@SecondaryTable(name = "SECONDARY_1"),
@SecondaryTable(name = "SECONDARY_2")
})
@VersionStrategy("version-numbers")
@VersionColumns({
@VersionColumn(name = "v01") // default is the PRIMARY table
@VersionColumn(name = "v11", table="SECONDARY_1", columnDefinition="FLOAT", scale=3, precision=10),
@VersionColumn(name = "v12", table="SECONDARY_1"),
@VersionColumn(name = "v21", table="SECONDARY_2"),
})