7.7. Version Indicator
Prev | Chapter 7. Object-Relational Mapping | Next

## 7.7. Version Indicator

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”.

### 7.7.1. Version Number Indicator

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.21. 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
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.

### 7.7.2. Version Date Indicator

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.22. 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>

### 7.7.3. State Image Indicator

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.23. 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>

### 7.7.4. Custom Version Indicator

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.

Prev | Up | Next
7.6. Class Mapping | Home | 7.8. Class Indicator