Appendix 6. Upgrading Kodo
Prev |  | Next

## Appendix 6. Upgrading Kodo

This document describes how to upgrade to a new version of Kodo from the prior version. When skipping versions, please follow the steps outlined as though you are converting to each intermediate version.

## 6.1. Compatibility Configuration

The sections below detail specific steps to switch from one Kodo release to another. Kodo also offers backwards compatibility settings for certain runtime behaviors, encompassed in the `kodo.Compatibility` property. This property uses Kodo's plugin syntax to control the following options:

- `ValidateFalseReturnsHollow`: Whether to return hollow objects (objects for which no state has been loaded) from calls to `PersistenceManager.getObjectById(oid, false)`. This is the default behavior of Kodo 4.0 and above. Previous Kodo versions, however, always loaded the object from the datastore. Set this property to `false` to get the old behavior.

- `ValidateTrueChecksStore`: Prior to Kodo 4.0, calling `PersistenceManager.getObjectById(oid, true)` always checked the datastore to be sure the given oid existed, even when the corresponding object was already cached. Kodo 4.0 and above does not check the datastore when the instance is already cached and loaded. Set this property to `true` to mimic previous behavior.

- `CopyObjectIds`: Kodo versions prior to 3.0 always copied oid objects before returning them to you. This prevents possible errors resulting from you mutating the oid object by reference, but wasn't very efficient for the majority of users who don't modify oid instances. Thus Kodo 3.0 and higher does not copy oids by default. Set this property to `true` to force Kodo to copy.

- `CloseOnManagedCommit`: If `true`, then the JDO `PersistenceManager` will close after a managed transaction commits, assuming you have invoked the `close` method. If this is set to `false`, then the `PersistenceManager` will not close. This means that objects passed to a processing tier in the same JVM will still be usable, as their owning `PersistenceManager` will still be open. This behavior is not in strict compliance with the JDO specification, but is convenient for applications that were coded against Kodo 2.x, which did not close the `PersistenceManager` in these situations. The default for this property is `true`, meaning that the `PersistenceManager` will close properly.

- `QuotedNumbersInQueries`: Whether to interpret quoted numbers in query strings as numbers, as opposed to strings. Defaults to treating quoted numbers as strings. Set to `true` to treat quoted numbers as numbers instead to mimic the behavior of Kodo 3.1 and prior.

- `StrictIdentityValues`: Whether to require identity values used for finding application identity instances to be of the exact right type. By default, Kodo allows stringified identity values, and performs conversions between numeric types.

- `NonOptimisticVersionCheck`: Whether or not to perform a version check on instances to be updated when a non-optimistic transaction is commited. Defaults to `false`, meaning that an dirty instance enlisted in a datastore transaction will not have its version columns (if any) validated upon commit, although those version columns will still be updated with the new values. This behavior is new as of Kodo 4.1. Setting it to `true` will mimic pre-4.1 behavior, which is to always update version columns when dirty instances are flushed to the datastore.

For example, the setting below cause Kodo to copy oids and not to return hollow objects:

JPA XML format:

    <property name="kodo.Compatibility"
        value="ValidateFalseReturnsHollow=false, CopyObjectIds=true">

JDO properties format:

    kodo.Compatibility: ValidateFalseReturnsHollow=false, CopyObjectIds=true

Prev |  | Next
Appendix 5. Common Database Errors | Home | 6.2. Migrating from Kodo 3.0 to Kodo 3.1