Appendix 5. Upgrading Kodo

5.1. Compatibility Configuration
5.2. Migrating from Kodo 3.0 to Kodo 3.1
5.3. Migrating from Kodo 3.1 to Kodo 3.2
5.4. Migrating from Kodo 3.x to Kodo 4.0
5.4.1. API Compatibility
5.4.2. Metadata and Mappings
5.4.3. Configuration
5.5. Migrating from Kodo 4.0 to Kodo 4.1
5.6. Migrating from Kodo 4.x.x to Kodo 4.1.3+

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.

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


Skip navigation bar   Back to Top