A version indicator is responsible for versioning each stored object so that optimistic locking errors can be detected. The version indicator is always placed on the base class in an inheritance tree. Subclasses inherit the version indicator of their parent class.
In Kodo JDO, version indicators extend the base kodo.jdbc.meta.VersionIndicator class. The concrete version indicators Kodo JDO provides are described in the sections below. By default, the mapping tool uses the version-number version indicator for all persistent classes. You can change the default version indicator type with the kodo.jdbc.VersionIndicator configuration property. You can also instruct the mapping tool to use a specific indicator for an individual class with the jdbc-version-ind-name JDO metadata extension.
Both the number and date version indicators can be used in conjunction with Kodo's lock group support. Details regarding use and limitations of field-level lock groups are available in Section 14.6, “Lock Groups”.
The version number indicator uses a version number stored in a database column to detect concurrent modifications to an object. When an object is loaded, its version number is loaded along with it. On transaction commit, the in-memory version number is compared to the database version number. If the database version number does not match, then the object has been modified concurrently by another transaction, and an optimistic lock exception is raised. Otherwise, the version number is incremented as a sign to other transactions that the object was changed.
The version number indicator has the following attributes:
type: version-number
column: The name of the column that holds the version number for each object. This column must be in the class' primary table. This property is required.
Example 7.22. Using a Version Number Indicator
Java class:
public class Magazine
{
... class content ...
}
Schema:
<table name="MAGAZINE">
... primary key columns ...
<column name="JDOVERSION" type="bigint"/>
... columns for magazine fields ...
</table>
JDO metadata:
<class name="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
... class mapping ...
<jdbc-version-ind type="version-number" column="JDOVERSION"/>
... field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-version-ind" value="version-number">
<extension vendor-name="kodo" key="column" value="JDOVERSION"/>
</extension>
... field metadata ...
</class>
![[Note]](img/note.gif) | Note |
|---|---|
When adding a version column to an existing schema, the values of the version should be seeded with zero, rather than null. Kodo expects non-null values for the contents of a version column. | |
The version date indicator uses a timestamp column to track the last revision to an object. The timestamp is updated whenever the object's database record is updated. On transaction commit, timestamps are compared to be sure that the object wasn't changed by another transaction since it was loaded by the current one.
The version date indicator is intended for legacy support only. The version number indicator is both more efficient and more robust, because it is not dependent on the granularity of the database's timestamps.
The version date indicator has the following attributes:
type: version-date
column: The name of the column that holds the SQL timestamp for each object. This column must be in the class' primary table. This property is required.
Example 7.23. Using a Version Date Indicator
Java class:
public class Magazine
{
... class content ...
}
Schema:
<table name="MAGAZINE">
... primary key columns ...
<column name="JDOVERSION" type="timestamp"/>
... columns for magazine fields ...
</table>
JDO metadata:
<class name="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
... class mapping ...
<jdbc-version-ind type="version-date" column="JDOVERSION"/>
... field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-version-ind" value="version-date">
<extension vendor-name="kodo" key="column" value="JDOVERSION"/>
</extension>
... field metadata ...
</class>
The state image indicator does not require any database columns in order to detect optimistic lock violations. Instead, it maintains an image of the object's state as it is loaded. When the object is committed for update, the indicator checks the in-memory image against the database values to make sure no other transaction has changed the object's record since it was loaded. The following limitations apply to the state image indicator:
State comparisons only use simple value fields such as strings, primitives, and primitive wrappers.
Comparisons exclude doubles, floats, and dates because they cannot be compared reliably.
If concurrent transactions modify fields in a disjoint set of tables, the conflict will go undetected.
Fields with the "none" lock group are not included in state image checks and conflict will go undetected.
The state image indicator has the following attributes:
type: state-image
Example 7.24. Using a State Image Indicator
Java class:
public class Magazine
{
... class content ...
}
Schema:
<table name="MAGAZINE">
... primary key columns ...
... columns for magazine fields ...
</table>
JDO metadata:
<class name="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
... class mapping ...
<jdbc-version-ind type="state-image"/>
... field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-version-ind" value="state-image"/>
... field metadata ...
</class>
Kodo JDO allows you to create your own version indicators. All version indicators must extend, directly or indirectly, from kodo.jdbc.meta.VersionIndicator.
The jdbc-version-ind-name JDO metadata extension tells the mapping tool which version indicator to install. If you write mappings by hand rather than with the mapping tool, simply specify the full class name of your custom indicator in the type attribute of the mapping XML.
The samples/ormapping directory of the Kodo JDO distribution includes examples of custom mappings.